modelverse/doc/examples.rst

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*.

Fibonacci Server
----------------

The first example is a simple Fibonacci server.
The code is identical to the action language example from before, as this already included the *server* part (*i.e.*, the while loop).
Now we will just connect to it using *prompt.py* and try out the code directly.

The code is repeated below::

    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()))

To run this code, save it to a file (*e.g.*, fibonacci.alc) and execute the following command::

    python scripts/run_local_modelverse.py 8001
    
Now, the Modelverse is running, but we still need to upload our code.
To compile the file, together with the primitives.alc file, execute the following command::

    python scripts/make_parallel.py http://localhost:8001 test fibonacci.alc bootstrap/primitives.alc

When this finishes, the Modelverse now stores a copy of our code in its own format.
The Modelverse will automatically create the user *test* and start executing the *main* function as this user.
We can therefore simply connect to the Modelverse as the *test* user and start seeing the responses.
To start the prompt, execute the following command::

    python scripts/prompt.py
    
In this prompt tool, you first have to configure the location of the Modelverse and the username.
The defaults should be fine, so just press <return> twice.
After that, you are in direct connection with the Modelverse.
Each message you type in, is made available in the *input()* function of the code.
Remember that, to send integers, you have to prefix this with a backslash (\\).
To get, for example, the 1st Fibonacci number, type in the command::

    \1

You will now see the following.

.. image:: img/prompt_fibonacci.png

Since we are in an unconditional loop, you can send as many requests as you want, as long as they are understandable by the *fib* function.

.. image:: img/prompt_fibonacci_more.png

Inputting a string directly, such as *1* instead of *\\1*, will make the Modelverse crash on the execution of this code.
This is normal, though in the future the Modelverse will keep running for other users: only the current user's code will be interrupted.

Modelling Server
----------------

The simple Fibonacci server is not very relevant to the primary concern of the Modelverse: (meta-)modelling.
But since we can create whatever kind of server we want, a simple (meta-)modelling server is created.
The code offers an interface for users to execute modelling operations.
The interface itself mostly just relays the incoming messages and operations to the internal modelling library.

The full code is seen below::

    include "primitives.alh"
    include "constructors.alh"
    include "object_operations.alh"
    include "library.alh"
    include "conformance_scd.alh"
    include "io.alh"
    include "metamodels.alh"
    include "modelling.alh"
    include "compilation_manager.alh"

    Element function model_loaded(model : Element):
        String cmd

        Element attr_list_pn
        Element attr_keys_pn
        String attr_key_pn
        Element metamodel_element_pn
        String typename
        Boolean bottom
        Element other_metamodel

        bottom = False
        other_metamodel = create_node()
        dict_add(other_metamodel, "model", model["model"])
        dict_add(other_metamodel, "type_mapping", create_node())
        dict_add(other_metamodel, "metamodel", import_node("models/LTM_bottom"))
        dict_add(other_metamodel, "inheritance", other_metamodel["metamodel"]["model"]["__Inheritance"])

        output("Model loaded, ready for commands!")
        output("Use 'help' command for a list of possible commands")

        while (True):
            output("Please give your command.")
            cmd = input()
            if (cmd == "help"):
                output("Generic model operations:")
                output("  instantiate -- Create a new model element")
                output("  delete      -- Delete an existing element")
                output("  attr_add    -- Add an attribute to an element")
                output("  attr_del    -- Delete an attribute of an element")
                output("  constrain   -- Add a constraint function to the model")
                output("  rename      -- Rename an existing element")
                output("  modify      -- Modify the attributes of an element")
                output("  list        -- Prints the list of elements in the model")
                output("  types       -- Prints the list of elements that can be instantiated")
                output("  read        -- Prints the current state of a model element")
                output("  verify      -- Check whether the model conforms to the metamodel")
                output("  retype      -- Change the type of an element")
                output("  switch      -- Switch between conformance bottom and the linguistic metamodel")
                output("  exit        -- Unload the model and go back to the loading prompt")
            elif (cmd == "exit"):
                return model!
            elif (cmd == "instantiate"):
                String mm_type_name
                output("Type to instantiate?")
                mm_type_name = input()
                if (dict_in(model["metamodel"]["model"], mm_type_name)):
                    String element_name
                    output("Name of new element?")
                    element_name = input()
                    if (dict_in(model["model"], element_name)):
                        output("Element already exists; aborting")
                    else:
                        if (is_edge(model["metamodel"]["model"][mm_type_name])):
                            output("Source name?")
                            String src_name
                            src_name = input()
                            if (dict_in(model["model"], src_name)):
                                output("Destination name?")
                                String dst_name
                                dst_name = input()
                                if (dict_in(model["model"], dst_name)):
                                    instantiate_link(model, mm_type_name, element_name, src_name, dst_name)
                                    output("Instantiation successful!")
                                else:
                                    output("Unknown destination; aborting")
                            else:
                                output("Unknown source; aborting")
                        else:
                            instantiate_node(model, mm_type_name, element_name)
                            output("Instantiation successful!")
                else:
                    output("Unknown type specified; aborting")
            elif (cmd == "set_inheritance"):
                String inh_name

                output("Which link in the metamodel is the inheritance link?")
                inh_name = input()

                if (dict_in(model["metamodel"]["model"], inh_name)):
                    dict_add(model, "inheritance", model["metamodel"]["model"][inh_name])
                    output("Set inheritance link!")
                else:
                    output("Element not found in metamodel; aborting")

            elif (cmd == "constrain"):
                output("Element to constrain (empty for global)?")
                String model_name
                model_name = input()

                if (model_name == ""):
                    // Global constraint
                    output("Give input to function constructors for GLOBAL constraint!")
                    set_model_constraints(model, construct_function())
                elif (dict_in(model["model"], model_name)):
                    // Local constraint for this model
                    output("Give input to function constructors for LOCAL constraint!")
                    add_constraint(model, model_name, construct_function())
                    output("Added constraint to model!")
                else:
                    // Local constraint, but model not found
                    output("Unknown model; aborting")
            elif (cmd == "modify"):
                String model_name
                output("Element to modify?")
                model_name = input()
                if (dict_in(model["model"], model_name)):
                    Element attrs
                    attrs = getAttributeList(model, model_name)
                    String attr_name
                    output("Attribute to modify?")
                    attr_name = input()
                    if (set_in(dict_keys(attrs), attr_name)):
                        output("New value?")
                        unset_attribute(model, model_name, attr_name)
                        instantiate_attribute(model, model_name, attr_name, input())
                        output("Modified!")
                    else:
                        output("No such attribute!")
                else:
                    output("No such model!")
            elif (cmd == "attr_add"):
                String model_name
                output("Which model do you want to assign an attribute to?")
                model_name = input()
                if (dict_in(model["model"], model_name)):
                    Element attrs
                    attrs = getAttributeList(model, model_name)
                    String attr_name
                    output("Which attribute do you wish to assign?")
                    attr_name = input()
                    if (set_in(dict_keys(attrs), attr_name)):
                        output("Value of attribute?")
                        instantiate_attribute(model, model_name, attr_name, input())
                        output("Added attribute!")
                    else:
                        output("No such attribute!")
                else:
                    output("No such model!")
            elif (cmd == "attr_del"):
                String model_name
                output("Which model do you want to remove an attribute of?")
                model_name = input()
                if (dict_in(model["model"], model_name)):
                    Element attrs
                    attrs = getAttributeList(model, model_name)
                    String attr_name
                    output("Which attribute do you want to delete?")
                    attr_name = input()
                    if (set_in(dict_keys(attrs), attr_name)):
                        unset_attribute(model, model_name, attr_name)
                        output("Attribute deleted!")
                    else:
                        output("No such attribute!")
                else:
                    output("No such model!")
            elif (cmd == "delete"):
                output("What is the name of the element you want to delete?")
                cmd = input()
                if (dict_in(model["model"], cmd)):
                    model_delete_element(model, cmd)
                    output("Deleted!")
                else:
                    output("No such element; aborting")
            elif (cmd == "rename"):
                output("Old name?")
                String old_name_e
                old_name_e = input()
                if (dict_in(model["model"], old_name_e)):
                    output("New name?")
                    String new_name_e
                    new_name_e = input()
                    if (dict_in(model["model"], new_name_e)):
                        output("New name already used; aborting")
                    else:
                        dict_add(model["model"], new_name_e, model["model"][old_name_e])
                        dict_delete(model["model"], old_name_e)
                        output("Rename complete!")
                else:
                    output("Unknown element; aborting")
            elif (cmd == "list"):
                Element keys_m
                keys_m = dict_keys(model["model"])
                output("List of all elements:")
                String v_m
                while (read_nr_out(keys_m) > 0):
                    v_m = set_pop(keys_m)
                    // Filter out anonymous objects
                    if (bool_not(string_startswith(v_m, "__"))):
                        typename = reverseKeyLookup(model["metamodel"]["model"], dict_read_node(model["type_mapping"], model["model"][v_m]))
                        output((("  " + v_m) + " : ") + typename)
            elif (cmd == "read"):
                output("Element to read?")
                cmd = input()
                if (dict_in(model["model"], cmd)):
                    Element read_elem
                    read_elem = model["model"][cmd]
                    metamodel_element_pn = dict_read_node(model["type_mapping"], read_elem)

                    output("Name: " + cmd)
                    output("Type: " + reverseKeyLookup(model["metamodel"]["model"], metamodel_element_pn))
                    if (is_edge(read_elem)):
                        output("Source: " + reverseKeyLookup(model["model"], read_edge_src(read_elem)))
                        output("Destination: " + reverseKeyLookup(model["model"], read_edge_dst(read_elem)))
                    if (cast_v2s(read_elem) != "None"):
                        output("Value: " + cast_v2s(read_elem))
                    output("Defines attributes:")
                    attr_list_pn = getInstantiatableAttributes(model, read_elem)
                    attr_keys_pn = dict_keys(attr_list_pn)
                    while (0 < read_nr_out(attr_keys_pn)):
                        attr_key_pn = set_pop(attr_keys_pn)
                        output(((("  " + attr_key_pn) + " : ") + cast_v2s(attr_list_pn[attr_key_pn])))
                    output("Attributes:")
                    attr_list_pn = getAttributeList(model, cmd)
                    attr_keys_pn = dict_keys(attr_list_pn)
                    while (0 < read_nr_out(attr_keys_pn)):
                        attr_key_pn = set_pop(attr_keys_pn)
                        output((((("  " + cast_v2s(attr_key_pn)) + " : ") + cast_v2s(attr_list_pn[attr_key_pn])) + " = ") + cast_v2s(read_attribute(model, reverseKeyLookup(model["model"], read_elem), attr_key_pn)))
                else:
                    output("Unknown element; aborting")
            elif (cmd == "verify"):
                output(conformance_scd(model))
            elif (cmd == "types"):
                Element keys_t
                keys_t = dict_keys(model["metamodel"]["model"])
                output("List of types:")
                String v_t
                while (read_nr_out(keys_t) > 0):
                    v_t = set_pop(keys_t)
                    if (bool_not(string_startswith(v_t, "__"))):
                        output(string_join(("  " + v_t) + " : ", reverseKeyLookup(model["metamodel"]["metamodel"]["model"], dict_read_node(model["metamodel"]["type_mapping"], model["metamodel"]["model"][v_t]))))
            elif (cmd == "retype"):
                output("Element to retype?")
                String elementname
                elementname = input()
                if (dict_in(model["model"], elementname)):
                    output("New type")
                    typename = input()
                    if (dict_in(model["metamodel"]["model"], typename)):
                        // OK, do the retyping
                        // First try removing the previous type if it exists
                        dict_delete(model["type_mapping"], model["model"][elementname])
                        // Now add the new type
                        dict_add(model["type_mapping"], model["model"][elementname], model["metamodel"]["model"][typename])
                        output("Retyped!")
                    else:
                        output("Unknown type; aborting")
                else:
                    output("Unknown element; aborting")
            elif (cmd == "switch"):
                bottom = bool_not(bottom)

                Element tmp_model
                tmp_model = model
                model = other_metamodel
                other_metamodel = tmp_model

                if (bottom):
                    // The type mapping we are using is probably not complete for our model
                    // so we completely recreate it from the model we have.
                    output("Switching to conformance bottom mode!")
                    generate_bottom_type_mapping(model)
                else:
                    // We already switched the models and such, so we are already done!
                    output("Switching to linguistic metamodel!")
            else:
                output("Unknown command: " + cast_v2s(cmd))
                output("Use command 'help' to get a list of available commands")

    Element function main():
        output("Welcome to the Model Management Interface, running live on the Modelverse!")
        output("Use 'help' command for a list of possible commands")
        String command
        Element root
        Element metamodel
        String name
        Element my_model
        String mm_name

        root = create_metamodels()

        while (True):
            output("Please give your command.")
            command = input()

            if (command == "help"):
                output("Currently no model is loaded, so your operations are limited to:")
                output("  new    -- Create a new model and save it for future use")
                output("  load   -- Load a previously made model")
                output("  rename -- Rename a previously made model")
                output("  delete -- Delete a previously made model")
                output("  list   -- Show a list of all stored models")
                output("  help   -- Show a list of possible commands")
            elif (command == "new"):
                output("Metamodel to instantiate?")
                mm_name = input()
                if (dict_in(root, mm_name)):
                    output("Name of model?")
                    name = input()
                    if (dict_in(root, name)):
                        output("Model exists; aborting")
                    else:
                        my_model = instantiate_model(root[mm_name])
                        dict_add(root, name, my_model)
                        model_loaded(my_model)
                else:
                    output("Unknown metamodel; aborting")
            elif (command == "load"):
                output("Model to load?")
                name = input()
                if (dict_in(root, name)):
                    my_model = root[name]
                    model_loaded(my_model)
                else:
                    output("Model not found; aborting")
            elif (command == "list"):
                Element keys
                String m_menu_list
                keys = dict_keys(root)
                output("Found models:")
                while (read_nr_out(keys) > 0):
                    m_menu_list = set_pop(keys)
                    output((("  " + m_menu_list) + " : ") + reverseKeyLookup(root, root[m_menu_list]["metamodel"]))
            elif (command == "delete"):
                output("Model to delete?")
                name = input()
                if (dict_in(root, name)):
                    dict_delete(root, name)
                    output("Deleted!")
                else:
                    output("Model not found; aborting")
            elif (command == "rename"):
                output("Old name?")
                String old_name
                old_name = input()
                if (dict_in(root, old_name)):
                    output("New name?")
                    String new_name
                    new_name = input()
                    if (dict_in(root, new_name)):
                        output("Model exists; aborting")
                    else:
                        dict_add(root, new_name, root[old_name])
                        dict_delete(root, old_name)
                        output("Rename complete!")
                else:
                    output("Model not found; aborting")
            elif (command == "actions"):
                output("Switching to compilation manager!")
                compilation_manager()
                output("Back in model manager!")
            else:
                output("Command not recognized, use 'help' for a list of possible commands")

This code implements a very simple (meta-)modelling tool.
Its use is documented with the provided *help* function.
A simple example of its use is shown below.

.. image:: img/prompt_pn_interface.png

In this case, note that the value of tokens is the string 3 instead of the integer (or natural) 3.
Therefore, the conformance check will flag this value as incorrectly typed.

Upload model
------------

Uploading a model, and using it, is very similar to what you usually do.
The exception is that your model will be added before any code is executed.
That way, you can just execute the same modelling server, but include a model in it.
Doing that, your interface will see additional models with the *list* command.

The command for this is (instead of the *make_all.py* script)::

    python scripts/execute_model.py http://localhost:8001 test bootstrap/*.alc integration/code/pn_interface.alc integration/code/rpgame.mvc