0.2.6

- use new ragdoc images
- add documentation for using
- add javadoc in Grammar2UmlProcessor

.gitlab-ci.yml

@@ -32,8 +32,8 @@ stages:
   script:
     - "./gradlew setDevVersionForCI"
     - "./gradlew publish"
-  except:
-    - main
+  only:
+    - dev
 
 .publish_main:
   stage: publish
@@ -78,12 +78,12 @@ publish_main11:
 ragdoc_build:
   image:
     name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder"
-    entrypoint: [""]
   stage: ragdoc
   needs:
     - test11
   script:
     - JAVA_FILES=$(find grammar2uml/src/ -name '*.java')
+    - echo $JAVA_FILES | wc -l
     - /ragdoc-builder/start-builder.sh -excludeGenerated -d data/ $JAVA_FILES
   only:
     - dev
@@ -95,7 +95,6 @@ ragdoc_build:
 ragdoc_view:
   image:
     name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations"
-    entrypoint: [""]
   stage: ragdoc
   needs:
     - ragdoc_build
@@ -104,7 +103,7 @@ ragdoc_view:
     - mkdir -p pages/docs/ragdoc
     - OUTPUT_DIR=$(pwd -P)/pages/docs/ragdoc
     - cd /ragdoc-view/src/ && rm -rf data && ln -s $DATA_DIR
-    - /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
+    - BASE_HREF=/grammar2uml/ragdoc/ /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
   only:
     - dev
     - main
@@ -126,4 +125,5 @@ pages:
     paths:
       - public/
   only:
+    - dev
     - main

grammar2uml/src/main/java/de/tudresden/inf/st/jastadd/grammar2uml/compiler/Grammar2UmlProcessor.java

@@ -36,31 +36,69 @@ public class Grammar2UmlProcessor {
     return this;
   }
 
+  /**
+   * Write debugging information while reading in grammar files.
+   * @param value whether to write debugging information
+   * @return this
+   */
   public Grammar2UmlProcessor setVerbose(boolean value) {
     this.verbose = value;
     return this;
   }
 
+  /**
+   * Add folders to the representation. The folder needs to be initialized.
+   * @param folders initialized folders to be added
+   * @return this
+   */
   public Grammar2UmlProcessor addFolder(Folder... folders) {
     Collections.addAll(this.folders, folders);
     return this;
   }
 
+  /**
+   * Configure to use one folder per given grammar file.
+   * @param value whether to use default folders
+   * @return this
+   */
   public Grammar2UmlProcessor setUseDefaultFolders(boolean value) {
     useDefaultFolders = value;
     return this;
   }
 
+  /**
+   * Add a callback to run after the complete parsed program has been parsed.
+   * @param callback a function to be run, given the processed grammar files
+   * @return this
+   */
   public Grammar2UmlProcessor addPostProcessing(Consumer<Grammar2Uml> callback) {
     this.callbacks.add(callback);
     return this;
   }
 
+  /**
+   * Sets the new definition to style the representation.
+   *
+   * This is a method that can alter the style for each {#{@link TypeDecl}}.
+   * @param definition the new style definition
+   * @return this
+   */
   public Grammar2UmlProcessor setStyleDefinition(StyleDefinition definition) {
     this.styleDefinition = definition;
     return this;
   }
 
+  /**
+   * Writes the representation to the given destination file.
+   *
+   * The file extension is used to decide the output type.
+   * Supported extensions are: md, html, png, pdf, svg.
+   *
+   * <br>
+   * <b>Note:</b> PDF requires additional dependencies, see <a href="https://plantuml.com/pdf">https://plantuml.com/pdf</a>
+   * @param destination the file to write to
+   * @throws CompilerException if generation or writing the file has failed
+   */
   public void writeFile(Path destination) throws CompilerException {
     build();
 
@@ -108,6 +146,15 @@ public class Grammar2UmlProcessor {
     }
   }
 
+  /**
+   * Create separate diagrams for each grammar file.
+   *
+   * Types from other grammar files are depicted using boxes with dashed borders.
+   * @param destinationDirectory a directory where all files shall be written to
+   * @param extension the file extension to be used for all diagrams
+   * @throws CompilerException if generation or writing the file has failed
+   * @see #writeFile(Path) method writeFile for supported file extensions
+   */
   public void generateSeparateGrammarDiagrams(Path destinationDirectory, String extension) throws CompilerException {
     build();
 
@@ -197,11 +244,11 @@ public class Grammar2UmlProcessor {
     }
 
     grammar2uml.setStyleDefinition(styleDefinition);
-    callbacks.forEach(consumer -> consumer.accept(grammar2uml));
-
     grammar2uml.setProgram(program);
     grammar2uml.treeResolveAll();
 
+    callbacks.forEach(consumer -> consumer.accept(grammar2uml));
+
     if (!grammar2uml.errors().isEmpty()) {
       System.err.println("Errors:");
       for (ErrorMessage e : grammar2uml.errors()) {

grammar2uml/src/main/resources/grammar2umlVersion.properties

-#Fri Aug 26 14:06:56 CEST 2022
-version=0.2.5
+#Fri Sep 30 14:31:26 CEST 2022
+version=0.2.6

pages/docs/adding.md

-# Add grammar2uml to your project
+# Add Grammar2uml to your project
 
-To use `Grammar2uml`, adjust your `build.gradle` as follows.
+There are two ways, how to use Grammar2uml: As a Gradle task, or programmatically.
+The latter offers more ways for configuration.
 
-Set up the maven package source as repository:
+For both, the repository has to added within `build.gradle`:
 
 ```gradle
 repositories {
@@ -14,7 +15,11 @@ repositories {
 }
 ```
 
-Add `Grammar2uml` as a dependency:
+## Usage as Gradle task
+
+To use `Grammar2uml` via Gradle task, adjust your `build.gradle` as follows.
+
+Add `Grammar2uml` as a dependency via a configuration:
 
 ```
 configurations {
@@ -22,11 +27,11 @@ configurations {
 }
 
 dependencies {
-    grammar2uml group: 'de.tudresden.inf.st', name: 'grammar2uml', version: '0.2.2'
+    grammar2uml group: 'de.tudresden.inf.st', name: 'grammar2uml', version: '<VERSION>'
 }
 ```
 
-Add a task to create your visualization:
+Then, add a task to create your visualization:
 
 ```
 task grammar2uml(type: JavaExec) {
@@ -38,7 +43,7 @@ task grammar2uml(type: JavaExec) {
 }
 ```
 
-## Build from source (not recommended)
+### Build from source (not recommended)
 
 If you want to build `Grammar2Uml` from source, first build the fat-jar from the [repository](https://git-st.inf.tu-dresden.de/jastadd/grammar2uml).
 The normal jar does not suffice, as it lacks the information on needed dependencies.
@@ -65,3 +70,15 @@ dependencies {
 ```
 
 The path to the jar file may need to be changed according to your project structure.
+
+## Programmatically Usage
+
+To use `Grammar2uml` programmatically, a similar setup is needed.
+
+Add `Grammar2uml` as an implementation dependency:
+
+```
+dependencies {
+    implementation group: 'de.tudresden.inf.st', name: 'grammar2uml', version: '<VERSION>'
+}
+```

pages/docs/index.md

@@ -7,26 +7,4 @@ The tool called `Grammar2Uml` ([see in repo](https://git-st.inf.tu-dresden.de/ja
 
 Every nonterminal will be shown as a rectangular box with its terminal children listed within it. Children are shown as containment relations between parent and child, whereas relations and intrinsic references are shown using arrows.
 
-Furthermore, more options may be specified.
-
-|         Name         |                               Description                               |
-|----------------------|-------------------------------------------------------------------------|
-| `--output`           | target file to be generated (default: `uml.md` or `uml.png`, depending on `--printSource`) |
-| `--inputGrammar2Uml` | grammar2uml definition file, see [below](#grammar2uml-definition-file). |
-| `--printSource`      | If set, the output will be the source code instead of a png. (default: create a png) |
-| `--defaultFolders`   | If set, creates a default folder per grammar file. (default: use one global folder) |
-| `--help`             | Print usage and exit.                                                   |
-| `--version`          | Print version and exit.                                                 |
-| `--verbose`          | Print more messages while compiling.                                    |
-
-## Grammar2uml definition file
-
-To structure the generated visualization, any number of nonterminals can be grouped with folders.
-Either specify the option `--defaultFolders` to use one folder per input grammar file, or specify a grammar2uml definition file.
-The definition file has a simple syntax, it is a list of folder specifications. One specifications looks like
-
-```
-folder FOLDER_NAME : NT1, NT2, ..., NT_n
-```
-
-It produces one folder named `FOLDER_NAME` containing all nonterminals (`NT1`, `NT2`, ..., `NT_n`) following it.
+Furthermore, more options may be specified, as described in ["Usage as Gradle task"](using.md#usage-as-gradle-task).

pages/docs/using.md

+# Using grammar2uml
+
+There are two ways, how to use Grammar2uml: As a Gradle task, or programmatically.
+The latter offers more ways for configuration.
+
+## Usage as Gradle task
+
+When starting the Gradle task, the following parameters can be provided:
+
+| Name                 | Description                                                                                |
+|----------------------|--------------------------------------------------------------------------------------------|
+| `--output`           | target file to be generated (default: `uml.md` or `uml.png`, depending on `--printSource`) |
+| `--inputGrammar2Uml` | grammar2uml definition file, see [below](#grammar2uml-definition-file).                    |
+| `--printSource`      | If set, the output will be the source code instead of a png. (default: create a png)       |
+| `--defaultFolders`   | If set, creates a default folder per grammar file. (default: use one global folder)        |
+| `--help`             | Print usage and exit.                                                                      |
+| `--version`          | Print version and exit.                                                                    |
+| `--verbose`          | Print more messages while compiling.                                                       |
+
+### Grammar2uml definition file
+
+To structure the generated visualization, any number of nonterminals can be grouped with folders.
+Either specify the option `--defaultFolders` to use one folder per input grammar file, or specify a grammar2uml definition file.
+The definition file has a simple syntax, it is a list of folder specifications. One specifications looks like
+
+```
+folder FOLDER_NAME : NT1, NT2, ..., NT_n
+```
+
+It produces one folder named `FOLDER_NAME` containing all nonterminals (`NT1`, `NT2`, ..., `NT_n`) following it.
+
+## Programmatically Usage
+
+After [adding Grammar2uml to your project](adding.md#programmatically-usage), you can start creating a representation of the grammar.
+Here is one example with a `Model` containing nodes of type `Robot`, `Joint` and `EndEffector` amongst others.
+It is explained in detail below.
+
+```java
+import de.tudresden.inf.st.jastadd.grammar2uml.compiler.Grammar2UmlProcessor;
+import org.jastadd.relast.compiler.CompilerException;
+
+public class Main {
+  public static void main(String[] args) throws CompilerException {
+    Grammar2UmlProcessor processor = new Grammar2UmlProcessor();  // (1)
+    processor
+        .addGrammar("src/main/jastadd/Model.relast",
+            "src/gen/jastadd-sources/common/shared.relast")  // (2)
+        .setVerbose(true)  // (3)
+        .setStyleDefinition((typeDecl, style) -> {  // (4)
+          switch (typeDecl.getName()) {
+            case "Robot":
+            case "Joint":
+              style.setInlineAsSuperType(true);  // (4.1)
+              break;
+            case "EndEffector":
+              style.setBackgroundColor("blue\\9932CC");  // (4.2)
+          }
+        })
+        .setUseDefaultFolders(true);  // (5)
+    processor.writeFile(Paths.get("api.md"));  // (6)
+    processor.writeFile(Paths.get("api.png"));  // (6)
+
+    processor.generateSeparateGrammarDiagrams(Paths.get("."), "png");  // (7)
+  }
+}
+```
+
+Grammar2uml uses the [Builder design pattern](https://en.wikipedia.org/wiki/Builder_pattern) as well as a [fluent API](https://en.wikipedia.org/wiki/Fluent_interface).
+That means, first, all settings are specified (2-5), and only after a "dump"-method is called (6,7) the actual representation is created.
+
+The steps in detail:
+
+- (1) In the beginning, a new `Grammar2UmlProcessor` is created. This is uses the same internals as the [Gradle task](#usage-as-gradle-task).
+- (2) Using this processor, the grammar files, that shall be included in the representation have to be specified. Currently, all types used in production rules have to be defined, i.e., the total grammar has to be complete. Otherwise, an error is raised.
+- (3) [Optional] To output information helpful for debugging problems, verbose processing can be turned on.
+- (4) [Optional] There is one entry point for styling types in the representation.
+    - (4.1) One possibility is to replace the normal inheritance relation with an inline notation (no conformance with UML) to reduce the number of arrows for inheritance. If a type `SubA` inherits from `A` and for the type `A`, this option is activated, then the former is represented using the label `SubA : A`.
+    - (4.2) The background color of the type box can be defined using `setBackgroundColor`.
+- (5) [Optional] If multiple grammar files have been passed in step (2), then there is the option to create a folder for each file containing all types defined in it. This way, types are better grouped by their defining grammar file.
+- (6) To create a representation containing all types, the method `writeFile` is used. It deduces the type of output from the file extension.
+- (7) It is also possible to create separate grammar diagrams, i.e., one for each grammar file with other used types depicted as boxes with dashed borders.
+
+To summarise the required steps: Create a processor, specify grammar files, configure the representation, and write the output.
+For more configuration options, please consult the [API Docs of Grammar2UmlProcessor](../ragdoc/#/type/Grammar2UmlProcessor).

pages/mkdocs.yml

@@ -5,6 +5,7 @@ site_dir: ../public
 nav:
   - "Grammar2uml": index.md
   - "Add to your project": adding.md
+  - "Using Grammar2uml": using.md
   - "API documentation": ragdoc/index.html
 
 theme: