Merge branch 'release/1.0.0' into 'master'

Version 1.0.0

See merge request !35

.gitlab-ci.yml

@@ -38,14 +38,28 @@ test:
   needs:
     - build
   script:
+    - ./gradlew --console=plain --no-daemon test
     - ./gradlew --console=plain --no-daemon allTests
   artifacts:
     when: always
+    paths:
+      - "ragconnect.tests/test.log"
     reports:
       junit: "ragconnect.tests/build/test-results/**/TEST-*.xml"
     expire_in: 1 week
 
-publish:
+publish-dev:
+  image: openjdk:11
+  stage: publish
+  needs:
+    - test
+  script:
+    - "./gradlew setDevVersionForCI"
+    - "./gradlew publish"
+  except:
+    - master
+
+publish-master:
   image: openjdk:11
   stage: publish
   needs:
@@ -53,7 +67,6 @@ publish:
   script:
     - "./gradlew publish"
   only:
-    - dev
     - master
 
 ragdoc_build:
@@ -83,23 +96,42 @@ ragdoc_view:
     - 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
-  only:
-    - dev
-    - master
   artifacts:
     paths:
       - "pages/docs/ragdoc"
 
-pages:
+build_cloc:
+  image: "alpine:latest"
+  needs:
+    - build
+  script:
+    - apk add cloc
+    - cd pages/cloc
+    - sh run-cloc.sh
+  artifacts:
+    paths:
+      - pages/docs/cloc.md
+
+.pages-template:
   image: python:3.10.0-bullseye
   stage: publish
   needs:
     - ragdoc_view
     - test
+    - build_cloc
   before_script:
     - pip install -r pages/requirements.txt
   script:
     - cd pages && mkdocs build
+
+pages-dry-run:
+  extends: .pages-template
+  except:
+    - dev
+    - master
+
+pages:
+  extends: .pages-template
   artifacts:
     paths:
       - public/
@@ -107,13 +139,7 @@ pages:
     - master
 
 pages-dev:
-  image: python:3.10.0-bullseye
-  stage: publish
-  needs:
-    - ragdoc_view
-    - test
-  before_script:
-    - pip install -r pages/requirements.txt
+  extends: .pages-template
   script:
     - cd pages && mkdocs build
     - echo "UPSTREAM_JOB_ID=$CI_JOB_ID" >> build.env

.gitmodules

-[submodule "relast-preprocessor"]
-	path = relast-preprocessor
-	url = ../relast-preprocessor.git
-	branch = develop

build.gradle

+plugins {
+    id 'com.github.ben-manes.versions' version '0.42.0'
+    id 'java'
+}
+
+java.toolchain.languageVersion.set(JavaLanguageVersion.of(11))
+
+if (JavaVersion.current().isJava8Compatible()) {
+    allprojects {
+        tasks.withType(Javadoc) {
+            options.addStringOption('Xdoclint:none', '-quiet')
+        }
+    }
+}

gradle.properties

-log4j_version = 2.14.0
-mustache_java_version = 0.9.7
+log4j_version = 2.17.2
+mustache_java_version = 0.9.10
+preprocessor_version = 0.1.0-41
+relast_version = 0.3.0-137
+dumpAst_version = 1.2.0

pages/.gitignore

 /docs/ragdoc/
+/docs/cloc.md
 __pycache__

pages/cloc/.clocignore

+run-cloc.sh

pages/cloc/.gitignore

+files.csv
+my_definitions.txt
+ragconnect.base.lang
+ragconnect.file
+ragconnect.lang
+ragconnect.base-*.md
+ragconnect.base-*.txt
+ragconnect.tests-*.md
+ragconnect.tests-*.txt
+tmp.json

pages/cloc/cloc-def-connect.txt

+Connect
+    filter call_regexp_common Java
+    extension connect
+    extension ragconnect
+    3rd_gen_scale 10

pages/cloc/cloc-def-flex.txt

+Flex
+    filter remove_matches ^\s*//
+    extension flex
+    3rd_gen_scale 1.5

pages/cloc/cloc-def-grammar.txt

+Grammar
+    filter call_regexp_common Java
+    extension ast
+    extension relast
+    3rd_gen_scale 30

pages/cloc/cloc-def-jrag-jadd.txt

+Attributes
+    filter call_regexp_common Java
+    extension jrag
+    extension jadd
+    3rd_gen_scale 1.5

pages/cloc/cloc-def-parser.txt

+Parser
+    filter remove_matches ^\s*//
+    extension parser
+    3rd_gen_scale 1.5

pages/cloc/run-cloc.sh

+#!/bin/bash
+if [ "$1" == "-h" ] || [ "$1" == "--help" ]; then
+  echo "-s -> skip running cloc commands"
+  echo "-a -> produce files.csv with code count for single src files"
+  exit
+fi
+if [ "$1" != "-s" ]; then
+  #  --force-lang=Java,jrag --force-lang=Java,jadd
+  DEF_FILE=my_definitions.txt
+  echo "Export language definitions"
+  cloc --quiet --write-lang-def="$DEF_FILE"
+  for f in cloc-def-*.txt;
+  do
+  	cat $f >> "$DEF_FILE"
+  done
+  REPO_ROOT="../.."
+  CLOC_CMD="cloc --exclude-lang=JSON --read-lang-def=my_definitions.txt --exclude-list-file=.clocignore --quiet --hide-rate"
+  #  --ignored=bad-files.txt
+  cloc_double() {
+    f=$1
+    shift
+    echo "Creating $f.txt"
+    $CLOC_CMD --report-file="$f.txt" $@
+    echo "Creating $f.md"
+    $CLOC_CMD --md --report-file=tmp.md $@
+    tail -n+3 tmp.md > "$f.md"
+    rm tmp.md
+  }
+  make_page() {
+    echo "# Evaluation Metrics: Lines of Code"
+    echo
+    echo "## Manually written generator code"
+    echo
+    cat ragconnect.base-src-result.md
+    echo
+    echo "## Generated generator code"
+    cat ragconnect.base-gen-result.md
+    echo
+    echo "## Manually written test code"
+    cat ragconnect.tests-src-result.md
+    echo
+    echo "## Generated test code"
+    cat ragconnect.tests-gen-result.md
+  }
+fi
+if [ "$1" != "-s" ] && [ "$1" != "-a" ]; then
+  echo "Running cloc with new definitions"
+  cloc_double "ragconnect.base-src-result" --found=ragconnect.base-src-found.txt ${REPO_ROOT}/ragconnect.base/src/main/
+  cloc_double "ragconnect.base-gen-result" --found=ragconnect.base-gen-found.txt ${REPO_ROOT}/ragconnect.base/src/gen/jastadd ${REPO_ROOT}/ragconnect.base/src/gen/java
+  cloc_double "ragconnect.tests-src-result" --found=ragconnect.tests-src-found.txt ${REPO_ROOT}/ragconnect.tests/src/test/01-input/ ${REPO_ROOT}/ragconnect.tests/src/test/java/
+  cloc_double "ragconnect.tests-gen-result" --found=ragconnect.tests-gen-found.txt ${REPO_ROOT}/ragconnect.tests/src/test/02-after-ragconnect/ ${REPO_ROOT}/ragconnect.tests/src/test/java-gen
+  $CLOC_CMD --sum-reports --report_file=ragconnect ragconnect.base-src-result.txt ragconnect.base-gen-result.txt ragconnect.tests-src-result.txt ragconnect.tests-gen-result.txt
+  echo "Creating ../docs/cloc.md"
+  make_page > ../docs/cloc.md
+fi
+if [ "$1" == "-a" ]; then
+  echo "filename,code" > files.csv
+  for f in $(find ${REPO_ROOT}/ragconnect.base/src/main/ ${REPO_ROOT}/ragconnect.base/src/gen/jastadd-sources/ -type f); do
+    printf '.'
+    echo $f,$($CLOC_CMD --json $f | jq '.SUM.code') >> files.csv
+  done
+  echo
+  exit
+fi
+
+
+# cat ragconnect.base-src-result.txt
+# cat ragconnect.base.file
+# cat ragconnect.tests-result.txt
+
+echo "LOC stats:"
+echo "Language                     files          blank        comment           code"
+( for t in *-result.txt ; do echo -e "==> $t <=="; grep -v -e '---' -e 'SUM' -e 'Language' -e 'github' $t; done)
+
+echo 
+echo "Summary:"
+grep -v -e '---' -e 'SUM' -e 'Language' -e 'github' ragconnect.file

pages/docs/changelog.md

 # Changelog
 
+## 1.0.0
+
+### Changes
+
+- Allow connection ports for
+  - relations ([#37](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/37))
+  - attributes ([#38](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/38)), especially collection and circular attributes ([#53](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/53))
+  - (sending) non-NTA nonterminals ([#36](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/36))
+  - context-free context ports ([#34](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/34))
+- Experimental support for Java handler ([#52](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/52))
+- Make specification language more concise ([#33](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/33))
+- Make dependency definitions deprecated ([#42](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/42)) and warn when used
+
+### Development Changes
+
+- Make grammar(s) more concise ([#40](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/40))
+- Enhance documentation, adding a DSL description
+- Refactor debug messages from System.out to SLF4J ([#46](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/46))
+
 ## 0.3.2
 
-- Allow connection endpoints for list nonterminals ([#21](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/21))
+- Allow connection ports for list nonterminals ([#21](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/21))
 - Ensure correct connect and disconnect functionality ([#31](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/31))
 - Enhance documentation ([#13](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/13), [#20](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/20), [#41](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/41))
 
 ## 0.3.1
 
 - Full support for incremental dependency tracking
-- Full support for subtree endpoint definitions ([#9](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/9))
+- Full support for subtree port definitions ([#9](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/9))
 - Internal: Use updated gradle plugin for tests ([#18](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/18))
-- Bugfix [#22](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/22): Correct handling of malformed URIs passed when connecting an endpoint
-- Bugfix [#23](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/23): Correct handling of OptComponents as endpoints
+- Bugfix [#22](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/22): Correct handling of malformed URIs passed when connecting an port
+- Bugfix [#23](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/23): Correct handling of OptComponents as ports
 - Bugfix [#27](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/27): Correctly handle whitespaces in grammars
 
 ## 0.3.0
 
 - Added [API documentation](ragdoc/index.html) to documentation
-- Add methods to `disconnect` an endpoint
-- Internal: PoC for incremental dependency tracking and subtree endpoint definitions ([#14](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/14))
+- Add methods to `disconnect` a port
+- Internal: PoC for incremental dependency tracking and subtree port definitions ([#14](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/14))
 - Bugfix [#17](https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/17): Added missing support for `boolean`
 
 ## 0.2.2

pages/docs/compiler.md

@@ -4,22 +4,23 @@ The compiler is JastAdd-compliant, i.e., it accepts all flags available for Jast
 Additional options are as follows.
 
 | Name | Required (Default) | Description |
-|-|-|-|
+|---|---|---|
 | `--rootNode` | Yes | Root node in the base grammar. |
-| `--protocols` | No (`mqtt`) | Protocols to enable, currently available: `mqtt, rest`. |
+| `--protocols` | No (`mqtt`) | Protocols to enable, currently available: `java` (experimental), `mqtt`, `rest`. |
 | `--printYaml` | No (false) | Print out YAML instead of generating files. |
 | `--verbose` | No (false) | Print more messages while compiling. |
 | `--logReads` | No (false) | Enable logging for every received message. |
 | `--logWrites` | No (false) | Enable logging for every sent message. |
 | `--logIncremental` | No (false) | Enable logging for observer in incremental dependency tracking. |
-| `--experimental-jastadd-329` | No (false) | Use trace events `INC_FLUSH_START` and `INC_FLUSH_END` ([JastAdd issue #329][jastadd-issue-329]), see [section about automatic dependency tracking](/using#dependency-tracking-automatically-derived). |
-| `--incremental` | No (false) | Enables incremental dependency tracking (if `trace` is also set appropriately). |
-| `--trace[=flush]` | No (false) | Enables incremental dependency tracking (if `incremental` is also set appropriately). |
+| `--logTarget` | No (`console`) | Logging target to use, currently available: `console, slf4j`. |
+| `--experimental-jastadd-329` | No (false) | Use tracing events `INC_FLUSH_START` and `INC_FLUSH_END` ([JastAdd issue #329][jastadd-issue-329]), see [section about automatic dependency tracking](using.md#dependency-tracking-automatically-derived). |
+| `--incremental` | No (false) | Enables incremental dependency tracking (if `tracing` is also set appropriately). |
+| `--tracing[=flush]` | No (false) | Enables incremental dependency tracking (if `incremental` is also set appropriately). |
 | `--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 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
 
@@ -28,6 +29,16 @@ However, depending on the selected protocols and/or used features, additional de
 
 ## Communication protocol characteristics
 
+### Java
+
+- Protocol identifier: `java`
+- URI scheme: `java://<ignored-host>[:ignored-port]/<topic>`
+    - the value for host and port are always ignored, but are necessary to form a legal URI
+- No required runtime dependencies
+- Additional remarks:
+    - 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
 
 - Protocol identifier: `mqtt`
@@ -52,22 +63,22 @@ However, depending on the selected protocols and/or used features, additional de
 - Additional remarks:
     - Host is always `localhost`.
     - Might work with newer versions of `com.sparkjava.spark-core` as well.
-    - For debugging, it is beneficial to include an implementation for [SLF4J](http://www.slf4j.org/).
+    - For debugging, it is beneficial to include an implementation for [SLF4J][slf4j].
 
 ## Used features
 
 ### Automatic dependency tracking
 
-- Condition: When passing `--incremental` and `--trace=flush` to RagConnect
+- Condition: When passing `--incremental` and `--tracing=flush` to RagConnect
 - Required runtime dependencies: _none_
 - Required options for RelAST compiler: _none_
 - Required options for JastAdd:
     - `--incremental`
-    - `--trace=flush`
+    - `--tracing=flush`
 - Remarks:
     - Other (additional) values passed to those two options must be equal (e.g., `--incremental=param` passed to RagConnect must be also passed to JastAdd)
-    - Other values besides `flush` can be added to `--trace`
-    - [Feature description](/using#dependency-tracking-automatically-derived)
+    - Other values besides `flush` can be added to `--tracing`
+    - [Feature description](using.md#dependency-tracking-automatically-derived)
 
 ### (Safer) Automatic dependency tracking
 
@@ -77,11 +88,11 @@ However, depending on the selected protocols and/or used features, additional de
 - Required options for JastAdd: _none_
 - Remarks:
     - JastAdd version has to support `INC_FLUSH_START` and `INC_FLUSH_END` (i.e., has [issue #329][jastadd-issue-329] resolved)
-    - [Feature description](/using#dependency-tracking-automatically-derived)
+    - [Feature description](using.md#dependency-tracking-automatically-derived)
 
-### Tree/List Endpoints
+### Tree/List Ports
 
-- Condition: When using `tree` or `list` endpoints along with default mappings
+- Condition: When using ports along with default mappings for subtrees
 - Required runtime dependencies:
     - `group: 'com.fasterxml.jackson.core', name: 'jackson-core', version: '2.12.1'`
     - `group: 'com.fasterxml.jackson.core', name: 'jackson-databind', version: '2.12.1'`
@@ -89,7 +100,17 @@ However, depending on the selected protocols and/or used features, additional de
     - `--serializer=jackson`
 - Required options for JastAdd: _none_
 - Remarks:
-    - [Feature description](/using#an-advanced-example)
+    - [Feature description](using.md#an-advanced-example)
+
+### Logging Target SLF4J
 
+- Condition: When passing `--logTarget=slf4j` to RagConnect
+- Required runtime dependencies:
+    - `group: 'org.slf4j', name: 'slf4j-api', version: '1.7.0'`
+- Required options for RelAST compiler: _none_
+- Required options for JastAdd: _none_
+- Remarks:
+    - Additionally, a slf4j binding is required, see [the slf4j user manual][slf4j]
 
 [jastadd-issue-329]: https://bitbucket.org/jastadd/jastadd2/issues/329/add-event-for-completion-of-flush
+[slf4j]: https://www.slf4j.org/manual.html

pages/docs/dsl.md

+# The RagConnect Specification Language
+
+To declare ports and mappings, a domain-specific language ([DSL](https://en.wikipedia.org/wiki/Domain-specific_language)) is used.
+
+## Ports
+
+A port marks an element of an AST as sending or receiving element.
+The kind of the element determines, whether an port for it can be receiving, sending, or both at the same time.
+
+To declare a new ports, use the following syntax:
+
+```
+("send"|"receive") ["indexed"] ["with add"] <Non-Terminal>[.<Target>["(<AttributeType>)"]] ["using" <Mapping-Name> (, <Mapping-Name>)*] ";"
+```
+
+A breakdown of the parts of that syntax:
+
+- The first word (`send` or `receive`) defines the kind of port - sending or receiving, respectively.
+- The optional `indexed` applies only for list children and lets the port act on elements of that list.
+  This only works for receiving ports, and is further changed by `with add`.
+    - A lonely `indexed` assigns each incoming "topic" to an index in a list.
+      This can be useful if multiple instances of this port are connected, or the communication protocol supports wildcard topics.
+      For the former case, the connect method with an explicit index can be used, whereas the "normal" connect method without the index acts as a method for "wildcard-connect".
+    - Combining `indexed with add`, incoming data is required to be an element of the list, and will be appended to the list.
+- The second optional keyword `with add` can also be used only for receiving ports targeting a list children.
+  As described above, it can be combined with `indexed`.
+  If used on its own, the incoming data is interpreted as a complete list and its elements will be appended to the current list.
+- The `<Non-Terminal>[.<Target>["(<AttributeType>)"]]` notation describes the actual affected node.
+    - If the target is omitted, all nodes of that non-terminal type can be connected, irrespective of their context. This is a context-free port definition.
+    - The target can be any child on the right-hand side of a production rule, a role of a relation, or an attribute.
+      The brackets `(<AttributeType>)` after the target must be used in case of an attribute, and only then.
+      Here, the return type of the attribute has to be specified, as aspect files are not parsed by RagConnect.
+      Hence, RagConnect can not and will not verify the existence of the attribute, and the possible non-existence of an attribute will be found by the Java compiler.
+- Optionally, a port can use one or more [mappings](#mappings).
+  They will be applied before sending, or after receiving a message.
+  Mappings will always be applied in the order they are listed after `using`.
+
+### Context-Free Ports
+
+A port with only a non-terminal and without a target is called context-free port.
+Specifying such a port has several consequences:
+
+- The given non-terminal can be connected to in all contexts it occurs as if there were ports for all those contexts.
+- There is a special method available on the given non-terminal to connect itself, which selects the correct connect-method depending on its context.
+- Context-sensitive ports for this non-terminal can still be specified to modify mappings in this context. If the context is a list, the port must use `indexed` and cannot use `with add`.
+
+**Example**:
+
+```
+// grammar
+Root ::= A SingleA:A [OptA:A] ListA:A* ;
+A ::= <Value> ;
+
+// connect
+receive A;
+receive Root.SingleA using MyMapping; // specialized port
+```
+
+Implied, additional connect specifications:
+
+```
+receive Root.A;
+receive Root.OptA;
+receive indexed Root.ListA;
+```
+
+Application code:
+
+```java
+A a = root.getOptA();
+// new method on A:
+a.connect("<some-uri-to-connect>");
+// equivalent to (implicitly generated):
+root.connectOptA("<some-uri-to-connect>");
+```
+
+## Mappings
+
+A mapping is a side effect-free function with one argument (the value that will be transformed) and one result (the transformed value), that will be applied on a value to be sent for a sending port, a received value for a receiving port, or the result of another mapping.
+Mappings can be shared between ports.
+
+To declare a mapping, use the following syntax:
+
+```
+<Mapping-Name> "maps" <From-Type> <Input-Variable-Name> "to" "To-Type" "{:"
+  <Java-Block>
+":}"
+```
+
+A breakdown of the parts of that syntax:
+
+- The `<Mapping-Name>` identifies the mapping.
+- The `<From-Type` is the type of the input. The type of the first mapping of a receiving port must be `byte[]`.
+- To refer to the input, `<Input-Variable-Name>` defines the name of it.
+- The `<To-Type>` is the type of the result. The type of the last mapping of a sending port must be `byte[]`.
+- Finally, the `<Java-Block>` is the actual definition of the mapping using normal Java syntax.
+  The previously defined input variable can be used via its name here.
+  This block can contain multiple statements, but must end with a `return` statement.
+  The validity of this block is not verified by RagConnect itself, but later in the compilation process by the Java compiler.
+
+Note: There are default mappings provided for all primitive Java types (using their "normal" byte representation), and for all non-terminal types (using their JSON representation converted from/to bytes).
+Those default mappings apply to both sending and receiving ports, and match their counterparts, e.g., the mapping from `int` to `byte[]` uses the same byte representation as the mapping back from `byte[]` to `int`.
+Default mappings are always inserted if either no mapping is present, or if the type of the first/last mapping is not `byte[]` as stated above.
+Their main intent is to allow quick prototyping without constraining a more complex use case.
+
+## Dependency definitions
+
+!!! note
+    Deprecated since `1.0.0`
+
+A dependency definition describes a possible dependency on type-level from a token to an attribute.
+Whenever the token changes, the attribute is eagerly re-computed and ports attached to it are triggered.
+
+Such a dependency must be added on instance-level for every token that could have an influence to the attribute.
+An alternative for those explicit dependency definitions is [incremental dependency tracking](using.md#dependency-tracking-automatically-derived).
+
+To declare a dependency definition, use the following syntax:
+
+```
+<Non-Terminal-1>.<Target> "canDependOn" <Non-Terminal-2>.<Token-Name> "as" <Dependency-Name> ";"
+```
+
+A breakdown of the parts of that syntax:
+
+- `<Non-Terminal-1>.<Target>` denotes the attribute (and the non-terminal it is defined on) which depends on the token
+- `<Non-Terminal-2>.<Token-Name>` denotes the token (and the non-terminal it is defined on) that (potentially) influences the attribute value
+- `<Dependency-Name>` identifies the dependency definition and is used for the generated method, which will be defined on `Non-Terminal-1` as `<Non-Terminal-1>.add<Dependency-Name>(<Non-Terminal-2> influencingNode)`

pages/docs/extending.md

 # Extending `RagConnect`
 
-To add a new communication protocol, the following locations have to be changed (replace `ABC` and `abc` with the name of the protocol):
+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`:
+### Within `ragconnect.base/src/main/resources`
 
 {% raw %}
-- Add a new handler `ABCHandler`, if appropriate, similar to the existing handlers
-    - If further methods are needed for handler initialization, add a new template `abc.mustache` containing those procedures. Add `{{#usesABC}}{{> abc}}{{/usesABC}}` at the top of `ragconnect.mustache` to use this template
-- 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`.
+- Add a new handler `ABCHandler.jadd`, similar to the existing handlers. 
+- In `handler.mustache`, add further methods if needed for handler usage in the application code (similar to `{{rootNodeName}}.{{SetupWaitUntilReadyMethodName}}` for `mqtt`)
+- In `receiveDefinition.mustache` and `sendDefinition.mustache`: add a new case in the switch statements defining the logic to happen upon connect and disconnect for both definitions. If the new protocol is close to a PUSH semantic, follow `mqtt`. If it is closer to PULL semantic, follow `rest`.
 {% endraw %}
 
-Within `ragconnect.base/src/main/jastadd`:
+### 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
-    - Add a newly constructed handler within the definition of `RagConnect.toMustache` with the needed fields (class name, construction snippet, handler attribute, handler field, the boolean flag you just added to Configuration)
-- 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 `Handlers.jrag`: Add a new attribute `RagConnect.abcHandler()` returning the resolved handler
 
-In `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler/Compiler.java`:
+### Within `ragconnect.base/src/main/java/org/jastadd/ragconnect/compiler`
 
+In `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`
+- Add a newly constructed handler in `setConfiguration`  with the needed fields (definition file name within `resources` directory, commonly `ABCHandler.jadd`; class name of the handler; unique name for the protocol; whether the handler is used, i.e., if it was given in `--protocols`)
 
 Furthermore, new test cases are appreciated, see [below](#writing-tests).
 
@@ -58,7 +50,7 @@ All tests are required to run both locally, and within the CI.
 
 ### build.gradle
 
-Use the [PreprocessorPlugin][preprocessor-plugin], the build process can be written concisely in three parts per task:
+Using the [PreprocessorPlugin][preprocessor-plugin], the build process can be written concisely in three parts per task:
 
 ```groovy
 task compileTreeAllowedTokens(type: RagConnectTest) {