diff --git a/.gitattributes b/.gitattributes
new file mode 100644
index 0000000000000000000000000000000000000000..071ebc630500d685a1de0c09e261e3eb476ea5f9
--- /dev/null
+++ b/.gitattributes
@@ -0,0 +1,2 @@
+pages/docs/img/2022_models/slides.pdf filter=lfs diff=lfs merge=lfs -text
+pages/docs/img/2022_models/poster.pdf filter=lfs diff=lfs merge=lfs -text
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index a33e8f0fcddb2760ec9a9e83e337ccd5035da873..ec7931d614a55e9107df68de039b151b1b0a65dd 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -27,6 +27,8 @@ build:
paths:
- "ragconnect.base/build/libs/ragconnect-*.jar"
- "ragconnect.base/src/gen"
+ - "ragconnect.tests/src/test/02-after-ragconnect"
+ - "ragconnect.tests/src/test/java-gen"
expire_in: 1 week
test:
@@ -72,12 +74,12 @@ publish-master:
ragdoc_build:
image:
name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-builder"
- entrypoint: [""]
stage: ragdoc_build
needs:
- build
script:
- JAVA_FILES=$(find ragconnect.base/src/ -name '*.java')
+ - echo $JAVA_FILES | wc -l
- /ragdoc-builder/start-builder.sh -excludeGenerated -d data/ $JAVA_FILES
artifacts:
paths:
@@ -86,7 +88,6 @@ ragdoc_build:
ragdoc_view:
image:
name: "git-st.inf.tu-dresden.de:4567/jastadd/ragdoc-view:relations"
- entrypoint: [""]
stage: ragdoc_view
needs:
- ragdoc_build
@@ -95,7 +96,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=/ragconnect/ragdoc/ /ragdoc-view/build-view.sh --output-path=$OUTPUT_DIR
artifacts:
paths:
- "pages/docs/ragdoc"
diff --git a/pages/docs/adding.md b/pages/docs/adding.md
index e06e9fc190a42dba21bec50807508c1ccf0d4bfa..ec7d67090ba46d64cb2a6c24028fce7170edc12a 100644
--- a/pages/docs/adding.md
+++ b/pages/docs/adding.md
@@ -1,6 +1,7 @@
# Adding `RagConnect` to your project
If you want to use `RagConnect`, either use the latest [pre-build version](#use-packaged-version) or clone the repository and [build it yourself](#build-from-source).
+Either way, a task for [compiling RelAst specifications](#compiling-relast-specifications) has to be specified.
## Use packaged version
@@ -25,7 +26,7 @@ configurations {
}
dependencies {
- ragconnectClasspath group: 'de.tudresden.inf.st', name: 'ragconnect', version: '0.2.3'
+ ragconnectClasspath group: 'de.tudresden.inf.st', name: 'ragconnect', version: '{{ragconnect_version()}}'
}
```
@@ -60,11 +61,11 @@ cd ragconnect
ls ragconnect.base/build/libs/
```
-This `ragconnect-<version>.jar` can then be copied to your project.
+This `ragconnect-{{ragconnect_version()}}.jar` can then be copied to your project.
Please note, that you can safely use `ragconnect.jar` as filename, because the version can always be printed using `java -jar path/to/ragconnect.jar --version`.
```bash
-cp ragconnect.base/build/libs/ragconnect-<version>.jar ../your-project/libs/ragconnect.jar
+cp ragconnect.base/build/libs/ragconnect-{{ragconnect_version()}}.jar ../your-project/libs/ragconnect.jar
cd ../your-project/
```
@@ -90,7 +91,7 @@ task ragConnect(type: JavaExec) {
You might need to add another task for [compiling relast specifications](#compiling-relast-specifications).
-# Compiling RelAst specifications
+## Compiling RelAst specifications
The task to compile `RagConnect` specifications is typically accompanied by a task to invoke the [RelAst compiler](http://relational-rags.eu/) and the [JastAdd gradle plugin](https://plugins.gradle.org/plugin/org.jastadd).
Currently, the parameter `--useJastAddNames` is **required**, and it may cause incompatibilities if not set.
diff --git a/pages/docs/compiler.md b/pages/docs/compiler.md
index e89ad8fc8169e084c97736d6447c3466f1e2bc27..130020ad63b878c254bfa8f8fc6db82e71a3414d 100644
--- a/pages/docs/compiler.md
+++ b/pages/docs/compiler.md
@@ -3,6 +3,8 @@
The compiler is JastAdd-compliant, i.e., it accepts all flags available for JastAdd, though there is no process how to chain pre-processors _yet_.
Additional options are as follows.
+## Table with available options
+
| Name | Required (Default) | Description |
|---|---|---|
| `--rootNode` | Yes | Root node in the base grammar. |
@@ -22,14 +24,14 @@ Additional options are as follows.
All files to be processed have to be passed as arguments.
Their type is deduced by the file extension (`ast` and `relast` for input grammars, `connect` and `ragconnect` for RagConnect definitions file).
-# Additional software dependencies
+## Additional software dependencies
Using RagConnect itself does not introduce dependencies.
However, depending on the selected protocols and/or used features, additional dependencies are required when using the generated code.
-## Communication protocol characteristics
+### Communication protocol characteristics
-### Java
+#### Java
- Protocol identifier: `java`
- URI scheme: `java://<ignored-host>[:ignored-port]/<topic>`
@@ -39,7 +41,7 @@ However, depending on the selected protocols and/or used features, additional de
- First leading slash not included in topic.
- Currently, the default mappings are applied, which requires a consumer to expect `byte[]` (instead of a more intuitive token or node value). This might change in future versions.
-### MQTT
+#### MQTT
- Protocol identifier: `mqtt`
- URI scheme: `mqtt://<broker-host>[:port]/<topic>`
@@ -52,7 +54,7 @@ However, depending on the selected protocols and/or used features, additional de
- Mqtt is selected by default, so this dependency therefore is required "by default".
- Might work with other versions of `org.fusesource.mqtt-client.mqtt.client` as well.
-### REST
+#### REST
- Protocol identifier: `rest`
- URI scheme: `rest://localhost[:port]/<path>`
@@ -65,9 +67,9 @@ However, depending on the selected protocols and/or used features, additional de
- Might work with newer versions of `com.sparkjava.spark-core` as well.
- For debugging, it is beneficial to include an implementation for [SLF4J][slf4j].
-## Used features
+### Used features
-### Automatic dependency tracking
+#### Automatic dependency tracking
- Condition: When passing `--incremental` and `--tracing=flush` to RagConnect
- Required runtime dependencies: _none_
@@ -80,7 +82,7 @@ However, depending on the selected protocols and/or used features, additional de
- Other values besides `flush` can be added to `--tracing`
- [Feature description](using.md#dependency-tracking-automatically-derived)
-### (Safer) Automatic dependency tracking
+#### (Safer) Automatic dependency tracking
- Condition: When passing `--experimental-jastadd-329` to RagConnect
- Required runtime dependencies: _none_
@@ -90,7 +92,7 @@ However, depending on the selected protocols and/or used features, additional de
- JastAdd version has to support `INC_FLUSH_START` and `INC_FLUSH_END` (i.e., has [issue #329][jastadd-issue-329] resolved)
- [Feature description](using.md#dependency-tracking-automatically-derived)
-### Tree/List Ports
+#### Tree/List Ports
- Condition: When using ports along with default mappings for subtrees
- Required runtime dependencies:
@@ -102,7 +104,7 @@ However, depending on the selected protocols and/or used features, additional de
- Remarks:
- [Feature description](using.md#an-advanced-example)
-### Logging Target SLF4J
+#### Logging Target SLF4J
- Condition: When passing `--logTarget=slf4j` to RagConnect
- Required runtime dependencies:
diff --git a/pages/docs/img/2022_acsos/architecture.png b/pages/docs/img/2022_acsos/architecture.png
new file mode 100644
index 0000000000000000000000000000000000000000..dec5fddc467ee34a0df7645ea5a056f31441c61e
Binary files /dev/null and b/pages/docs/img/2022_acsos/architecture.png differ
diff --git a/pages/docs/img/2022_models/poster.pdf b/pages/docs/img/2022_models/poster.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..337666ceb491e1a1a0b1999a2342f77509416535
--- /dev/null
+++ b/pages/docs/img/2022_models/poster.pdf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:227796a5a16324465dab6c2cdf082e02f9b17c7fc3b97b7f1f1e05a8e5b38aa5
+size 5178029
diff --git a/pages/docs/img/2022_models/slides.pdf b/pages/docs/img/2022_models/slides.pdf
new file mode 100644
index 0000000000000000000000000000000000000000..9df4a199dd964ce5e4825dceb320bbf555ef9606
--- /dev/null
+++ b/pages/docs/img/2022_models/slides.pdf
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:b257454ed44ae2b94b5373275984a77ca2ca9cf8e5829bc5a1f82d5f93fce18a
+size 6713501
diff --git a/pages/docs/img/ST-black.png b/pages/docs/img/ST-black.png
new file mode 100644
index 0000000000000000000000000000000000000000..1dff814753e73b1d10ddd456817e6d72ee7b82e2
Binary files /dev/null and b/pages/docs/img/ST-black.png differ
diff --git a/pages/docs/inner-workings.md b/pages/docs/inner-workings.md
index c3f88279d126ec6f4f878621c6eb0f0650061225..93103a23ed1e125700aad1eec61a9ec6f7f16037 100644
--- a/pages/docs/inner-workings.md
+++ b/pages/docs/inner-workings.md
@@ -20,11 +20,11 @@ The other main aspect (which is currently not really used) is `IntermediateToYAM
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.
-# Implementation Details
+## Implementation Details
In the following, details for special implementation topics are discussed.
-## Forwarding
+### Forwarding
When a nonterminal is used in a send ports, it needs an implicit forwarding attribute to work, because only _computed elements_ can be sent.
Since the nonterminal itself should be sent, the generated attribute simply returns this nonterminal.
@@ -34,9 +34,9 @@ This way, the dependency tracking registers a dependency between structure and t
The attribute (as well as any other generated element) is prefixed with `_ragconnect_` to avoid potential name conflicts with user-specified elements.
-# Implementation Hints
+## Implementation Hints
-## Debugging Tests and Finding Bugs
+### Debugging Tests and Finding Bugs
To help with finding errors/bugs when tests fail, there are several things to find the correct spot.
diff --git a/pages/docs/use_cases.md b/pages/docs/use_cases.md
index 56c5af23a33a6aded02584dd4d1b37828dfdac4d..7e79e8839493ba3b4a54f9242de2bcbd224aebbf 100644
--- a/pages/docs/use_cases.md
+++ b/pages/docs/use_cases.md
@@ -1,5 +1,27 @@
# Use cases with `RagConnect`
+## MODELS Paper (2022) - Codename 'Ros3Rag'
+
+In the paper [*"Incremental Causal Connection for Self-Adaptive Systems Based on Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3550355.3552460), a [previous use case](#mpm4cps-paper-2020-codename-ros2rag) was extended to Collaborative, Teaching-Based Robotic Cells.
+
+
+
+This paper was presented on October, 26th 2022 in the technical track of the [MODELS 2022 conference](https://conf.researchr.org/home/models-2022) (Oct 23 - Oct 29).
+There is an [artifact hosted at Zenodo](https://doi.org/10.5281/zenodo.7009758) containing all source code and the executable case study.
+For more information, see the [presented slides](img/2022_models/slides.pdf) or the accompanied [poster](img/2022_models/poster.pdf).
+
+The repository with the used source code can be found at: <https://git-st.inf.tu-dresden.de/ceti/ros/models2022>
+
+## ACSOS Paper (2022) - Codename 'Motion Grammar Demo'
+
+In the paper [*"Specifying Reactive Robotic Applications
+With Reference Attribute Motion Grammars"*](http://mg.relational-rags.eu), motion grammars (an older approach by [Dantham and Stilman](https://doi.org/10.1109/TRO.2013.2239553)) were implemented using Relational RAGs.
+
+
+
+This paper was presented on September, 21st 2022 during the [Posters and Demos session](https://2022.acsos.org/track/acsos-2022-posters-and-demos) of the [ACSOS 2022 conference](https://2022.acsos.org/).
+For more information, see <http://mg.relational-rags.eu/>.
+
## MPM4CPS Paper (2020) - Codename 'Ros2Rag'
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 connected to it was shown.
@@ -28,22 +50,3 @@ docker-compose up rag_app
# Terminal 3: Goal-Model
docker-compose up rag_goal
```
-
-## ACSOS Paper (2022) - Codename 'Motion Grammar Demo'
-
-In the paper [*"Specifying Reactive Robotic Applications
-With Reference Attribute Motion Grammars"*](http://mg.relational-rags.eu), motion grammars (an older approach by [Dantham and Stilman](https://doi.org/10.1109/TRO.2013.2239553)) were implemented using Relational RAGs.
-This paper will be presented on September, 21st 2022 during the [Posters and Demos session](https://2022.acsos.org/track/acsos-2022-posters-and-demos) of the [ACSOS 2022 conference](https://2022.acsos.org/).
-For more information, see <http://mg.relational-rags.eu/>.
-
-## MODELS Paper (2022) - Codename 'Ros3Rag'
-
-In the paper [*"Incremental Causal Connection for Self-Adaptive Systems Based on Relational Reference Attribute Grammars"*](https://doi.org/10.1145/3550355.3552460), a [previous use case](#mpm4cps-paper-codename-ros2rag) was extended to Collaborative, Teaching-Based Robotic Cells.
-
-
-
-This paper will be presented in the technical track of the [MODELS 2022 conference](https://conf.researchr.org/home/models-2022) (Oct 23 - Oct 29).
-There is an [artifact hosted at Zenodo](https://doi.org/10.5281/zenodo.7009758) containing all source code and the executable case study.
-Furthermore, the presentation slides and a poster will be available soon.
-
-The repository with the used source code can be found at: <https://git-st.inf.tu-dresden.de/ceti/ros/models2022>
diff --git a/pages/docs/using.md b/pages/docs/using.md
index e9705465ab851344f0abda19acd75e1cad334cb4..cc159984d25dc975f4688ebd4e1efe995f5075b3 100644
--- a/pages/docs/using.md
+++ b/pages/docs/using.md
@@ -127,11 +127,11 @@ Round maps float f to int {:
... connecting first could mean to store the first rounded value and not propagating this update, since no dependencies are set, and not propagating further updates leading to the same rounded value even after setting the dependencies.
-# An advanced example
+## An advanced example
Non-terminal children can also be selected as ports (not only tokens).
-## Normal Non-Terminal Children
+### Normal Non-Terminal Children
Receiving normal non-terminal children and optionals means to replace them with a new node deserialized from the received message.
Sending them involves serializing a node, and sending this representation in a message.
@@ -158,7 +158,7 @@ To process non-terminals, default mappings are provided for every non-terminal t
They use the JSON serialization offered by the RelAST compiler, i.e., interpret the message as a `String`, deserialize the content reading the message as JSON, or vice versa.
Additional dependencies are required to use this feature, as detailed in [the compiler section](compiler.md#treelist-ports).
-## Receiving List Children
+### Receiving List Children
When receiving list children, there are a few more options to match the connection to given requirements.
@@ -171,7 +171,7 @@ ReceiverRoot ::= A* ;
Several options are possible (please also refer to the specification of the [connect DSL](dsl.md):
-### (empty)
+#### (empty)
A message for a list port can be interpreted as a complete list (a sequence of nodes of type `A`) by not specifying any special keyword:
@@ -179,7 +179,7 @@ A message for a list port can be interpreted as a complete list (a sequence of n
receive ReceiverRoot.A ;
```
-### with add
+#### with add
Upon receiving the message, the deserialized list can also be appended to the existing list instead of replace the latter.
This can be achieved using the keyword `with add` :
@@ -188,7 +188,7 @@ This can be achieved using the keyword `with add` :
receive with add ReceiverRoot.Alfa ;
```
-### indexed
+#### indexed
A message for a list port can also be interpreted as an element of this list.
@@ -203,7 +203,7 @@ The list must have enough elements once a message is received.
receiverRoot.connectA("<some-url>", 1);
```
-### indexed (wildcard)
+#### indexed (wildcard)
Similar to the `indexed` case above, messages are interpreted as an element of the list, but the connection can also be made using a "wildcard topic" and without an index.
Then, once a message is received from a new concrete topic, the deserialized element will be appended to the list and this topic is associated with the index of the newly added element.
@@ -223,7 +223,7 @@ assertEquals(receiverRoot.getAList(), list("1", "other"));
assertEquals(receiverRoot.getAList(), list("new", "other"));
```
-### indexed + with add
+#### indexed + with add
Combining `indexed` and `with add` results in a connection, where messages are interpreted as elements of the list, and new elements are appended to the existing list.
In that case, wildcard and non-wildcard connections behave in the same way, as no index has to be passed, and the element is always append at the end.
@@ -245,7 +245,7 @@ assertEquals(receiverRoot.getAList(), list("1", "other"));
assertEquals(receiverRoot.getAList(), list("1", "other", "new"));
```
-## Using attributes as port targets
+### Using attributes as port targets
As described in the [DSL specification](dsl.md), attributes can be used as port targets.
They can only be used in send ports, and the return type of the attribute must be specified in the connect specification (because aspect files are not handled completely yet).
diff --git a/pages/mkdocs.yml b/pages/mkdocs.yml
index 8ff01eda0839ea0231b98a152a2820a50bef92c1..15c561496d48591b4d5b66049646633b142fe3ef 100644
--- a/pages/mkdocs.yml
+++ b/pages/mkdocs.yml
@@ -15,12 +15,26 @@ nav:
- "API documentation": ragdoc/index.html
theme:
- name: readthedocs
- custom_dir: custom_theme/
+ name: material
+ font: false
+ palette:
+ # Palette toggle for light mode
+ - scheme: default
+ toggle:
+ icon: material/brightness-7
+ name: Switch to dark mode
+ # Palette toggle for dark mode
+ - scheme: slate
+ toggle:
+ icon: material/brightness-4
+ name: Switch to light mode
+ favicon: img/ST-black.png
+ icon:
+ logo: material/connection
markdown_extensions:
- toc:
- permalink:
+ permalink: true
- admonition
plugins:
diff --git a/pages/requirements.txt b/pages/requirements.txt
index 15f2ba17edb0e5afa8886d4a3cc191baf4f89248..25d7d3180e71c0bcdc15dc8bf7d53d08dec06173 100644
--- a/pages/requirements.txt
+++ b/pages/requirements.txt
@@ -1,6 +1,7 @@
-mkdocs==1.2.2
-mkdocs-git-revision-date-localized-plugin==0.10.3
-mkdocs-macros-plugin==0.6.3
-mike==1.1.2
-Jinja2==2.11.2
-MarkupSafe==1.1.1
+mkdocs==1.4.2
+mkdocs-git-revision-date-localized-plugin==1.1.0
+mkdocs-macros-plugin==0.7.0
+mkdocs-material==8.5.10
+mkdocs-material-extensions==1.1
+Jinja2==3.1.2
+MarkupSafe==2.1.1
diff --git a/ragconnect.base/build.gradle b/ragconnect.base/build.gradle
index b00a4301c412901a14dd13199829a2ad7904eab1..7eceb8458788b01ba26a88116a2bf8e3a048eb56 100644
--- a/ragconnect.base/build.gradle
+++ b/ragconnect.base/build.gradle
@@ -249,7 +249,7 @@ task newVersion() {
task setDevVersionForCI() {
doFirst {
def props = new Properties()
- props['version'] = version + "-$System.env.CI_PIPELINE_IID"
+ props['version'] = version + "-dev-$System.env.CI_PIPELINE_IID"
props.store(file(versionFile).newWriter(), null)
}
}
diff --git a/ragconnect.base/src/main/resources/ragconnectVersion.properties b/ragconnect.base/src/main/resources/ragconnectVersion.properties
index 08b12cf3b90afcc13f9ba32d5b42877333390019..457710a4dad0e1834e7ac15eca127843ae48ee12 100644
--- a/ragconnect.base/src/main/resources/ragconnectVersion.properties
+++ b/ragconnect.base/src/main/resources/ragconnectVersion.properties
@@ -1,2 +1,2 @@
-#Tue Sep 06 12:31:39 CEST 2022
-version=1.0.0
+#Tue Nov 22 14:21:26 CET 2022
+version=1.0.1