Resolve "Feature: Add context-free connect"

Closes #34 (closed)

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.