modelverse/doc/interaction.rst

Basic Interaction
=================

As previously mentioned during the installation phase, the Modelverse is merely a collection of scripts.
We briefly present how the Modelverse is structured, and introduce the most important scripts for general use.
A more elaborate view on the architecture and the different scripts is only required for developers of the Modelverse.

Simplified Architecture
-----------------------

The Modelverse architecture consists of three core concepts, which will be referred to throughout the documentation.

Modelverse State (MvS)
^^^^^^^^^^^^^^^^^^^^^^

The Modelverse State (MvS) is the memory of the Modelverse, and contains all data pertaining to it.
This includes not only the different models created by the users, but also all metamodels, transformations, operations, but also all bootstrap files.
Furthermore, it includes all execution state of operations being executed in the Modelverse.
As such, the Modelverse State is the database of the Modelverse, which is the only component containing data.
Only developers will ever have to directly interface with the Modelverse State.

Modelverse Kernel (MvK)
^^^^^^^^^^^^^^^^^^^^^^^

The Modelverse Kernel (MvK) is the execution core of the Modelverse, and connects to the Modelverse State to fetch the instructions to execute.
All its execution information is stored in the MvS as well, and therefore it has to (theoretically) query the MvS for each and every instruction.
It merely consists of a set of model transformation rules which take the current state of the MvS, and do a set of modifications on it.
Only developers will ever have to directly interface with the Modelverse Kernel.

Modelverse Interface (MvI)
^^^^^^^^^^^^^^^^^^^^^^^^^^

The Modelverse Interface (MvI) is the actual interface used by most users of the Modelverse.
It provides any type of interface, whether it be graphical, textual, or any other interface.
While this is the component that users interact with, there should be no (meta-)modelling knowledge whatsoever in this part, as it is only responsible for providing a user-friendly interface to the Modelverse.
This component can make use of the provided wrapper, which does the binding with the Modelverse.

Necessary scripts
-----------------

The Modelverse consists of a set of scripts.
For most users, there are only three relevant scripts, none of them taking parameters:

1. *run_tests.py*, which runs all tests.
2. *run_local_modelverse.py*, which starts up a local Modelverse server, combining the MvS and MvK.
3. *prompt.py*, which connects to the local Modelverse and provides a minimal raw interface.

Wrapper
-------

In addition to these scripts, we provide a simple Python-based wrapper for the Modelverse.
As the Modelverse can run as a service, wrappers can be created in any language that supports XML/HTTPRequests.
By default, a Python wrapper is provided, which is discussed in this documentation.
This Python wrapper was used by a variety of MvI implementations supported today.
Tools can include all Modelverse operations merely by including the *modelverse.py* file from the *wrappers* folder.

The wrapper provides all necessary (meta-)modelling operations that can be used by the MvI.
As the Modelverse is independent of its (visual/textual) user interface, we only discuss the Modelverse wrapper in this documentation.
The wrapper functions are explained through the use of examples, in a tutorial-like fashion.
A full overview of all wrapper functions is also provided at the end of the documentation.

Initializing the Modelverse
^^^^^^^^^^^^^^^^^^^^^^^^^^^

Before we start, we must connect to the Modelverse.
This can be done by executing the operation *init*::

    >>> init("http://modelverse.uantwerpen.be")

This assumes that there is a Modelverse running at the specified address.
It is also possible to work fully locally.
For that, you must start up a Modelverse at your own system by invoking the command::

    python scripts/run_local_modelverse.py

Afterwards, connect to the local Modelverse through the usual *init* operation.
Note that, for a local Modelverse, the init can be left empty::

    >>> init()

Logging in
^^^^^^^^^^

Now that we are connected to the Modelverse, we need to log in.
Without logging in, the Modelverse has no clue which operations are permitted, and which models are readable, or even writable.
To log in, use the *login* operation::

    >>> login("yentl", "secret password")

The operation will succeed if it terminates normally, and throw a Python exception otherwise.
When the username does not exist yet, it is created upon invocation.
The provided password can be used in subsequent invocations of the Modelverse to login as this user again.

If this command finished successfully, the Modelverse is ready to be used.