Wrote section on action language

doc/_build/html/_sources/actionlanguage.txt

@@ -1,17 +1,268 @@
 Action Language
 ===============
 
+The primary language of the Modelverse, is its action language.
+This language serves as a nicer representation of the underlying Modelverse Graph Language, which is stored as a graph.
+The action language gets parsed by the parser, resulting in a kind of abstract syntax graph.
+This abstract syntax graph highly resembles an executable graph in the Modelverse Graph Language.
+
+Users will mainly use this language to write actions and constraints, but maybe also to implement their own interfaces, or override core functionality of the Modelverse.
+
+.. warning::
+   The current parser is unable to handle whitespaces in a general way.
+   As such, all indentation needs to be done using tabs, and the difference needs to be exactly 1.
+   This is different from Python, where tabs and whitespaces can be mixed, and the number can even vary.
+
+Files
+-----
+
+There are two kinds of files: code files, and headers.
+This distinction is similar to C and related languages.
+Code in header files will always be copied throughout all including files.
+As such, it is a good idea to have header files which declare the signatures of functions, but leave the actual implementation to the code files.
+Code files do not need to import the headers they are implementing: all variable names are automatically shared.
+
 Language description
 --------------------
 
+The language is inspired by Python syntax, and highly resembles it.
+Nonetheless, it is a lot simpler.
+In the remainder of this subsection, we go over the different language constructs.
+
+If
+^^
+
+The IF construct is similar to that found in other languages.
+Its structure is as follows::
+
+    if condition1:
+       do_when_condition1
+    elif condition2:
+       do_when_condition2
+    else:
+       do_otherwise
+
+Each condition can be an expression.
+The code blocks can be any other kind of code.
+Just like Python, indentation is the only way to structure code.
+Unlike Python, only tabs are allowed (thus no space), and the number of tabs must be exactly one higher for a deeper block.
+
+The presence of an "elif" and "else" is optional.
+
+While
+^^^^^
+
+The WHILE construct is similar to that found in other languages.
+Contrary to Python, there is no support for the "else" construct.
+Its structure is as follows::
+
+    while condition:
+        action
+
+Conditions and actions are similar to the If construct.
+
+Break
+^^^^^
+
+Whereas this is supported in the Modelverse, the parser currently does not consider this keyword.
+
+Continue
+^^^^^^^^
+
+Whereas this is supported in the Modelverse, the parser currently does not consider this keyword.
+
+Return
+^^^^^^
+
+The RETURN construct is again similar to how it is expected.
+To prevent ambiguity in the grammar, an exclamation mark should follow after the expression to return.
+Its structure is as follows::
+
+    return expression!
+
+The expression can be any expression, similar to the condition in an If and While.
+
+Function call
+^^^^^^^^^^^^^
+
+Function calls happen like usual, by appending an opening and closing parenthesis at the end.
+Its structure is as follows::
+
+    my_function(argument_a, argument_b)
+
+Arguments can again be any kind of expression.
+Named parameters are not supported in the grammar, though the Modelverse can internally handle them.
+
+Function definition
+^^^^^^^^^^^^^^^^^^^
+
+Defining a function makes the function available as a variable in the remainder of the context.
+Forward declaration is unnecessary: all function names are retrieved before going over the body of the functions.
+This makes mutual recursion easy.
+
+A function needs to define its return type, as well as the type of all its parameters.
+In case the type is unknown, or can be anything, *Element* can be used as a kind of "void pointer".
+Its structure is as follows::
+
+    Element function function_name(parameter_a : Integer):
+        body_of_the_function
+
+First comes the returntype, followed by the keyword "function".
+Again, indentation needs to happen using tabs.
+
+Assignment
+^^^^^^^^^^
+
+Assignment is like usual.
+Its structure is::
+
+    a = expression
+
+This assumes that a is already defined.
+
+Declaration
+^^^^^^^^^^^
+
+All variables used in the Modelverse need to be defined statically.
+Defining a variable reserves a part of the Modelverse State to hold the value for this value.
+As such, variables cannot be used if they are not defined.
+Additionally, a declared variable will have a type defined with it.
+Again, if the type can vary or is unknown, this can be *Element*.
+
+.. warning::
+   Contrary to other languages, declaring a variable does not equal defining the variable.
+   Therefore, after a variable is declared, it can be used, but its contents will be non-existing.
+   It is wise to always assign a value to a declared value right after declaration!
+
+Its structure is as follows::
+
+    String abc
+
+There are two kinds of declaration: local declaration, and global declaration.
+Local declarations happen in the current block of the code, and their references get removed when exiting the block.
+Global declarations have identically the same syntax, but are specified at the top level (*i.e.*, they have no tabs in front of them).
+Global declarations do not assign a value and are thus external references, to be defined in the future or by some other module.
+Sharing between modules is possible this way, as all global names are linked together when linking the application together.
+A global declaration that is never defined is flagged as invalid by the compiler and will prevent compilation.
+
+Definition
+^^^^^^^^^^
+
+Defining a variable is similar to a global declaration, but now there is an immediate assignment.
+Immediate assignment is only possible at the top level.
+Note that the assignment must be of a constant which requires no execution of functions or such.
+Also, it is impossible to assign the value of another variable.
+
+Its structure is as follows::
+
+    String abc = "abc"
+
+It is possible that a definition does not yet know the value to assign, or is an empty element.
+To notify the other files that this is the defining element, use the import syntax to assign *?* to it::
+
+    Element abc = ?
+
+This results in the Modelverse creating an empty node as placeholder for a value.
+The value will now be defined and accessible.
+
+Imports
+^^^^^^^
+
+Direct imports in the Modelverse are possible, but are not recommended for ordinary users.
+This syntax allows a variable to be bound to an absolute location in the Modelverse, which is resolved at compile time.
+The primary use case for this is the creation of bootstrap files, but it is also possible for other purposes.
+Use with care!
+
+Its structure is as follows::
+
+    String abc = ?path/in/modelverse
+
+A special case is when the path is empty, which indicates that a new (anonymous) node should be created for it::
+
+    Element abc = ?
+
+Include
+^^^^^^^
+
+Other files can easily be included using the include syntax.
+This is a raw include: the contents of the file are just copied inside the file at that exact spot.
+Generally, you should only include *.alh* files, unless you know what you are doing.
+
+Constants
+^^^^^^^^^
+
+The Modelverse supports a set of constants that can be used.
+All constants can be assigned in a definition of globals.
+
+============= ========================================================================== =======
+Constant type Values                                                                     Example
+============= ========================================================================== =======
+Integer       Any possible integer, either positive (no prefix) or negative (- prefix)   1
+Float         Any possible floating point value; scientific notation is not supported    1.0
+Boolean       Either True or False                                                       True
+String        Any possible string, enclosed with either double or single quotes          "abc"
+Action        An action construct from the Modelverse, prefixed with an exclamation mark !If
+============= ========================================================================== =======
+
+Operators
+^^^^^^^^^
+
+While operators are seemingly supported by the compiler, these are actually expanded to function calls to relevant functions.
+For example, *1 + 2*, is expanded to *integer_addition(1, 2)*
+
+User I/O
+^^^^^^^^
+
+User input and output is done through the keyworded operations *input()* and *output(msg)*.
+*input()* returns the first message in the input queue of the current user.
+*output(msg)* places the value of the expression in the output queue of the current user.
+
+All I/O is done using queues: the value is only read and written to a specific place in the Modelverse.
+To actually read or write it at the client side, these special places should be accessed through dedicated Modelverse operations.
+
 Examples
 --------
 
-Simple addition
-^^^^^^^^^^^^^^^
+We now show some simple code fragments written in valid Action Language code.
+As this code is directly executable in the Modelverse, the main function is always called "main" and all includes are also present.
+We do not currently handle how to execute this code: this is explained further on.
 
 Fibonacci
 ^^^^^^^^^
 
+The Fibonacci code is fairly simple.
+First, the primitives are imported to make sure that we know about all operations on primitives.
+Then, a function *fib* is defined, which will recursively compute the specified Fibonacci number.
+This is wrapped by a *main* function, which takes input from the user and outputs the result of the *fib* function.
+
+This code looks as follows::
+
+    include "primitives.alh"
+
+    Integer function fib(param : Integer):
+        if (param <= 2):
+            return 1!
+        else:
+            return fib(param - 1) + fib(param - 2)!
+
+    Void function main():
+        while(True):
+            output(fib(input()))
+
 Factorial
 ^^^^^^^^^
+
+Similarly, the code for computing a factorial is given below::
+
+    include "primitives.alh"
+
+    Integer function factorial(n : Integer):
+        if(n <= 1):
+            return 1!
+        else:
+            return n * factorial(n - 1)!
+
+    Void function main():
+        while(True):
+            output(factorial(input()))
+

doc/_build/html/_sources/examples.txt

@@ -1,6 +1,21 @@
 Examples
 ========
 
+To run this code, store it in a file (*e.g.*, test.alc), and execute the following commands::
+
+    python scripts/run_local_modelverse.py 8001 &
+    python scripts/make_parallel.py http://localhost:8001 test test.alc bootstrap/primitives.alc
+    python scripts/prompt.py
+
+In the prompt, log on to http://localhost:8001 as user *test*.
+Now, all input you send, will be caught in the *input()* calls seen in the code.
+Results will also be printed.
+
+Note that all content will, by default, be typed as string.
+If you want to send integers or so, prepend the input with a backslash (\\), which allows you to directly input the JSON code.
+For example, input *5* will be received as the string "5".
+To send the integer 5, the input should be *\\5*.
+
 Simple Fibonacci Server
 -----------------------
 

doc/_build/html/actionlanguage.html

@@ -51,19 +51,270 @@
             
   <div class="section" id="action-language">
 <h1>Action Language<a class="headerlink" href="#action-language" title="Permalink to this headline">¶</a></h1>
+<p>The primary language of the Modelverse, is its action language.
+This language serves as a nicer representation of the underlying Modelverse Graph Language, which is stored as a graph.
+The action language gets parsed by the parser, resulting in a kind of abstract syntax graph.
+This abstract syntax graph highly resembles an executable graph in the Modelverse Graph Language.</p>
+<p>Users will mainly use this language to write actions and constraints, but maybe also to implement their own interfaces, or override core functionality of the Modelverse.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">The current parser is unable to handle whitespaces in a general way.
+As such, all indentation needs to be done using tabs, and the difference needs to be exactly 1.
+This is different from Python, where tabs and whitespaces can be mixed, and the number can even vary.</p>
+</div>
+<div class="section" id="files">
+<h2>Files<a class="headerlink" href="#files" title="Permalink to this headline">¶</a></h2>
+<p>There are two kinds of files: code files, and headers.
+This distinction is similar to C and related languages.
+Code in header files will always be copied throughout all including files.
+As such, it is a good idea to have header files which declare the signatures of functions, but leave the actual implementation to the code files.
+Code files do not need to import the headers they are implementing: all variable names are automatically shared.</p>
+</div>
 <div class="section" id="language-description">
 <h2>Language description<a class="headerlink" href="#language-description" title="Permalink to this headline">¶</a></h2>
+<p>The language is inspired by Python syntax, and highly resembles it.
+Nonetheless, it is a lot simpler.
+In the remainder of this subsection, we go over the different language constructs.</p>
+<div class="section" id="if">
+<h3>If<a class="headerlink" href="#if" title="Permalink to this headline">¶</a></h3>
+<p>The IF construct is similar to that found in other languages.
+Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="k">if</span> <span class="n">condition1</span><span class="p">:</span>
+   <span class="n">do_when_condition1</span>
+<span class="k">elif</span> <span class="n">condition2</span><span class="p">:</span>
+   <span class="n">do_when_condition2</span>
+<span class="k">else</span><span class="p">:</span>
+   <span class="n">do_otherwise</span>
+</pre></div>
+</div>
+<p>Each condition can be an expression.
+The code blocks can be any other kind of code.
+Just like Python, indentation is the only way to structure code.
+Unlike Python, only tabs are allowed (thus no space), and the number of tabs must be exactly one higher for a deeper block.</p>
+<p>The presence of an &#8220;elif&#8221; and &#8220;else&#8221; is optional.</p>
+</div>
+<div class="section" id="while">
+<h3>While<a class="headerlink" href="#while" title="Permalink to this headline">¶</a></h3>
+<p>The WHILE construct is similar to that found in other languages.
+Contrary to Python, there is no support for the &#8220;else&#8221; construct.
+Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="k">while</span> <span class="n">condition</span><span class="p">:</span>
+    <span class="n">action</span>
+</pre></div>
+</div>
+<p>Conditions and actions are similar to the If construct.</p>
+</div>
+<div class="section" id="break">
+<h3>Break<a class="headerlink" href="#break" title="Permalink to this headline">¶</a></h3>
+<p>Whereas this is supported in the Modelverse, the parser currently does not consider this keyword.</p>
+</div>
+<div class="section" id="continue">
+<h3>Continue<a class="headerlink" href="#continue" title="Permalink to this headline">¶</a></h3>
+<p>Whereas this is supported in the Modelverse, the parser currently does not consider this keyword.</p>
+</div>
+<div class="section" id="return">
+<h3>Return<a class="headerlink" href="#return" title="Permalink to this headline">¶</a></h3>
+<p>The RETURN construct is again similar to how it is expected.
+To prevent ambiguity in the grammar, an exclamation mark should follow after the expression to return.
+Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre>return expression!
+</pre></div>
+</div>
+<p>The expression can be any expression, similar to the condition in an If and While.</p>
+</div>
+<div class="section" id="function-call">
+<h3>Function call<a class="headerlink" href="#function-call" title="Permalink to this headline">¶</a></h3>
+<p>Function calls happen like usual, by appending an opening and closing parenthesis at the end.
+Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">my_function</span><span class="p">(</span><span class="n">argument_a</span><span class="p">,</span> <span class="n">argument_b</span><span class="p">)</span>
+</pre></div>
+</div>
+<p>Arguments can again be any kind of expression.
+Named parameters are not supported in the grammar, though the Modelverse can internally handle them.</p>
+</div>
+<div class="section" id="function-definition">
+<h3>Function definition<a class="headerlink" href="#function-definition" title="Permalink to this headline">¶</a></h3>
+<p>Defining a function makes the function available as a variable in the remainder of the context.
+Forward declaration is unnecessary: all function names are retrieved before going over the body of the functions.
+This makes mutual recursion easy.</p>
+<p>A function needs to define its return type, as well as the type of all its parameters.
+In case the type is unknown, or can be anything, <em>Element</em> can be used as a kind of &#8220;void pointer&#8221;.
+Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">Element</span> <span class="n">function</span> <span class="n">function_name</span><span class="p">(</span><span class="n">parameter_a</span> <span class="p">:</span> <span class="n">Integer</span><span class="p">):</span>
+    <span class="n">body_of_the_function</span>
+</pre></div>
+</div>
+<p>First comes the returntype, followed by the keyword &#8220;function&#8221;.
+Again, indentation needs to happen using tabs.</p>
+</div>
+<div class="section" id="assignment">
+<h3>Assignment<a class="headerlink" href="#assignment" title="Permalink to this headline">¶</a></h3>
+<p>Assignment is like usual.
+Its structure is:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">a</span> <span class="o">=</span> <span class="n">expression</span>
+</pre></div>
+</div>
+<p>This assumes that a is already defined.</p>
+</div>
+<div class="section" id="declaration">
+<h3>Declaration<a class="headerlink" href="#declaration" title="Permalink to this headline">¶</a></h3>
+<p>All variables used in the Modelverse need to be defined statically.
+Defining a variable reserves a part of the Modelverse State to hold the value for this value.
+As such, variables cannot be used if they are not defined.
+Additionally, a declared variable will have a type defined with it.
+Again, if the type can vary or is unknown, this can be <em>Element</em>.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">Contrary to other languages, declaring a variable does not equal defining the variable.
+Therefore, after a variable is declared, it can be used, but its contents will be non-existing.
+It is wise to always assign a value to a declared value right after declaration!</p>
+</div>
+<p>Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">String</span> <span class="n">abc</span>
+</pre></div>
+</div>
+<p>There are two kinds of declaration: local declaration, and global declaration.
+Local declarations happen in the current block of the code, and their references get removed when exiting the block.
+Global declarations have identically the same syntax, but are specified at the top level (<em>i.e.</em>, they have no tabs in front of them).
+Global declarations do not assign a value and are thus external references, to be defined in the future or by some other module.
+Sharing between modules is possible this way, as all global names are linked together when linking the application together.
+A global declaration that is never defined is flagged as invalid by the compiler and will prevent compilation.</p>
+</div>
+<div class="section" id="definition">
+<h3>Definition<a class="headerlink" href="#definition" title="Permalink to this headline">¶</a></h3>
+<p>Defining a variable is similar to a global declaration, but now there is an immediate assignment.
+Immediate assignment is only possible at the top level.
+Note that the assignment must be of a constant which requires no execution of functions or such.
+Also, it is impossible to assign the value of another variable.</p>
+<p>Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">String</span> <span class="n">abc</span> <span class="o">=</span> <span class="s">&quot;abc&quot;</span>
+</pre></div>
+</div>
+<p>It is possible that a definition does not yet know the value to assign, or is an empty element.
+To notify the other files that this is the defining element, use the import syntax to assign <em>?</em> to it:</p>
+<div class="highlight-default"><div class="highlight"><pre>Element abc = ?
+</pre></div>
+</div>
+<p>This results in the Modelverse creating an empty node as placeholder for a value.
+The value will now be defined and accessible.</p>
+</div>
+<div class="section" id="imports">
+<h3>Imports<a class="headerlink" href="#imports" title="Permalink to this headline">¶</a></h3>
+<p>Direct imports in the Modelverse are possible, but are not recommended for ordinary users.
+This syntax allows a variable to be bound to an absolute location in the Modelverse, which is resolved at compile time.
+The primary use case for this is the creation of bootstrap files, but it is also possible for other purposes.
+Use with care!</p>
+<p>Its structure is as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre>String abc = ?path/in/modelverse
+</pre></div>
+</div>
+<p>A special case is when the path is empty, which indicates that a new (anonymous) node should be created for it:</p>
+<div class="highlight-default"><div class="highlight"><pre>Element abc = ?
+</pre></div>
+</div>
+</div>
+<div class="section" id="include">
+<h3>Include<a class="headerlink" href="#include" title="Permalink to this headline">¶</a></h3>
+<p>Other files can easily be included using the include syntax.
+This is a raw include: the contents of the file are just copied inside the file at that exact spot.
+Generally, you should only include <em>.alh</em> files, unless you know what you are doing.</p>
+</div>
+<div class="section" id="constants">
+<h3>Constants<a class="headerlink" href="#constants" title="Permalink to this headline">¶</a></h3>
+<p>The Modelverse supports a set of constants that can be used.
+All constants can be assigned in a definition of globals.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="14%" />
+<col width="79%" />
+<col width="7%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Constant type</th>
+<th class="head">Values</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Integer</td>
+<td>Any possible integer, either positive (no prefix) or negative (- prefix)</td>
+<td>1</td>
+</tr>
+<tr class="row-odd"><td>Float</td>
+<td>Any possible floating point value; scientific notation is not supported</td>
+<td>1.0</td>
+</tr>
+<tr class="row-even"><td>Boolean</td>
+<td>Either True or False</td>
+<td>True</td>
+</tr>
+<tr class="row-odd"><td>String</td>
+<td>Any possible string, enclosed with either double or single quotes</td>
+<td>&#8220;abc&#8221;</td>
+</tr>
+<tr class="row-even"><td>Action</td>
+<td>An action construct from the Modelverse, prefixed with an exclamation mark</td>
+<td>!If</td>
+</tr>
+</tbody>
+</table>
+</div>
+<div class="section" id="operators">
+<h3>Operators<a class="headerlink" href="#operators" title="Permalink to this headline">¶</a></h3>
+<p>While operators are seemingly supported by the compiler, these are actually expanded to function calls to relevant functions.
+For example, <em>1 + 2</em>, is expanded to <em>integer_addition(1, 2)</em></p>
+</div>
+<div class="section" id="user-i-o">
+<h3>User I/O<a class="headerlink" href="#user-i-o" title="Permalink to this headline">¶</a></h3>
+<p>User input and output is done through the keyworded operations <em>input()</em> and <em>output(msg)</em>.
+<em>input()</em> returns the first message in the input queue of the current user.
+<em>output(msg)</em> places the value of the expression in the output queue of the current user.</p>
+<p>All I/O is done using queues: the value is only read and written to a specific place in the Modelverse.
+To actually read or write it at the client side, these special places should be accessed through dedicated Modelverse operations.</p>
+</div>
 </div>
 <div class="section" id="examples">
 <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
-<div class="section" id="simple-addition">
-<h3>Simple addition<a class="headerlink" href="#simple-addition" title="Permalink to this headline">¶</a></h3>
-</div>
+<p>We now show some simple code fragments written in valid Action Language code.
+As this code is directly executable in the Modelverse, the main function is always called &#8220;main&#8221; and all includes are also present.
+We do not currently handle how to execute this code: this is explained further on.</p>
 <div class="section" id="fibonacci">
 <h3>Fibonacci<a class="headerlink" href="#fibonacci" title="Permalink to this headline">¶</a></h3>
+<p>The Fibonacci code is fairly simple.
+First, the primitives are imported to make sure that we know about all operations on primitives.
+Then, a function <em>fib</em> is defined, which will recursively compute the specified Fibonacci number.
+This is wrapped by a <em>main</em> function, which takes input from the user and outputs the result of the <em>fib</em> function.</p>
+<p>This code looks as follows:</p>
+<div class="highlight-default"><div class="highlight"><pre>include &quot;primitives.alh&quot;
+
+Integer function fib(param : Integer):
+    if (param &lt;= 2):
+        return 1!
+    else:
+        return fib(param - 1) + fib(param - 2)!
+
+Void function main():
+    while(True):
+        output(fib(input()))
+</pre></div>
+</div>
 </div>
 <div class="section" id="factorial">
 <h3>Factorial<a class="headerlink" href="#factorial" title="Permalink to this headline">¶</a></h3>
+<p>Similarly, the code for computing a factorial is given below:</p>
+<div class="highlight-default"><div class="highlight"><pre>include &quot;primitives.alh&quot;
+
+Integer function factorial(n : Integer):
+    if(n &lt;= 1):
+        return 1!
+    else:
+        return n * factorial(n - 1)!
+
+Void function main():
+    while(True):
+        output(factorial(input()))
+</pre></div>
+</div>
 </div>
 </div>
 </div>
@@ -77,9 +328,26 @@
   <h3><a href="index.html">Table Of Contents</a></h3>
   <ul>
 <li><a class="reference internal" href="#">Action Language</a><ul>
-<li><a class="reference internal" href="#language-description">Language description</a></li>
+<li><a class="reference internal" href="#files">Files</a></li>
+<li><a class="reference internal" href="#language-description">Language description</a><ul>
+<li><a class="reference internal" href="#if">If</a></li>
+<li><a class="reference internal" href="#while">While</a></li>
+<li><a class="reference internal" href="#break">Break</a></li>
+<li><a class="reference internal" href="#continue">Continue</a></li>
+<li><a class="reference internal" href="#return">Return</a></li>
+<li><a class="reference internal" href="#function-call">Function call</a></li>
+<li><a class="reference internal" href="#function-definition">Function definition</a></li>
+<li><a class="reference internal" href="#assignment">Assignment</a></li>
+<li><a class="reference internal" href="#declaration">Declaration</a></li>
+<li><a class="reference internal" href="#definition">Definition</a></li>
+<li><a class="reference internal" href="#imports">Imports</a></li>
+<li><a class="reference internal" href="#include">Include</a></li>
+<li><a class="reference internal" href="#constants">Constants</a></li>
+<li><a class="reference internal" href="#operators">Operators</a></li>
+<li><a class="reference internal" href="#user-i-o">User I/O</a></li>
+</ul>
+</li>
 <li><a class="reference internal" href="#examples">Examples</a><ul>
-<li><a class="reference internal" href="#simple-addition">Simple addition</a></li>
 <li><a class="reference internal" href="#fibonacci">Fibonacci</a></li>
 <li><a class="reference internal" href="#factorial">Factorial</a></li>
 </ul>

doc/_build/html/index.html

@@ -78,6 +78,7 @@
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="actionlanguage.html">Action Language</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="actionlanguage.html#files">Files</a></li>
 <li class="toctree-l2"><a class="reference internal" href="actionlanguage.html#language-description">Language description</a></li>
 <li class="toctree-l2"><a class="reference internal" href="actionlanguage.html#examples">Examples</a></li>
 </ul>

doc/actionlanguage.rst

@@ -1,17 +1,268 @@
 Action Language
 ===============
 
+The primary language of the Modelverse, is its action language.
+This language serves as a nicer representation of the underlying Modelverse Graph Language, which is stored as a graph.
+The action language gets parsed by the parser, resulting in a kind of abstract syntax graph.
+This abstract syntax graph highly resembles an executable graph in the Modelverse Graph Language.
+
+Users will mainly use this language to write actions and constraints, but maybe also to implement their own interfaces, or override core functionality of the Modelverse.
+
+.. warning::
+   The current parser is unable to handle whitespaces in a general way.
+   As such, all indentation needs to be done using tabs, and the difference needs to be exactly 1.
+   This is different from Python, where tabs and whitespaces can be mixed, and the number can even vary.
+
+Files
+-----
+
+There are two kinds of files: code files, and headers.
+This distinction is similar to C and related languages.
+Code in header files will always be copied throughout all including files.
+As such, it is a good idea to have header files which declare the signatures of functions, but leave the actual implementation to the code files.
+Code files do not need to import the headers they are implementing: all variable names are automatically shared.
+
 Language description
 --------------------
 
+The language is inspired by Python syntax, and highly resembles it.
+Nonetheless, it is a lot simpler.
+In the remainder of this subsection, we go over the different language constructs.
+
+If
+^^
+
+The IF construct is similar to that found in other languages.
+Its structure is as follows::
+
+    if condition1:
+       do_when_condition1
+    elif condition2:
+       do_when_condition2
+    else:
+       do_otherwise
+
+Each condition can be an expression.
+The code blocks can be any other kind of code.
+Just like Python, indentation is the only way to structure code.
+Unlike Python, only tabs are allowed (thus no space), and the number of tabs must be exactly one higher for a deeper block.
+
+The presence of an "elif" and "else" is optional.
+
+While
+^^^^^
+
+The WHILE construct is similar to that found in other languages.
+Contrary to Python, there is no support for the "else" construct.
+Its structure is as follows::
+
+    while condition:
+        action
+
+Conditions and actions are similar to the If construct.
+
+Break
+^^^^^
+
+Whereas this is supported in the Modelverse, the parser currently does not consider this keyword.
+
+Continue
+^^^^^^^^
+
+Whereas this is supported in the Modelverse, the parser currently does not consider this keyword.
+
+Return
+^^^^^^
+
+The RETURN construct is again similar to how it is expected.
+To prevent ambiguity in the grammar, an exclamation mark should follow after the expression to return.
+Its structure is as follows::
+
+    return expression!
+
+The expression can be any expression, similar to the condition in an If and While.
+
+Function call
+^^^^^^^^^^^^^
+
+Function calls happen like usual, by appending an opening and closing parenthesis at the end.
+Its structure is as follows::
+
+    my_function(argument_a, argument_b)
+
+Arguments can again be any kind of expression.
+Named parameters are not supported in the grammar, though the Modelverse can internally handle them.
+
+Function definition
+^^^^^^^^^^^^^^^^^^^
+
+Defining a function makes the function available as a variable in the remainder of the context.
+Forward declaration is unnecessary: all function names are retrieved before going over the body of the functions.
+This makes mutual recursion easy.
+
+A function needs to define its return type, as well as the type of all its parameters.
+In case the type is unknown, or can be anything, *Element* can be used as a kind of "void pointer".
+Its structure is as follows::
+
+    Element function function_name(parameter_a : Integer):
+        body_of_the_function
+
+First comes the returntype, followed by the keyword "function".
+Again, indentation needs to happen using tabs.
+
+Assignment
+^^^^^^^^^^
+
+Assignment is like usual.
+Its structure is::
+
+    a = expression
+
+This assumes that a is already defined.
+
+Declaration
+^^^^^^^^^^^
+
+All variables used in the Modelverse need to be defined statically.
+Defining a variable reserves a part of the Modelverse State to hold the value for this value.
+As such, variables cannot be used if they are not defined.
+Additionally, a declared variable will have a type defined with it.
+Again, if the type can vary or is unknown, this can be *Element*.
+
+.. warning::
+   Contrary to other languages, declaring a variable does not equal defining the variable.
+   Therefore, after a variable is declared, it can be used, but its contents will be non-existing.
+   It is wise to always assign a value to a declared value right after declaration!
+
+Its structure is as follows::
+
+    String abc
+
+There are two kinds of declaration: local declaration, and global declaration.
+Local declarations happen in the current block of the code, and their references get removed when exiting the block.
+Global declarations have identically the same syntax, but are specified at the top level (*i.e.*, they have no tabs in front of them).
+Global declarations do not assign a value and are thus external references, to be defined in the future or by some other module.
+Sharing between modules is possible this way, as all global names are linked together when linking the application together.
+A global declaration that is never defined is flagged as invalid by the compiler and will prevent compilation.
+
+Definition
+^^^^^^^^^^
+
+Defining a variable is similar to a global declaration, but now there is an immediate assignment.
+Immediate assignment is only possible at the top level.
+Note that the assignment must be of a constant which requires no execution of functions or such.
+Also, it is impossible to assign the value of another variable.
+
+Its structure is as follows::
+
+    String abc = "abc"
+
+It is possible that a definition does not yet know the value to assign, or is an empty element.
+To notify the other files that this is the defining element, use the import syntax to assign *?* to it::
+
+    Element abc = ?
+
+This results in the Modelverse creating an empty node as placeholder for a value.
+The value will now be defined and accessible.
+
+Imports
+^^^^^^^
+
+Direct imports in the Modelverse are possible, but are not recommended for ordinary users.
+This syntax allows a variable to be bound to an absolute location in the Modelverse, which is resolved at compile time.
+The primary use case for this is the creation of bootstrap files, but it is also possible for other purposes.
+Use with care!
+
+Its structure is as follows::
+
+    String abc = ?path/in/modelverse
+
+A special case is when the path is empty, which indicates that a new (anonymous) node should be created for it::
+
+    Element abc = ?
+
+Include
+^^^^^^^
+
+Other files can easily be included using the include syntax.
+This is a raw include: the contents of the file are just copied inside the file at that exact spot.
+Generally, you should only include *.alh* files, unless you know what you are doing.
+
+Constants
+^^^^^^^^^
+
+The Modelverse supports a set of constants that can be used.
+All constants can be assigned in a definition of globals.
+
+============= ========================================================================== =======
+Constant type Values                                                                     Example
+============= ========================================================================== =======
+Integer       Any possible integer, either positive (no prefix) or negative (- prefix)   1
+Float         Any possible floating point value; scientific notation is not supported    1.0
+Boolean       Either True or False                                                       True
+String        Any possible string, enclosed with either double or single quotes          "abc"
+Action        An action construct from the Modelverse, prefixed with an exclamation mark !If
+============= ========================================================================== =======
+
+Operators
+^^^^^^^^^
+
+While operators are seemingly supported by the compiler, these are actually expanded to function calls to relevant functions.
+For example, *1 + 2*, is expanded to *integer_addition(1, 2)*
+
+User I/O
+^^^^^^^^
+
+User input and output is done through the keyworded operations *input()* and *output(msg)*.
+*input()* returns the first message in the input queue of the current user.
+*output(msg)* places the value of the expression in the output queue of the current user.
+
+All I/O is done using queues: the value is only read and written to a specific place in the Modelverse.
+To actually read or write it at the client side, these special places should be accessed through dedicated Modelverse operations.
+
 Examples
 --------
 
-Simple addition
-^^^^^^^^^^^^^^^
+We now show some simple code fragments written in valid Action Language code.
+As this code is directly executable in the Modelverse, the main function is always called "main" and all includes are also present.
+We do not currently handle how to execute this code: this is explained further on.
 
 Fibonacci
 ^^^^^^^^^
 
+The Fibonacci code is fairly simple.
+First, the primitives are imported to make sure that we know about all operations on primitives.
+Then, a function *fib* is defined, which will recursively compute the specified Fibonacci number.
+This is wrapped by a *main* function, which takes input from the user and outputs the result of the *fib* function.
+
+This code looks as follows::
+
+    include "primitives.alh"
+
+    Integer function fib(param : Integer):
+        if (param <= 2):
+            return 1!
+        else:
+            return fib(param - 1) + fib(param - 2)!
+
+    Void function main():
+        while(True):
+            output(fib(input()))
+
 Factorial
 ^^^^^^^^^
+
+Similarly, the code for computing a factorial is given below::
+
+    include "primitives.alh"
+
+    Integer function factorial(n : Integer):
+        if(n <= 1):
+            return 1!
+        else:
+            return n * factorial(n - 1)!
+
+    Void function main():
+        while(True):
+            output(factorial(input()))
+

doc/examples.rst

@@ -1,6 +1,21 @@
 Examples
 ========
 
+To run this code, store it in a file (*e.g.*, test.alc), and execute the following commands::
+
+    python scripts/run_local_modelverse.py 8001 &
+    python scripts/make_parallel.py http://localhost:8001 test test.alc bootstrap/primitives.alc
+    python scripts/prompt.py
+
+In the prompt, log on to http://localhost:8001 as user *test*.
+Now, all input you send, will be caught in the *input()* calls seen in the code.
+Results will also be printed.
+
+Note that all content will, by default, be typed as string.
+If you want to send integers or so, prepend the input with a backslash (\\), which allows you to directly input the JSON code.
+For example, input *5* will be received as the string "5".
+To send the integer 5, the input should be *\\5*.
+
 Simple Fibonacci Server
 -----------------------