More examples of the wrapper

doc/wrappers.rst

@@ -557,7 +557,7 @@ Functions
    Examples:
 
    To get a list of all types usable in the PetriNets metamodel (i.e., when altering the metamodel itself):
-   .. code..
+   .. code::
       >> types("PetriNets")
       ["Class", "Association", "SimpleAttribute", ...]
 
@@ -566,42 +566,164 @@ Functions
    Returns a list of all types usable in the model named *model_name*.
    In contrast to *types*, this includes hidden elements as well (i.e., those starting with __)
 
+   Examples:
+
+   To get a list of all types usable in the PetriNets metamodel (i.e., when altering the metamodel itself):
+   .. code::
+      >> types("PetriNets")
+      ["Class", "Association", "SimpleAttribute", "__12345", ...]
+
 .. function:: read(model_name, ID)
 
    Read the content of model element *ID* in model *model_name*.
    This returns the type of the element, and the set of source and destination if the element is an edge (*None* otherwise).
 
+   Examples:
+
+   To read out the P2T link in the PetriNets metamodel:
+   .. code::
+      >> read("PetriNets", "P2T")
+      ["Association", ("Place", "Transition")]
+
+   To read out the Place node in the PetriNets metamodel:
+   .. code::
+      >> read("PetriNets", "Place")
+      ["Class", None]
+
+   To read out some P2T instance in a PetriNets model:
+   .. code::
+      >> read("my_pn", "p1_to_t1")
+      ["P2T", ("p1", "t1")]
+
+   To read out some Place instance in a PetriNets model:
+   .. code::
+      >> read("my_pn", "p1")
+      ["Place", None]
+
 .. function:: read_attrs(model_name, ID)
 
    Return a dictionary of all attributes of model element *ID* in model *model_name*, containing their values.
    All values in the Modelverse are primitive types, and as such, this is also the case in this operation.
+   The value is *None* in case the attribute is not set.
+
+   Examples:
+
+   To read out the attributes of the Place class:
+   .. code::
+      >> read_attrs("PetriNets", "Place")
+      {"lower_cardinality": None, "upper_cardinality": None}
+
+   To read out the attributes of a Place instance:
+   .. code::
+      >> read_attrs("my_pn", "p1")
+      {"name": "critical_section", "tokens": 1}
 
 .. function:: instantiate(model_name, typename, edge=None, ID="")
 
    Instantiate a new instance of *typename* in the model *model_name*.
    If the instance is an edge, provide a tuple containing the source and target as *edge*.
-   A preferred *ID* can be specified, though there is no guarantee that this name is actually taken (e.g., if it is already taken by another element).
+   A preferred *ID* can be specified, though there is no guarantee that this name is actually used (e.g., if it is already taken by another element).
    This operation returns the actually assigned ID.
+   It is this ID that is used for all other operations on the model.
+
+   Examples:
+
+   To create a new Place instance in a PetriNets model:
+   .. code::
+      >> instantiate("my_pn", "Place")
+      "__12345"
+
+   To create a new Place instance with a preferred ID, which is granted:
+   .. code::
+      >> instantiate("my_pn", "Place", ID="critical_section")
+     "critical_section"
+
+   To create a new Place instance with a preferred ID, which is not granted:
+   .. code::
+      >> instantiate("my_pn", "Place", ID="critical_section")
+     "critical_section_12345"
+
+   To create a new P2T instance in a PetriNets model:
+   .. code::
+      >> instantiate("my_pn", "P2T", ("p1", "t1"))
+      "__12345"
+
+   To create a new concept in the PetriNets metamodel, which can later on be used:
+   .. code::
+      >> instantiate("PetriNets", "Association", ("Place", "Transition"), ID="InhibitorArc")
+      "InhibitorArc"
+      >> instantiate("my_pn", "InhibitorArc", ("p1", "t1"))
+      "__12345"
 
 .. function:: delete_element(model_name, ID)
 
    Delete the element *ID* in the model *model_name*.
    This is a recursive delete, and all incoming and outgoing edges will be removed (recursively) as well.
 
+   Examples:
+
+   To delete an existing element in a PetriNets model:
+   .. code::
+      >> delete_element("my_pn", "critical_section")
+
+   To delete an existing exdge in a PetriNets model:
+   .. code::
+      >> delete_element("my_pn", "p1_to_t1")
+
+    When deleting an element "p1", the arc "p1_to_t1" is also removed automatically.
+    .. code::
+       >> delete_element("my_pn", "p1")
+       >> delete_element("my_pn", "p1_to_t1") # <-- Raises an exception: arc is already removed
+
 .. function:: attr_assign(model_name, ID, attr, value)
 
    Assign the value *value* to the attribute named *attr* of the element *ID* in the model named *model_name*.
    If the attribute already has an assigned value, the previous value is removed first.
 
+   Examples:
+
+   To assign some attributes to a Place instance:
+   .. code::
+      >> attr_assign("my_pn", "p1", "name", "my first place")
+      >> attr_assign("my_pn", "p1", "tokens", 1)
+
+   To assign some attributes to the Place class itself:
+   .. code::
+      >> attr_assign("PetriNets", "Place", "upper_cardinality", 1)
+
 .. function:: attr_assign_code(model_name, ID, attr, code)
 
    Assign the code block *code* to the attribute named *attr* of the element *ID* in the model named *model_name*.
    If the attribute already has an assigned value, the previous value is removed first.
    The assigned code is compiled to Action Language by the HUTN compiler.
 
+   Examples:
+
+   To assign a piece of action code to a Statecharts transition, loaded from file:
+   .. code::
+      >> attr_assign_code("my_sc", "t1", "script", open("models/t1_script", "r").read())
+
+   To assign a piece of action code to a Statecharts transition, defined inline
+   .. code::
+      >> code = \
+      >>   """
+      >>   Void function action(attributes : Element):
+      >>        dict_overwrite(attributes, "counter", 1)
+      >>        return!
+      >>   """
+      >> attr_assign_code("my_sc", "t1", "script", code)
+
 .. function:: attr_delete(model_name, ID, attr)
 
    Unset the attribute *attr* of model element *ID* in the model *model_name*.
+   This is not necessary when assigning a new value, as *attr_assign* automatically does this when required.
+   As such, this only is useful when dealing with an optional attribute, or when you want to create a non-conforming model.
+
+   Examples:
+
+   To unset the name attribute of a place
+   .. code::
+      >> attr_delete("my_pn", "p1", "name")
 
 .. function:: read_outgoing(model_name, ID, typename)
 
@@ -609,20 +731,68 @@ Functions
    Typename can be set to the empty string to indicate that all types must match.
    Note that this returns the association itself, **NOT** the destination.
 
+   Examples:
+
+   To get all arcs starting in place p1:
+   .. code::
+      >> read_outgoing("my_pn", "p1", "P2T")
+      ["p1_to_t1"]
+
+   To get all allowed connections starting in a Place:
+   .. code::
+      >> read_outgoing("PetriNets", "Place", "Association")
+      ["P2T", "InhibitorArc"]
+
 .. function:: read_incoming(model_name, ID, typename)
 
    Returns a list of all incoming associations of *ID*, typed by *typename*, in model *model_name*.
    Typename can be set to the empty string to indicate that all types must match.
    Note that this returns the association itself, **NOT** the source.
 
+   Examples:
+
+   To get all arcs going to place p1:
+   .. code::
+      >> read_incoming("my_pn", "p1", "T2P")
+      ["t1_to_p1"]
+
+   To get all allowed connections going to a Place:
+   .. code::
+      >> read_incoming("PetriNets", "Place", "Association")
+      ["T2P"]
+
 .. function:: read_association_source(model_name, ID)
 
    Returns the identifier of the source of association *ID* in model *model_name*.
 
+   Example:
+
+   To read out the source of the P2T link:
+   .. code::
+      >> read_association_source("PetriNets", "P2T")
+      "Place"
+
+   To read out the source of an arc:
+   .. code::
+      >> read_association_source("my_pn", "p1_to_t1")
+      "p1"
+
 .. function:: read_association_destination(model_name, ID)
 
    Returns the identifier of the target of association *ID* in model *model_name*.
 
+   Example:
+
+   To read out the target of the P2T link:
+   .. code::
+      >> read_association_destination("PetriNets", "P2T")
+      "Transition"
+
+   To read out the target of an arc:
+   .. code::
+      >> read_association_destination("my_pn", "p1_to_t1")
+      "t1"
+
 .. function:: service_register(name, function)
 
 .. function:: service_stop()
@@ -639,6 +809,10 @@ Functions
 
 .. function:: connections_between(model_name, source_element, target_element)
 
+.. function:: define_attribute(model_name, node, attr_name, attr_type)
+
+.. function:: all_instances(model_name, type_name)
+
 Exceptions
 ^^^^^^^^^^