The Model Language

Labels

About labels

Stimuli in the models considered so far have been human-readable. However for some activities it may be necessary to associate arbitrary data with an arc, state, or model.

For example, one might wish to automate testing of an application using an automated testing tool. An arc with stimulus "Open" might correspond to the action left_button_click("OpenButton"). Further, one cannot know what the target language will be. Batch files, C source code, or proprietary scripting languages may all be used. Further, there may be different actions for the same model depending on the environment of testing.

To address this concern and others, TML supports attaching arbitrary information to models, states, and arcs. Such information is called a label.

Syntax

Labels are declared using one of two forms.

• all text within a {$..$} pair
• all text following a |$ token, up to and including the end of line character

TML does not interpret this information (except in the case of special characters, as discussed below). The information is simply stored for later use in test script generation or for other actions. (Some care is required; see the end of this section.)

Labels are attached to models, states, and arcs by writing the label declaration immediately after the model name, state name, or arc stimulus. In short, labels follow names. This distinguishes labels from constraints while keeping them close to the entity they describe.

Every label must be prefixed with a key followed by a colon :. Keys may consist of upper- and lower-case letter, digits, and underscores. All keys used for labels on a single entity (model, state, or arc) must be unique.

Label forms which follow one another are combined into a single label. The following two labels are equivalent.

// The {$..$} form can span multiple lines,
// but using it for multi-line labels is
// ugly.  This uses a multi-line label with
// key "c".
[Enter]
  "Start"
    c:{$#include <stdio.h>
int main(int argc, char *argv) {
  printf("Hello, world!");
}
$} [Startup]

// The |$ form was created specifically
// for labels which span multiple lines.
// The multi-line label with key "c" is
// repeated.
[Enter]
  "Start"
    c:|$#include <stdio.h>
      |$int main(int argc, char *argv) {
      |$  printf("Hello, world!");
      |$}
  [Startup]

Figure 1: Simple labels

In general, use the {$..$} form for labels which do not include end of line characters, or for the last line of a multi-line label if the last line should not have an end-of-line character. Use the |$ form for each line of a multi-line label which should include an end-of-line character.

Special characters

The usual C escapes are allowed: \n for newline (ASCII 10), \r for carriage return (ASCII 13), and \\ for a literal backslash character. Additionally, Unicode escapes (\uhhhh), hexadecimal escapes (\uhh), and octal escapes (\ooo) are allowed. For example the following all denote the same sequence of ASCII 13 followed by ASCII 10: \r\n, \x0d\x0a, \u000d\u000a, and \15\12.

The combination of a backslash and any character not mentioned simply inserts that particular character. This allows labels to include the $} and other character sequences which would normally be parsed as tokens by breaking them up with a backslash: $\}, for example.

Other uses of labels

Labels attach arbitrary information to arcs, states, and models. Other uses of labels include giving hints to conversion filters. For example, the GML filter uses labels with the key GML for graph layout information.

Warnings about labels

Be careful when commenting out labels which themselves contain long (C style) comments. The following is an example of one such error. TML takes the */ token of the comment in the label as the end of the comment.

/* Try to comment out the state.
[A State]
  "An event"
    c:|$ /* Click the open button. */
      |$ left_mouse_click("OpenButton");
  [NextState]
*/

Figure 2: Commenting error

The moral is: if you use long (C style) comments in a label, break up the end token with a backslash: *\/. This will avoid any problems when commenting out such labels.

Also, be sure that if a {$..$} label form must contain the characters $}, a backslash is used to break up the pair: $\}. TML takes the first occurrence of $} as the end of such a label.