Targeted Text statements: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (moved AuditText, PrintText, TraceText, and SetText Statements to Targetted Text Statements: Number of entries in title getting Ridiculous)
(No difference)

Revision as of 13:31, 11 October 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, and Text Trace 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 arget variable.

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:

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

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

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:

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

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. For example, the following would display “%i = 22, %j = 33, (%i + %j):toPower(3) = 166375”:

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

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. For example, if one had:

  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

One 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 simply "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 simply also show the subscript value:

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

This ends up displaying:

  %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 string tokenizer
   ...
  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:

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