# UVL - Universal Variability Language
This is a small default library used to parse and print the Universal Variability Language (UVL).
Under the hood it uses [ANTLR4](https://www.antlr.org/) as the parsing library.
The grammar in EBNF form is located in `uvl/UVL.g4` and the modifications for Java and Python
## The Language
On a high level, each feature model in UVL consists of five optional separated elements:
1. **A list of used language levels**
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.
2. **A namespace which can be used for references in other models**
3. **A list of imports that can be used to reference external feature models**
The models are referenced by their file name and can be given an alias using a Java import like syntax.
External models in subdirectories can be referenced like this: subdir.filename as fn
4. **The tree hierarchy consisting of: features, group types, and attributes whose relations are specified using nesting (indentation)**
Groups may have an arbitrary number of features as child nodes. A feature can also have a feature cardinality.
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`
5. **Cross-tree constraints**
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).
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).
```
namespace Server
features
Server {abstract}
mandatory
FileSystem
or // with cardinality: [1..*]
NTFS
APFS
EXT4
OperatingSystem {abstract}
alternative
Windows
macOS
Debian
optional
Logging {
default,
log_level "warn" // Feature Attribute
}
constraints
Windows => NTFS
macOS => APFS
```
In this snippet, we can recognize the following elements:
* The feature `Server` is abstract (i.e., corresponds to no implementation artifact.
* Each `Server` requires a `FileSystem`and an `OperatingSystem` denoted by the *mandatory* group
* The `Server` may have `Logging` denoted by the *optional* group
* A `FileSystem` requires at least one type of `NTFS`, `APFS`, and `Ext4` denoted by the *or* group
* An `OperatingSystem` has exactly one type of `Windows`, `macOS`, and `Debian`denoted by the *alternative* group
* `Logging` has the feature attribute `log_level` attached which is set to "warn"
* `Windows` requires `NTFS` denoted by the first cross-tree constraint
* `macOS`requires `APFS`
## Building a jar
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:
```
mvn clean compile assembly:single
```
The `target/uvl-parser-1.0-SNAPSHOT-jar-with-dependencies.jar` includes all dependencies.
## Usage from Java
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.
A model can be printed with the `toString()` method of the `de.vill.model.FeatureModel` object.
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)
```Java
// Read
Path filePath = Paths.get(pathAsString);
String content = new String(Files.readAllBytes(filePath));
UVLModelFactory uvlModelFactory = new UVLModelFactory();
FeatureModel featureModel = uvlModelFactory.parse(content);
// Write
String uvlModel = featureModel.toString();
Path filePath = Paths.get(featureModel.getNamespace() + ".uvl");
Files.write(filePath, uvlModel.getBytes());
```
## Links
UVL models:
* https://github.com/Universal-Variability-Language/uvl-models
Other parsers:
* https://github.com/Universal-Variability-Language/uvl-parser *deprecated, Initial UVL Parser, based on Clojure and instaparse* **UVL-Parser**
* https://github.com/diverso-lab/uvl-diverso/ *Under development, Antlr4 Parser* **Diverso Lab**
Usage of UVL:
* https://github.com/FeatureIDE/FeatureIDE *Feature modelling tool*
Raw data
{
"_id": null,
"home_page": "https://github.com/Universal-Variability-Language/uvl-parser",
"name": "uvlparser",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": "",
"keywords": "",
"author": "UVL Team",
"author_email": "jagalindo@us.es",
"download_url": "https://files.pythonhosted.org/packages/42/1d/b2b44500ac17098e74dbe202af6e4d9b0f08c1abe1659406ae40ecbb5087/uvlparser-2.0.1.tar.gz",
"platform": null,
"description": "# UVL - Universal Variability Language\nThis is a small default library used to parse and print the Universal Variability Language (UVL).\n\nUnder the hood it uses [ANTLR4](https://www.antlr.org/) as the parsing library.\nThe grammar in EBNF form is located in `uvl/UVL.g4` and the modifications for Java and Python\n\n## The Language\n\nOn a high level, each feature model in UVL consists of five optional separated elements:\n\n1. **A list of used language levels**\nThe model can use different concepts which are part of language levels. These levels can either be enumerated with the `include` keyword or be implicit.\n2. **A namespace which can be used for references in other models**\n3. **A list of imports that can be used to reference external feature models**\nThe models are referenced by their file name and can be given an alias using a Java import like syntax.\nExternal models in subdirectories can be referenced like this: subdir.filename as fn\n4. **The tree hierarchy consisting of: features, group types, and attributes whose relations are specified using nesting (indentation)**\nGroups may have an arbitrary number of features as child nodes. A feature can also have a feature cardinality.\nAttributes 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`\n5. **Cross-tree constraints**\nCross-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).\n\nThe 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).\n\n```\nnamespace Server\n\nfeatures\n Server {abstract}\n mandatory\n FileSystem\n or // with cardinality: [1..*]\n NTFS\n APFS\n EXT4\n OperatingSystem {abstract}\n alternative\n Windows\n macOS\n Debian\n optional\n Logging\t{\n default,\n log_level \"warn\" // Feature Attribute\n }\n\nconstraints\n Windows => NTFS\n macOS => APFS\n```\n\nIn this snippet, we can recognize the following elements:\n* The feature `Server` is abstract (i.e., corresponds to no implementation artifact.\n* Each `Server` requires a `FileSystem`and an `OperatingSystem` denoted by the *mandatory* group\n* The `Server` may have `Logging` denoted by the *optional* group\n* A `FileSystem` requires at least one type of `NTFS`, `APFS`, and `Ext4` denoted by the *or* group\n* An `OperatingSystem` has exactly one type of `Windows`, `macOS`, and `Debian`denoted by the *alternative* group\n* `Logging` has the feature attribute `log_level` attached which is set to \"warn\"\n* `Windows` requires `NTFS` denoted by the first cross-tree constraint\n* `macOS`requires `APFS`\n\n## Building a jar\n\nThe 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:\n```\nmvn clean compile assembly:single\n```\n\nThe `target/uvl-parser-1.0-SNAPSHOT-jar-with-dependencies.jar` includes all dependencies.\n\n## Usage from Java\nThe 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.\nA model can be printed with the `toString()` method of the `de.vill.model.FeatureModel` object.\nThe 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)\n\n```Java\n// Read\nPath filePath = Paths.get(pathAsString);\nString content = new String(Files.readAllBytes(filePath));\nUVLModelFactory uvlModelFactory = new UVLModelFactory();\nFeatureModel featureModel = uvlModelFactory.parse(content);\n\n\n// Write\nString uvlModel = featureModel.toString();\nPath filePath = Paths.get(featureModel.getNamespace() + \".uvl\");\nFiles.write(filePath, uvlModel.getBytes());\n``` \n\n## Links\nUVL models:\n* https://github.com/Universal-Variability-Language/uvl-models\n\nOther parsers:\n* https://github.com/Universal-Variability-Language/uvl-parser *deprecated, Initial UVL Parser, based on Clojure and instaparse* **UVL-Parser**\n* https://github.com/diverso-lab/uvl-diverso/ *Under development, Antlr4 Parser* **Diverso Lab**\n\nUsage of UVL:\n* https://github.com/FeatureIDE/FeatureIDE *Feature modelling tool* \n\n\n",
"bugtrack_url": null,
"license": "GNU General Public License v3 (GPLv3)",
"summary": "This module provides a get_tree function to obtain an ANTLR parse-tree from a UVL-defined feature model",
"version": "2.0.1",
"project_urls": {
"Homepage": "https://github.com/Universal-Variability-Language/uvl-parser"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9e1278edbc93542f2381ace831d87e178d6303a5ca757feec32e4f79a2c98a67",
"md5": "4105f8df795d384826ce9975170513e7",
"sha256": "6d26f67279c5b2610ee2fe2079ece42d8f4ed1448dc993704c0a04f8a282aec2"
},
"downloads": -1,
"filename": "uvlparser-2.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4105f8df795d384826ce9975170513e7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 27487,
"upload_time": "2023-10-17T16:54:48",
"upload_time_iso_8601": "2023-10-17T16:54:48.479092Z",
"url": "https://files.pythonhosted.org/packages/9e/12/78edbc93542f2381ace831d87e178d6303a5ca757feec32e4f79a2c98a67/uvlparser-2.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "421db2b44500ac17098e74dbe202af6e4d9b0f08c1abe1659406ae40ecbb5087",
"md5": "f073acd43a0f683f1b7730ce77954684",
"sha256": "73fb283ff10fae599cbc2d8a8e192ec789cc91a0d1c384757459e327ca682109"
},
"downloads": -1,
"filename": "uvlparser-2.0.1.tar.gz",
"has_sig": false,
"md5_digest": "f073acd43a0f683f1b7730ce77954684",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 28831,
"upload_time": "2023-10-17T16:54:50",
"upload_time_iso_8601": "2023-10-17T16:54:50.534464Z",
"url": "https://files.pythonhosted.org/packages/42/1d/b2b44500ac17098e74dbe202af6e4d9b0f08c1abe1659406ae40ecbb5087/uvlparser-2.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-17 16:54:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Universal-Variability-Language",
"github_project": "uvl-parser",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "uvlparser"
}
JSON
