MAML Reference Manual for (xmc) v0.03.1

Table of Contents

Introduction

MAML Lexical Elements and High Level Structures

PrePro: The `Preprocessor Phase'

Importing External Files

Defining New Words

Other Features

MAML: Keywords and High Level Structures

Creating Model and Observer

Introducing and Extending Agents

Introducing Variables and Subroutines

Planning and Scheduling

The `Create Phase'

Probing Variables

Using C, Objective-C, Swarm and Other Library Functions

The Initialization Phase

Final Complex Example

General Lexical Elements and Other Standard Names

Introduction

[Back to the Table of Contents]

MAML Lexical Elements and High Level Structures

[Back to the Table of Contents]

PrePro: The `Preprocessor Phase'

The PrePro lexical elements are:

$ , : ;
import global local
define undefine

ifdef ifndef elifdef elifndef else begin end
error warning fatal

In a MAML source code one can use C and C++ comment notation as any text coming after `//' to the end of line or enclosed between `/*' and `*/' will be eliminated in the preprocessor phase. Very long lines can be broken up into multiple ones by using the `\' sign. If the `\' sign stands at the end of a line, it will be eliminated and the next line will be joined to the current one.

In what follows, a short presentation of the implemented PrePro keywords will come. The most important are: import and define. We will focus on these in the next subsections.

[Back to the Table of Contents]

Importing External Files

A typical example for the usage is: 

$import "myfirst.maml.stub", "mysecond.maml.stub";

The usage for these is:

$import local "myfirst.maml.stub", global "mysecond.maml.stub";

[Back to the Table of Contents]

Defining New Words

A simple definition looks like: 

$define first_word : "FIRST WORD", second_word : "SECOND WORD", third_word;

After a definition, any identifier matching the defined word will be replaced with the given string (without the `"' sign) as it would be printed using the C `printf' function. If the string is omitted, the word will be `defined' but won't be replaced in the subsequent text. This feature  was introduced to support `ifndef/ifdef' structures which take as an argument a word which could be either defined or undefined; but the definition itself (the string following the `:' sign), is unimportant. (The `ifndef/ifdef' structures have not been implemented yet, but will be implemented later.)

One can also use an `undefine' directive, which tells the compiler to forget the previously defined word and stop replacing it with some given string. The `undefine' directive can also take as an argument a word which wasn't previously defined, and it may come many times without limitations. A defined word cannot be redefined unless the definition is exactly the same as before, or it comes after an `undefine' (after which any word can take a new definition).

To undefine the `second_word' and the `third_word' one can enter: 

$undefine second_word, third_word;

The error messages related to word definitions are: "Illegal redefinition of symbol", "Define string expected", "Invalid define string". The first is issued when a definition is repeated with different `define' string. The second specifies that at the given place a `define' string would be expected. This message typically appears when there is a discordance with the define syntax. The third is issued when there is something wrong with the `define' string (e.g., it contains a line break).

[Back to the Table of Contents]

Other Features

[Back to the Table of Contents]

MAML: Keywords and High Level Structures

The MAML keywords and special signs are: 

, : ; @ { } ( ) [ ] []
model observe gui batch as agent extendAgent
var sub inline private protected public static
char int short long float double boolean string id void
planDef addToPlan extendPlan seq con rnd plan to forEach
schedule addToSchedule extendSchedule cyclic relative in
create createBegin createEnd probe
init initModel buildProbes uses

MAML also defines a few reserved variables, whose use will be discussed later. These variables have the following form:

maxTimeSteps
groupOf***

[Back to the Table of Contents]

Creating Model and Observer

A simple MAML program looks like: 

@model MyModel {}
@observe MyModel {}

@model MyModel {}
@observe MyModel as MyObserver {}

@model MyModel {}
@observe MyModel batch as MyObserver {}

@model MyModel {}
@observe MyModel batch {}

The MAML system provides the `model' variable name, which denotes the model defined in the current application. Any internal structure of the model can be accessed using the `model-><V/SN>' construct where `<V/SN>' denotes any variable or subroutine name. (In the model's instance-subroutines one can use `self' instead of `model'.)

In accordance with the MAML syntax the model name must be a C-identifier (as described earlier), otherwise the "Identifier expected" error message will be issued. If the model name is omitted in the `model' or `observe' directive, the "Model name expected" or the "Invalid extension of model" error will be sent. (The same error is sent if one tries to `observe' an undefined model.) If the `as' keyword is not followed by a valid observer name, the "Observer name expected" error is generated.

[Back to the Table of Contents]

Introducing and Extending Agents

Each agent has a name which has to be specified as follows: 

@agent MyAgent {}

In some computational aspects agents are `objects', thus MAML is going to be an OOP language but it will try to simplify and reorganize the OOP way of thinking by blurring the objects' boundaries, making them look more like `real agents'. As a typical OOP feature, an agent may inherit another agent as in the following example:

@agent MySecondAgent : MyFirstAgent {}

Any agent can be extended unlimited times with the help of the `extendAgent' keyword. This keyword needs the agent's name to be extended:

@extendAgent MyAgent {}

For any agent class, an agent list is generated automatically with the name of `groupOf<Agent Name>' where `<Agent Name>' denotes the agent's class name. Using this list any member of the agent class can be referenced in one `group'.

If an agent uses the name of a previously defined agent, the "Multiple declaration for agent" error will be generated. If one tries to extend an agent which wasn't defined, the "Invalid extension of agent" error will be issued. If something is wrong with the agent or agent super-class name, the "Identifier expected", "Agent name expected" or the "Invalid inheritance" errors will be issued.

[Back to the Table of Contents]

Introducing Variables and Subroutines

The `private', `protected' and `public' keywords specify the protection type (in the OOP meaning) for agent variables and subroutines. Only one of these can be used for any variable or subroutine. The default value (if no protection type is specified) is `public'. This means that any agent (and the model) can access the given variable or subroutine. The `protected' and `private' ones can be accessed only within the agent's class, and the difference between them is that the `private' variables and subroutines cannot be accessed in any sub-class.

In the current version of the compiler, the `protected' and `private' subroutines are only partially supported due to restricted Objective-C capabilities. These modifiers lead to a warning message of the form: "Structure only partially supported".

Objective-C  introduces the so called `+/- subroutines' and the idea of instance, class variables, and methods. This idea finds its MAML equivalent in static variables and subroutines which are the class variables and subroutines. The  default type for these is `non-static'; thus, by default they are instance variables and subroutines. The static subroutines are the equivalent of the Objective-C `+ subroutines' and the non-static subroutines for the `- subroutines'. Like the `protected' and `private' subroutines, the `static' variables are only partially supported. The `static' modifier for variables leads to the already mentioned warning message.

In the current version, MAML and its compiler (xmc)  provides the `inline' modifier which defines any Objective-C variables and subroutines. (This keyword may disappear in later versions.) Without the `inline' modifier only restricted types of variable and subroutine definitions are allowed. These will be changed later to fulfill the requirements of a `real programming language' in a genuine MAML style.

The implemented, basic variable types are: `char', `int', `short', `long', `float', `double', `boolean', `string', `id'. In general these have been borrowed from C and Objective-C. The `string' and `boolean' types are defined as follows:

typedef enum {false, true} boolean;
typedef char string[256];

A simple integer variable definition looks like: 

@var: int x1, x2;

Simple arrays of variables of type `int' can be defined as:

@var: [] int x1, x2;

@var: [][] int y1, y2;

Using the `inline' modifier you can enter any C-like definition:

@var inline: int (*f[10])(char *);
@var inline: MyAgent * a;
@var inline: id <List> l;

If you use `inline' in variable declaration, any agent variable must be preceded by the `*' sign. (We will return to these with more details in the MAML Technical Manual.) As in the above example the modifiers may come between the var keyword and the `:' sign. No specific order is defined for the modifiers. For example:

@var static protected: int x;

@var protected static: int x;

Subroutines are defined in a very similar way to Objective-C methods. A subroutine headline looks like:
 

(<RT>) <BN> : (<PT1>) <P1> <NE1> : (<PT2>) <P2> <NE2> : (<PT3>) <P3>

Unlike Objective-C, the return and parameter types are obligatory. If they are omitted the following error messages are generated: "Subroutine return type expected", and "Subroutine parameter type expected". For return and parameter types, you can use the same constructs as for variable definition (e.g., [] int, [][] char). If the parameter types are incorrect, the following error messages will be generated: "Illegal subroutine return type", and "Illegal subroutine parameter type".

Some simple examples for these are:

@sub: (void) skip {}
@sub: (int) print: (string) {}
@sub: (int) setFor: (int) i Name: (string) {}
@sub: (int) setNameFor: (int) i: (string) {}

@sub inline: setFor: i Name: (char *) t {}

@sub static protected: (void) skip {}

The names of the variables and subroutines must be unique in an agent or in the model. Different agents may use the same names, and the model and an agent can both have a variable or subroutine with the same name, but you cannot have a variable or a subroutine with the same name in the model or an agent. Variable and subroutine names are C-type identifiers (of the form discussed earlier). The names cannot be either keywords or reserved variables of Swarm, Objective-C, or C. (For reserved words, please contact your language manual.) MAML also provides reserved names (as was already mentioned); but you can use keywords as subroutine names, but you cannot use keywords for variable names.

[Back to the Table of Contents]

Planning and Scheduling

To define a plan, you must use the `planDef' keyword. Each plan has a name and an execution order. The latter can be of three different types: sequential, concurrent, and randomized. The `seq', `con' and `rnd' keywords are used to denote these types. The sequential type instructs the computer to execute the actions in the given plan sequentially in the specified order. For concurrent and randomized types, parallel and respectively randomized execution order will be used. The default value for the execution order (if nothing is specified) is sequential (i.e., seq). The current version of the (xmc) compiler cannot generate code for `concurrent' and `randomized' order, because there is no implementation for them in Swarm; thus it generates a warning message (Structure not supported yet) and any plan is created in `sequential' order.

An empty plan is defined as follows:

 @planDef myPlan {}

@planDef myPlan rnd {}

You can insert actions in a plan by using the `plan', `to', `forEach', and `planDef' keywords. The `plan' keyword subscribes the execution of a plan that was defined elsewhere. The `to' and `forEach' keywords plan the execution of model and agent subroutines. The `to' keyword refers to the model or only one agent, while the `forEach' keyword refers to a list of agents. (A special agent list is created automatically for any agent class as was described earlier. But you can create any other agent list using Swarm tools.) The `planDef' keyword defines a new sub-plan which is automatically introduced in the current one. The `plan' keyword needs the name of a plan as an argument. The `to' and `forEach' keywords need an agent name, and an agent list name, and a valid subroutine name. The inner `planDef' keyword needs an optional plan name. If no name is specified, a name will be created automatically by the compiler, but this remains hidden and cannot be referenced anywhere else. The outer `planDef' always requires a name, because it has to be referenced in a schedule (see following text). Aside from the mentioned name problem, the inner `planDef' follows the same rules as the outer one, and  thus a recursive plan definition can be created. There is no limitation for the recursive plan's depth.

A simple example for this looks like:

@planDef myPlan {
    @to myFirstAgent doSomething;
    @forEach myAgentList doSomethingElse;
    @plan myPreviousPlan;
    @planDef rnd {}
}

A schedule differs from a plan in that for each action there is a time specification. For example:

@schedule  mySchedule {
    1: @to myFirstAgent doSomething;
    3: @forEach myAgentList doSomethingElse;
    4: @plan myPreviousPlan;
    6: @planDef rnd {}
}

An empty relative schedule and an empty cyclic schedule with a time period of 10 arbitrary units looks like:

@schedule relative {}
@schedule cyclic (10) {
    0: @to myFirstAgent doSomething;
    5: @forEach myAgentList doSomethingElse;
    9: @plan myPreviousPlan;
}

A schedule may reference any plan in a MAML code even if this is defined later but can reference only the schedules defined earlier.

To extend a plan or a schedule, MAML provides the `extendPlan' and `extendSchedule' keywords. These keywords take as an argument the plan or schedule's name, which then has to be extended.
 

@extendPlan myFirstPlan {}
@extendSchedule myFirstSchedule {}

For dynamic extension of plans and schedules, you can use the `addToPlan' and `addToSchedule' keywords. These keywords -- as for static extension -- take a plan and a schedule name. 

@addToPlan myFirstPlan {}
@addToSchedule myFirstSchedule {}

[Back to the Table of Contents]

The `Create Phase'

To create an array of 10 integers and store the information in the x degenerated variable you can type: 

@create [10] int x;

@var: [] int x;

@create [10:i] int x { x[i]=0; }

@create [10] int x { x[_i1_]=0; }

@create [10:i][5:j] int x { x[i][j]=0; }

The syntax for the creation of agent variables is largely the same as presented above. To create a GoodGuy agent (defined previously with the agent keyword) you can use the following: 

@create GoodGuy whoMomLikes { [whoMomLikes setName: "Joe"]; }

@createBegin GoodGuy whoMomLikes;
[whoMomLikes setName: "Joe"];
@createEnd GoodGuy whoMomLikes;

@create [10] GoodGuy whoMomLikes;

@var: [] GoodGuy whoMomLikes;

@create [10] int x, y;
@create [10] GoodGuy allMyFriends, otherPeople;

The values in a created array can be accessed by indexing, but you must be careful with this because the current version of the compiler performs no check on the index range, and thus wrong indexing can generate run-time error.

MAML also provides the `create', `createEnd', and `createBegin' predefined subroutines for model and agents. These are inherited methods, and thus they can be changed (in OOP meaning). You can call these subroutines directly or use the create constructs, as presented above, which add more functionality. (The details for this can be found in the MAML Technical Manual.)

If the creation of a variable of a `non-degenerated' standard type (e.g. int, char, id, ..) is forced, the "Cannot create non-degenerated standard type" error will be issued. Aside from this problem, the same error messages are sent in the `create phase' as in the variable declaration that we disussed earlier.

[Back to the Table of Contents]

Probing Variables

One can use `probe' for either variables or subroutines in the following way:

@probe: var "x1", sub "skip", var "x2", sub "setFor:Name:";

[model probe];
[myAgent probe];

[Back to the Table of Contents]

Using C, Objective-C, Swarm and Other Library Functions

@uses <stdio.h>, "myCRoutines.h";

The "String or bracketed string expected" error will be generated if something is wrong with file names specified in a `uses' directive. In the current version of the compiler, the files denoted by the specified names are not tested. (Any potential error will be detected only in a Swarm compilation phase.)

[Back to the Table of Contents]

The `Initialization Phase'

To create an initialization routine you can use the example below:

@model MyModel {
    @var: int x;
@init:
    x=1;
}

@observe MyModel {
    @probe: var "x";
@init:
   @initModel;
   @buildProbes;
   [model probe];
}
 
 

MAML provides the `maxTimeSteps' variable to set the maximal timesteps of the model. This variable may be set in the initialization phase. By default its value is `-1' which means that there is no upper limit for executing timesteps. MAML also provides the `stop' predefined model subroutine, which (if it is called in either a subroutine or initialization routine) will hang up the simulation.

[Back to the Table of Contents]

Final Complex Example

@model MyModel {
    @uses <stdio.h>, <stdlib.h>;

    @var: int x;
    @sub: (id) incX { x+=1; return self; }

    @agent MyAgent {
         @uses <stdio.h>;

         @var: int y;
         @sub: (id) incY { y+=1; return self; }
     }

    @var: MyAgent a1, a2;

    @planDef myPlan {
         @to a1 incY;
         @to a2 incY;
     }

    @schedule mySchedule cyclic (3) {
         0: @to model incX;
         1: @plan myPlan;
    }

@init:
     model->x=0;
    @create MyAgent a1, a2 { a1->y=0; a2->y=0; }
}

@observe MyModel {
     @sub: (void) printX { printf("x: %d\n",x); }

     @extendAgent MyAgent {
          @sub: (void) printY { printf("y: %d\n",y); }

          @probe: var "y", sub "incY";
     }

     @extendPlan myPlan {
          @to a1 printY;
          @to a2 printY;
     }

    @extendSchedule mySchedule {
          2: @to model printX;
    }

    @probe: var "x", sub "incX";

@init:
    @initModel;
    @buildProbes;
    [model probe];
    [a1 probe]; [a2 probe];
}
 

[Back to the Table of Contents]

General Lexical Elements and Other Standard Names

In addition to the MAML keywords, C, Objective-C, and Swarm define keywords and standard names which can be used in MAML code. To avoid name conflicts, you must take this in consideration when creating your own (model, agent, variable, subroutine, plan, schedule, .. etc.) names. For these, please refer to the appropriate reference manuals.

[Back to the Table of Contents]
[Back to the Top of Page]