# template

The keyword is a homonym. It is used to...

1. specify a set of values to be sent or received (see below);
2. extend the range of allowed parameters (see here and here).

Related keywords:

- modifies (sense 1)
- complement (sense 1)
- ifpresent (sense 1)
- sizeof (sense 1)
- subset (sense 1)
- superset (sense 1)
- pattern
- permutation (sense 1)
- function (sense 2)

1. Templates are used either to test whether a set of received values matches the template specification or to transmit a set of distinct values.

- Templates used to receive messages have the advantage that all valid message variants may be described in a single template. When a message arrives, the program can decide whether it is a valid one or not. This procedure is called matching.

- Templates used to send messages are advantageous because they can be parameterized, thus, reused. All fields of these templates must have a determined value at the point when a message is sent using them. These templates may be used to receive messages as well, but only when all fields of the expected message are fixed and known beforehand.

### template type identifier [ formal_parameter_list ] [ modifies base_template_identifier ] := body

- type specifies the legal set of values of the template. In case of structured types it also determines the fields of the template.

- identifier is a name used to refer to the template. Must begin with a letter, may contain letters, numbers and underscore characters. According to the Naming convention, the prefix t_ or tr_ is recommended. The former one is used denote a specific value the template used with sending operations, whereas the latter one is used to denote a receiving template including field matching.

- formal_parameter_list provides the list of the parameters of the template. The formal parameters themselves can be templates or values. (In the first case, the keyword is used in sense 2., see example) These optional parameters may be used to alter the template at every invocation.

- modifies denotes a derived template where only some of the fields of the original template are changed.

- base_template_identifier identifies the parent template some of the field of which are modified. Both templates have the same fields.

- body lists the permitted values for each field: constants, matching expressions, templates or parameter references shall be assigned to each field of a template. The matching mechanisms are elucidated in detail in Annex B of the standard. Below, abundant examples are given as illustrations.

Examples:

1. Parameterized value list template
2. Value range template, parameterized with a template parameter
3. Complemented value list template
4. Matching not omitted optional fields only
5. Excluding a field with superfluous elements
6. Excluding a field with missing elements
7. Character pattern matching
8. Modified template

Example 1 (parameterized value list template):

type record MyMessageType {

> integer field1 optional,
> charstring field2,
> boolean field3
> }

template MyMessageType tr_MyTemplate (boolean pl_param) := {

> field1 := ?,
> field2 := (âBâ, âOâ, âQâ),
> field3 := pl_param
> }

First, we define a record (MyMessageType) containing three fields, the first one being optional. The type of the template will be the one just defined. The template we'll define is called tr_MyTemplate. In the template name prefix, 't' stands for 'template' and 'r' for receiving.
The template accepts the following messages: the first field must be present, but its content is don't care. The second field may have the value B, O or Q. The value of the last field must be in function of the parameter pl_param either true or false.
The template can be used for receiving only, because it contains an undefined field (the first one).

Example 2 (value range template, parameterized with a template parameter):

type record MujMessageType {

> integer field1 optional,
> charstring field2,
> float field3
> }

template MujMessageType tr_MujTemplate (template integer pl_parametr) := {

> field1 := pl_parametr,
> field2 := (âCâ .. âXâ),
> field3 := (1.0 .. 1.37)
> }

First, we define a record (MujMessageType) containing three fields, the first one being optional. The type of the template will be the one just defined. The template we'll define is called tr_MujTemplate.
The template accepts the following messages: the first field is determined by the parameter pl_parametr. When the actual value of the parameter gives a value or a range, the field must have the same value or range. When the parameter contains an asterisk, the field may be absent. When the parameter holds a question mark, the field must be present, but its content is don't care. The second field may have any value from the series C, D, E, and so on to X included. The value of the last field must be between 1.0 and 1.37.
The template can be used for receiving only, because it contains an undefined field (the first one).

Example 3 (complemented value list template):

type record MiaMessageType {

> float field1 optional,
> charstring field2,
> integer field3
> }

template MiaMessageType tr_MiaTemplate := {

> field1 := *,
> field2 := complement (âCâ, "L", âXâ),
> field3 := (1 .. infinity)
> }

First, we define a record (MiaMessageType) containing three fields, the first one being optional. The type of the template will be the one just defined. The template we'll define is called tr_MiaTemplate.
The template accepts the following messages: the first field may be either absent or present, in either case its content is don't care. The second field may have any value except the capital letters C, L, and X. The value of the last field must be greater than 1.

Example 4 (matching not omitted optional fields only):

type record MonMessageType {

> float field1 optional
> }

template MonMessageType tr_MonTemplate := {

> field1 := (1.0 .. 1.99, 2.71) ifpresent
> }

First, we define a record (MonMessageType) containing an optional field. The type of the template will be the one just defined. The template we'll define is called tr_MonTemplate.
The template accepts the following messages: the first field may be either absent or present. If it is present, its value must either fit in the range 1.0 .. 1.99 or equal 2.71.

Example 5 (excluding a field with superfluous elements):

type set of integer MeinMessageType;

template MeinMessageType tr_MeinTemplate := subset { 1, 2, 3 };

The template matches the sets {1,3,1,2} and {1,3} but does not match {4,3,2} and {0,1,2,3,4}. (In the latter sets there are superfluous elements, like 0 or 4)

Example 6 (excluding a field with missing elements):

type set of integer MeenMessageType;

template MeenMessageType tr_MeenTemplate := superset { 1, 2, 3 };

The template matches the sets {1,3,1,2} and {0,1,2,3,4} but does not match {1,3} and {4,3,2}. (In the latter sets there are missing elements, like 2 or 1)

Example 7: (character pattern matching)

template charstring tr_AzulejoTemplate:= pattern "ab?\?xyz*";

The template tr_AzulejoTemplate would match any character string which consists of the characters 'ab', followed by a single arbitrary character, followed by the characters '?xyz', followed by any number of any characters.

Example 8 (modified template):

// Parent template:
template MyMsgType t_MyMessage1 := {

> field1 := 123,
> field2 := true
> }

// modified template:
template MyMsgType t_MyMessage2 modifies t_MyMessage1 :={

> field2 := false
> }

The modified template (t_MyMessage2) has the same structure (the same fields) as the parent template (t_MyMessage1). The first field has the same value as specified in the parent template, but the second one has a new value assigned (false).

BNF definition of template (sense 1)
BNF definition of template (sense 2)