help/info/template.html

   1 <!--
   2  Copyright (c) 2000-2015 Ericsson Telecom AB
   3
   4  All rights reserved. This program and the accompanying materials
   5  are made available under the terms of the Eclipse Public License v1.0
   6  which accompanies this distribution, and is available at
   7  http://www.eclipse.org/legal/epl-v10.html
   8  -->
   9 <html>
  10 <head>
  11 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  12 <meta http-equiv="Content-Language" content="en-us">
  13 <title>template</title>
  14 </head>
  15 <body bgcolor="#DAD3C5" vlink="#0094D2" link="#003258">
  16 <table align="left" border="0" cellspacing="0" cellpadding="0" valign=top>
  17   <tr>
  18     <td width=105 height=40><a href="https://projects.eclipse.org/projects/tools.titan"><img src="../images/titan_transparent.gif" border=0 width=105 height=40 align="left" alt="Titan"></a></td>
  19   </tr>
  20 </table>
  21 <table border="0" align="right" cellpadding="0" cellspacing="0">
  22   <tr>
  23     <td><a href="../titan_main.html" alt="contents"><img border="0" src="../images/ao.jpg" width="53" height="40"></a></td>
  24     <td><a href="../titan_index.html" alt="index"><img border="0" src="../images/up.jpg" width="53" height="40"></a></td>
  25     <td><a href="system.html" alt="previous"><img border="0" src="../images/left.jpg" width="53" height="40"></a></td>
  26     <td><a href="testcase.html" alt="next"><img border="0" src="../images/right.jpg" width="53" height="40"></a></td>
  27   </tr>
  28 </table>
  29 <p><br clear="all">
  30 </p>
  31 <hr>
  32 <h1>template</h1>
  33 <hr align="left" width="75%">
  34 <p>The keyword is a homonym. It is used to...
  35 <ol>
  36   <li>specify a set of values to be sent or received (<a href="#Templates">see below</a>);</li>
  37   <li>extend the range of allowed parameters (<a href="function.html#template">see here</a> <a href="#Example 3">and here</a>).</li>
  38 </ol>
  39 <p>Related keywords:</p>
  40 <ul>
  41   <li><a href="modifies.html"><b><font face="Courier New" color="#003258" size="4">modifies</font></b></a> (sense 1)</li>
  42   <li><a href="complement.html"><b><font face="Courier New" color="#003258" size="4">complement</font></b></a> (sense 1)</li>
  43   <li><a href="ifpresent.html"><b><font face="Courier New" color="#003258" size="4">ifpresent</font></b></a> (sense 1)</li>
  44   <li><a href="sizeof.html"><b><font face="Courier New" color="#003258" size="4">sizeof</font></b></a> (sense 1)</li>
  45   <li><a href="subset.html"><b><font face="Courier New" color="#003258" size="4">subset</font></b></a> (sense 1)</li>
  46   <li><a href="superset.html"><b><font face="Courier New" color="#003258" size="4">superset</font></b></a> (sense 1)</li>
  47   <li><a href="pattern.html"><b><font face="Courier New" color="#003258" size="4">pattern</font></b></a>
  48   <li><a href="permutation.html"><b><font face="Courier New" color="#003258" size="4">permutation</font></b></a> (sense 1)</li>
  49   <li><a href="function.html"><b><font face="Courier New" color="#003258" size="4">function</font></b></a> (sense 2)</li>
  50 </ul>
  51 <hr align="left" width="75%">
  52 <p>1. <a name="Templates">Templates</a> are used either to test whether a set of received values matches the template specification or to transmit a set of distinct values.
  53 <ul>
  54   <li>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
  55   valid one or not. This procedure is called matching.</li>
  56   <p>
  57   <li>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
  58   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.</li>
  59   </p>
  60 </ul>
  61 <hr align="left" width="50%">
  62 <div align="center">
  63 <center>
  64 <table border="0" width="90%" bgcolor="#FFB599" cellpadding="4">
  65   <tr>
  66     <td width="100%">
  67     <h3 align="center"><font face="Courier New" color="#003258" size="5"><b>template</b></font> <i>type identifier </i>[<i> formal_parameter_list</i> ] [<font face="Courier New" color="#003258"
  68       size="5"><b>&nbsp;modifies</b></font>&nbsp;<i>base_template_identifier</i>&nbsp;] := <i>body </i></h3>
  69     </td>
  70   </tr>
  71 </table>
  72 </center>
  73 </div>
  74 <ul>
  75   <li>
  76   <p><i>type</i> specifies the legal set of values of the template. In case of structured types it also determines the fields of the template.</p>
  77   </li>
  78   <li>
  79   <p><i>identifier</i> is a name used to refer to the template. Must begin with a letter, may contain letters, numbers and
  80   underscore characters. According to the&nbsp; Naming convention, the prefix <b>t_</b> or <b>tr_</b> is recommended. The former one is used denote a
  81   specific value the template used with sending operations, whereas the latter one is used to denote a receiving template including field matching.</p>
  82   </li>
  83   <li>
  84   <p><i> formal_parameter_list</i> 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
  85   sense 2., <a href="#Example 3">see example</a>) These optional parameters may be used to alter the template at every invocation.</p>
  86   </li>
  87   <li>
  88   <p><font face="Courier New"><b>modifies</b></font> denotes a <a href="#Example 4">derived template</a> where only some of the fields of the original template are changed.</p>
  89   </li>
  90   <li>
  91   <p><i>base_template_identifier</i> identifies the parent template some of the field of which are modified. Both templates have the same fields.</p>
  92   </li>
  93   <li>
  94   <p><i>body</i> 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
  95   mechanisms are elucidated in detail in Annex B of the standard. Below, abundant examples are given as illustrations.</p>
  96   </li>
  97 </ul>
  98 <hr align="left" width="50%">
  99 <p>Examples:</p>
 100 <ol>
 101   <li><a href="#parametrized">Parameterized value list template</a></li>
 102   <li><a href="#Example 2">Value range template, parameterized with a template parameter</a></li>
 103   <li><a href="#Example 3">Complemented value list template</a></li>
 104   <li><a href="#ifpresent">Matching not omitted optional fields only</a></li>
 105   <li><a href="#subset">Excluding a field with superfluous elements</a></li>
 106   <li><a href="#superset">Excluding a field with missing elements</a></li>
 107   <li><a href="#Example 7">Character pattern matching</a></li>
 108   <li><a href="#Example 4">Modified template</a></li>
 109 </ol>
 110 <hr align="left" width="50%">
 111 <p><a name="parametrized">Example</a> 1 (parameterized value list template):
 112 <p><font face="Courier New">type record MyMessageType {<br>
 113 <blockquote>integer&nbsp;&nbsp;&nbsp;&nbsp;field1 optional,<br>
 114 charstring field2,<br>
 115 boolean&nbsp;&nbsp;&nbsp;&nbsp;field3<br>
 116 }</blockquote>
 117 <p>template MyMessageType tr_MyTemplate (boolean pl_param) := {<br>
 118 <blockquote>field1 := ?,<br>
 119 field2 := (”B”, ”O”, ”Q”),<br>
 120 field3 := pl_param<br>
 121 }</blockquote>
 122 </font>
 123 <p>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
 124 tr_MyTemplate. In the template name prefix, 't' stands for 'template' and 'r' for receiving.<br>
 125 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
 126 function of the parameter pl_param either true or false.<br>
 127 The template can be used for receiving only, because it contains an undefined field (the first one).</p>
 128 <hr align="left" width="25%">
 129 <p><a name="Example 2">Example 2</a> (value range template, parameterized with a template parameter):
 130 <p><font face="Courier New">type record MujMessageType {<br>
 131 <blockquote>integer&nbsp;&nbsp;&nbsp;&nbsp;field1 optional,<br>
 132 charstring field2,<br>
 133 float&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;field3<br>
 134 }</blockquote>
 135 <p>template MujMessageType tr_MujTemplate (template integer pl_parametr) := {<br>
 136 <blockquote>field1 := pl_parametr,<br>
 137 field2 := (”C” .. ”X”),<br>
 138 field3 := (1.0 .. 1.37)<br>
 139 }</blockquote>
 140 </font>
 141 <p>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
 142 tr_MujTemplate.<br>
 143 The template accepts the following messages: the first field is determined by the parameter pl_parametr.&nbsp; When the actual value of the parameter gives a value or a range, the field must have the
 144 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
 145 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.<br>
 146 The template can be used for receiving only, because it contains an undefined field (the first one).</p>
 147 <hr align="left" width="25%">
 148 <p><a name="Example 3">Example 3</a> (complemented value list template):
 149 <p><font face="Courier New">type record MiaMessageType {<br>
 150 <blockquote>float&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;field1 optional,<br>
 151 charstring field2,<br>
 152 integer&nbsp;&nbsp;&nbsp;&nbsp;field3<br>
 153 }</blockquote>
 154 <p>template MiaMessageType tr_MiaTemplate&nbsp; := {<br>
 155 <blockquote>field1 := *,<br>
 156 field2 := complement (”C”, &quot;L&quot;, ”X”),<br>
 157 field3 := (1 .. infinity)<br>
 158 }</blockquote>
 159 </font>
 160 <p>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
 161 tr_MiaTemplate.<br>
 162 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
 163 C, L, and X. The value of the last field must be greater than 1.</p>
 164 <hr align="left" width="25%">
 165 <p><a name="ifpresent">Example 4</a> (matching not omitted optional fields only):
 166 <p><font face="Courier New">type record MonMessageType {<br>
 167 <blockquote>float&nbsp; &nbsp;&nbsp;&nbsp;&nbsp;field1 optional<br>
 168 }</blockquote>
 169 <p>template MonMessageType tr_MonTemplate&nbsp; := {<br>
 170 <blockquote>field1 := (1.0 .. 1.99, 2.71) ifpresent<br>
 171 }</blockquote>
 172 </font>
 173 <p>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.<br>
 174 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.</p>
 175 <hr align="left" width="25%">
 176 <p><a name="subset">Example 5</a> (excluding a field with superfluous elements):
 177 <p><font face="Courier New">type set of integer MeinMessageType;</font>
 178 <p><font face="Courier New"> template MeinMessageType tr_MeinTemplate&nbsp; := subset { 1, 2, 3 };</font>
 179 <p>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)</p>
 180 <hr align="left" width="25%">
 181 <p><a name="superset">Example 6</a> (excluding a field with missing elements):
 182 <p><font face="Courier New">type set of integer MeenMessageType;</font>
 183 <p><font face="Courier New"> template MeenMessageType tr_MeenTemplate&nbsp; := superset { 1, 2, 3 };</font>
 184 <p>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)</p>
 185 <hr align="left" width="25%">
 186 <p><a name="Example 7">Example 7</a>: (character pattern matching)</p>
 187 <p><font face="Courier New">template charstring tr_AzulejoTemplate:= pattern &quot;ab?\?xyz*&quot;;</font>
 188 <p>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
 189 any number of any characters.</p>
 190 <hr align="left" width="25%">
 191 <p><a name="Example 4">Example 8</a> (modified template):
 192 <p><font face="Courier New">// Parent template:<br>
 193 template MyMsgType t_MyMessage1 := {<br>
 194 <blockquote>field1 := 123,<br>
 195 field2 := true<br>
 196 }</p>
 197 </blockquote>
 198 // modified template:
 199 <br>
 200 template MyMsgType t_MyMessage2 modifies t_MyMessage1 :={
 201 <br>
 202 <blockquote>field2 := false<br>
 203 }
 204 </p>
 205 </blockquote>
 206 </font>
 207 <p>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
 208 the second one has a new value assigned (false).
 209 <hr align="left" width="25%">
 210 <hr align="left" width="25%">
 211 <p><a HREF="../info/BNF.html#templatedef">BNF definition</a> of <font face="Courier New"> template</font> (sense 1)<br>
 212 <a HREF="BNF.html#formaltemplatepar">BNF definition</a> of <font face="Courier New"> template</font> (sense 2)</p>
 213 </body>
 214 </html>