ArborX

^

Longname:   Open the Documentation Legend
Released: not available 
Created: not available 
See also: getvar run savevars
3B2 Variables

Summary
 Defines, modifies or inserts the value of a variable item, depending on what operator is used. Arbortext APP keeps only one set of variables which it shares across the entire system. All open documents use the same variables.
Example extract

This example is part of a error log builder from a frame building script. It processes the variable and getvar values to show into the ^result variable, this is then appended to the end of the error log stream.

 ^result?There were $^frames_on_page placed on page $^01530
 ^"error_log".^result

Syntax (SVNNA)
^ variable:m operator:w value:n
variable:m

A regular variable name consists of any valid Arbortext APP tag name, prefixed by a ^ character. Post Arbortext APP version 7 the use of upper or lower case letters was not significant: ^fred was the same variable as ^FRED. Due to the implementation of Perl in Arbortext APP variable names are now case sensitive, so ^fred is now a different variable entirely to ^FRED or ^Fred.

Examples of valid variable names are ^page_size, ^fred3, ^_special, or ^body. A variable does not actually bear any relation to a tag of the same name. Variable names must not contain hyphens. A variable name is only followed by a ^ when it is to be interpreted within a macro, e.g. in the macro tpsize the variable ^psize^ would be replaced by whatever the contents of the variable were.
operator:w

The operator is the type of operation you want to carry out on a variable. They work by looking at the value on the right of the operator and changing the left hand value accordingly. All arithmetic is done with 32-bit integers. Numerical results are stored back into variables as a string of ASCII digits. Variables that do not begin with ASCII digits have the value '0'. This is also true of variables which do not exist, or to which a value has never been assigned.

=  Sets variable to value. The simplest way of giving a variable a value is to create a new variable using the =operator. The example below creates three new variables. If the variable already existed these macros would reset them to the new values.
Example
 ^num=123 1
 ^string1=Dave 2
 ^num=^Dave 3
+  Increases the value of variable by value. Two ++ is a short-cut for increasing the value of variable by 1:
Example
 ^Num+^Val 1
 ^Num+1 3
 ^Num1++ 5
-  Decreases the value of variable by value. Two -- in a row is a short-cut for decreasing the value of variable by 1.
*  Multiplies the value of variable by value.
example.ref entityref="A3B2.Ex.DecreaseValueofVariable_en" type="include"/>
Example
 ^Num*5 1
 ^Num1*^Num2 3
/  Divides the value of variable by value.
Example
 tsgmdocomp 1,0,1
}  Makes the contents of variable have exactly value characters, by truncating it or by adding spaces on the left. The example below makes ^string have five characters, making its final value ...Ad (where points represent a space character):
Example
 ^string1=Adv 1
 ^string1}5 3
{  Makes the contents of variable have exactly value characters, by truncating it or by adding spaces on the right. The example below makes ^string1 have five characters, making its final value Adv.. (where points represent a space character):
Example
 ^string1=Adv 1
 ^string1{5 2

In this case the result will be "Adv##" (# indicates space).

.  Appends value to the end of the contents of variable. The example below sets two variables and then concentrates them. The result is that ^string 1 will now contain 'HelloDave':
Example
 ^string1=Hello 1
 ^string2=Dave 3
 ^string1.^string2 5
!  Gets the length of a string. The example below gives ^string1 a value of 4, this being the number of characters in the word 'Four'.
Example
 ^string2=Four 1
 ^string!^string2 3
[  Replaces the contents of variable with a sub-string of itself, counting from the v1st to the v2nd characters where v1 is the first character, numbered 1, in the string. The last character's number is the same as the length of the string. If v1 is zero or not present it defaults to the first character of the string. If v2 is zero or not present it defaults to the last character of the string. If you wish you can add a ] at the end of the line. This has no effect and is for readability only. The example below effectively cuts off the first character of ^string1, which becomes 'def)'
Example
 ^string1=(def) 1
 ^string1[2.. 3
]  The ] operator is similar to [, but works from the end of the string. v1 is therefore the last character in the string. v2, is the first character in the string. If v2 is zero or not present it defaults to the first character of the string. If v1 is zero or not present it defaults to the last character of the string. If you wish you can add a [ at the end of each line. This has no effect and is for readability only.
Example
 ^string1=(def) 1
 ^string1]2.. 3
Example

A problem with using the wdb macro to extract the data from a Arbortext APP dialogue box is that in many cases the data you want to examine is enclosed in either ( ) or [ ] characters, representing either the system or document defaults for a particular setting. In order to examine these sensibly you must strip the unwanted ( ) or [ ] characters:

A slightly simpler version of the same script avoids using loops by including the operations on the ^typeface variable on the same line as the tests. This makes the script a few characters longer, admittedly, but perhaps gains in clarity:

 ^parenthesis=( 1
 ^bracket=[ 2
 wdb "typeface" 3
 tf 4
 ^tmp=^typeface 5
 ^tmp[..1 6
 ?=^tmp,^parenthesis }strip 7
 ?=^tmp,^bracket }strip 8
 }nextstep 9
 :strip 10
 ^typeface[2.. 11
 ^typeface]2.. 12
 :nextstep 13
 ^parenthesis=( 14
 ^bracket=[ 15
 wdb "typeface" 16
 tf 17
 ^tmp=^typeface 18
 ^tmp[..1 19
 ?=^tmp,^parenthesis (^typeface[2..):(^typeface]2..) 20
 ?=^tmp,^bracket (^typeface[2..):(^typeface]2..) 21
Example

The following examples will assume that this assignment has taken place:

 ^sh=hello

Then:

 ^sh[2..3]
result:
^sh = el
 ^sh[..3]
result:
sh = "hel"
 ^sh]..3[
result:
sh = "llo"
 ^sh]2..3[
result:
sh = "ll"
Example

This example crops characters from a string using variable values.

The following examples will assume that this assignment has taken place:

 ^lg=abcdefghijklmnopqrstuvwxyz 1
 ^a=3 2
 ^b=5 3
 ^c=15 4

Then:

 ^lg[^a..8]

lg = "cdefgh"

 ^lg[^c..]

lg = "opqrstuvwxyz"

 ^lg]^b..^c[

lg = "lmnopqrstuv"

 ^lg]..^a[

lg = "xyz"

@  Retrieves the position of a single specified character in a line. The example below gets position of the 'd' character, set in ^var from the contents of the ^string variable
Example

Resulting in the value of ^var being '4'.

 ^string=abcdefg 3
 ^var=d 5
 ^var@^string 7
$  Two commands have been implemented for converting between deci-microns and any of Arbortext APP units. You may come across this when using floating points with variables and measurement getvars.
#  The second operator converts from unit form to deci-microns. The syntax of 'mm' is the same as for the '$' operator, but this time it provides the default units if none are present in ^variable. A valid default must always be specified, even if ^variable is known to contain its own unit type.
|  Logical or used to perform binary bitwise arithmetic on two binary values. In the result digits which are set in either value are returned with a value of 1.
:  Logical and used to perform binary bitwise arithmetic on two binary values. In the result digits which are set in both values are returned with a value of 1.
^  Logical xor used to perform binary bitwise arithmetic on two binary values.
%  Modulus (remainder of division).
value:n

The value of the variable. This may either be another variable name, or a string.

— Most of the 'Extensions' scripts supplied have been edited by Advent to minimize memory usage by reusing variables wherever possible. They therefore use variable names in the form ^_z_..^_a_.. Using this limited set of variable names helps avoid possible conflicts with variable names chosen by the user. You can conserve memory by using the same names for variables which only need to be stored whilst a particular script is running, but should realise that these variables' contents may be changed by other scripts.

A variable is used to hold a specific piece of information needed by your script, rather like the memory button on a pocket calculator. Each variable has a name and a value.

Once a variable has been assigned a value, it can be used with any macro in place of the parameters that the macro would usually take. This is done by including the variable name on a macro line and appending a ^ character to the end of the line. When Arbortext APP's macro processor receives a macro line ending with ^ it immediately scans the whole line looking for valid variable names with their preceding ^ and replaces them with the 'variables' contents. The resulting line is then executed as a normal macro.
Example

To set a carriage return or other special characters to a variable, the following syntax would be used.

 ^return?$10# 3
 ^superior?$142# 5

Document created on 08-Feb-2003 (revision 1)