At sign (@) on right side of assignment

This feature is new in version 7.9 of the Sirius Mods.

Some programming languages have operators that allow the right-hand side of an assignment statement to reference the left-hand side. In C, for example, i += 2 is equivalent to i = i + 2.

A feature introduced in version 7.9 of the Sirius Mods allows a much more generalized approach to doing this. In the right-hand side expression of an assignment statement, the "at" sign (@) character refers to the left-hand side of the assignment. For example:

%x = 4 %x = @:toPower(@) print %x

This fragment produces 256, that is, the same result that would be obtained by substituting '%x', the left side of the assignment, for '@' in '%x = @:ToPower(@)'. This is the value of %x raised to that same power.

The @ character is used in an expression on the right side of an assignment statement wherever a "value" phrase may occur, for example, a variable, literal, method expression, $function, or sub-expression. The @ portion of the expression is called the "@ phrase."

Examples

Some examples of the @ phrase are:

Add 2 to a Float variable:	%x = @ + 2
Raise a Float variable to its own power:	%x = @:toPower(@)
Code with long variable names can become much more readable:	%numberOfCustomerInteractions = @ + 1 %totalTimeUsedForTransaction = @ + %time As opposed to: %numberOfCustomerInteractions = %numberOfCustomerInteractions + 1 %totalTimeUsedForTransaction = %totalTimeUsedForTransaction + %time
Concatenate to string:	%foo = @ with '.suffix'
Concatenate to lowercased string:	%foo = 'prefix.' with @:toLower
Get number plus next prime number:	%foo = @ + @:nextPrime
Map variable using NamedArraylist:	%foo = %namedArrlis(@)
Get next item in linked list of objects:	class list public variable next object list ... end class %item object list ... %item = @:next

"@" may refer to variable, array/screen/image item, or property

When the @ phrase is in the right hand side of an assignment, the left side of the assignment is something which could be used as an expression. In terms of the operation (or semantics) of the @ phrase, there are two cases for the left side of the assignment:

a variable, array item, screen item, or image item

In this case, when the @ phrase is used on the right side, it simply refers to the value of the left side.

a property

In this case, as the right side of the assignment is evaluated, each instance of the @ phrase will invoke the "get" method of the property to obtain its value — and to perform any other actions of the "get" method. Note: the property may not be a write-only property.

Left-hand side sub-expressions evaluate once, prior to right-hand side

If the left side of an assignment statement contains sub-expressions, these are only evaluated once, prior to evaluating any of the right-hand side. Consider the following two example assignment statements:

%x(10+%y) = @ + 17 %nLis(%i):selectSingleNode('customer[@id="' with %cusId with '"]'):value = - %prefix with @ with %suffix

In the first assignment above:

The value 17 is added to the Array element (or Arraylist item) located at position 10+%y. The expression 10+%y is only evaluated once.

In the second assignment above:

• Item %i is obtained from the XmlNodelist %nLis.
• The resulting XmlNode is used as the context node to select the first XmlDoc node matching the XPath expression (which is the concatenation of 'customer[@id="' with the value of %cusId with '"]').

Those operations are performed once, resuling in an XmlNode. The Value property of that node is replaced with the string which is the concatenation the value of %prefix with the former value of the Value property with the value of %suffix.

The above examples that use "@", where the left-hand sub-expressions are evaluated only once, are more efficient than the equivalent statements where the left-hand side is literally substituted for each instance of @ on the right-hand side, and so those sub-expressions are evaluated multiple times.

However, in cases in which sub-expressions in the left-hand side invoke some functions or properties that have side-effects, it is important to note that since the sub-expressions are only evaluated once, the result of such an assignment can be different from a statement in which the left-hand side is literally substituted for each instance of @ on the right-hand side. Also, there may be sub-expressions on the right-hand side that have side-effects, which could change the result of the sub-expressions of the left-hand side, were they substituted for @ phrases.

Programming practices that produce such side-effects are best avoided, but here is an example:

local function (string):getStateCode string len 2 %bal float %secretAccount is longstring common for 1 record where AcctNum = %this for 1 record where AcctNum = %secretAccount %bal = Balance + 100 change Balance to %bal end for %bal = Balance - 100 change Balance to %bal return StateCode end for end function ... %balancesByState namedArraylist of float auto new %balancesByState:useDefault = true fr where ... * Notice that getStateCode is only evaluated once, so a dollar * is only stolen once for each account processed: %balancesByState(AcctNum:getStateCode) = @ + Balance end for

"@" is not a "self-delimiting" phrase except before or after a colon

In a User Language expression, some characters or character sequences are "self-delimiting," that is, they may be adjacent to other "words" in the expression without intervening whitespace. For example:

%x=%x*%y+%x/(%z-1)

In the expression on the right side of the above statement, no whitespace is required around any of the following characters:

* + / ( - )

Other characters, for example a comma, or character sequences, for example <=, also do not require surrounding whitespace when used in an expression. However, for non-self-delimiting phrases, either a self-delimiting character or character sequence or whitespace is required to separate words in an expression. For example, the following statement assigns to %c the concatenation of the string values of variables %a and %b:

%c=%a with %b

The following, however, is a syntax error, because the concatenation operator (with) is not self-delimiting:

%c=%a with%b

Similarly, the @ phrase is not (except when preceding a colon) self-delimiting; for example, the following assigns to %c the concatenation of the string values of variables %c and %b:

%c=@ with %b

Each of the following, however, is a syntax error, because neither with nor @ is self-delimiting:

%c=@with %b %c=%b with@

"@" may appear immediately before or after a colon

The colon character (:) behaves, in most contexts, as if it were a self-delimiting character, hence, no whitespace is required between : and @. For example:

%c = @:substring(10)

The above statement, in effect, removes the first 9 bytes of the variable %c.

"@" and the SetText statement

In the SetText statement, the @ character can occur in the right hand side, and, just as with the ordinary assignment statement, @ refers to the value of the left hand side of the statement. For example:

%s = 'Hello, world!' SetText %s = {@} and its reverse {%s:Reverse} Print %s

The result of the above fragment is Hello, world! and its reverse !dlrow ,olleH.

Authorizing products

The @ phrase is available to any customer who owns any of the following products:

• Fast/Unload User Language Interface
• Janus SOAP
• Janus Sockets
• Janus Web Server
• Sirius Functions

The Html block is also available if the Limited Janus Web Server capability is available.