miccautil - Supporting Executable Model Translation into C
This manpage describes the miccautil package. Miccautil is a Tcl script-based extension that give a set of utility procedures to use with micca generated XUML domains.
The package exports the following commands which also constitute an ensemble command on the ::miccautil namespace.
The name of the command to be created which represents the model. The new version of the constructor creates a name automatically.
The name of a file saved from a micca run. This file should be saved in TclRAL native serialization format.
The create and new methods create an instance of a model object. The savefile argument is required and is the name of a file produced by a run of micca with the -save option. The return value of the function is a fully qualified command that may be used with the methods given below.
a graph command as returned from struct::graph, usually obtained by invoking, modelobj stateModelGraph class.
the name of node where the search is to start. If start is not given, then the search starts at node given by the initialstate attribute of the graph.
The dfs subcommand performs a depth first search (DFS) of graph. graph is a command as returned from struct::graph, usually obtained by invoking the stateModelGraph method with the desired class name. The return value of the command is the empty string.
During the DFS, each node in the graph is annotated with the following additional attributes:
the pre-order number of the node, starting at 1. This is the order in which the node was visited during the DFS.
the reverse post-order number of the node, starting at 1. This is the order the node would be visited in a reverse post-order traversal. For graphs that do not contain cycles, the rpost numbers form a topological sort of the graph. Graphs which have no back edges (see following) have no cycles.
Each edge in the graph is annotated with one additional attribute:
the classification of the graph edge. The type attribute has one of the following values:
the edge is part of a spanning tree for the graph, i.e. the target node is visited for the first time when the edge is traversed.
the edge is a forward directed, i.e. the target node is a decendent of the source node.
the edge is a back edge, i.e. the target node is an ancestor of the source node.
the edge is a cross edge. All edges which are not classified as tree, forw, or back are classified as cross edges.
a graph command as returned from struct::graph, usually obtained by invoking, modelobj stateModelGraph class.
the name of node where the DFS for the tree is to start. If start is not given, then the tree starts at node given by the initialstate attribute of the graph.
The spanningTree subcommand returns a graph command handle as obtained from the struct::graph package in Tcllib. The returned graph contains a spanning tree of the graph argument. The spanning tree returned is the sub-graph of graph where only tree type edges are retained. The caller is responsible for invoking the destroy method on the returned graph command when it is no longer needed. It is not necessary to have run the dfs command previously on graph as that will be done by spanningTree.
a graph command as returned from struct::graph, usually obtained by invoking, modelobj stateModelGraph class.
a list of key names which will be included as the label of an edge.
a list of key names which will be included in the label of a node.
The graphToDot subcommand returns a Tcldot command handle which is the dot representation of graph. The edges of the dot drawing are annotated with the values given by the edge attribute keys contained in the edgekeys list. Similarly, the nodes of the dot drawing are annotated with the values given by the node attribute keys contained in the nodekeys list. The command handle can be used in the same way as those returned by the stateModelDot method. Note that invoking graphToDot with the return value of stateModelGraph does not yield the same rendering as the stateModelDot method. The later method insures the rendered state model appears more in line with usual UML notation.
The return value of the ::miccautil model create and ::miccautil model new commands is a TclOO command object. The following methods may be applied to the object.
The destroy method is used to delete modelobj when it is no longer needed.
The domainName method returns the name of the domain represented by modelobj.
The classes method returns a list of the names of the classes defined in the domain represented by modelobj.
The name of a class in the domain represented by modelobj.
The attributes method returns a dictionary of the attributes of class. The keys to the dictionary are the names of the attributes. The values associated to the keys are the data type of the attribute. If class does not exist in the domain, an empty dictionary is returned.
The name of a class or assigner in the domain represented by modelobj.
The states method returns a list of state names for class. If class does not exist in the domain or if class does not have a state model, an empty list is returned. A state name of, @, indicates the pseudo-initial state out from which creation events transition.
The name of a class or assigner in the domain represented by modelobj.
The events method returns a list of event names for class. If class does not exist in the domain or if class does not have a state model or any polymorphic events, an empty list is returned. The returned list includes the event names for any type of event that the class may have. For example, a superclass may not have a state model, but could have polymorphic events and these names would be returned.
The name of a class or assigner in the domain represented by modelobj.
The creationevents method returns a list of event names for class which cause a transition out of the pseudo-initial creation state (represented here as the state named, "@"). If class does not exist in the domain or if class does not have a state model or any creation events, an empty list is returned.
The name of a class or assigner in the domain represented by modelobj.
The transitions method returns a relation value that contains the state transitions for class. The heading of the returned relation value is:
|Domain |Model |State |Event |NewState |Params | |string |string |string |string |string |Relation |
where:
is the name of the domain.
is the name of the class or assigner.
is the name of a state. A State name of, @, indicates the pseudo-initial state out of which creation events transition.
is the name of an event which causes a transition out of State.
is the name of the state entered by the transition caused when Event is received in State. A NewState name of IG indicates the Event is ignored when it is received in State. A NewState name of "CH" indicates it is logically impossible to receive _Event_ in _State_ (i.e. can't happen) and at run time will cause a panic condition.
is a relation valued attribute giving the parameters of Event (and hence the arguments to NewState). The cardinality of the Params attribute is zero if the event carries no supplemental event data. The Params attribute has the heading:
|Name |Position |DataType | |string |int |string |
where:
is the name of the parameter.
is the order of the parameter carried in Event. Position values start at zero and sequentially increase for each tuple in Params.
is the "C" type name for the parameter.
The cardinality of the returned relation is states times events where states (including the pseudo-initial state for a creation event, if present in the model) is the number of states in the model and events is the number of events. The cardinality of the returned relation is zero if the class has no state model. Each tuple in the returned relation represents a cell in a conceptual states by events transition matrix with NewState as the cell value.
The startTransitionRecording method initializes internal data structures in preparation for recording event transitions in the domain represented by modelobj. In particular, any previous event transition counts are reset back to zero. Attempting to start an already running session is silently ignored. The method returns the empty string.
The stopTransitionRecording method closes an ongoing event transition recording session. The information gathered during the session is not modified. Attempting to stop an already stopped session is silently ignored. The method returns the empty string.
The name of a class or assigner in the domain represented by modelobj.
The name of the state in class which is the source state in a transition.
The name of an event in class which caused a transition from currstate.
The recordTransition method counts the transition which occurred when class was in currstate and received event. It is necessary to start the event transition recording session by invoking the startTransitionRecording method before invoking this method. The method returns a boolean value indicating if the counting occurred, i.e. if currstate and event form a valid transition in class.
A pattern of the format used by the string match command for the names of classes or assigners in the domain represented by modelobj.
The reportTransitions method returns a relation value containing the transition counts for all classes whose names match pattern. The heading of the returned relation value is:
|Domain |Model |State |Event |NewState |TransCount | |string |string |string |string |string |int |
where:
is the name of the domain.
is the name of the class or assigner.
is the name of a state. A State name of, @, indicates the pseudo-initial state out of which creation events transition.
is the name of an event which causes a transition out of State.
The name of the state entered by the transition caused when Event is received in State. A NewState name of IG indicates the Event is ignored when it is received in State. A NewState name of CH indicates it is logically impossible to receive Event in State (i.e. can't happen) and at run time will cause a panic condition.
The number of times recorded when Model was in a given State and Event was received.
An object command as returned from the rein command of the mecate package. A reinobj represents a bosal generated test harness and methods of the object allow for operations on the test harness.
The startMecateTransitionCount method starts capturing event transitions as they arrive from a bosal generated test harness. This method uses the traceNotify method of the reinobj to install a callback handler for when event traces arrive. Note this method does not turn on event tracing in the test harness. That is done with the reinobj trace on command which must be executed before any events will be received and counted.
An object command as returned from the rein command of the mecate package. A reinobj represents a bosal generated test harness and methods of the object allow for operations on the test harness.
The stopMecateTransitionCount method stops capturing event transitions as they arrive from a bosal generated test harness. The previous reinobj callback handler is re-instated.
The defaultAttributeValues returns a relation value giving the default values that attributes in the domain represented by modelobj are given if not otherwise specified. The heading of the returned relation is:
|Domain |Class |Defaults | |string |string |Relation |
where:
is the name of the domain.
is the name of a class in *Domain*.
is a relation valued attribute containing the attribute names and values for Class.
The heading of the Defaults attribute is:
|Attribute |Value |DataType | |string |string |string |
where:
is the name of the attribute of the instance.
is the value of the attribute in the instance.
is the "C" type name for the attribute.
The initialInstancePopulation method returns a relation value containing the initial instance population of the domain represented by modelobj. The heading of the returned relation is:
|Domain |Class |Instances | |string |string |Relation |
where:
is the name of the domain.
is the name of a class in Domain.
is a relation valued attribute containing the initial instances of Class.
The heading of the Instance attribute is:
|Instance |ID |Attributes | |string |int |Relation |
where:
is the name given to the inital instance in the micca population.
is the numeric identifier of the instance. This number is the same as the array index of the instance in the storage pool for the class.
is a relation valued attribute giving the attribute names and values of the initial instance.
The heading of the Attributes attribute is:
|Attribute |Value | |string |string |
where:
is the name of the attribute of the instance.
is the value of the attribute in the instance.
The name of a class or assigner in the domain represented by modelobj.
The stateModelGraph method returns a graph command from the struct::graph package in Tcllib that represents the state model for class as a graph. It is the responsibility of the caller to insure that the returned graph command is disposed of properly by invoking graph destroy when no longer needed. If class does not not have a state model, the returned graph has no nodes or arcs. The returned graph is annotated by the following key / value attributes:
the name of the domain.
the name of the class or assigner.
the name of the default initial state.
the name of the default transition, i.e. IG or CH.
Nodes in the graph represent states in the state model and are named the same as the state name. Nodes are annotated by the following key / value attributes:
the state activity code.
a boolean value indicating if the state is a final state.
Arcs in the graph represent the directed transitions from a source state to a target state. Note that IG and CH transitions are not represented by arcs since as target states they do not cause an actual transition. Arcs are annotated by the following key / value attributes:
the name of the event causing the transition.
a list of event parameter names giving the additional values carried by the event.
The name of a class or assigner in the domain represented by modelobj.
The stateModelDot method returns a Tcldot command handle to the state model of class. The command handle can be used to render an image of the state model graph (along with many other uses).
micca
translation
Copyright © 2020 - 2023 by G. Andrew Mangogna