From fd0dd20b97633e03b069b5860918ed3d2987c5cb Mon Sep 17 00:00:00 2001 From: rschoene <rene.schoene@tu-dresden.de> Date: Wed, 25 Nov 2020 09:57:19 +0100 Subject: [PATCH] Update pages. --- pages/adding.md | 12 ++++++------ pages/extending.md | 40 +++++++++++++++++++++------------------- pages/index.rst | 2 +- pages/inner-workings.md | 19 ++++++++++--------- pages/use_cases.md | 4 ++-- pages/using.md | 6 +++--- 6 files changed, 43 insertions(+), 40 deletions(-) diff --git a/pages/adding.md b/pages/adding.md index fa26d5f..0abf449 100644 --- a/pages/adding.md +++ b/pages/adding.md @@ -1,8 +1,9 @@ -# Adding `ragconnect` to your project +# Adding `RagConnect` to your project -If you want to use `ragconnect`, the currently suggested way is to first build the jar from this repository: +If you want to use `RagConnect`, the currently suggested way is to first build the jar from the [RagConnect repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect): ```bash +git clone https://git-st.inf.tu-dresden.de/jastadd/ragconnect.git cd ragconnect ./gradlew jar ls ragconnect.base/build/libs/ @@ -15,7 +16,7 @@ cp ragconnect.base/build/libs/ragconnect-<version>.jar ../your-project/libs/ragc cd ../your-project/ ``` -Finally, this jar has to be integrated into your build process. In case, [Gradle](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag usecase](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)). The path to the jar files may need to be changed according to your project structure. +Finally, this jar has to be integrated into your build process. In case, [Gradle](https://gradle.org/) is used, a task could look like the following (example taken from the [ros2rag usecase](https://git-st.inf.tu-dresden.de/jastadd/ros2rag)). The path to the jar file may need to be changed according to your project structure. ```groovy task ragConnect(type: JavaExec) { @@ -33,7 +34,7 @@ task ragConnect(type: JavaExec) { } ``` -This is typically accompanied with a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd). The additional arguments "--useJastAddNames", "--listClass", "--jastAddList" and "--resolverHelper" to relast are not required. Please see the user manual of the RelAst compiler for more information. +This is typically accompanied with a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd). The additional arguments `--useJastAddNames`, `--listClass`, `--jastAddList` and `--resolverHelper` to relast are not required. Please see the user manual of the RelAst compiler for more information. ```groovy task relastToJastAdd(type: JavaExec) { @@ -65,11 +66,10 @@ relastToJastAdd.dependsOn ragConnect ## Introduced dependencies -Ragconnect itself does not introduce dependencies. +RagConnect itself does not introduce dependencies. However, depending on the selected protocols (see [compiler options](/using#compiler-options)), additional dependencies are required. | Protocol | Dependency (Gradle format) | Remarks | |-|-|-| | `mqtt` | `group: 'org.fusesource.mqtt-client', name: 'mqtt-client', version: '1.15'` | Mqtt is selected by default, so this dependency therefore is required "by default". Might work with other versions as well. | | `rest` | `group: 'com.sparkjava', name: 'spark-core', version: '2.9.2'` | Might work with other versions as well. For debugging, it is beneficial to include an implementation for [SLF4J](http://www.slf4j.org/). | - diff --git a/pages/extending.md b/pages/extending.md index 6a98f72..e3f2b01 100644 --- a/pages/extending.md +++ b/pages/extending.md @@ -1,23 +1,25 @@ -# Extending `ragconnect` +# Extending `RagConnect` -To add a new communication protocol `ABC`, the following locations have to be changed: +To add a new communication protocol, the following locations have to be changed (replace `ABC` and `abc` with the name of the protocol): -- within `ragconnect.base/src/main/resources` - - add a new handler `ABCHandler`, if appropriate, similar to the existing handlers - - add a new template `abc.mustache` containing an aspect `ABC` initializing the handler (if any) similar to the existing protocols - - in `ragconnect.mustache`: add `{{#usesABC}}{{> abc}}{{/usesABC}}` and `{{#usesABC}}{{abcHandlerField}}.close();{{/usesABC}}`, respectively if appropriate - - in `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statement defining the logic to happen for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`. -- within `ragconnect.base/src/main/jastadd` - - in `backend/Configuration`: add a new static boolean flag `usesABC` to indicate whether the protocol is used - - in `backend/Generation`: - - add new attributes for type `MRagConnect` for handler-attribute and handler-field, if needed - - add attributes for newly introduced references in changed mustache templates, if any - - in `backend/MustacheNodesToYAML`: - - add key-value-pair for `usesABC` (and handler, if any) - - add key-value-pairs for newly introduced referemces in changed mustache templates, if any -- in `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java` - - add a new choice for `--protocols` similar to the existing ones - - set the flag `usesABC` if the choice is given. - - add code to add the handler to the list `handlers` if the choice is given, i.e., if `ASTNode.usesABC` +Within `ragconnect.base/src/main/resources`: +- Add a new handler `ABCHandler`, if appropriate, similar to the existing handlers + - Add a new template `abc.mustache` containing an aspect `ABC` initializing the handler (if any) similar to the existing protocols + - In `ragconnect.mustache`: add `{{#usesABC}}{{> abc}}{{/usesABC}}` and `{{#usesABC}}{{abcHandlerField}}.close();{{/usesABC}}`, respectively if appropriate +- In `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statement defining the logic to happen for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`. + +Within `ragconnect.base/src/main/jastadd`: +- In `backend/Configuration`: add a new static boolean flag `usesABC` to indicate whether the protocol is used +- In `backend/Generation`: + - Add new attributes for type `MRagConnect` for handler-attribute and handler-field, if needed + - Add attributes for newly introduced references in changed mustache templates, if any +- In `backend/MustacheNodesToYAML`: + - Add key-value-pair for `usesABC` (and handler, if any) + - Add key-value-pairs for newly introduced referemces in changed mustache templates, if any + +In `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`: +- Add a new choice for `--protocols` similar to the existing ones +- Set the flag `usesABC` if the choice is given. +- Add code to add the handler to the list `handlers` if the choice is given, i.e., if `ASTNode.usesABC` Furthermore, new test cases are appreciated. They can be added in the [ragconnect.rests repository](https://git-st.inf.tu-dresden.de/jastadd/ragconnect-tests) diff --git a/pages/index.rst b/pages/index.rst index 7e466d2..2da98fa 100644 --- a/pages/index.rst +++ b/pages/index.rst @@ -6,7 +6,7 @@ RagConnect Documentation ======================== -RagConnect is a preprocessor to enable easy connection to/from models based on `Reference Attribute Grammars <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf>`_ and `Relation Reference Attribute Grammars <https://doi.org/10.1016/j.cola.2019.100940>`_ built with `JastAdd <http://jastadd.org/>`_. +`RagConnect <https://git-st.inf.tu-dresden.de/jastadd/ragconnect>`_ is a preprocessor to enable easy connection to/from models based on `Reference Attribute Grammars <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.108.8792&rep=rep1&type=pdf>`_ and `Relation Reference Attribute Grammars <https://doi.org/10.1016/j.cola.2019.100940>`_ built with `JastAdd <http://jastadd.org/>`_. .. toctree:: :maxdepth: 2 diff --git a/pages/inner-workings.md b/pages/inner-workings.md index e10239e..9a244b9 100644 --- a/pages/inner-workings.md +++ b/pages/inner-workings.md @@ -1,12 +1,13 @@ -# Inner workings of `ragconnect` +# Inner workings of `RagConnect`  -- `ragconnect` uses the [relast-preprocessor](https://git-st.inf.tu-dresden.de/jastadd/relast-preprocessor) to parse `.relast` grammar files. This results in an ASTNode of type `Program`. -- it further uses a dedicated parser for `.connect` files containing endpoint-, mapping-, and dependency-definitions. This results in an ASTNode of type `RagConnect`. -- the goal is to generate an aspect file containing setters and getters of tokens referred to by endpoint-definitions -- we use [mustache](https://mustache.github.io/) (currently its [Java version](https://github.com/spullara/mustache.java)) making use of partials resulting in a set of `.mustache` files located in `ragconnect.base/src/main/resources` -- the generation process uses an intermediate NTA of type `MRagConnect` defined in `MustacheNodes.relast` to separate this generation concern from the content of the DSL -- there are aspect files for `Navigation` (mainly isX/asX attributes), `Analysis` (lookup attributes), `Printing`, `backend/Mappings` (default mappings) -- one of the main aspects is `backend/Generation` containing attributes to construct the `MRagConnect` NTA and all necessary attributes used within the mustache templates -- the other main aspect (which is currently not really used) is `backend/MustacheNodesToYAML.jrag` containing the transformation from a `MRagConnect` subtree to a `Document` subtree defined by `YAML.relast`. This is used to generate a YAML file containing the data used by mustache. It can be used by the default mustache implementation together with the templates. +`RagConnect` uses the [relast-preprocessor](https://git-st.inf.tu-dresden.de/jastadd/relast-preprocessor) to parse `.relast` grammar files. This results in an ASTNode of type `Program`. +It further uses a dedicated parser for `.connect` files containing endpoint-, mapping-, and dependency-definitions. This results in an ASTNode of type `RagConnect`. +The goal is to generate an aspect file containing setters and getters of tokens referred to by endpoint-definitions +We use [mustache](https://mustache.github.io/) (currently its [Java version](https://github.com/spullara/mustache.java)) making use of partials resulting in a set of `.mustache` files located in `ragconnect.base/src/main/resources`. +The generation process uses an intermediate NTA of type `MRagConnect` defined in `MustacheNodes.relast` to separate this generation concern from the content of the DSL + +There are aspect files for `Navigation` (mainly isX/asX attributes), `Analysis` (lookup attributes), `Printing`, `backend/Mappings` (default mappings) +One of the main aspects is `backend/Generation` containing attributes to construct the `MRagConnect` NTA and all necessary attributes used within the mustache templates +The other main aspect (which is currently not really used) is `backend/MustacheNodesToYAML.jrag` containing the transformation from a `MRagConnect` subtree to a `Document` subtree defined by `YAML.relast`. This is used to generate a YAML file containing the data used by mustache. It can be used by the default mustache implementation together with the templates. diff --git a/pages/use_cases.md b/pages/use_cases.md index 4aa8345..c479b65 100644 --- a/pages/use_cases.md +++ b/pages/use_cases.md @@ -1,8 +1,8 @@ -# Use cases with `ragconnect` +# Use cases with `RagConnect` ## 1⃣ MPM4CPS Paper - Codename 'Ros2Rag' -In the publication [*"Connecting conceptual models using Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3417990.3421437) (⚠ DOI still pending), a use case involving a simulated robot arm and two different models conencted to it was shown. +In the publication [*"Connecting conceptual models using Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3417990.3421437), a use case involving a simulated robot arm and two different models conencted to it was shown. One model was used to ensure a low speed of the robot when within a safety zone (purple boxes in the picture below), and the other model executes a workflow to control the robot.  diff --git a/pages/using.md b/pages/using.md index 7bd13ca..8dfe19e 100644 --- a/pages/using.md +++ b/pages/using.md @@ -1,4 +1,4 @@ -# Using `ragconnect` -- an example +# Using `RagConnect` -- an example ## Preparation @@ -119,14 +119,14 @@ Additional options are as follows. | `--version` | No (false) | Print version info and exit (reused JastAdd option) | | `--o` | No (`.`) | Output directory (reused JastAdd option) | -All files to be process have to be passed as arguments. Their type is decided by the file extension (`ast` and `relast` for input grammars, `connect` and `ragconnect` for ragconnect definitions file). +All files to be process have to be passed as arguments. Their type is decided by the file extension (`ast` and `relast` for input grammars, `connect` and `ragconnect` for RagConnect definitions file). ## Remarks When constructing the AST and connecting it, one should always set dependencies before connecting, especially if updates already arriving for receiving endpoints. Otherwise, updates might not be propagated after setting dependencies, if values are equal after applying transformations of mapping definitions. -As an example, when using the following grammar and ragconnect-definitions ... +As an example, when using the following grammar and definitions for RagConnect ... ```bnf A ::= <Input:int> /<Output:String>/ ; -- GitLab