Added part about interface

doc/_build/html/_sources/communication_models.txt

@@ -40,7 +40,3 @@ MvK server
     For performance reasons, many of these parts are merged together in the *run_local_modelverse.py* script.
     As a result, it only implements the *MvKController*, *Server*, and *Socket* classes.
     A more elaborate statechart implementation also exists, which does implements this whole figure.
-
-The MvK server again has a HTTP server, similar to the one of the MvS, but also has a HTTP client.
-
-Apart from this, there is also a 

doc/_build/html/_sources/components.txt

@@ -21,12 +21,6 @@ To the Modelverse State, all data needs to be representable as a graph, which it
 
 All basic, and some composite, operations are implemented on this graph, such as creating nodes and edges, reading them, and deleting them.
 
-Interface
-^^^^^^^^^
-
-All communication happens through sockets, using XML/HTTP Requests.
-(TODO)
-
 Modelverse Kernel (MvK)
 -----------------------
 
@@ -40,12 +34,6 @@ Complex programs can be written by encoding the program as a graph, and letting
 To allow for maximal flexibility, the MvK can never expose the users to the internal identifier of the MvS, which the MvK uses.
 This allows the MvS to internally restructure itself without having to worry about stale references elsewhere.
 
-Interface
-^^^^^^^^^
-
-All communication happens through sockets, using XML/HTTP Requests.
-(TODO)
-
 Modelverse Interface (MvI)
 --------------------------
 

doc/_build/html/_sources/index.txt

@@ -20,4 +20,5 @@ Contents:
    Advanced examples <advanced>
    Common problems and solutions <problems>
    Internal workings <internal>
+   Interface <interface>
    Network communication models <communication_models>

doc/_build/html/_sources/interface.txt

@@ -0,0 +1,91 @@
+Interface description
+=====================
+
+All Modelverse components communicate with each other through the use of sockets.
+On these sockets, XML/HTTP Requests are used for communication.
+In this brief section, we describe the form of these requests.
+
+MvS server
+----------
+
+The MvS server listens to a fixed set of commands.
+All commands have a fully defined signature and result.
+Note that commands are encoded: a decoding table is presented below.
+
+==== ======================
+Code Description
+==== ======================
+CN   create_node
+CE   create_edge
+CNV  create_nodevalue
+CD   create_dict
+RV   read_value
+RO   read_outgoing
+RI   read_incoming
+RE   read_edge
+RD   read_dict
+RDN  read_dict_node
+RDNE read_dict_node_edge
+RDE  read_dict_edge
+RRD  read_reverse_dict
+RR   read_root
+RDK  read_dict_keys
+DE   delete_edge
+DN   delete_node
+==== ======================
+
+Requests are sent as POST requests (*i.e.*, in the data of a HTTP request).
+They have the following form::
+
+    op=CODE&params=PARAMS
+
+In this case, *CODE* is one of the codes mentioned above, and the value of *PARAMS* is a JSON encoded list of Modelverse identifiers.
+The choice of what is a Modelverse identifier is left to the MvS itself.
+
+The result will be a JSON serialized list containing as first element the response to the request, and as second element the statuscode.
+If the statuscode is 200, the first element will be correct.
+Otherwise, the statuscode indicates the error, and the first element is set to *null*.
+
+MvK server
+----------
+
+The communication with the MvK is a lot easier, as there is only a very minimal interface: the actual interface needs to be explicitly modelled in action language.
+Requests have the following form::
+
+    op=OPERATION&username=USERNAME&value=VALUE
+
+Here, *OPERATION* defines the operation to execute, of which only two exist:
+
+1. *set_input*, which adds the sent value to the input queue of the user;
+2. *get_output*, which blocks until there is a value in the output queue of the user.
+
+Obviously, *USERNAME* specifies the name of the user for which the operation needs to happen.
+
+The *VALUE* is just a JSON encoded value which will be added to the input queue of the Modelverse.
+This is ignored when the *get_output* operation is used.
+Note that there are some minor differences between our encoding and JSON encoding.
+
+The supported types are shown below.
+
+======= ===================
+Type    Example
+======= ===================
+Integer 1
+Float   1.0
+Boolean true
+String  "abc"
+Action  if
+======= ===================
+
+While this list mostly resembles JSON, there are some important differences:
+
+* Lists and objects are not supported;
+* Null object is not supported;
+* Action type is new, and contains a string representation (without quotes!) of the action language construct to add
+
+Performance notes
+^^^^^^^^^^^^^^^^^
+
+For performance reasons, sending a huge amount of data to the Modelverse (*e.g.*, a compiled program), should not happen with individual requests for each line.
+To allow for packed messages, users can ignore the *value* parameter, and use the *data* parameter instead.
+The content of this parameter should be a JSON encoded list of all individual values to be inserted.

doc/_build/html/communication_models.html

@@ -77,8 +77,6 @@ For performance reasons, many of these parts are merged together in the <em>run_
 As a result, it only implements the <em>MvKController</em>, <em>Server</em>, and <em>Socket</em> classes.
 A more elaborate statechart implementation also exists, which does implements this whole figure.</p>
 </div>
-<p>The MvK server again has a HTTP server, similar to the one of the MvS, but also has a HTTP client.</p>
-<p>Apart from this, there is also a</p>
 </div>
 </div>
 

doc/_build/html/components.html

@@ -64,11 +64,6 @@ By using sockets, it becomes possible to switch everything about the implementat
 <p>The Modelverse State implements the data storage features of the Modelverse.
 To the Modelverse State, all data needs to be representable as a graph, which it will manipulate.</p>
 <p>All basic, and some composite, operations are implemented on this graph, such as creating nodes and edges, reading them, and deleting them.</p>
-<div class="section" id="interface">
-<h3>Interface<a class="headerlink" href="#interface" title="Permalink to this headline">¶</a></h3>
-<p>All communication happens through sockets, using XML/HTTP Requests.
-(TODO)</p>
-</div>
 </div>
 <div class="section" id="modelverse-kernel-mvk">
 <h2>Modelverse Kernel (MvK)<a class="headerlink" href="#modelverse-kernel-mvk" title="Permalink to this headline">¶</a></h2>
@@ -79,11 +74,6 @@ Through this architecture, the MvK becomes completely stateless and easily repla
 Complex programs can be written by encoding the program as a graph, and letting the MvK interpret it.</p>
 <p>To allow for maximal flexibility, the MvK can never expose the users to the internal identifier of the MvS, which the MvK uses.
 This allows the MvS to internally restructure itself without having to worry about stale references elsewhere.</p>
-<div class="section" id="id1">
-<h3>Interface<a class="headerlink" href="#id1" title="Permalink to this headline">¶</a></h3>
-<p>All communication happens through sockets, using XML/HTTP Requests.
-(TODO)</p>
-</div>
 </div>
 <div class="section" id="modelverse-interface-mvi">
 <h2>Modelverse Interface (MvI)<a class="headerlink" href="#modelverse-interface-mvi" title="Permalink to this headline">¶</a></h2>
@@ -106,14 +96,8 @@ For example, a graphical tool could serve as an interface to the Modelverse, whe
   <h3><a href="index.html">Table Of Contents</a></h3>
   <ul>
 <li><a class="reference internal" href="#">Modelverse components</a><ul>
-<li><a class="reference internal" href="#modelverse-state-mvs">Modelverse State (MvS)</a><ul>
-<li><a class="reference internal" href="#interface">Interface</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#modelverse-kernel-mvk">Modelverse Kernel (MvK)</a><ul>
-<li><a class="reference internal" href="#id1">Interface</a></li>
-</ul>
-</li>
+<li><a class="reference internal" href="#modelverse-state-mvs">Modelverse State (MvS)</a></li>
+<li><a class="reference internal" href="#modelverse-kernel-mvk">Modelverse Kernel (MvK)</a></li>
 <li><a class="reference internal" href="#modelverse-interface-mvi">Modelverse Interface (MvI)</a></li>
 </ul>
 </li>

doc/_build/html/index.html

@@ -111,6 +111,11 @@
 <li class="toctree-l2"><a class="reference internal" href="internal.html#adding-a-precompiled-function">Adding a precompiled function</a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="interface.html">Interface</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="interface.html#mvs-server">MvS server</a></li>
+<li class="toctree-l2"><a class="reference internal" href="interface.html#mvk-server">MvK server</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="communication_models.html">Network communication models</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="communication_models.html#mvs-server">MvS server</a></li>
 <li class="toctree-l2"><a class="reference internal" href="communication_models.html#mvk-server">MvK server</a></li>

doc/_build/html/interface.html

@@ -0,0 +1,242 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+    
+    <title>Interface description &#8212; Modelverse 0.4.0 documentation</title>
+    
+    <link rel="stylesheet" href="_static/classic.css" type="text/css" />
+    <link rel="stylesheet" href="_static/pygments.css" type="text/css" />
+    
+    <script type="text/javascript">
+      var DOCUMENTATION_OPTIONS = {
+        URL_ROOT:    './',
+        VERSION:     '0.4.0',
+        COLLAPSE_INDEX: false,
+        FILE_SUFFIX: '.html',
+        HAS_SOURCE:  true
+      };
+    </script>
+    <script type="text/javascript" src="_static/jquery.js"></script>
+    <script type="text/javascript" src="_static/underscore.js"></script>
+    <script type="text/javascript" src="_static/doctools.js"></script>
+    <link rel="top" title="Modelverse 0.4.0 documentation" href="index.html" /> 
+  </head>
+  <body role="document">
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             accesskey="I">index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">Modelverse 0.4.0 documentation</a> &#187;</li> 
+      </ul>
+    </div>  
+
+    <div class="document">
+      <div class="documentwrapper">
+        <div class="bodywrapper">
+          <div class="body" role="main">
+            
+  <div class="section" id="interface-description">
+<h1>Interface description<a class="headerlink" href="#interface-description" title="Permalink to this headline">¶</a></h1>
+<p>All Modelverse components communicate with each other through the use of sockets.
+On these sockets, XML/HTTP Requests are used for communication.
+In this brief section, we describe the form of these requests.</p>
+<div class="section" id="mvs-server">
+<h2>MvS server<a class="headerlink" href="#mvs-server" title="Permalink to this headline">¶</a></h2>
+<p>The MvS server listens to a fixed set of commands.
+All commands have a fully defined signature and result.
+Note that commands are encoded: a decoding table is presented below.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="15%" />
+<col width="85%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Code</th>
+<th class="head">Description</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>CN</td>
+<td>create_node</td>
+</tr>
+<tr class="row-odd"><td>CE</td>
+<td>create_edge</td>
+</tr>
+<tr class="row-even"><td>CNV</td>
+<td>create_nodevalue</td>
+</tr>
+<tr class="row-odd"><td>CD</td>
+<td>create_dict</td>
+</tr>
+<tr class="row-even"><td>RV</td>
+<td>read_value</td>
+</tr>
+<tr class="row-odd"><td>RO</td>
+<td>read_outgoing</td>
+</tr>
+<tr class="row-even"><td>RI</td>
+<td>read_incoming</td>
+</tr>
+<tr class="row-odd"><td>RE</td>
+<td>read_edge</td>
+</tr>
+<tr class="row-even"><td>RD</td>
+<td>read_dict</td>
+</tr>
+<tr class="row-odd"><td>RDN</td>
+<td>read_dict_node</td>
+</tr>
+<tr class="row-even"><td>RDNE</td>
+<td>read_dict_node_edge</td>
+</tr>
+<tr class="row-odd"><td>RDE</td>
+<td>read_dict_edge</td>
+</tr>
+<tr class="row-even"><td>RRD</td>
+<td>read_reverse_dict</td>
+</tr>
+<tr class="row-odd"><td>RR</td>
+<td>read_root</td>
+</tr>
+<tr class="row-even"><td>RDK</td>
+<td>read_dict_keys</td>
+</tr>
+<tr class="row-odd"><td>DE</td>
+<td>delete_edge</td>
+</tr>
+<tr class="row-even"><td>DN</td>
+<td>delete_node</td>
+</tr>
+</tbody>
+</table>
+<p>Requests are sent as POST requests (<em>i.e.</em>, in the data of a HTTP request).
+They have the following form:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">op</span><span class="o">=</span><span class="n">CODE</span><span class="o">&amp;</span><span class="n">params</span><span class="o">=</span><span class="n">PARAMS</span>
+</pre></div>
+</div>
+<p>In this case, <em>CODE</em> is one of the codes mentioned above, and the value of <em>PARAMS</em> is a JSON encoded list of Modelverse identifiers.
+The choice of what is a Modelverse identifier is left to the MvS itself.</p>
+<p>The result will be a JSON serialized list containing as first element the response to the request, and as second element the statuscode.
+If the statuscode is 200, the first element will be correct.
+Otherwise, the statuscode indicates the error, and the first element is set to <em>null</em>.</p>
+</div>
+<div class="section" id="mvk-server">
+<h2>MvK server<a class="headerlink" href="#mvk-server" title="Permalink to this headline">¶</a></h2>
+<p>The communication with the MvK is a lot easier, as there is only a very minimal interface: the actual interface needs to be explicitly modelled in action language.
+Requests have the following form:</p>
+<div class="highlight-default"><div class="highlight"><pre><span class="n">op</span><span class="o">=</span><span class="n">OPERATION</span><span class="o">&amp;</span><span class="n">username</span><span class="o">=</span><span class="n">USERNAME</span><span class="o">&amp;</span><span class="n">value</span><span class="o">=</span><span class="n">VALUE</span>
+</pre></div>
+</div>
+<p>Here, <em>OPERATION</em> defines the operation to execute, of which only two exist:</p>
+<ol class="arabic simple">
+<li><em>set_input</em>, which adds the sent value to the input queue of the user;</li>
+<li><em>get_output</em>, which blocks until there is a value in the output queue of the user.</li>
+</ol>
+<p>Obviously, <em>USERNAME</em> specifies the name of the user for which the operation needs to happen.</p>
+<p>The <em>VALUE</em> is just a JSON encoded value which will be added to the input queue of the Modelverse.
+This is ignored when the <em>get_output</em> operation is used.
+Note that there are some minor differences between our encoding and JSON encoding.</p>
+<p>The supported types are shown below.</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="27%" />
+<col width="73%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Type</th>
+<th class="head">Example</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td>Integer</td>
+<td>1</td>
+</tr>
+<tr class="row-odd"><td>Float</td>
+<td>1.0</td>
+</tr>
+<tr class="row-even"><td>Boolean</td>
+<td>true</td>
+</tr>
+<tr class="row-odd"><td>String</td>
+<td>&#8220;abc&#8221;</td>
+</tr>
+<tr class="row-even"><td>Action</td>
+<td>if</td>
+</tr>
+</tbody>
+</table>
+<p>While this list mostly resembles JSON, there are some important differences:</p>
+<ul class="simple">
+<li>Lists and objects are not supported;</li>
+<li>Null object is not supported;</li>
+<li>Action type is new, and contains a string representation (without quotes!) of the action language construct to add</li>
+</ul>
+<div class="section" id="performance-notes">
+<h3>Performance notes<a class="headerlink" href="#performance-notes" title="Permalink to this headline">¶</a></h3>
+<p>For performance reasons, sending a huge amount of data to the Modelverse (<em>e.g.</em>, a compiled program), should not happen with individual requests for each line.
+To allow for packed messages, users can ignore the <em>value</em> parameter, and use the <em>data</em> parameter instead.
+The content of this parameter should be a JSON encoded list of all individual values to be inserted.</p>
+</div>
+</div>
+</div>
+
+
+          </div>
+        </div>
+      </div>
+      <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+        <div class="sphinxsidebarwrapper">
+  <h3><a href="index.html">Table Of Contents</a></h3>
+  <ul>
+<li><a class="reference internal" href="#">Interface description</a><ul>
+<li><a class="reference internal" href="#mvs-server">MvS server</a></li>
+<li><a class="reference internal" href="#mvk-server">MvK server</a><ul>
+<li><a class="reference internal" href="#performance-notes">Performance notes</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+
+  <div role="note" aria-label="source link">
+    <h3>This Page</h3>
+    <ul class="this-page-menu">
+      <li><a href="_sources/interface.txt"
+            rel="nofollow">Show Source</a></li>
+    </ul>
+   </div>
+<div id="searchbox" style="display: none" role="search">
+  <h3>Quick search</h3>
+    <form class="search" action="search.html" method="get">
+      <div><input type="text" name="q" /></div>
+      <div><input type="submit" value="Go" /></div>
+      <input type="hidden" name="check_keywords" value="yes" />
+      <input type="hidden" name="area" value="default" />
+    </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+        </div>
+      </div>
+      <div class="clearer"></div>
+    </div>
+    <div class="related" role="navigation" aria-label="related navigation">
+      <h3>Navigation</h3>
+      <ul>
+        <li class="right" style="margin-right: 10px">
+          <a href="genindex.html" title="General Index"
+             >index</a></li>
+        <li class="nav-item nav-item-0"><a href="index.html">Modelverse 0.4.0 documentation</a> &#187;</li> 
+      </ul>
+    </div>
+    <div class="footer" role="contentinfo">
+        &#169; Copyright 2016, Yentl Van Tendeloo.
+      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.4.6.
+    </div>
+  </body>
+</html>

doc/components.rst

@@ -21,12 +21,6 @@ To the Modelverse State, all data needs to be representable as a graph, which it
 
 All basic, and some composite, operations are implemented on this graph, such as creating nodes and edges, reading them, and deleting them.
 
-Interface
-^^^^^^^^^
-
-All communication happens through sockets, using XML/HTTP Requests.
-(TODO)
-
 Modelverse Kernel (MvK)
 -----------------------
 
@@ -40,12 +34,6 @@ Complex programs can be written by encoding the program as a graph, and letting
 To allow for maximal flexibility, the MvK can never expose the users to the internal identifier of the MvS, which the MvK uses.
 This allows the MvS to internally restructure itself without having to worry about stale references elsewhere.
 
-Interface
-^^^^^^^^^
-
-All communication happens through sockets, using XML/HTTP Requests.
-(TODO)
-
 Modelverse Interface (MvI)
 --------------------------
 

doc/index.rst

@@ -20,4 +20,5 @@ Contents:
    Advanced examples <advanced>
    Common problems and solutions <problems>
    Internal workings <internal>
+   Interface <interface>
    Network communication models <communication_models>

doc/interface.rst

@@ -0,0 +1,91 @@
+Interface description
+=====================
+
+All Modelverse components communicate with each other through the use of sockets.
+On these sockets, XML/HTTP Requests are used for communication.
+In this brief section, we describe the form of these requests.
+
+MvS server
+----------
+
+The MvS server listens to a fixed set of commands.
+All commands have a fully defined signature and result.
+Note that commands are encoded: a decoding table is presented below.
+
+==== ======================
+Code Description
+==== ======================
+CN   create_node
+CE   create_edge
+CNV  create_nodevalue
+CD   create_dict
+RV   read_value
+RO   read_outgoing
+RI   read_incoming
+RE   read_edge
+RD   read_dict
+RDN  read_dict_node
+RDNE read_dict_node_edge
+RDE  read_dict_edge
+RRD  read_reverse_dict
+RR   read_root
+RDK  read_dict_keys
+DE   delete_edge
+DN   delete_node
+==== ======================
+
+Requests are sent as POST requests (*i.e.*, in the data of a HTTP request).
+They have the following form::
+
+    op=CODE&params=PARAMS
+
+In this case, *CODE* is one of the codes mentioned above, and the value of *PARAMS* is a JSON encoded list of Modelverse identifiers.
+The choice of what is a Modelverse identifier is left to the MvS itself.
+
+The result will be a JSON serialized list containing as first element the response to the request, and as second element the statuscode.
+If the statuscode is 200, the first element will be correct.
+Otherwise, the statuscode indicates the error, and the first element is set to *null*.
+
+MvK server
+----------
+
+The communication with the MvK is a lot easier, as there is only a very minimal interface: the actual interface needs to be explicitly modelled in action language.
+Requests have the following form::
+
+    op=OPERATION&username=USERNAME&value=VALUE
+
+Here, *OPERATION* defines the operation to execute, of which only two exist:
+
+1. *set_input*, which adds the sent value to the input queue of the user;
+2. *get_output*, which blocks until there is a value in the output queue of the user.
+
+Obviously, *USERNAME* specifies the name of the user for which the operation needs to happen.
+
+The *VALUE* is just a JSON encoded value which will be added to the input queue of the Modelverse.
+This is ignored when the *get_output* operation is used.
+Note that there are some minor differences between our encoding and JSON encoding.
+
+The supported types are shown below.
+
+======= ===================
+Type    Example
+======= ===================
+Integer 1
+Float   1.0
+Boolean true
+String  "abc"
+Action  if
+======= ===================
+
+While this list mostly resembles JSON, there are some important differences:
+
+* Lists and objects are not supported;
+* Null object is not supported;
+* Action type is new, and contains a string representation (without quotes!) of the action language construct to add
+
+Performance notes
+^^^^^^^^^^^^^^^^^
+
+For performance reasons, sending a huge amount of data to the Modelverse (*e.g.*, a compiled program), should not happen with individual requests for each line.
+To allow for packed messages, users can ignore the *value* parameter, and use the *data* parameter instead.
+The content of this parameter should be a JSON encoded list of all individual values to be inserted.