V7.8 changes affecting all or multiple products

{{#hierarchy-top:}}

Double quotation marks for quoted strings

As of Sirius Mods version 7.8, the User Language and Janus SOAP compiler accepts either a single-quotation-mark character ( ' ) or a double-quotation-mark character ( " ) as a quoted-string delimiter. Prior to this version, only a single-quotation-mark character (also called an apostrophe) could be such a delimiter.

These are examples of the feature:

1. The statements below are equivalent as of version 7.8:

       %n = 'abc':stringToHex
    
       %n = "abc":stringToHex
   

2. The hex string produced by the statements below as of version 7.8 is 818283:

       printText {'abc':stringToHex}
    
       printText {"abc":stringToHex}
   

3. The first and second statements below are equivalent as of version 7.8, producing the string IT'S COOL!:

       printText {'It''s cool!':toUpper}
    
       printText {"It's cool!":toUpper}
    
       printText {"It''s cool!":toUpper}
   

   
   The last statement in the example above produces the string IT''S COOL!, which demonstrates that repeating a single quotation mark does not escape it if the quoted string is delimited with double quotation marks.

Note: Since this double quotation mark feature is restricted to the compiler, it does not affect command parsing, and the following command is still invalid:

    RESET FUNCOPTS X"00"

As a rule, the double quotation mark character can be used to enclose, or bracket, a quoted region that begins a string literal, or to bracket a "continuation" of a string literal that begins with a double quotation mark, but it may not otherwise be used to bracket a quoted region.

The "continuation of a string literal" refers to the peculiar User Language concept that a quoted token does not end until it reaches a space or separator character after the closing quotation mark character. So, the following statement prints Hello:

    print 'Hel'lo

You can also continue the quoted region:

    print 'Hel'lo' World'

This prints Hello World. In addition, you can quote parts of unquoted tokens:

    pr'int' 'Hello World'

This also prints Hello World.

User Language quoted string continuation and the new functionality of double quotation marks are shown in the following annotated request, which is valid in Sirius Mods version 7.8. The letter labels on the left are not part of the request but are for the commentary that follows:

          Begin
    (A)   %b'y' string len 255
          %b'y' = 'abc'
          print  %b'y'
    (B)   print  %by
          call foobar
    (C)   subroutine foo'bar'
    (D)      print "here I am"
    (E)      print 'come and 'g"et"
    (F)      print "say ""uncle"""
    (G)      print "Bob's"Your"Uncle"
          end subroutine
          end

(A)	%b'y' string len 255 'y' is a quoted region that is a continuation of the %variable name.
(B)	print %by The %variable %by is the same as the %variable %b'y'.
(C)	subroutine foo'bar' 'bar' is a quoted region that is a continuation of the subroutine name; the name is the same as the name foobar.
(D)	print "here I am" The result is: here I am, because of the new feature. Prior to this version, this statement was invalid.
(E)	print 'come and 'g"et" The result is come and g"et", because the double quotation marks are ordinary characters (not brackets for a quoted region) in a string literal that starts with a single quotation mark. The string literal extends beyond the second single quotation mark until ended by a blank or the end of the string. Since this result also occurred prior to version 7.8, backward compatibility dictates the new rule that the opening quotation mark in a quoted string determines the quote bracketing character through the rest of the quoted string.
(F)	print "say ""uncle""" The result is: say "uncle", because within a quoted region started by a double quotation mark, two consecutive double quotation marks are folded into one.
(G)	print "Bob's"Your"Uncle" The result is: Bob'sYourUncle, because "Uncle" is a quoted region which continues the string literal that was started by the initial double quotation mark.

The following statement would produce a compilation error:

    print 'say'Uncle" Bob"

" Bob" is not a quoted region that continues the string literal (because the string literal is started by the initial single quotation mark and not by an initial double quotation mark), so the blank before Bob" ends the quoted string and makes the final four characters extraneous and invalid for the Print statement.

A final note: in a string that does not start with a quotation mark, only a single quotation mark character is allowed to produce a quoted piece of the token. For example, the following statement is valid:

    %x = foo'BAR'

This statement causes %x to be set to the value of field FOOBAR. However, the following statement results in %x being set to the value of field FOO"BAR":

    %x = foo"BAR"

This is necessary to preserve backward compatibility.

Text/Html statement enhancements

These features are added in Sirius Mods 7.8.

Tilde directives

As of Sirius Mods 7.8, certain Text/Html statement directives can be placed after a tilde character (~) inside curly braces ({ }) in any of the targeted text statements (which include AuditText, PrintText, TraceText, and new in V7.8, SetText and ReturnText. 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.

~= directives

As of Sirius Mods version 7.8, you can 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.

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: As shown above for SetText:

• If you need to include blank characters from the next line, use {} (a null expression) to indicate the start of the continuation.
• If you need to terminate the string with a hyphen, add the {} null expression to the end of a line.
• You can also use the ~noCont directive to indicate that a trailing hyphen is not to be treated as a continuation character.

{{#hierarchy-bottom:}}