Targeted Text statements: Difference between revisions

From m204wiki
Jump to navigation Jump to search
mNo edit summary
mNo edit summary
Line 4: Line 4:
The AuditText, PrintText, and TraceText statements are available in Sirius Mods 7.2 and later.
The AuditText, PrintText, and TraceText statements are available in Sirius Mods 7.2 and later.


In addition 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.
In addition, 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.


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.
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.


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 former cannot be used if you want to include other Html/Text options, as in:
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:
   text noexpr print The set is {2, 3, 5, 8, 13, ...}
   text noexpr print The set is {2, 3, 5, 8, 13, ...}
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
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
   setText %ls = {~nocont}---{$time}---
   setText %ls = {~nocont}---{$time}---
sets %ls to the current time embedded in hyphens. 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:
sets %ls to the current time embedded in hyphens. 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:
<dl>
<dl>
<dt>~exprE
<dt>~exprE
<dd>Sets the expression end characters. This directive must be followed by a space and then the expression start characters as in ''{~expre >}'' which sets the expression end characters to a single greater than sign. ~exprE can also be written as ~exprEnd. Note that the ~exprE directive must be ended by the expression end characters in effect before the ~expre directive is processed.
<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>. Note that the ~exprE directive must be ended by the expression end characters in effect before the ~expre directive is processed.
<dd>Sets the expression start characters. This directive must be followed by a space and then the expression start characters as in ''{~exprs <}'' which sets the expression start characters to a single less than sign. ~exprS can also be written as ~exprStart.
<dt>~exprS
<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>.
<dt>~noCont
<dt>~noCont
<dd>Indicates that a trailing hyphen is not treated as a continuation character. ~noCont can also be written as ~noContinuations.
<dd>Indicates that a trailing hyphen is not treated as a continuation character. ~noCont can also be written as <tt>~noContinuations</tt>.
<dt>~noEll
<dt>~noEll
<dd>Indicates that a trailing ellipses (...) is not treated as partial line indicator. Because it makes no sense to end a SetText or ReturnText with ellipses, this is the default for those two statements so, while allowed, this directive is completely unnecessary for SetText and ReturnText. ~noEll can also be written as ~noEllipses.
<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>.
<dt>~noExpr
<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 ~noExpressions.
<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
<dt>~raw
<dd>The same as specifying all of ~noCont, ~noEll, and ~noExpr. Note that this is slightly different from the Raw directive on the Text/Html statement which also implies NoDum/NoDummy. This is because dummy string substitution applies to lines before they are parsed up so that dummy string substitution would already have happened in any single line Text statement before the ~raw directive was processed.
<dd>Acts as if ~noCont, ~noEll, and ~noExpr are specified simultaneously. Note that 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.
</dl>
</dl>


As would be expected, 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.
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.
These statements are the recommended/preferred alternatives to the traditional Audit, Print, and Trace statements.
The reason they are recommend over these other statements is because they are more flexible and have more consistent behavior.
They are recommended because they are more flexible and have more consistent behavior.


All text not inside of curly braces in an AuditText, PrintText, or TraceText statement is considered to be literal text. For example, the following will display ''"Suit the action to the word, the word to the action"'' on the primary output stream:
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:
   printText Suit the action to the word, the word to the action
   printText Suit the action to the word, the word to the action
Values of variables and calculated values, can be placed inside of curly braces to that the value of what's inside the braces is displayed.
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 ''"%i = 22, %j = 33, %i * %j = 726"'':
For example, the following would display <tt>%i = 22, %j = 33, %i * %j = 726</tt>:
   %i = 22
   %i = 22
   %j = 33
   %j = 33
   printText %i = {%i}, %j = {%j}, %i * %j = {%i * %j}
   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.
Any valid expression is allowed inside the curly braces, including those that contain parentheses, $functions, and method calls.
For example, the following would display ''"%i = 22, %j = 33, (%i + %j):toPower(3) = 166375"'':
For example, the following would display <tt>%i = 22, %j = 33, (%i + %j):toPower(3) = 166375</tt>:
   %i = 22
   %i = 22
   %j = 33
   %j = 33
   printText %i = {%i}, %j = {%j}, (%i + %j):toPower(3) = {(%i + %j):toPower(3)}
   printText %i = {%i}, %j = {%j}, (%i + %j):toPower(3) = {(%i + %j):toPower(3)}
If a single tilde (~) character is found inside curly braces, it must be followed (possibly with some intervening text) with an expression inside curly braces. The {~} would then be replaced with the literal contents of the following curly braces.
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 would display ''"%i = 22, %j = 33, (%i + %j):toPower(3) = 166375"'':
For example, the following sequence would display <tt>%i = 22, %j = 33, (%i + %j):toPower(3) = 166375</tt>:
   %i = 22
   %i = 22
   %j = 33
   %j = 33
   printText {~} = {%i}, {~} = {%j}, {~} = {(%i + %j):toPower(3)}
   printText {~} = {%i}, {~} = {%j}, {~} = {(%i + %j):toPower(3)}
As of Sirius Mods 7.8 one can also use a ~= directive as a shorthand for {~}={''expression''} as in
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.  
whih would display ''"%i=22, %j=33, (%i + %j):toPower(3)=166375"''. Note that in the directive, spaces are optional after the equals sign and the output produces no spaces before or after the equals sign. If more control of spacing is required, the {~} directive should be used.  


One common issue with the {~} syntax is that one might feel that a variable used as a subscript (perhaps for an ArrayList), should be replaced by its value.
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:
For example, if one had:
   b
   b
   %i is float
   %i is float
Line 62: Line 63:
   end for
   end for
   end
   end
One might expect the following to be displayed:
You might expect the following to be displayed:
   %al(1) = 13
   %al(1) = 13
   %al(2) = 17
   %al(2) = 17
Line 70: Line 71:
   %al(%i) = 17
   %al(%i) = 17
   %al(%i) = 30
   %al(%i) = 30
One way to deal with this is to simply "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
   for %i from 1 to %al:count
       printText %al({%i}) = {%al(%i)}
       printText %al({%i}) = {%al(%i)}
   end for
   end for
Another way, is to simply also show the subscript value:
Another way is to show the subscript value also:
   for %i from 1 to %al:count
   for %i from 1 to %al:count
       printText {~} = {%i}, {~} = {%al(%i)}
       printText {~} = {%i}, {~} = {%al(%i)}
   end for
   end for
This ends up displaying:
This displays:
   %i = 1, %al(%i) = 13
   %i = 1, %al(%i) = 13
   %i = 2, %al(%i) = 17
   %i = 2, %al(%i) = 17

Revision as of 01:27, 17 December 2010

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, Text Trace, Text Return, and Text Set statements respectively.

The AuditText, PrintText, and TraceText statements are available in Sirius Mods 7.2 and later.

In addition, 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.

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.

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:

  text noexpr print The set is {2, 3, 5, 8, 13, ...}

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

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

sets %ls to the current time embedded in hyphens. 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 that the ~exprE directive must be ended by the expression end characters in effect before the ~expre directive is processed.
~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 that 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.

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, the following would display %i = 22, %j = 33, %i * %j = 726:

  %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 %i = 22, %j = 33, (%i + %j):toPower(3) = 166375:

  %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 %i = 22, %j = 33, (%i + %j):toPower(3) = 166375:

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

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 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:

  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

SetText statement

The SetText statement works much the same as AuditText, PrintText, and TraceText, but is used to set a variable instead of outputting a string. The syntax of the SetText statement is:

  setText %variable = string

Where

string
is a literal string with expressions inside of curly braces, just as is used in the Text statement.

For example, the following

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

sets %x to the literal string "Patriotism is the last refuge of the scoundrel". And the following:

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

Sets %x to the literal string "The sum of %x and %y is " followed by the sum of %x and %y.

The target of SetText can be 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:

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

sets the String propert of a StringTokenizer object to the literal string "Once upon a time". A single blank after the equals sign after a SetText is ignored so can be used for readability, but is not required. That is

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

and

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

both set %str to "Once a jolly swagman camped by a billabong". Any additional blanks beyond the first one, are treated as part of the literal source string.

Continuations are treated in the normal way, that is 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

will set %str to:

  Once a jolly swagman camped by:   a billabong

However, trailing blanks before a continuation are not stripped so one can accomplish the same thing 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 {} to the end of a line. For example:

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

will set %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 is used to return a string value in a User Language function or property Get method instead of outputting a string. The syntax of the ReturnText statement is:

  ReturnText string

Where

string
is a literal string with expressions inside of curly braces, just as is used in the Text statement.

For example, the following

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

returns the literal string "Patriotism is the first refuge of the scoundrel" if the Aphorism local function was applied to the number 1. And the following:

local function stringAdd(%x is float, %y is float)

   returnText The sum of %x and %y is {%x + %y}

end 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.

Continuations are treated in the normal way, that is 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:

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

will return:

  Down came a jumbuck to drink at:   that billabong,

However, trailing blanks before a continuation are not stripped so one can accomplish the same thing by putting extra blanks at the end of the first SetText line:

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

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

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

will return:

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

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

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