Targeted Text statements: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
 
(6 intermediate revisions by 3 users not shown)
Line 1: Line 1:
The AuditText, PrintText, and TraceText statements are abbreviated forms of the [[Text and Html statements]].
__TOC__
They have the same effect as the Text Audit, Text Print, and Text Trace statements respectively.
The <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var> statements are abbreviated forms of the [[Text and Html statements|Text and Html]] statements.
The AuditText, PrintText, and TraceText statements are available in Sirius Mods 7.2 and later.
They have the same effect as the <var>Text Audit</var>, <var>Text Print</var>, and <var>Text Trace</var> statements, respectively.
The <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var> statements are available in <var class="product">Sirius Mods</var> 7.2 and later.
The <var>[[#SetText statement|SetText]]</var> statement, which is available in <var class="product">Sirius Mods</var> 7.8 and later,
uses the same syntax as <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var> to set a target variable.
And the <var>[[#ReturnText statement|ReturnText]]</var> statement, which is available in <var class="product">Sirius Mods</var> 7.8 and later, uses the same syntax as <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var> to return a string value from a <var class="product">User Language</var> function or property <var>Get</var> method.


The [[#SetText statement|SetText statement]], which is available in Sirius Mods 7.8 and later, uses the same syntax as AuditText, PrintText, and TraceText to set a target variable. And the [[#ReturnText statement|ReturnText statement]], which is available in Sirius Mods 7.8 and later, uses the same syntax as AuditText, PrintText, and TraceText to return a string value from a User Language function or property Get method.
==AuditText, PrintText, and TraceText==
The <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var> keywords are simply a merging and reordering of <var>Text Audit</var>, <var>Text Print</var>, and <var>Text Trace</var> to emphasize the principle action.  


The AuditText, PrintText, and TraceText keywords are simply a merging and reordering of Text Audit, Text Print, and Text Trace to emphasize the principle action. The lone difference between the former and latter forms is that the former cannot be used if you want to include other Html/Text options, as in:
<var>AuditText</var> sends its output to the <var class="product">Model 204</var> audit trail, <var>PrintText</var> sends its output to the current output stream (output terminal or use dataset), and <var>TraceText</var> sends its output to the current trace targets.
  text noexpr print The set is {2, 3, 5, 8, 13, ...}
These statements are the recommended/preferred alternatives to the traditional <var>Audit</var>, <var>Print</var>, and <var>Trace</var> statements.
However, as of Sirius Mods 7.8, certain Text statement directives can be placed after a tilde character (~) inside curly braces ({ }) in any of the targeted text statements. For example, this statement sets <tt>%ls</tt> to the current time, embedded in hyphens.  
They are recommended because they are more flexible and have more consistent behavior.
  setText %ls = {~nocont}---{$time}---
Because the <tt>~nocont</tt> directive was specified, the terminating hyphen is not treated as a continuation character.  


The '''tilde directives''' that are allowed in targeted text statements are:
All text not inside curly braces in an <var>AuditText</var>, <var>PrintText</var>, or <var>TraceText</var> statement is considered to be literal text. For example, the following statement will display <code>Suit the action to the word, the word to the action</code> on the primary output stream:
<dl>
<p class="code">printText Suit the action to the word, the word to the action </p>
<dt>~exprE
You can place values of variables and also calculated values inside of curly braces to display the value of what is inside the braces.
<dd>Sets the expression end characters. This directive must be followed by a space and then the expression start characters. For example, <tt>{~expre >}</tt> sets the expression end characters to a single greater-than sign (>). ~exprE can also be written as <tt>~exprEnd</tt>.
For example, these statements:
<p class="code">%i = 22
%j = 33
printText %i = {%i}, %j = {%j}, %i * %j = {%i * %j}   </p>
 
Display the following:
<p class="code">%i = 22, %j = 33, %i * %j = 726</p>


'''Note:''' The ~exprE directive must be ended by the current expression end characters, that is, by the end characters that the ~expre directive is replacing.
Any valid expression is allowed inside the curly braces, including those that contain parentheses, $functions, and method calls.
<dt>~exprS
For example, the following statements:
<dd>Sets the expression start characters. This directive must be followed by a space and then the expression start characters. For example, <tt>{~exprs <}</tt> sets the expression start characters to a single less-than sign (<). ~exprS can also be written as  <tt>~exprStart</tt>.
<p class="code">%i = 22
<dt>~noCont
%j = 33
<dd>Indicates that a trailing hyphen is not treated as a continuation character. ~noCont can also be written as <tt>~noContinuations</tt>.
printText %i = {%i}, %j = {%j}, (%i + %j):toPower(3) = {(%i + %j):toPower(3)} </p>
<dt>~noEll
Display:
<dd>Indicates that a trailing ellipsis (...) is '''not''' treated as a partial-line indicator. Because it makes no sense to end a SetText or ReturnText with an ellipsis, this is the default for those two statements. So, while allowed, a ~noEll directive is completely unnecessary for SetText and ReturnText. ~noEll can also be written as <tt>~noEllipses</tt>.
<p class="code">%i = 22, %j = 33, (%i + %j):toPower(3) = 166375</p>
<dt>~noExpr
<dd>Indicates that no expressions are to be processed after the directive, and that everything after the ~noExpr directive is treated as literal text. No further tilde directives will be processed after a ~noExpr. ~noExpr can also be written as <tt>~noExpressions</tt>.
<dt>~raw
<dd>Acts as if ~noCont, ~noEll, and ~noExpr are specified simultaneously.


'''Note:''' This is slightly different from the <tt>Raw</tt> directive on the Text/Html statement, which also implies NoDum/NoDummy. Because dummy string substitution applies to lines before they are parsed, dummy string substitution would already have happened in any single-line Text statement before the ~raw directive was processed.
===~ and ~= directives===
</dl>
A single tilde character inside curly braces, <b>{~}</b>, must be followed (possibly with some intervening text) by an expression inside curly braces. The <b>{~}</b> would then be replaced with the literal contents of the following curly braces.


AuditText sends its output to the [[Model 204]] audit trail, PrintText sends its output to the current output stream (output terminal or use dataset), and TraceText sends its output to the current trace targets.
For example, the following sequence:
These statements are the recommended/preferred alternatives to the traditional Audit, Print, and Trace statements.
<p class="code">%i = 22
They are recommended because they are more flexible and have more consistent behavior.
%j = 33
printText {~} = {%i}, {~} = {%j}, {~} = {(%i + %j):toPower(3)}  </p>


All text not inside curly braces in an AuditText, PrintText, or TraceText statement is considered to be literal text. For example, the following statement will display <tt>Suit the action to the word, the word to the action</tt> on the primary output stream:
Displays:  
  printText Suit the action to the word, the word to the action
<p class="code">%i = 22, %j = 33, (%i + %j):toPower(3) = 166375</p>
You can place values of variables and also calculated values inside of curly braces to display the value of what is inside the braces.
For example, the following would display <tt>%i = 22, %j = 33, %i * %j = 726</tt>:
  %i = 22
  %j = 33
  printText %i = {%i}, %j = {%j}, %i * %j = {%i * %j}
Any valid expression is allowed inside the curly braces, including those that contain parentheses, $functions, and method calls.
For example, the following would display <tt>%i = 22, %j = 33, (%i + %j):toPower(3) = 166375</tt>:
  %i = 22
  %j = 33
  printText %i = {%i}, %j = {%j}, (%i + %j):toPower(3) = {(%i + %j):toPower(3)}
A single tilde character inside curly braces {~} must be followed (possibly with some intervening text) by an expression inside curly braces. The {~} would then be replaced with the literal contents of the following curly braces.
For example, the following sequence would display <tt>%i = 22, %j = 33, (%i + %j):toPower(3) = 166375</tt>:
  %i = 22
  %j = 33
  printText {~} = {%i}, {~} = {%j}, {~} = {(%i + %j):toPower(3)}
As of ''Sirius Mods'' version 7.8, you can also use a <tt>~=</tt> directive as a shorthand for <tt>{~}={''expression''}</tt>. For example, <br><tt>printtext {~=%i}, {~=%j}, {~=(%i+%j):toPower(3)}</tt> would display <tt>%i=22, %j=33, (%i + %j):toPower(3)=166375</tt>. <br>Note that in the directive, spaces are optional after the equal sign, and the output produces no spaces before or after the equal sign. If more control of spacing is required, use the {~} directive.


One common issue with the {~} syntax is that it does not replace with its value a variable used as a subscript (perhaps for an ArrayList). For example, if you have:
<div id="tildeEqual"></div>
  b
As of <var class="product">Sirius Mods</var> version 7.8, you can also use '''a ~= directive''' as a shorthand for <code>{~}={<i>expression</i>}</code>.
  %i is float
For example, <br><code>printtext {~=%i}, {~=%j}, {~=(%i+%j):toPower(3)}</code> would display <code>%i=22, %j=33, (%i + %j):toPower(3)=166375</code>.
  %j is float
<p>
  %al is arraylist of float
Note that in the directive, spaces are optional after the equal sign, and the output can produce spaces before or after the equal sign. For example: </p>
  %al = list(13, 17, 30)
<p class="code">b
  for %i from 1 to %al:count
printText "{~=1234:nextPrime  }"
      printText {~} = {%al(%i)}
printText "{~= 1234:nextPrime  }"
  end for
printText "{~=  1234:nextPrime}" 
  end
end  </p>
<p>
The result is: </p>
<p class="output">"1234:nextPrime  =1237"         
"1234:nextPrime  = 1237"
"1234:nextPrime=  1237"  </p>
'''Note:''' One common issue with the <b>{~}</b> syntax is that it does not replace with its value '''''a variable used as a subscript''''' (perhaps for an <var>ArrayList</var>). For example, if you have:
<p class="code">b
%i is float
%j is float
%al is arraylist of float
%al = list(13, 17, 30)
for %i from 1 to %al:count
  printText {~} = {%al(%i)}
end for
end </p>
You might expect the following to be displayed:
You might expect the following to be displayed:
  %al(1) = 13
<p class="code">%al(1) = 13
  %al(2) = 17
%al(2) = 17
  %al(3) = 30
%al(3) = 30 </p>
But, instead, the following is displayed:
But, instead, the following is displayed:
  %al(%i) = 13
<p class="code">%al(%i) = 13
  %al(%i) = 17
%al(%i) = 17
  %al(%i) = 30
%al(%i) = 30 </p>
One way to deal with this is to "manually" build the part before the value:
One way to deal with this is to "manually" build the part before the value:
  for %i from 1 to %al:count
<p class="code">for %i from 1 to %al:count
      printText %al({%i}) = {%al(%i)}
  printText %al({%i}) = {%al(%i)}
  end for
end for </p>
Another way is to show the subscript value also:
Another way is to show the subscript value also:
  for %i from 1 to %al:count
<p class="code">for %i from 1 to %al:count
      printText {~} = {%i}, {~} = {%al(%i)}
  printText {~} = {%i}, {~} = {%al(%i)}
  end for
end for </p>
This displays:
This displays:
  %i = 1, %al(%i) = 13
<p class="code">%i = 1, %al(%i) = 13
  %i = 2, %al(%i) = 17
%i = 2, %al(%i) = 17
  %i = 3, %al(%i) = 30
%i = 3, %al(%i) = 30 </p>
 
===Tilde statement directives===
As of <var class="product">Sirius Mods</var> 7.8, certain <var>Text</var> statement directives can be placed after a tilde character (<b>~</b>) inside curly braces (<b>{ }</b>) in any of the targeted text statements. For example, this statement sets <code>%ls</code> to the current time, embedded in hyphens:
<p class="code">setText %ls = {~nocont}---{$time}--- </p>
Because the <code>~nocont</code> directive was specified, the terminating hyphen is not treated as a continuation character.
 
The '''tilde directives''' that are allowed in targeted text statements are:
<table>
<tr><th>~exprE</th>
<td>Sets the expression end characters. This directive must be followed by a space and then the expression start characters. For example, <code>{~expre >}</code> sets the expression end characters to a single greater-than sign (<b>></b>). <var>~exprE</var> can also be written as <var>~exprEnd</var>.
<p>
'''Note:''' The <var>~exprE</var> directive must be ended by the current expression end characters, that is, by the end characters that the <var>~expre</var> directive is replacing.  </p>
</td></tr>
<tr><th>~exprS</th>
<td>Sets the expression start characters. This directive must be followed by a space and then the expression start characters. For example, <code>{~exprs <}</code> sets the expression start characters to a single less-than sign (<b><</b>). <var>~exprS</var> can also be written as  <var>~exprStart</var>.
</td></tr>
<tr><th>~noCont</th>
<td>Indicates that a trailing hyphen is not treated as a continuation character. <var>~noCont</var> can also be written as <var>~noContinuations</var>.
</td></tr>
<tr><th>~noEll</th>
<td>Indicates that a trailing ellipsis (<b>...</b>) is '''not''' treated as a partial-line indicator. Because it makes no sense to end a <var>SetText</var> or <var>ReturnText</var> with an ellipsis, this is the default for those two statements. So, while allowed, a <var>~noEll</var> directive is completely unnecessary for <var>SetText</var> and <var>ReturnText</var>. <var>~noEll</var> can also be written as <var>~noEllipses</var>.
</td></tr>
<tr><th>~noExpr</th>
<td>Indicates that no expressions are to be processed after the directive, and that everything after the <var>~noExpr</var> directive is treated as literal text. No further tilde directives will be processed after a <var>~noExpr</var>. <var>~noExpr</var> can also be written as <var>~noExpressions</var>.
</td></tr>
<tr><th>~raw</th>
<td>Acts as if <var>~noCont</var>, <var>~noEll</var>, and <var>~noExpr</var> are specified simultaneously.
<p>
'''Note:''' This is slightly different from the <var>Raw</var> directive on the <var>Text</var>/<var>Html</var> statement, which also implies <var>NoDum</var>/<var>NoDummy</var>. Because dummy string substitution applies to lines before they are parsed, dummy string substitution would already have happened in any single-line <var>Text</var> statement before the <var>~raw</var> directive was processed.  </p>
</td></tr></table>
 
==SetText statement==
==SetText statement==
The SetText statement works much the same as AuditText, PrintText, and TraceText, but it is used to set a variable instead of outputting a string. That is, its primary intent is to use the text it sets in the current program.  
The <var>SetText</var> statement works much the same as <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var>, but it is used to set a variable instead of outputting a string. That is, its primary intent is to use the text it sets in the current program.
                     
The syntax of the SetText statement is:
The syntax of the <var>SetText</var> statement is:
  setText %variable = string
{{Template:SetText statement syntax}}
Where:
Where:
<dl>
<table class="syntaxTable">
<dt>string
<tr><th>%variable</th>
<dd>A literal string which may include expressions enclosed by curly braces, just as is used in the Text statement.
<td>A simple variable, a class variable, a class property, or a collection member (which is really just a special kind of class property). <br><br>For example, the following statement sets the <var>String</var> property of a <var>StringTokenizer</var> object to the literal string <code>Once upon a time</code>:
<br><br>For example, the following statement sets <tt>%x</tt> to the literal string ''"Patriotism is the last refuge of the scoundrel"''.
<p class="code">%toke        is object stringTokenizer
  setText %x = Patriotism is the last refuge of the scoundrel
...
And the following sets <tt>%x</tt> to the literal string ''"The sum of %x and %y is "'' followed by the sum of <tt>%x</tt> and <tt>%y</tt>:
setText %toke:string = Once upon a time   </p>
  setText %x = The sum of %x and %y is {%x + %y}
A single blank after the equal sign following a <var>SetText</var> is not required and is ignored, though you can use it for readability. The following statements both set <code>%str</code> to <code>Once a jolly swagman camped by a billabong</code>:
 
<p class="code">setText %str =Once a jolly swagman camped by a billabong </p>
<dt>%variable
<dd>A simple variable, a class variable, a class property, or a collection member (which is really just a special kind of class property). <br><br>For example, the following statement sets the String property of a StringTokenizer object to the literal string ''"Once upon a time"'':
  %toke        is object stringTokenizer
    ...
  setText %toke:string = Once upon a time
A single blank after the equal sign following a SetText is not required and is ignored, though you can use it for readability. The following statements both set %str to ''"Once a jolly swagman camped by a billabong"''.
  setText %str =Once a jolly swagman camped by a billabong
and
and
  setText %str = Once a jolly swagman camped by a billabong
<p class="code">setText %str = Once a jolly swagman camped by a billabong </p>
Any additional blanks beyond the first one are treated as part of the literal source string.
Any additional blanks beyond the first one are treated as part of the literal source string.</td></tr>
</dl>


<tr><th>string</th>
<td>A literal string which may include expressions enclosed by curly braces, just as is used in the <var>Text</var> statement. <br><br>For example, the following statement sets <code>%x</code> to the literal string <code>Patriotism is the last refuge of the scoundrel</code>:
<p class="code">setText %x = Patriotism is the last refuge of the scoundrel </p>
And the following sets <code>%x</code> to the literal string <code>The sum of %x and %y is </code> followed by the sum of <code>%x</code> and <code>%y</code>:
<p class="code">setText %x = The sum of %x and %y is {%x + %y}  </p></td></tr>
</table>
Continuations are treated in the normal way: the text continues from the first non-blank character on the next line.
Continuations are treated in the normal way: the text continues from the first non-blank character on the next line.
<br><b>Tip</b>: if you need to include blank characters from the next line, use {} (a null expression) to indicate the start of the continuation.  For example:
<br><b>Tip</b>: if you need to include blank characters from the next line, use <code>{}</code> (a null expression) to indicate the start of the continuation.  For example:
  setText %str = Once a jolly swagman camped by:-
<p class="code">setText %str = Once a jolly swagman camped by:-
                  {}  a billabong
              {}  a billabong   </p>
The statement above sets <tt>%str</tt> to:
The statement above sets <code>%str</code> to:
  Once a jolly swagman camped by:  a billabong
<p class="code">Once a jolly swagman camped by:  a billabong </p>
However, since trailing blanks before a continuation are '''not''' stripped, you can also include blank characters by putting extra blanks at the end of the first SetText line:
However, since trailing blanks before a continuation are '''not''' stripped, you can also include blank characters by putting extra blanks at the end of the first <var>SetText</var> line:
  setText %str = Once a jolly swagman camped by:  -
<p class="code">setText %str = Once a jolly swagman camped by:  -
                  a billabong
              a billabong   </p>
 
If you need to terminate the string with a hyphen, add the <code>{}</code> null expression to the end of a line. For example:
If you need to terminate the string with a hyphen, add the {} null expression to the end of a line. For example:
<p class="code">setText %str = ------------{} </p>
  setText %str = ------------{}
The statement above sets <code>%str</code> to:
The statement above sets %str to:  
<p class="code">------------ </p>
  ------------
You can also use the <var>~noCont</var> directive to indicate that a trailing hyphen is not to be treated as a continuation character:
You can also use the ~noCont directive to indicate that a trailing hyphen is not to be treated as a continuation character:
<p class="code">setText %str = {~nocont}------------ </p>
  setText %str = {~nocont}------------


==ReturnText statement==
==ReturnText statement==
The ReturnText statement works much the same as AuditText, PrintText, and TraceText, but instead of outputting a string it is used to return a string value in a User Language function or property Get method. The syntax of the ReturnText statement is:
The <var>ReturnText</var> statement works much the same as <var>AuditText</var>, <var>PrintText</var>, and <var>TraceText</var>, but instead of outputting a string it is used to return a string value in a <var class="product">User Language</var> function or property <var>Get</var> method. The syntax of the <var>ReturnText</var> statement is:
  ReturnText string
<p class="syntax"><span class="literal">ReturnText</span> <span class="term">string</span> </p>
Where:
Where:
<dl>
<table>
<dt>string
<tr><th>string
<dd>A literal string which may include expressions enclosed by curly braces, just as in the Text statement.
</th><td>A literal string which may include expressions enclosed by curly braces, just as in the <var>Text</var> statement.
</dl>
</td></tr>
For example, if the Aphorism local function is applied to the number 1 in the following fragment, the function returns the literal string ''"Patriotism is the first refuge of the scoundrel"'':  
</table>
<pre>
For example, if the <code>Aphorism</code> local function is applied to the number 1 in the following fragment, the function returns the literal string <code>Patriotism is the first refuge of the scoundrel</code>:
  local function (float):aphorism is longstring
<p class="code">local function (float):aphorism is longstring
 
  if %this eq 1 then
if %this eq 1 then
      returnText Patriotism is the first refuge of the scoundrel
  returnText Patriotism is the first refuge of the scoundrel
  end if
end if
  ...
&#46;..
  end function
end function
</pre>
</p>
The following function returns the literal string ''"The sum of %x and %y is "'' followed by the sum of the <tt>%x</tt> and <tt>%y</tt> parameters passed to the local function:
The following function returns the literal string <code>The sum of %x and %y is </code> followed by the sum of the <code>%x</code> and <code>%y</code> parameters passed to the local function:
<pre>
<p class="code">local function stringAdd(%x is float, %y is float)
  local function stringAdd(%x is float, %y is float)
 
  returnText The sum of %x and %y is {%x + %y}
      returnText The sum of %x and %y is {%x + %y}
 
end function
  end function
</p>
</pre>
 
Continuations are treated in the normal way: the text continues from the first non-blank character on the next line.<br>
Continuations are treated in the normal way: the text continues from the first non-blank character on the next line.<br>
<b>Tip</b>: if you need to include blank characters from the next line, use {} (a null expression) to indicate the start of the continuation. For example:
<b>Tip</b>: if you need to include blank characters from the next line, use <code>{}</code> (a nullexpression) to indicate the start of the continuation. For example:
  returnText %str = Down came a jumbuck to drink at:-
<p class="code">returnText %str = Down came a jumbuck to drink at:-
                    {}  that billabong                    
                  {}  that billabong   </p>
The statement above returns:
<p class="code">Down came a jumbuck to drink at:  that billabong  </p>
However, since trailing blanks before a continuation are '''not''' stripped, you can also include blank characters by putting extra blanks at the end of the first <var>ReturnText</var> line:
<p class="code">returnText %str = Down came a jumbuck to drink at:  -
                  that billabong  </p>
If you need to terminate the string with a hyphen, add the <code>{}</code> null expression to the end of a line. For example:
<p class="code">returnText ------------{}  </p>
The statement above returns:
The statement above returns:
  Down came a jumbuck to drink at:  that billabong
<p class="code">------------   </p>
However, since trailing blanks before a continuation are '''not''' stripped, you can also include blank characters by putting extra blanks at the end of the first ReturnText line:
You can also use the <var>~noCont</var> directive to indicate that a trailing hyphen is not to be treated as a continuation character:
  returnText %str = Down came a jumbuck to drink at:  -
<p class="code">returnText {~nocont}------------ </p>
                    that billabong                   
[[Category:User Language statements]]
If you need to terminate the string with a hyphen, add the {} null expression to the end of a line. For example:
  returnText ------------{}
The statement above returns:
  ------------
You can also use the ~noCont directive to indicate that a trailing hyphen is not to be treated as a continuation character:
  returnText {~nocont}------------

Latest revision as of 15:27, 7 November 2015

The AuditText, PrintText, and TraceText statements are abbreviated forms of the Text and Html statements. They have the same effect as the Text Audit, Text Print, and Text Trace statements, respectively. The AuditText, PrintText, and TraceText statements are available in Sirius Mods 7.2 and later.

The SetText statement, which is available in Sirius Mods 7.8 and later, uses the same syntax as AuditText, PrintText, and TraceText to set a target variable. And the ReturnText statement, which is available in Sirius Mods 7.8 and later, uses the same syntax as AuditText, PrintText, and TraceText to return a string value from a User Language function or property Get method.

AuditText, PrintText, and TraceText

The AuditText, PrintText, and TraceText keywords are simply a merging and reordering of Text Audit, Text Print, and Text Trace to emphasize the principle action.

AuditText sends its output to the Model 204 audit trail, PrintText sends its output to the current output stream (output terminal or use dataset), and TraceText sends its output to the current trace targets. These statements are the recommended/preferred alternatives to the traditional Audit, Print, and Trace statements. They are recommended because they are more flexible and have more consistent behavior.

All text not inside curly braces in an AuditText, PrintText, or TraceText statement is considered to be literal text. For example, the following statement will display Suit the action to the word, the word to the action on the primary output stream:

printText Suit the action to the word, the word to the action

You can place values of variables and also calculated values inside of curly braces to display the value of what is inside the braces. For example, these statements:

%i = 22 %j = 33 printText %i = {%i}, %j = {%j}, %i * %j = {%i * %j}

Display the following:

%i = 22, %j = 33, %i * %j = 726

Any valid expression is allowed inside the curly braces, including those that contain parentheses, $functions, and method calls. For example, the following statements:

%i = 22 %j = 33 printText %i = {%i}, %j = {%j}, (%i + %j):toPower(3) = {(%i + %j):toPower(3)}

Display:

%i = 22, %j = 33, (%i + %j):toPower(3) = 166375

~ and ~= directives

A single tilde character inside curly braces, {~}, must be followed (possibly with some intervening text) by an expression inside curly braces. The {~} would then be replaced with the literal contents of the following curly braces.

For example, the following sequence:

%i = 22 %j = 33 printText {~} = {%i}, {~} = {%j}, {~} = {(%i + %j):toPower(3)}

Displays:

%i = 22, %j = 33, (%i + %j):toPower(3) = 166375

As of Sirius Mods version 7.8, you can also use a ~= directive as a shorthand for {~}={expression}. For example,
printtext {~=%i}, {~=%j}, {~=(%i+%j):toPower(3)} would display %i=22, %j=33, (%i + %j):toPower(3)=166375.

Note that in the directive, spaces are optional after the equal sign, and the output can produce spaces before or after the equal sign. For example:

b printText "{~=1234:nextPrime }" printText "{~= 1234:nextPrime }" printText "{~= 1234:nextPrime}" end

The result is:

"1234:nextPrime =1237" "1234:nextPrime = 1237" "1234:nextPrime= 1237"

Note: One common issue with the {~} syntax is that it does not replace with its value a variable used as a subscript (perhaps for an ArrayList). For example, if you have:

b %i is float %j is float %al is arraylist of float %al = list(13, 17, 30) for %i from 1 to %al:count printText {~} = {%al(%i)} end for end

You might expect the following to be displayed:

%al(1) = 13 %al(2) = 17 %al(3) = 30

But, instead, the following is displayed:

%al(%i) = 13 %al(%i) = 17 %al(%i) = 30

One way to deal with this is to "manually" build the part before the value:

for %i from 1 to %al:count printText %al({%i}) = {%al(%i)} end for

Another way is to show the subscript value also:

for %i from 1 to %al:count printText {~} = {%i}, {~} = {%al(%i)} end for

This displays:

%i = 1, %al(%i) = 13 %i = 2, %al(%i) = 17 %i = 3, %al(%i) = 30

Tilde statement directives

As of Sirius Mods 7.8, certain Text statement directives can be placed after a tilde character (~) inside curly braces ({ }) in any of the targeted text statements. For example, this statement sets %ls to the current time, embedded in hyphens:

setText %ls = {~nocont}---{$time}---

Because the ~nocont directive was specified, the terminating hyphen is not treated as a continuation character.

The tilde directives that are allowed in targeted text statements are:

~exprE Sets the expression end characters. This directive must be followed by a space and then the expression start characters. For example, {~expre >} sets the expression end characters to a single greater-than sign (>). ~exprE can also be written as ~exprEnd.

Note: The ~exprE directive must be ended by the current expression end characters, that is, by the end characters that the ~expre directive is replacing.

~exprS Sets the expression start characters. This directive must be followed by a space and then the expression start characters. For example, {~exprs <} sets the expression start characters to a single less-than sign (<). ~exprS can also be written as ~exprStart.
~noCont Indicates that a trailing hyphen is not treated as a continuation character. ~noCont can also be written as ~noContinuations.
~noEll Indicates that a trailing ellipsis (...) is not treated as a partial-line indicator. Because it makes no sense to end a SetText or ReturnText with an ellipsis, this is the default for those two statements. So, while allowed, a ~noEll directive is completely unnecessary for SetText and ReturnText. ~noEll can also be written as ~noEllipses.
~noExpr Indicates that no expressions are to be processed after the directive, and that everything after the ~noExpr directive is treated as literal text. No further tilde directives will be processed after a ~noExpr. ~noExpr can also be written as ~noExpressions.
~raw Acts as if ~noCont, ~noEll, and ~noExpr are specified simultaneously.

Note: This is slightly different from the Raw directive on the Text/Html statement, which also implies NoDum/NoDummy. Because dummy string substitution applies to lines before they are parsed, dummy string substitution would already have happened in any single-line Text statement before the ~raw directive was processed.

SetText statement

The SetText statement works much the same as AuditText, PrintText, and TraceText, but it is used to set a variable instead of outputting a string. That is, its primary intent is to use the text it sets in the current program.

The syntax of the SetText statement is:

SetText %variable = string

Where:

%variable A simple variable, a class variable, a class property, or a collection member (which is really just a special kind of class property).

For example, the following statement sets the String property of a StringTokenizer object to the literal string Once upon a time:

%toke is object stringTokenizer ... setText %toke:string = Once upon a time

A single blank after the equal sign following a SetText is not required and is ignored, though you can use it for readability. The following statements both set %str to Once a jolly swagman camped by a billabong:

setText %str =Once a jolly swagman camped by a billabong

and

setText %str = Once a jolly swagman camped by a billabong

Any additional blanks beyond the first one are treated as part of the literal source string.
string A literal string which may include expressions enclosed by curly braces, just as is used in the Text statement.

For example, the following statement sets %x to the literal string Patriotism is the last refuge of the scoundrel:

setText %x = Patriotism is the last refuge of the scoundrel

And the following sets %x to the literal string The sum of %x and %y is followed by the sum of %x and %y:

setText %x = The sum of %x and %y is {%x + %y}

Continuations are treated in the normal way: the text continues from the first non-blank character on the next line.
Tip: if you need to include blank characters from the next line, use {} (a null expression) to indicate the start of the continuation. For example:

setText %str = Once a jolly swagman camped by:- {} a billabong

The statement above sets %str to:

Once a jolly swagman camped by: a billabong

However, since trailing blanks before a continuation are not stripped, you can also include blank characters by putting extra blanks at the end of the first SetText line:

setText %str = Once a jolly swagman camped by: - a billabong

If you need to terminate the string with a hyphen, add the {} null expression to the end of a line. For example:

setText %str = ------------{}

The statement above sets %str to:

------------

You can also use the ~noCont directive to indicate that a trailing hyphen is not to be treated as a continuation character:

setText %str = {~nocont}------------

ReturnText statement

The ReturnText statement works much the same as AuditText, PrintText, and TraceText, but instead of outputting a string it is used to return a string value in a User Language function or property Get method. The syntax of the ReturnText statement is:

ReturnText string

Where:

string A literal string which may include expressions enclosed by curly braces, just as in the Text statement.

For example, if the Aphorism local function is applied to the number 1 in the following fragment, the function returns the literal string Patriotism is the first refuge of the scoundrel:

local function (float):aphorism is longstring if %this eq 1 then returnText Patriotism is the first refuge of the scoundrel end if ... end function

The following function returns the literal string The sum of %x and %y is followed by the sum of the %x and %y parameters passed to the local function:

local function stringAdd(%x is float, %y is float) returnText The sum of %x and %y is {%x + %y} end function

Continuations are treated in the normal way: the text continues from the first non-blank character on the next line.
Tip: if you need to include blank characters from the next line, use {} (a nullexpression) to indicate the start of the continuation. For example:

returnText %str = Down came a jumbuck to drink at:- {} that billabong

The statement above returns:

Down came a jumbuck to drink at: that billabong

However, since trailing blanks before a continuation are not stripped, you can also include blank characters by putting extra blanks at the end of the first ReturnText line:

returnText %str = Down came a jumbuck to drink at: - that billabong

If you need to terminate the string with a hyphen, add the {} null expression to the end of a line. For example:

returnText ------------{}

The statement above returns:

------------

You can also use the ~noCont directive to indicate that a trailing hyphen is not to be treated as a continuation character:

returnText {~nocont}------------