From fbab9af83ffaee0a553e67e3192a99dfdff98fd5 Mon Sep 17 00:00:00 2001 From: Miriam Gaus Date: Sun, 8 Jun 2025 11:44:20 +0200 Subject: [PATCH] docs: add explantions about the aggreate functions --- README.md | 53 ++++++++++++++++++++++++++++++++--------------------- 1 file changed, 32 insertions(+), 21 deletions(-) diff --git a/README.md b/README.md index 9f2a5ed..d1bf85f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,5 @@ # 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. @@ -9,16 +10,21 @@ The grammar in EBNF form is located in `uvl/UVL.g4` and the modifications for Ja 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. + 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 + 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` + 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). + 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 sum and avg functions compute the total or average of a numeric attribute across all instances, optionally limited to a specified feature subtree, using the syntax e.g. + ``` + constraints + sum(att, rootFeature). + ``` 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). @@ -50,18 +56,20 @@ constraints ``` 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` + +- 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 ``` @@ -69,9 +77,10 @@ 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) +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/java-fm-metamodel/blob/main/src/main/java/de/vill/main/Example.java) ```Java // Read @@ -85,17 +94,19 @@ FeatureModel featureModel = uvlModelFactory.parse(content); 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 + +- 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* +- 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_