BREAKING CHANGE: Adopt new structure for proper grammar generation (#60)

* Reworked the parser generation

* Use an UTF-8 maven build

* Working python grammar

* JS grammar generation is now working

* Minor changes to the README

* fix: remove tests which are not necessary here

* docs: change some guidance on the uvl-models

* Updated Java to 21

* Fixed arithmatic expression bug

* New npm command for the grammar generation

* Removed unnecessary exports

* Restored comments in UVLJavaLexer"

* Fixed wrong symbols in the grammar

* fix: Closes #41, wrong pointer to same charakter

---------

Co-authored-by: Miriam Gaus <ugwan@student.kit.edu>

Author: gravemalte

.gitignore

@@ -1,7 +1,21 @@
-# User-specific stuff
+# VSCode, Eclipse, and IntelliJ IDEA project files
 .vscode
+.settings
+.classpath
+.project
+.idea
+
+# Python virtual environments
 env
+build
 python/uvl/__pycache__
-uvl/.antlr
+python/uvl/*
+!python/uvl/UVLCustomLexer.py
+
+# Node.js
 js/node_modules
-js/package-lock.json
+js/package-lock.json
+
+# Java build files
+.antlr/
+target/

Makefile

@@ -1,33 +1,44 @@
+.PHONY: all java_parser python_parser js_parser python_prepare_package clean test dev
+
 all: java_parser python_parser js_parser
 
+LIB_FLAG = -lib
+LIB_PATH = uvl
+
+ROOT_DIR = $(shell pwd)
+PYTHON_OUTPUT_DIR = python/uvl
+JAVASCRIPT_OUTPUT_DIR = js/src/lib
+
 java_parser:
-	antlr4 -Dlanguage=Java -o java/src/main/ uvl/UVLJava.g4
-	cd java && mvn compile
+	cd java && mvn package
 	cd java && mvn install
 
+js_parser:
+	mkdir -p $(JAVASCRIPT_OUTPUT_DIR)
+	cd uvl/JavaScript && \
+		antlr4 $(LIB_FLAG) $(ROOT_DIR)/$(LIB_PATH) -Dlanguage=JavaScript -o $(ROOT_DIR)/$(JAVASCRIPT_OUTPUT_DIR) UVLJavaScriptLexer.g4 UVLJavaScriptParser.g4	
+
 python_parser:
-	antlr4 -Dlanguage=Python3 -o python uvl/UVLPython.g4
-	cp README.md python
-	cd python && python setup.py build
+	cd uvl/Python && \
+		antlr4 $(LIB_FLAG) $(ROOT_DIR)/$(LIB_PATH) -Dlanguage=Python3 -o $(ROOT_DIR)/$(PYTHON_OUTPUT_DIR) UVLPythonLexer.g4 UVLPythonParser.g4
 
-js_parser:
-	mkdir -p js/src/lib
-	antlr4 -Dlanguage=JavaScript -o js/src/lib/ uvl/UVLJavaScript.g4
-	
 python_prepare_package:
 	cd python && python3 -m build
 
 clean:
-	# Remove generated Java files except CustomLexer.java and Main.java
-	find java/src/ -type f ! -name 'UVLCustomLexer.java' ! -name 'Main.java' -delete
+	# Clean Java build artifacts
+	cd java && mvn clean
+	
 	# Remove generated Python files except custom_lexer.py and main.py
 	find python/uvl/ -type f ! -name 'UVLCustomLexer.py' ! -name 'main.py' -delete
 	# Remove compiled Python files
 	find . -name "*.pyc" -exec rm {} \;
 	# Remove Python build artifacts
 	rm -rf python/build python/dist
-	# Clean Java build artifacts
-	cd java && mvn clean
+
+	# Clean JavaScript generated files
+	rm -rf js/src/lib
+
 
 test:
 	python3 ./python/main.py ./tests/parsing/boolean.uvl

README.md

@@ -1,112 +1,186 @@
 # 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 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.
+**UVL (Universal Variability Language)** is a concise and extensible language for modeling variability in software product lines. It supports multiple programming languages and provides a grammar-based foundation for building tools and parsers.
+
+This repository contains the **ANTLR4 grammar files** for UVL. With these, you can generate parsers for UVL tailored to specific programming languages like Java, JavaScript, and Python.
+
+## ✨ Key Features
+
+- Language-level modularity
+- Namespaces and imports
+- Feature trees with attributes and cardinalities
+- Cross-tree constraints
+- Extensible for different target languages
+
+## 📦 Repository Structure
+
+- `uvl/UVLParser.g4` – Base grammar in EBNF form
+- `uvl/UVLLexer.g4` – Base lexer grammar for UVL
+- `uvl/Java/UVLJava*.g4`, `uvl/Python/UVLPython*.g4`, etc. – Language-specific grammar files
+- `java/` – Java-based parser implementation using Maven (generated)
+- `python/` – Python-based parser implementation (generated)
+- `js/` – JavaScript-based parser implementation (generated)
+
+UVL uses [ANTLR4](https://www.antlr.org/) as its parser generator.
+
+## Usage
+
+To use UVL in your projects, you can either:
+
+1. **Use the pre-built parsers**
+   ### Java Parser
+   Include the following dependency in your Maven project:
+   ```xml
+   <dependency>
+       <groupId>io.github.universal-variability-language</groupId>
+       <artifactId>uvl-parser</artifactId>
+       <version>0.3</version>
+   </dependency>
+   ```
+   ### Python Parser
+   Install the package via pip:
+   ```bash
+   pip install uvlparser
    ```
-    constraints
-      sum(att, rootFeature).
+   ### JavaScript Parser
+   Install the package via npm:
+   ```bash
+   npm install uvl-parser
    ```
+2. **Build the parser manually** See the sections below for details.
 
-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).
+## ⚙️ Building the Parser manually
 
+### Java Parser
+
+#### Prerequisites
+
+- Java 17+
+- [Maven](https://maven.apache.org/)
+
+#### Build Steps
+
+1. Clone the repository:
+
+```bash
+ git clone https://github.com/Universal-Variability-Language/uvl-parser
 ```
-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
+
+2. Build the parser:
+
+```bash
+make java_parser
+```
+
+This will generate the jar file in the `java/target/` directory. You can also build the JAR with:
+
+```bash
+cd java && mvn clean package
 ```
 
-In this snippet, we can recognize the following elements:
+3. Include the generated JAR in your Java project.
 
-- 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
+### Python Parser
 
-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:
+#### Prerequisites
 
+- Python 3.8+
+- [ANTLR4](https://www.antlr.org/)
+
+#### Build Steps
+
+1. Clone the repository:
+
+```bash
+ git clone https://github.com/Universal-Variability-Language/uvl-parser
+```
+
+2. Build the parser:
+
+```bash
+  make python_parser
 ```
-mvn clean compile assembly:single
+
+This will generate the parser files in the `python/` directory. To build the wheel package, run:
+
+```bash
+  make python_prepare_package
 ```
 
-The `target/uvl-parser-1.0-SNAPSHOT-jar-with-dependencies.jar` includes all dependencies.
+### JavaScript Parser
 
-## Usage from Java
+#### Prerequisites
 
-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/java-fm-metamodel/blob/main/src/main/java/de/vill/main/Example.java)
+- Node.js 14+
+- [ANTLR4](https://www.antlr.org/)
 
-```Java
-// Read
-Path filePath = Paths.get(pathAsString);
-String content = new String(Files.readAllBytes(filePath));
-UVLModelFactory uvlModelFactory = new UVLModelFactory();
-FeatureModel featureModel = uvlModelFactory.parse(content);
+#### Build Steps
 
+1. Clone the repository:
 
-// Write
-String uvlModel = featureModel.toString();
-Path filePath = Paths.get(featureModel.getNamespace() + ".uvl");
-Files.write(filePath, uvlModel.getBytes());
+```bash
+ git clone https://github.com/Universal-Variability-Language/uvl-parser
 ```
 
-## Links
+2. Build the parser:
 
-UVL models:
+```bash
+make javascript_parser
+```
 
-- https://github.com/Universal-Variability-Language/uvl-models
+## This will generate the parser files in the `js/` directory.
 
-Other parsers:
+## 💡 Universal-Variability-Language (UVL)
+
+For comprehensive guidance on utilizing UVL, please refer to the following publication:
+
+[![DOI](https://img.shields.io/badge/DOI-10.1016%2Fj.jss.2024.112326-blue)](https://doi.org/10.1016/j.jss.2024.112326)
+
+🔗 **Sample UVL models** are available at: https://github.com/Universal-Variability-Language/uvl-models
+
+---
+
+## 📚 Resources
+
+**UVL Models & Tools**
+
+- https://github.com/Universal-Variability-Language/uvl-models
+- https://www.uvlhub.io/
+
+**Tooling Ecosystem**
+
+- https://github.com/FeatureIDE/FeatureIDE
+- https://ide.flamapy.org/
+- https://github.com/Universal-Variability-Language/uvl-lsp
+- https://github.com/SECPS/TraVarT
+- https://github.com/AlexCortinas/spl-js-engine
+
+---
+
+## 📖 Citation
+
+If you use UVL in your research, please cite:
+
+```bibtex
+@article{UVL2024,
+  title     = {UVL: Feature modelling with the Universal Variability Language},
+  journal   = {Journal of Systems and Software},
+  volume    = {225},
+  pages     = {112326},
+  year      = {2025},
+  issn      = {0164-1212},
+  doi       = {https://doi.org/10.1016/j.jss.2024.112326},
+  url       = {https://www.sciencedirect.com/science/article/pii/S0164121224003704},
+  author    = {David Benavides and Chico Sundermann and Kevin Feichtinger and José A. Galindo and Rick Rabiser and Thomas Thüm},
+  keywords  = {Feature model, Software product lines, Variability}
+}
+```
 
-- 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:
+## 📬 Contact & Contributions
 
-- https://github.com/FeatureIDE/FeatureIDE _Feature modelling tool_
+Feel free to open issues or pull requests if you have suggestions or improvements. For questions or collaboration inquiries, visit the UVL Website:
+https://universal-variability-language.github.io/