modelverse/techreport/general/modelverse_interface.tex

\chapter{Modelverse Interface}

\section{Browser}
As the Modelverse uses ordinary XML/HTTP requests, it is possible to easily transfer data through normal web clients, such as internet browsers.
Since these clients are not built with the Modelverse in mind, users will have to use the raw API of the Modelverse Kernel (\textit{i.e.}, using \texttt{set\_input} and \texttt{get\_output}).

\section{Serialized Graph}
The most efficient, though also most low-level, way of transferring a model to the Modelverse, is through the serialisation of a graph structure.
This graph, following a very minimal description format, will subsequently be merged into the current Modelverse graph.
After serialization, the entry point to the graph is returned.

This approach is very efficient, as it constitutes a single call to the Modelverse with the complete graph.
All serialization and deserialization will happen in pure Python code (thus not explicitly modelled!), so basically everything is possible.

The problem with this approach is that the interface needs to know the internal representation of models inside of the Modelverse.
All connections need to be made manually, and the serialization format also needs to be known.
It is therefore not recommended to use this interface, unless no other option is possible (\textit{i.e.}, during bootstrapping).

\section{HUTN for Action Language}
The more elegant way of sending action code to the Modelverse, is by using the explicitly modelled constructors.
These constructors are simple action code that was previously loaded inside the Modelverse, which interprets the requests send to it as creation requests.
While this is much less efficient, models can be created on-the-fly (without first creating the complete graph in the interface), and follows a standardized interface.
Future changes to the internal representation of models will not affect these calls, as the actual creation of the model happens in the Modelverse itself.
Users need thus only know Table~\ref{table:constructors}, which contains a list of all understood construction requests.

Apart from hiding basic complexity (the names of the links), it also has simple requests to make more difficult constructs, such as function declarations or function calls.
Furthermore, all complexity is hidden from the user, as all identifiers are kept in the Modelverse.
Only those identifiers that need to be passed (\textit{i.e.}, variable declarations), will be provided to the interface.

This is the recommended interface to use when transferring models to the Modelverse.

\begin{table}
\begin{tabular}{l|l l}
instruction     & parameter     & type              \\
\hline
if              & condition     & instruction       \\
                & then          & instruction       \\
                & else?         & instruction       \\
                & next?         & instruction       \\
\hline
while           & condition     & instruction       \\
                & body          & instruction       \\
                & next?         & instruction       \\
\hline
access          & lvalue        & instruction       \\
\hline
resolve         & variable      & variable          \\
\hline
assign          & lvalue        & instruction       \\
                & rvalue        & instruction       \\
                & next?         & instruction       \\
\hline
call            & function      & instruction       \\
                & nrParams      & integer           \\
                & name\#        & string            \\
                & value\#       & instruction       \\
                & next?         & instruction       \\
\hline
return          & value?        & instruction       \\
\hline
const           & value         & anything          \\
\hline
declare         & variable!     & variable          \\
\hline
global          & variable!     & variable          \\
\hline
output          & value         & instruction       \\
                & next?         & instruction       \\
\hline
input           &               &                   \\
\hline
deref           & link          & string            \\
\hline
funcdef         & variable      & variable          \\
                & nrParams      & integer           \\
                & name\#        & string            \\
                & formal!\#     & variable          \\
                & body          & instruction       \\
                & next?         & instruction       \\
\hline
break           &               &                   \\
\hline
continue        &               &                   \\
\hline
\end{tabular}
\caption{List of constructor keywords and parameters they take (in order). Questionmark after a parameter means that you first need to pass true/false for whether or not the element exists. Exclamation mark indicates that this is output at this place. A hash means that it occurs as often as previously specified.}
\end{table}

\section{HUTN for Models}