micca-DSL - Commands for Defining a Domain
This manpage describes the micca DSL. When translating an executable model using micca, the model is transcoded into the DSL described in this manual. The DSL is implemented as an internal DSL in Tcl and the script follows Tcl syntax rules.
At the highest level, the commands in this section allow you to define the characteristics of a domain and its initial instance population.
The domain command defines a domain named, name, and evaluates script in a context where commands in script may be used to define the characteristics of a domain. The script argument should contain invocations of the domain commands described below.
domain wmctrl {
# A script containing domain commands to define the domain.
...
}
The population command is used to define the initial instance population for the domain named, domain. The script argument should contain commands that define the attribute values, relationship linkages and storage allocations for domain. It is evaluated in a context where the population commands described below are available.
population wmctrl {
# A script containing populations commands to define the initial
# instance population and storage allocation for the domain.
...
}
The commands in this section are used to define the characteristics of a domain using the micca DSL. These are the commands that are available when the script argument of the domain is evaluated.
The class command defines a class named, classname. The script argument is optional and if provided is a script that is evaluated in a context where class commands are available to define the characteristics of the class. The class command may invoked multiple times for the same classname and the class definition is cumulative.
class Pump {
# Commands that define the characteristics of the Pump class.
...
}
The association command defines an association relationship called, name, between a source class and target class. Traditionally, association names follow a naming convention of a capital R followed by a number (e.g. R27), but any non-empty string not starting with a tilde character (~) is allowed. The forward direction of navigating the relationship is from source to target. For simple associations (i.e. those not involving a associator class), the source class serves as the refering class (i.e. it contains the referential attributes formalizing the association) and the target class serves as the referenced class (i.e. it contains the identifier to which the referential attributes of the source class refer). The conditionality and multiplicity of the association is given by the spec argument. The spec argument must take one of the following forms:
A class based association is indicated by the -associator argument with class being defined as the associator class. Note that micca will insist that any association whose multiplicity and conditionality on the target class side is 0..1 or where both sides have a multiplicity greater than one be formalized using an associator class. This is the same as disallowing any of a NULL value for a referential attribute and insisting the instances of the association track the instances of the associator class. For class bases associations, the -multiple argument may be present to indicate that multiple instances of the associator class may reference the same instances of the participating classes. This option is only allowed for class bases associations and is used to define many-to-many-to-many relationships. If the -static argument is given then the association is defined to be static and the number of instances of the association itself cannot vary during the run time of the domain. If the -dynamic argument is given or neither -static or -dynamic is given, then the instances of the association are assumed to vary during the run time of the domain. These options allow micca to choose the appropriate data structures for relationship storage given the run time behavior of the relationship. The association command may have an optional script argument. If script is present, then the association is defined to have an assigner and script is evaluated to define the characteristics of the assigner. The script is evaluated in a context where assigner commands are available to define the characteristics of the association assigner.
association R13 -static WashingMachine 1--1 Tub
association R22 -associator Ownership Dog 1..*--0..* Owner
association R2 -associator Service Clerk 0..1--0..1 Client {
statemodel {
# State model for assigning clerks to clients.
}
}
The generalization command defines a generalization relationship called, name. Traditionally, generalization names follow a naming convention of a capital R followed by a number (e.g. R27), but any non-empty string not starting with a tilde character (~) is allowed. The super is the name of a class that will serve as the superclass in the generalization. The subN arguments give the names of the subclasses of the generalization. At least two subclasses must be given. If the -union argument is given, then subclasses will be stored in a union within the structure of the superclass. If the -reference argument is given or if neither -union nor -reference is present, the subclasses are stored separate from the superclass and instance references are used to implement the generalization relationship.
generalization R12 Lamp TableLamp FloorLamp generalization R32 -union Washer FrontLoader TopLoader
The domainop command defines a domain operation called, name. A domain operation is translated to a "C" function of external scope. The "C" return type of the function is given by the rettype argument. Formal parameters to the operation are given as a list of parameter name / parameter type pairs in the parameters argument. The code for the domain operation is supplied in the body argument. If present, the optional comment argument text is inserted as a comment in the generated header file for the domain just before the external declaration of the domain operation function. This provides a convenient way to provide addition information to users of the domain operation in the generated header file.
domainop void startWasher {washerID MRT_InstId when MRT_DelayTime} {
// C Code to start a washing machine.
} {
Use this operation to start a washing machine.
}
The eentity command defines an external entity which serves as a proxy for operations delegated by the domain. The entityname argument gives the name of the entity. The script argument is a script that is evaluated in a context where external entity commands are available to define the characteristics of the external entity. The eentity command may invoked multiple times for the same entityname and the entity definition is cumulative.
eentity MSG {
# External entity commands go here
}
The typealias command defines a new data type name, name, and equates it to the "C" type defintion given by definition.
typealias Direction_t {enum {
Up, Down
}
}
The micca code generator produces a header file for the domain. The interface command will insert text near the beginning of the generated header file. The interface command may be invoked multiple times, and the text is concatenated in the order the commands are encountered. This command is typically used for declarations and include files needed by other code in the domain.
interface {
#include "myheader.h"
}
The micca code generator produces a code file for the domain. The prologue command will insert text near the beginning of the generated code file. The prologue command may be invoked multiple times, and the text is concatenated in the order the commands are encountered. This command is typically used for declarations and include files needed by code in the domain.
prologue {
struct Point {
int x ;
int y ;
} ;
static void scalarMultiple(int, struct Point *) ;
}
The micca code generator produces a code file for the domain. The epilogue command will insert text near the end of the generated code file. The epilogue command may be invoked multiple times, and the text is concatenated in the order the commands are encountered. This command is typically used for local definitions needed by code in the domain.
epilogue {
static void
scalarMultiple(
int a,
struct Point *p)
{
p->x *= a ;
p->y *= a ;
return ;
}
}
The commands in this section may appear in the script argument of the class command to define the properties of a class.
The attribute command defines name to be an attribute of the enclosing class. The attribute has a data type of type. Name must be a valid "C" identifier and type must be a valid "C" type name or a type name given by the typealias command. A default value for the attribute may optionally be specified using the -default option. Default values are used in any context where the an instance of the class is created and no value for the attribute is given in the creation invocation. The value of a default value must be a valid "C" initializer and is passed directly to the generated code. By special dispensation, attributes of type array of character (e.g. char[16]) are treated as NUL terminated strings in the usual "C" conventions.
If the -zeroinit is present, then the attribute value is initialized to all bits of zero if no value is explicitly supplied.
If the -dependent arguments is present, the name attribute is defined as a mathematically dependent attribute. These types of attributes may only be read and when they are read, the value of the attribute is that returned by the formula. The formula value should consist of "C" code to compute the value of the attribute. When invoked, formula is supplied with a value of self for the class instance, a pointer to a location where the attribute value is to be written and the number of bytes memory for the result. The variable name of the pointer is the same as the name of the attribute and it is a pointer to the same type as the attribute. The variable name of the memory size is size.
class Washer {
attribute ModelName {char[20]} ; # This is a NUL terminated string
attribute Capacity unsigned -default 4
}
class Extent {
attribute Height int
attribute Width int
attribute Area int -dependent {
*Area = self->Height * self->Width ;
}
}
class Name {
attribute FirstName {char[32]} ;
attribute LastName {char[32]} ;
attribute FullName {char[64]} -dependent {
size_t firstLen = strlen(self->FirstName) ;
size_t lastLen = strlen(self->LastName) ;
*FullName = '\0' ;
if (size >= firstLen + lastLen + 2) {
strcat(FullName, self->FirstName)
strcat(FullName, " ") ;
strcat(FullName, self->LastName) ;
}
}
}
The classop command defines a class based operation of the enclosing class. The name of the operation is given by the name argument and its "C" return type is rettype. Formal parameters to the operation are given as a list of parameter name / parameter type pairs in the parameters argument. The code for the operation is supplied in the body argument. Class operations do not have an implied parameter of self. Class operation typically do not arise as part of a domain model and are most useful when implementing particular search or summarizing code on the class as a whole.
classop {struct Washer *} findById {washerID MRT_InstId} {
// Code to find a specific washer instance.
}
The instop command defines an instance based operation of the enclosing class. The name of the operation is given by the name argument and its "C" return type is rettype. Formal parameters to the operation are given as a list of parameter name / parameter type pairs in the parameters argument. The code for the operation is supplied in the body argument. Instance operations have an implied parameter of self, which is supplied automatically to the operation upon invocation.
instop unsigned incrCapacity {howmuch unsigned} {
return self->Capacity += howmuch ;
}
The statemodel command defines the states, events and transitions of a state model which is associated with the enclosing class. The body argument should contain invocations of state model commands to define the properties of the class state model.
statemodel {
# Commands to define the states, events and transitions of
# the class state model.
}
The polymorphic command defines a polymorphic event named, event which has optional parameters given by ?argnameN argtypeN? pairs. A polymorphic event may only be defined on a class that serves as a superclass in a generalization relationship. If event requires any parameters they must be given in this command. Polymorphic events are inherited across all generalizations in which the enclosing class is a superclass.
polymorphic Run howfast int howlong int polymorphic Stop
The constructor command defines a constructor for the enclosing class. The body argument consists of "C" code which is run whenever a class is created during run time. The constructor is supplied automatically with a value for the self variable. Typically, constructors are used to initialize complex user defined data types associated with attributes.
The destructor command defines a destructor for the enclosing class. The body argument consists of "C" code which is run whenever a class is deleted during run time. The destructor is supplied automatically with a value for the self variable. Typically, destructors are used to clean up complex user defined data types associated with attributes.
The commands in this section are used to define the state model for a class.
The state command defines a new state called, name. If the state accepts parameters, they are given in the parameters argument as a list of parameter name / parameter type pairs. If the state does not accept parameters, the empty list ( {} ) should be given. Upon entry into the state, the "C" code given in the body argument is executed. The body will have a pre-defined variable named, self, which is a reference to the class instance for which the state transition happened.
The body should contain "C" code and micca embedded macro commands. The embedded commands provide a convenient interface for performing model level actions such as signaling events. See the micca-embedded manual page for a description of the available embedded commands.
state Running {} {
<%my findOneRelated car R3 R7%>
if (car != NULL) {
<%instance car signal Started%>
}
}
state Activate {count int} {
<%my update Number count%>
<%my signal Run%>
}
The transition command defines a state model transition from currstate to newstate when event is received. The currstate argument may be the name of any state in the state model (that state need not have been defined yet) or the pseudo-initial state "@". If currstate is given as "@", the event is a creation event. The newstate argument may be the name of any state or the special non-transitioning states of "IG" (ignore), which causes event to be ignored or "CH" (can't happen), which results in a system error if event is received. The "-" and "->" arguments are syntactic sugar and are ignored.
transition Running - Stop -> Stopped transition Stopped - Run -> Running
The event command defines an event named, name, with optional parameters given by the argnameN argtypeN pairs. It is not required to define events. The names and parameter signatures will be deduced from their usage in transition statements. However, in some cases, particularly those where the event carrys parameters, it may be more convenient to define the event and its signature rather than relying on assuming a signature by virtue of the event causing a transition into a particular state.
event Run speed int
state Running {fast int} {
}
transition Stopped - Run -> Running
In this example, the Run event and the Running state have the same parameter signature, despite the difference in naming of the parameter itself.
The initialstate command defines state to be the default initial state for the state model. Instances may be created in any state, but by default they are created in state. If the initialstate command does not appear in the state model definition, then the default initial state is taken to be the lexically first state defined in the state model.
The defaulttrans command defines transition to be the default transition. The default transition is used for all transitions not explicitly mentioned in a transition command. The transition argument must be either IG or CH. If no defaulttrans command is given in the state model definition, the default transition is assumed to be CH.
The final command defines the states as final states. An instance that enters a final state is automatically deleted after its state activity is run. The final may appear multiple times in the state model definition.
Assigner commands can appear in the script argument of the association command and are used to define the properties of the association assigner.
The statemodel command defines the state model of an assigner. All the commands defined for state models of classes can be used to define the state model of an assigner. An assigner must have a state model.
The identifyby command defines class as the partitioning class for a multiple assigner. Multiple assigners have the same number of instances as there are instances of class.
External entity commands can appear in the script argument of the eentity command and are used to define external operations that the entity must provide.
The operation command defines an external entity operation called, name, which the domain assumes will be supplied out side of the domain definition. An external entity operation is translated into an external function reference. The "C" return type of the function is given by the rettype argument. Formal parameters to the operation are given as a list of parameter name / parameter type pairs in the parameters argument. "C" code may be supplied as the body argument. By default, the code is not placed in the output, but to aid in testing and simulation, the micca translator has an option to include the code in the translated output. If present, the optional comment argument text is inserted as a comment in the generated header file for the domain just before the external declaration of the external operation function.
eentity MSG {
operation {char const *} Get_message {lang {char const *}} {} {
Get a message from the MSG external entity.
}
}
The population comands are used to define the intial instance population for a domain. Populations may be defined for classes and multiple assigners. Single assigner populations are automatically instanciated by micca. Base attribute values are specified as strings that are passed directly as initializers into the output ``C'' code. Referential values use the names of class instances to implement the references. Consider:
domain FlightSchedule {
class Passenger {
attribute Name {char[32]}
}
class Flight {
attribute FlightID {char[32]}
}
association R1 Passenger 0..*--1 Flight
}
The Passenger class is deemed to have an R1 referential attribute which must be given as the name of a Flight instance.
population FightSchedule {
class Passenger {
instance Fred R1 f1
instance Alice R1 f1
}
class Flight {
instance f1 FlightID SWA172
}
}
The ordering of the instance definitions is arbitrary. Above the Passenger instances may be defined before the Flight instances to which they are related are defined. The same pattern is used when specifying the links between a subclass instance and its related superclass instance. For associator classes, there are two references, one for each participant in the association. In that case the value of the referential attribute is a list consisting of two pairs, the class name and an instance name for one participant and a class name and instance name for the other participant.
class Ownership {
instance ow1 Acquired 2015 R23 {Owner fred Dog rover}
}
For reflexive associator classes, the class names of the participants are the same and so we resort to the keywords forward and backward to specify the references in the forward and backward directions of the association, respectively.
class Authorship {
instance ath1 R16 {forward author2 backward author1}
}
The class command (in a population command script) defines the population for a class named, class. The script argument is a script that is evaluated in a context where class population commands are available to define the initial population of class instances.
The assigner command defines the population the multiple assigner for the association named, association. The script argument is a script that is evaluated in a context where assigner population commands are available to define the initial population of class instances.
The instance command defines the attribute and relationship values for an instance of the enclosing class. The instance is named, name, and this name may be used to refer to the instance when supplying relationship linkage values. Instance names must be unque within the class to which they pertain. The attribute and relationship values are given in pairs by the compN / valueN arguments. Every component of the instance must either be specified in the instance command or have defined default values. An attribute may be given its default value by specifying the value of the attribute as a dash character ( - ). If the value of an attribute need to be a dash character, then it must be escaped with a backslash character ( \- )
instance dog1 Name Rover Born 2010
The table command allows defining multiple class instance in a more tabular layout. The heading is a list of instance component names, i.e. attribute names or relationship names. Each instance is defined by a name and a list of values. The values argument is a simple list of values and they are used as initializers in the same order as the attributes are listed in the heading.
table {Name Born}\
dog2 {Jumper 2012}\
dog3 {Fluffy 2015}
The allocation command requests that size number of additional storage slots be allocated for the class. The maximum number of instances of the class is the sum of the number of instances in the initial instance population plus size.
The instance command (in the context of an assigner population script) defines a multiple assigner instance called, name, and set the identifying instance of the assigner to idinstance. The idinstance must be the name of a class instance from the identifying class specified when the multiple assigner was defined (see identifyby command above).
Copyright © 2015 - 2020 by G. Andrew Mangogna