Added some examples for the Python wrapper

doc/wrappers.rst

@@ -37,6 +37,16 @@ Functions
    The timeout includes all HTTP errors, and will therefore keep retrying even on failed attempts.
    As this request is synchronous, like all others, it will block until a connection has been established.
 
+   Examples:
+
+   To create a connection to the Modelverse that runs locally at port 8001 (default configuration):
+   .. code::
+      >> init()
+
+   To create a connection to the Modelverse running remotely:
+   .. code::
+      >> init("http://modelverse.uantwerpen.be:8001")
+
 .. function:: login(username, password)
 
    Explanation
@@ -44,6 +54,12 @@ Functions
    If the user does not exist, it will create a new user with the specified password.
    If the user already exists, it will try to log in with the provided password.
 
+   Examples:
+
+   To login as user yentl, with the specified password:
+   .. code::
+      >> login("yentl", "my_password")
+
 .. function:: model_add(model_name, metamodel_name, model_code=None)
 
    Explanation
@@ -52,6 +68,20 @@ Functions
    This string is parsed using the HUTN compiler and subsequently sent to the Modelverse.
    When *model_code* is empty, an empty model is created.
 
+   Examples:
+
+   To create a new model called PetriNets, conforming to SimpleClassDiagrams, and load the model stored in models/PetriNets.mvc:
+   .. code::
+      >> model_add("PetriNets", "SimpleClassDiagrams", open("models/PetriNets.mvc", "r").read())
+
+   To create a minimal instance of the language afterwards, which only contains a single place (and no attributes):
+   .. code::
+      >> model_add("my_pn", "PetriNets", """Place p1 {}""")
+
+   To create a less minimal instance of the language, stored in models/my_pn2.mvc:
+   .. code::
+      >> model_add("my_pn2", "PetriNets", open("models/my_pn2.mvc", "r").read())
+
 .. function:: upload_code(code)
 
    Upload a string of *code* in the Action Language formalism.
@@ -59,37 +89,103 @@ Functions
    Makes the assumption that the **construct_function()** operation is currently running on the Modelverse, as otherwise the data will be misinterpreted.
    This is normally only useful in model transformations, where you want to upload a piece of code on-the-fly (e.g., adding a breakpoint in Action Language).
 
+   Examples:
+
+   To upload the file models/code.alc:
+   .. code::
+      >> upload_code(open("models/code.alc", "r").read())
+
+   To upload a code fragment inline:
+   .. code::
+      >> upload_code("Void function a():\nreturn!")
+
 .. function:: model_delete(model_name)
 
    Delete the model referred to by name *model_name*.
    This is a non-cascading delete, with almost no checks: model transformations depending on this model will likely become corrupted.
 
+   Examples:
+
+   To delete a previously created model:
+   .. code::
+      >> model_delete("my_pn2")
+
+   Or to delete a metamodel, which is itself just a model:
+   .. code::
+      >> model_delete("PetriNets")
+
 .. function:: model_list()
 
    Returns a list of all models existing in the Modelverse, together with their type.
 
+   Examples:
+
+   .. code::
+      >> model_list()
+      [("my_pn", "PetriNets"), 
+       ("my_pn2", "PetriNets"),
+       ("PetriNets", "SimpleClassDiagrams"),
+       ("SimpleClassDiagrams", "SimpleClassDiagrams")]
+
 .. function:: model_list_full()
 
    Returns a detailed list of all models existing in the Modelverse.
    This list includes information on permissions, owner, and group.
 
+   Examples:
+
+   .. code::
+      >> model_list_full()
+      [("my_pn", "PetriNets", "yentl", "users", "200"), 
+       ("my_pn2", "PetriNets", "yentl", "users", "200"),
+       ("PetriNets", "SimpleClassDiagrams", "yentl", "users", "211"),
+       ("SimpleClassDiagrams", "SimpleClassDiagrams", "admin", "admin", "211")]
+
 .. function:: verify(model_name)
 
    Verify whether *model_name* conforms to its specified metamodel, as stored in the Modelverse.
    Returns either "OK" if the model conforms, or a string specifying the reason for non-conformance.
 
+   Examples:
+
+   When verifying a conforming model:
+   .. code::
+      >> verify("PetriNets")
+      OK
+
+   When verifying a non-conforming model:
+   .. code::
+      >> verify("my_pn")
+      Lower cardinality violation for attribute "name" at Place p1.
+
 .. function:: model_overwrite(model_name, new_model_code=None)
 
    Overwrites the model previously known under the name *model_name* with the model code in *new_model_code*.
    This operation differs from first deleting the model and then recreating it, as all metadata of the model is kept, such as access permissions.
    The new model can be kept empty, in which case the model will be cleared.
 
+   Examples:
+
+   To overwrite the PetriNets metamodel with a newer version, thereby also updating the metamodel of all existing instances ("my_pn" and "my_pn2"):
+   .. code::
+      >> model_overwrite("PetriNets", open("models/PetriNets2.mvc", "r").read())
+
+   To overwrite an existing PetriNets instance:
+   .. code::
+      >> model_overwrite("my_pn", """Place p2 {}""")
+
 .. function:: user_logout()
 
    Logs out the current user, thereby closing the task.
    Subsequent operations will no longer have any effect, as the task was terminated.
    To log in as a different user, the *init* operation has to be executed again.
 
+   Examples:
+
+   To log out the current user and allow future logins by this user:
+   .. code::
+      >> user_logout()
+
 .. function:: user_delete()
 
    Delete the current user and thereafter log out.
@@ -97,17 +193,43 @@ Functions
    Existing models tied to this user, such as those the user is an owner of, remain bound to the (removed) user.
    While it is possible to recreate a new user with the same name, model permissions will not be inherited to this new user with the same name.
 
+   Examples:
+
+   To delete the current user, and make all owned models owner-less:
+   .. code::
+      >> user_delete()
+
 .. function:: model_render(model_name, mapper_name)
 
    Render the model by name of *model_name* using the mapper by name of *mapper_name*.
    Both parameters have to be known models in the Modelverse.
    Outputs a JSON representation of the rendered model.
+   This is basically just a shortcut for executing the specified operation and reading out the resulting model with a JSON representation.
+
+   Examples:
+
+   To render the PetriNets instance using the PetriNetsMapper:
+   .. code::
+      >> model_render("my_pn", "PetriNetsMapper")
+      [{"id": "__12345", "type": "Ellipse", "x": 100, "y": 150, "height": 20, "width: "20"}]
 
 .. function:: transformation_between(source, target)
 
    List all transformations that originate at *source* and end at *target*.
    Transformations can still be selected, even if they take more source models than those specified in the parameters.
 
+   Examples:
+
+   To fetch all endogenous transformations on PetriNets, assuming that some were previously defined:
+   .. code::
+      >> transformation_between("PetriNets", "PetriNets")
+      ["PN_simulate", "PN_optimize"]
+
+    To fetch all transformations from a DSL to PetriNets, assuming that multiple people created different denotational semantics:
+    .. code::
+       >> transformation_between("RPGame", "PetriNets")
+       ["denotational1", "denotational_2", "denotational_3"]
+
 .. function:: transformation_add_MT(source_metamodels, target_metamodels, operation_name, code, callback=lambda: None)
 
    Create a new model transformation operation.
@@ -120,17 +242,56 @@ Functions
    Optionally, a callback is defined which performs some operations on the merged metamodel, for example to define tracability links between (previously unrelated) metamodels.
    In the background, this operation does all necessary RAMification and model merging.
 
+   Examples:
+
+   To create a new model transformation for PetriNets simulation:
+   .. code::
+      >> transformation_add_MT({"pn": "PetriNets"}, {"pn": "PetriNets"}, "pn_simulate", open("models/PN_simulate.mvc", "r").read())
+
+   To create a model transformation from a DSL to PetriNets, which requires tracability links:
+   .. code::
+      >> def tracability_links():
+      >>     instantiate("Association", ID="Tile2Place", ("dsl/Tile", "pn/Place"))
+      >>     instantiate("Association", ID="Dirrection2Transition", ("dsl/Direction", "pn/Transition"))
+      >> transformation_add_MT({"dsl": "RPGame"}, {"pn": "PetriNets"}, "denotational_1", open("models/denotational_1.mvc", "r").read(), tracability_links)
+
+   To create a multi-input model transformation:
+   .. code::
+      >> transformation_add_MT({"pn_1": "PetriNets", "pn_2": "PetriNets", "architecture: "Architecture"}, {"result": "PetriNets"}, "PN_merge", open("models/PN_merge.mvc", "r").read())
+
 .. function:: transformation_add_AL(source_metamodels, target_metamodels, operation_name, code, callback=lambda: None)
 
    Creates a new action language operation.
    Similar to *transformation_add_MT*, but now does not require RAMification.
    The *code* parameter also is not specified as a Modelverse model (.mvc), but as action language (.alc).
 
+   Examples:
+
+   To create a new action language operation for PetriNets reachability analysis:
+   .. code::
+      >> transformation_add_AL({"pn": "PetriNets"}, {"graph": "ReachabilityGraph"}, "pn_analyze", open("models/PN_reachability.alc", "r").read())
+
+   To create an action language operation from a Scheduling DSL to a list, which requires tracability links:
+   .. code::
+      >> def tracability_links():
+      >>     instantiate("Association", ID="Task2Event", ("schedule/Task", "list/Event"))
+      >> transformation_add_AL({"schedule": "SchedulingDSL"}, {"list": "EventList"}, "sequentialize", open("models/sequentialize_schedule.alc", "r").read(), tracability_links)
+
 .. function:: transformation_add_MANUAL(source_metamodels, target_metamodels, operation_name, callback=lambda: None)
 
    Creates a new manual operation.
    Identical to *transformation_add_AL*, but does not take any code as content.
 
+   Examples:
+
+   To create a manual refinement operation on PetriNets:
+   .. code::
+      >> transformation_add_MANUAL({"pn": "PetriNets"}, {"pn": "PetriNets"}, "pn_refine")
+
+   To create a multi-input refinement operation on PetriNets:
+   .. code::
+      >> transformation_add_MANUAL({"pn": "PetriNets", "requirements": "Requirements"}, {"pn": "PetriNets"}, "pn_refine_req")
+
 .. function:: transformation_execute_AL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)
 
    Executes the Action Language model *operation_name* with *input_models_dict* as inputs and *output_models_dict* as outputs.
@@ -139,6 +300,24 @@ Functions
    A *callback* function can be defined when the action language model requires user input or output.
    This callback function can be used to communicate with the executing action language directly.
 
+   Examples:
+
+   To execute reachability analysis on an existing petri net:
+   .. code::
+      >> transformation_execute_AL("pn_analyze", {"pn": "my_pn"}, {"graph": "my_pn_reachability"})
+
+   To execute reachability analysis which prompts the user, for example because it is a debugging prompt:
+   .. code::
+      >> def callback(value):
+      >>     print(value)
+      >>     return raw_input()
+      >> transformation_execute_AL("pn_simulate", {"pn": "my_pn"}, {"graph": "my_pn_reachability"}, callback)
+      << Which operation do you want to execute?
+      >> step
+      << Step performed! New operation?
+      >> continuous
+      << Finished analysis!
+
 .. function:: transformation_execute_MANUAL(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)
 
    Executes the manual model operation *operation_name*.
@@ -146,6 +325,16 @@ Functions
    In this case, the callback function can be just another series of Modelverse operations, though pertaining to a single model.
    As such, the *model_name* parameter of these operations **MUST** be set to *None*.
 
+   Examples:
+
+   To execute a manual operation, which requires you to refine a PetriNets instance:
+   .. code::
+      >> def callback():
+      >>     p1 = instantiate(None, "pn/Place")
+      >>     t1 = instantiate(None, "pn/Transition")
+      >>     instantiate(None, "pn/P2T", (p1, t1))
+      >> transformation_execute_MANUAL("pn_refine", {"pn": "my_pn"}, {"pn": "my_pn"}, callback)
+
 .. function:: transformation_execute_MT(operation_name, input_models_dict, output_models_dict, callback=lambda i: None)
 
    Executes the model transformation operation *operation_name*.