From 40f351b8bc21c4bb56a8d9b090b95dea385fa49c Mon Sep 17 00:00:00 2001
From: rschoene <rene.schoene@tu-dresden.de>
Date: Wed, 8 Dec 2021 16:08:52 +0100
Subject: [PATCH] working on context-free connect

- updated documentation
- cleanup build and test case
---
 pages/docs/dsl.md                             | 42 ++++++++++++++++++-
 ragconnect.tests/build.gradle                 |  2 -
 .../tests/ContextFreeSimpleTest.java          |  2 +-
 3 files changed, 42 insertions(+), 4 deletions(-)

diff --git a/pages/docs/dsl.md b/pages/docs/dsl.md
index 11bdae7..3f83c71 100644
--- a/pages/docs/dsl.md
+++ b/pages/docs/dsl.md
@@ -29,13 +29,53 @@ A breakdown of the parts of that syntax:
   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>["()"]]` 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.
+  - If the target is omitted, all nodes of that non-terminal type can be connected, irrespective of their context. This is a context-free endpoint 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 `()` after the target must be used in case of an attribute, and only then.
 - Optionally, an endpoint 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 Endpoints
+
+!!! attention
+    Context-Free endpoints are currently only supported for receiving endpoints.
+
+An endpoint with only a non-terminal and without a target is called context-free endpoint.
+Specifying such an endpoint has several consequences:
+
+- The given non-terminal can be connected to in all contexts it occurs as if there were endpoints 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 endpoints for this non-terminal can still be specified to modify mappings in this context. If the context is a list, the endpoint must use `indexed` and cannot use `with add`.
+
+**Example**:
+
+```java
+// grammar
+Root ::= A SingleA:A [OptA:A] ListA:A* ;
+A ::= <Value> ;
+
+// connect
+receive A;
+receive Root.SingleA using MyMapping; // specialized endpoint
+```
+
+Implied, additional connect specifications:
+```java
+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 endpoint, a received value for a receiving endpoint, or the result of another mapping.
diff --git a/ragconnect.tests/build.gradle b/ragconnect.tests/build.gradle
index 7c10c5f..865abd9 100644
--- a/ragconnect.tests/build.gradle
+++ b/ragconnect.tests/build.gradle
@@ -582,7 +582,6 @@ task compileContextFreeSimpleIncremental(type: RagConnectTest, dependsOn: ':ragc
     jastadd {
         jastAddList = 'JastAddList'
         packageName = 'contextFreeSimpleInc.ast'
-//        inputFiles = [file('src/test/01-input/contextFreeSimple/Test.jadd')]
         extraOptions = ['--tracing=cache,flush',
                         '--incremental=param',
                         '--cache=all',
@@ -590,4 +589,3 @@ task compileContextFreeSimpleIncremental(type: RagConnectTest, dependsOn: ':ragc
                         '--flush=full']
     }
 }
-compileContextFreeSimpleIncremental.outputs.upToDateWhen { false }
diff --git a/ragconnect.tests/src/test/java/org/jastadd/ragconnect/tests/ContextFreeSimpleTest.java b/ragconnect.tests/src/test/java/org/jastadd/ragconnect/tests/ContextFreeSimpleTest.java
index 5e5510b..afd6c59 100644
--- a/ragconnect.tests/src/test/java/org/jastadd/ragconnect/tests/ContextFreeSimpleTest.java
+++ b/ragconnect.tests/src/test/java/org/jastadd/ragconnect/tests/ContextFreeSimpleTest.java
@@ -17,7 +17,7 @@ import static org.junit.jupiter.api.Assertions.*;
  *
  * @author rschoene - Initial contribution
  */
-@Tag("New")
+@Tag("Incremental")
 public class ContextFreeSimpleTest extends AbstractMqttTest {
 
   private static final String TOPIC_UNNAMED = "unnamed";
-- 
GitLab