Skip to content

Commit f082ce4

Browse files
MiriamGausMiriamGaus
committed
docs: restructure readme
1 parent a7dc5e4 commit f082ce4

1 file changed

Lines changed: 83 additions & 68 deletions

File tree

‎README.md‎

Lines changed: 83 additions & 68 deletions
Original file line numberDiff line numberDiff line change
@@ -1,98 +1,113 @@
1-
# UVL - Universal Variability Language Java Metamodel
2-
This is a small default library used to manipulate UVL metamodels in JAVA
1+
# UVL - Universal Variability Language Java Feature Model Metamodel
32

4-
## The Language
3+
This is a small default library used to manipulate UVL metamodels in JAVA. It uses the [UVL-Grammar](https://github.com/Universal-Variability-Language/) to parse the a given metamodel. If parsed the model can be modified in JAVA. It is possible to also convert the models to different levels.
54

6-
On a high level, each feature model in UVL consists of five optional separated elements:
5+
**How to use UVL** can be found in this paper
6+
[![DOI](https://img.shields.io/badge/DOI-10.1016%2Fj.jss.2024.112326-blue)](https://doi.org/10.1016/j.jss.2024.112326)
77

8-
1. **A list of used language levels**
9-
The model can use different concepts which are part of language levels. These levels can either be enumerated with the `include` keyword or be implicit.
10-
2. **A namespace which can be used for references in other models**
11-
3. **A list of imports that can be used to reference external feature models**
12-
The models are referenced by their file name and can be given an alias using a Java import like syntax.
13-
External models in subdirectories can be referenced like this: subdir.filename as fn
14-
4. **The tree hierarchy consisting of: features, group types, and attributes whose relations are specified using nesting (indentation)**
15-
Groups may have an arbitrary number of features as child nodes. A feature can also have a feature cardinality.
16-
Attributes consist of a key-value pair whose key is always a string and its value may be a boolean, number, string, a list attributes, a vector, or a constraint. If the value is a constraint the key must be `constraint`. If the value is a list of constraints the key must be `constraints`
17-
5. **Cross-tree constraints**
18-
Cross-tree constraints may be arbitrary propositional formulas with the following symbols: => (implies), <=> (iff), & (and), | (or), ! (not), or brackets. Through the usage of language levels cross-tree constraints can also contain equations (<,>,==) which consist of expressions (+,-,*,/) with numbers or numerical feature attributes as literals and aggregate functions (avg, sum).
8+
## ✨ Key Features
199

20-
The following snippet shows a simplified server architecture in UVL. We provide more examples (e.g., to show the composition mechanism) in [https://github.com/Universal-Variability-Language/uvl-models/tree/main/Feature_Models](https://github.com/Universal-Variability-Language/uvl-models/tree/main/Feature_Models).
10+
- full support of UVL-Syntax (nampaces, feature hircharcies and constraints)
11+
- convert between different language levels
12+
- direct access to feature model components like features, groups and attributes
2113

22-
```
23-
namespace Server
24-
25-
features
26-
Server {abstract}
27-
mandatory
28-
FileSystem
29-
or // with cardinality: [1..*]
30-
NTFS
31-
APFS
32-
EXT4
33-
OperatingSystem {abstract}
34-
alternative
35-
Windows
36-
macOS
37-
Debian
38-
optional
39-
Logging {
40-
default,
41-
log_level "warn" // Feature Attribute
42-
}
43-
44-
constraints
45-
Windows => NTFS
46-
macOS => APFS
47-
```
14+
## 💡 Usages/Examples
4815

49-
In this snippet, we can recognize the following elements:
50-
* The feature `Server` is abstract (i.e., corresponds to no implementation artifact.
51-
* Each `Server` requires a `FileSystem`and an `OperatingSystem` denoted by the *mandatory* group
52-
* The `Server` may have `Logging` denoted by the *optional* group
53-
* A `FileSystem` requires at least one type of `NTFS`, `APFS`, and `Ext4` denoted by the *or* group
54-
* An `OperatingSystem` has exactly one type of `Windows`, `macOS`, and `Debian`denoted by the *alternative* group
55-
* `Logging` has the feature attribute `log_level` attached which is set to "warn"
56-
* `Windows` requires `NTFS` denoted by the first cross-tree constraint
57-
* `macOS`requires `APFS`
16+
To use the Java-fm-metamodel it needs to be built with [Maven](https://maven.apache.org/):
5817

59-
## Building a jar
60-
61-
The library is a maven project and can therefore be build with maven. To update the generated parser classes and create a jar with all necessary dependencies, use:
62-
```
63-
mvn clean compile assembly:single
18+
```bash
19+
mvn clean compile
6420
```
6521

66-
The `target/uvl-parser-1.0-SNAPSHOT-jar-with-dependencies.jar` includes all dependencies.
22+
More usage examples that also show how to use the acquired UVLModel object can be found in [src/main/java/de/vill/main/Example.java](https://github.com/Universal-Variability-Language/java-fm-metamodel/blob/main/src/main/java/de/vill/main/Example.java)
6723

68-
## Usage from Java
69-
The class `de.vill.main.UVLModelFactory` exposes the static method `parse(String)` which will return an instance of a `de.vill.model.FeatureModel` class. If there is something wrong, a `de.vill.exception.ParseError` is thrown. The parser tries to parse the whole model, even if there are errors. If there are multiple errors, a `de.vill.exception.ParseErrorList` is returned which contains all errors that occurred.
70-
A model can be printed with the `toString()` method of the `de.vill.model.FeatureModel` object.
71-
The following snippet shows a minimal example to read and write UVL models using the jar. More usage examples that also show how to use the acquired UVLModel object can be found in [src/main/java/de/vill/main/Example.java](https://github.com/Universal-Variability-Language/uvl-parser2.0/blob/main/src/main/java/de/vill/main/Example.java)
24+
### Parsing
7225

7326
```Java
74-
// Read
27+
// First option:
28+
UVLModelFactory uvlModelFactory = new UVLModelFactory();
29+
FeatureModel featureModel = uvlModelFactory.parse(Paths.get("path/to/your/file.uvl"));
30+
31+
// Second option:
7532
Path filePath = Paths.get(pathAsString);
7633
String content = new String(Files.readAllBytes(filePath));
7734
UVLModelFactory uvlModelFactory = new UVLModelFactory();
7835
FeatureModel featureModel = uvlModelFactory.parse(content);
36+
```
37+
38+
The class `de.vill.main.UVLModelFactory` exposes the static method `parse(String)` which will return an instance of a `de.vill.model.FeatureModel` class. If there is something wrong, a `de.vill.exception.ParseError` is thrown. The parser tries to parse the whole model, even if there are errors. If there are multiple errors, a `de.vill.exception.ParseErrorList` is returned which contains all errors that occurred.
39+
40+
### Modifing
7941

42+
```Java
43+
Feature feature = featureModel.getFeatureMap().get(featureName);
44+
if (feature != null) {
45+
Attribute<?> attribute = feature.getAttributes().get(attributeName);
46+
if (attribute != null) {
47+
System.out.println("Name of the feature" + feature.getFeatureName());
48+
System.out.println("Name of the attribute" + attribute.getName());
49+
}
50+
}
51+
52+
// Conversion
53+
ConvertTypeLevel converter = new ConvertTypeLevel();
54+
converter.convertFeatureModel(featureModel, convertedModel);
55+
```
8056

57+
### Writing into a file
58+
59+
```Java
8160
// Write
8261
String uvlModel = featureModel.toString();
8362
Path filePath = Paths.get(featureModel.getNamespace() + ".uvl");
8463
Files.write(filePath, uvlModel.getBytes());
85-
```
64+
```
65+
66+
A model can be printed with the `toString()` method of the `de.vill.model.FeatureModel` object.
67+
The following snippet shows a minimal example to read and write UVL models using the jar.
68+
69+
## ⚙️ Running Tests
70+
71+
The Java-fm-metamodel can be tested by running:
72+
73+
```bash
74+
mvn test
75+
```
76+
77+
## 📖 Citation
78+
79+
If you use UVL in your research, please cite:
80+
81+
```bibtex
82+
@article{UVL2024,
83+
title = {UVL: Feature modelling with the Universal Variability Language},
84+
journal = {Journal of Systems and Software},
85+
volume = {225},
86+
pages = {112326},
87+
year = {2025},
88+
issn = {0164-1212},
89+
doi = {https://doi.org/10.1016/j.jss.2024.112326},
90+
url = {https://www.sciencedirect.com/science/article/pii/S0164121224003704},
91+
author = {David Benavides and Chico Sundermann and Kevin Feichtinger and José A. Galindo and Rick Rabiser and Thomas Thüm},
92+
keywords = {Feature model, Software product lines, Variability}
93+
}
94+
```
8695

8796
## Links
97+
8898
UVL models:
89-
* https://github.com/Universal-Variability-Language/uvl-models
99+
100+
- https://github.com/Universal-Variability-Language/uvl-models
101+
102+
UVL parser:
103+
104+
- https://github.com/Universal-Variability-Language/uvl-parser
90105

91106
Other parsers:
92-
* https://github.com/Universal-Variability-Language/uvl-parser *deprecated, Initial UVL Parser, based on Clojure and instaparse* **UVL-Parser**
93-
* https://github.com/diverso-lab/uvl-diverso/ *Under development, Antlr4 Parser* **Diverso Lab**
94107

95-
Usage of UVL:
96-
* https://github.com/FeatureIDE/FeatureIDE *Feature modelling tool*
108+
- https://github.com/Universal-Variability-Language/uvl-parser _deprecated, Initial UVL Parser, based on Clojure and instaparse_ **UVL-Parser**
109+
- https://github.com/diverso-lab/uvl-diverso/ _Under development, Antlr4 Parser_ **Diverso Lab**
97110

111+
Usage of UVL:
98112

113+
- https://github.com/FeatureIDE/FeatureIDE _Feature modelling tool_

0 commit comments

Comments
 (0)