Deployed 2085e9bd to dev in public with MkDocs 1.2.2 and mike 1.1.2

public/dev/404.html

@@ -52,6 +52,10 @@
                     <li class="toctree-l1"><a class="reference internal" href="/adding/">Adding RagConnect to your project</a>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="/dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul>
                     <li class="toctree-l1"><a class="reference internal" href="/compiler/">Compiler options</a>
                     </li>

public/dev/adding/index.html

@@ -65,6 +65,10 @@
     </ul>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul>
                     <li class="toctree-l1"><a class="reference internal" href="../compiler/">Compiler options</a>
                     </li>
@@ -240,7 +244,7 @@ Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https:/
       <span><a href="../use_cases/" style="color: #fcfcfc">&laquo; Previous</a></span>
     
     
-      <span><a href="../compiler/" style="color: #fcfcfc">Next &raquo;</a></span>
+      <span><a href="../dsl/" style="color: #fcfcfc">Next &raquo;</a></span>
     
   </span>
 </div>

public/dev/changelog/index.html

@@ -59,6 +59,10 @@
                     <li class="toctree-l1"><a class="reference internal" href="../adding/">Adding RagConnect to your project</a>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul>
                     <li class="toctree-l1"><a class="reference internal" href="../compiler/">Compiler options</a>
                     </li>
@@ -74,6 +78,8 @@
                 <ul class="current">
                     <li class="toctree-l1 current"><a class="reference internal current" href="./">Changelog</a>
     <ul class="current">
+    <li class="toctree-l2"><a class="reference internal" href="#032">0.3.2</a>
+    </li>
     <li class="toctree-l2"><a class="reference internal" href="#031">0.3.1</a>
     </li>
     <li class="toctree-l2"><a class="reference internal" href="#030">0.3.0</a>
@@ -125,6 +131,12 @@
             <div class="section">
               
                 <h1 id="changelog">Changelog<a class="headerlink" href="#changelog" title="Permanent link"></a></h1>
+<h2 id="032">0.3.2<a class="headerlink" href="#032" title="Permanent link"></a></h2>
+<ul>
+<li>Allow connection endpoints for list nonterminals (<a href="https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/21">#21</a>)</li>
+<li>Ensure correct connect and disconnect functionality (<a href="https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/31">#31</a>)</li>
+<li>Enhance documentation (<a href="https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/13">#13</a>, <a href="https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/20">#20</a>, <a href="https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/issues/41">#41</a>)</li>
+</ul>
 <h2 id="031">0.3.1<a class="headerlink" href="#031" title="Permanent link"></a></h2>
 <ul>
 <li>Full support for incremental dependency tracking</li>
@@ -168,7 +180,7 @@
 <hr>
 Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
 
-<small><br><i>Last updated <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime">July 28, 2021 15:44:35</span></i></small>
+<small><br><i>Last updated <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime">November 24, 2021 11:42:30</span></i></small>
 
 </p>
 

public/dev/compiler/index.html

@@ -59,6 +59,10 @@
                     <li class="toctree-l1"><a class="reference internal" href="../adding/">Adding RagConnect to your project</a>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul class="current">
                     <li class="toctree-l1 current"><a class="reference internal current" href="./">Compiler options</a>
     <ul class="current">
@@ -300,7 +304,7 @@ Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https:/
   <span class="rst-current-version" data-toggle="rst-current-version">
     
     
-      <span><a href="../adding/" style="color: #fcfcfc">&laquo; Previous</a></span>
+      <span><a href="../dsl/" style="color: #fcfcfc">&laquo; Previous</a></span>
     
     
       <span><a href="../inner-workings/" style="color: #fcfcfc">Next &raquo;</a></span>

public/dev/dsl/index.html

+<!DOCTYPE html>
+<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
+<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
+<head>
+  <meta charset="utf-8">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  
+  
+  
+  <link rel="shortcut icon" href="../img/favicon.ico">
+  <title>RagConnect Specification Language - RagConnect dev</title>
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700" />
+
+  <link rel="stylesheet" href="../css/theme.css" />
+  <link rel="stylesheet" href="../css/theme_extra.css" />
+  <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/styles/github.min.css" />
+  <link href="../css/version-select.css" rel="stylesheet" />
+  
+  <script>
+    // Current page data
+    var mkdocs_page_name = "RagConnect Specification Language";
+    var mkdocs_page_input_path = "dsl.md";
+    var mkdocs_page_url = null;
+  </script>
+  
+  <script src="../js/jquery-2.1.1.min.js" defer></script>
+  <script src="../js/modernizr-2.8.3.min.js" defer></script>
+  <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/10.5.0/highlight.min.js"></script>
+  <script>hljs.initHighlightingOnLoad();</script> 
+</head>
+
+<body class="wy-body-for-nav" role="document">
+
+  <div class="wy-grid-for-nav">
+
+    
+    <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
+    <div class="wy-side-scroll">
+      <div class="wy-side-nav-search">
+        <a href=".." class="icon icon-home"> RagConnect dev</a>
+        <div role="search">
+  <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
+      <input type="text" name="q" placeholder="Search docs" title="Type search term here" />
+  </form>
+</div>
+      </div>
+
+      <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../using/">RagConnect by Example</a>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../use_cases/">Use Cases</a>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../adding/">Adding RagConnect to your project</a>
+                    </li>
+                </ul>
+                <ul class="current">
+                    <li class="toctree-l1 current"><a class="reference internal current" href="./">RagConnect Specification Language</a>
+    <ul class="current">
+    <li class="toctree-l2"><a class="reference internal" href="#endpoints">Endpoints</a>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#mappings">Mappings</a>
+    </li>
+    <li class="toctree-l2"><a class="reference internal" href="#dependency-definitions">Dependency definitions</a>
+    </li>
+    </ul>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../compiler/">Compiler options</a>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../inner-workings/">Inner workings</a>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../extending/">Extending RagConnect</a>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../changelog/">Changelog</a>
+                    </li>
+                </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../ragdoc/">API documentation</a>
+                    </li>
+                </ul>
+      </div>
+    </div>
+    </nav>
+
+    <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
+
+      
+      <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
+        <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
+        <a href="..">RagConnect dev</a>
+      </nav>
+
+      
+      <div class="wy-nav-content">
+        <div class="rst-content">
+          <div role="navigation" aria-label="breadcrumbs navigation">
+  <ul class="wy-breadcrumbs">
+    <li><a href="..">Docs</a> &raquo;</li>
+    
+      
+    
+    <li>RagConnect Specification Language</li>
+    <li class="wy-breadcrumbs-aside">
+      
+    </li>
+  </ul>
+  
+  <hr/>
+</div>
+
+          <div role="main">
+            <div class="section">
+              
+                <div class="admonition attention">
+<p class="admonition-title">Attention</p>
+<p>Not all features described here are (fully) implemented yet, please see the <a href="https://git-st.inf.tu-dresden.de/jastadd/ragconnect/-/milestones/2">progress of milestone for 1.0.0</a> first.</p>
+</div>
+<h1 id="the-ragconnect-specification-language">The RagConnect Specification Language<a class="headerlink" href="#the-ragconnect-specification-language" title="Permanent link"></a></h1>
+<p>To declare endpoints and mappings, a domain-specific language (<a href="https://en.wikipedia.org/wiki/Domain-specific_language">DSL</a>) is used.</p>
+<h2 id="endpoints">Endpoints<a class="headerlink" href="#endpoints" title="Permanent link"></a></h2>
+<p>An endpoint marks an element of an AST as sending or receiving element.
+The kind of the element determines, whether an endpoint for it can be receiving, sending, or both at the same time.</p>
+<p>To declare a new endpoints, use the following syntax:</p>
+<pre><code>(&quot;send&quot;|&quot;receive&quot;) [&quot;indexed&quot;] [&quot;with add&quot;] &lt;Non-Terminal&gt;[.&lt;Target&gt;[&quot;()&quot;]] [&quot;using&quot; &lt;Mapping-Name&gt; (, &lt;Mapping-Name&gt;)*] &quot;;&quot;
+</code></pre>
+<p>A breakdown of the parts of that syntax:</p>
+<ul>
+<li>The first word (<code>send</code> or <code>receive</code>) defines the kind of endpoint - sending or receiving, respectively.</li>
+<li>The optional <code>indexed</code> applies only for list children and lets the endpoint act on elements of that list.
+  This only works for receiving endpoints, and is further changed by <code>with add</code>.</li>
+<li>A lonely <code>indexed</code> assigns each incoming "topic" to an index in a list.
+    This can be useful if multiple instances of this endpoint 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".</li>
+<li>Combining <code>indexed with add</code>, incoming data is required to be an element of the list, and will be appended to the list.</li>
+<li>The second optional keyword <code>with add</code> can also be used only for receiving endpoints targeting a list children.
+  As described above, it can be combined with <code>indexed</code>.
+  If used on its own, the incoming data is interpreted as a complete list and its elements will be appended to the current list.</li>
+<li>The <code>&lt;Non-Terminal&gt;[.&lt;Target&gt;["()"]]</code> notation describes the actual affected node.</li>
+<li>If the target is omitted, all nodes of that non-terminal type can be connected, irrespective of their context.</li>
+<li>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 <code>()</code> after the target must be used in case of an attribute, and only then.</li>
+<li>Optionally, an endpoint can use one or more <a href="#mappings">mappings</a>.
+  They will be applied before sending, or after receiving a message.
+  Mappings will always be applied in the order they are listed after <code>using</code>.</li>
+</ul>
+<h2 id="mappings">Mappings<a class="headerlink" href="#mappings" title="Permanent link"></a></h2>
+<p>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.
+Mappings can be shared between endpoints.</p>
+<p>To declare a mapping, use the following syntax:</p>
+<pre><code>&lt;Mapping-Name&gt; &quot;maps&quot; &lt;From-Type&gt; &lt;Input-Variable-Name&gt; &quot;to&quot; &quot;To-Type&quot; &quot;{:&quot;
+  &lt;Java-Block&gt;
+&quot;:}&quot;
+</code></pre>
+<p>A breakdown of the parts of that syntax:</p>
+<ul>
+<li>The <code>&lt;Mapping-Name&gt;</code> identifies the mapping.</li>
+<li>The <code>&lt;From-Type</code> is the type of the input. The type of the first mapping of a receiving endpoint must be <code>byte[]</code>.</li>
+<li>To refer to the input, <code>&lt;Input-Variable-Name&gt;</code> defines the name of it.</li>
+<li>The <code>&lt;To-Type&gt;</code> is the type of the result. The type of the last mapping of a sending endpoint must be <code>byte[]</code>.</li>
+<li>Finally, the <code>&lt;Java-Block&gt;</code> 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 <code>return</code> statement.
+  The validity of this block is not verified by RagConnect itself, but later in the compilation process by the Java compiler.</li>
+</ul>
+<p>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 endpoints, and match their counterparts, e.g., the mapping from <code>int</code> to <code>byte[]</code> uses the same byte representation as the mapping back from <code>byte[]</code> to <code>int</code>.
+Default mappings are always inserted if either no mapping is present, or if the type of the first/last mapping is not <code>byte[]</code> as stated above.
+Their main intent is to allow quick prototyping without constraining a more complex use case.</p>
+<h2 id="dependency-definitions">Dependency definitions<a class="headerlink" href="#dependency-definitions" title="Permanent link"></a></h2>
+<div class="admonition note">
+<p class="admonition-title">Note</p>
+<p>Deprecated since <code>1.0.0</code></p>
+</div>
+<p>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 endpoints attached to it are triggered.</p>
+<p>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 <a href="/using#dependency-tracking-automatically-derived">incremental dependency tracking</a>.</p>
+<p>To declare a dependency definition, use the following syntax:</p>
+<pre><code>&lt;Non-Terminal-1&gt;.&lt;Target&gt; &quot;canDependOn&quot; &lt;Non-Terminal-2&gt;.&lt;Token-Name&gt; &quot;as&quot; &lt;Dependency-Name&gt; &quot;;&quot;
+</code></pre>
+<p>A breakdown of the parts of that syntax:</p>
+<ul>
+<li><code>&lt;Non-Terminal-1&gt;.&lt;Target&gt;</code> denotes the attribute (and the non-terminal it is defined on) which depends on the token</li>
+<li><code>&lt;Non-Terminal-2&gt;.&lt;Token-Name&gt;</code> denotes the token (and the non-terminal it is defined on) that (potentially) influences the attribute value</li>
+<li><code>&lt;Dependency-Name&gt;</code> identifies the dependency definition and is used for the generated method, which will be defined on <code>Non-Terminal-1</code> as <code>&lt;Non-Terminal-1&gt;.add&lt;Dependency-Name&gt;(&lt;Non-Terminal-2&gt; influencingNode)</code></li>
+</ul>
+              
+            </div>
+          </div>
+          
+<p>
+<hr>
+Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
+
+<small><br><i>Last updated <span class="git-revision-date-localized-plugin git-revision-date-localized-plugin-datetime">November 24, 2021 13:01:59</span></i></small>
+
+</p>
+
+      
+        </div>
+      </div>
+
+    </section>
+
+  </div>
+
+  <div class="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    
+    
+      <span><a href="../adding/" style="color: #fcfcfc">&laquo; Previous</a></span>
+    
+    
+      <span><a href="../compiler/" style="color: #fcfcfc">Next &raquo;</a></span>
+    
+  </span>
+</div>
+    <script>var base_url = '..';</script>
+    <script src="../js/theme_extra.js" defer></script>
+    <script src="../js/theme.js" defer></script>
+      <script src="../search/main.js" defer></script>
+      <script src="../js/version-select.js" defer></script>
+    <script defer>
+        window.onload = function () {
+            SphinxRtdTheme.Navigation.enable(true);
+        };
+    </script>
+
+</body>
+</html>

public/dev/extending/index.html

@@ -59,6 +59,10 @@
                     <li class="toctree-l1"><a class="reference internal" href="../adding/">Adding RagConnect to your project</a>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul>
                     <li class="toctree-l1"><a class="reference internal" href="../compiler/">Compiler options</a>
                     </li>

public/dev/index.html

@@ -59,6 +59,10 @@
                     <li class="toctree-l1"><a class="reference internal" href="adding/">Adding RagConnect to your project</a>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul>
                     <li class="toctree-l1"><a class="reference internal" href="compiler/">Compiler options</a>
                     </li>
@@ -157,5 +161,5 @@ Built with <a href="https://www.mkdocs.org/">MkDocs</a> using a <a href="https:/
 
 <!--
 MkDocs version : 1.2.2
-Build Date UTC : 2021-11-24 10:28:13.974198+00:00
+Build Date UTC : 2021-11-24 13:26:05.125117+00:00
 -->

public/dev/inner-workings/index.html

@@ -59,6 +59,10 @@
                     <li class="toctree-l1"><a class="reference internal" href="../adding/">Adding RagConnect to your project</a>
                     </li>
                 </ul>
+                <ul>
+                    <li class="toctree-l1"><a class="reference internal" href="../dsl/">RagConnect Specification Language</a>
+                    </li>
+                </ul>
                 <ul>
                     <li class="toctree-l1"><a class="reference internal" href="../compiler/">Compiler options</a>
                     </li>