Summary

This chapter details the specifics of 3B2 variables, their use, types and application.

1 

Introduction

In Arbortext APP, variables are named areas of memory used to store a sequence of characters and during the execution of a Arbortext APP session, numbers, strings, or arrays can be stored in variables and used in future computations.   A variable is recognised by the ^ character that must prefix the variable name, for example:

The names given to variables are case sensitive.  ^FRED is not the same as ^fred, likewise ^Fred is not the same as ^freD.  In order to use the variable again the name has to be exact.

Variables can be used across documents as they are retained by Arbortext APP and are only reset when the application is closed down.  All open documents in one Arbortext APP session can effectively share the same variables.

There are numerous kinds of variables in Arbortext APP, with varying syntax, which can be manipulated and used throughout the application. This chapter will describe the different aspects of working with variables, the various kinds of variables and their uses.  Below is a list of the different kinds of variable syntax that can be used in Arbortext APP.

2 

Manipulation of variables

Variables have to be assigned a value in order for it to have any use and there are numerous ways in which this can be carried out.  Below is a list of the different types of syntax that can be used to populate a variable:

3 

The boxit command

The macro boxit can be used to display the value of a variable or a string on screen. This is useful when writing scripts to test if variable assignments are working correctly etc.  It is displayed on screen as a small box with the contents inside, for example:

Below is an example of using the boxit macro to display the contents of a variable:

7

The variable 'var' is populated with the value 2.

9

The contents of 'var' are to be shown in a boxit.

The example above produces the following boxit:

The enter or escape keys will remove a boxit message from the screen.  For further information see boxit

4 

Conditional tests with variables

The testing of variables is a fundamental part of scripting and consequently provides more scope for using and manipulating variables in Arbortext APP.  For example if a user has created a dialogue box with a tickbox then at some point the variable assigned to the tickbox will be tested to check its value.  For more information on scripting in Arbortext APP, go to 3B2 Scripting

The most common syntax for a conditional variable test is as follows:

Conditions

A basic example would be:

This is a test to see if ^var1 is greater than ^var2 and if true, issue the macro trun 0

Below are some more examples:

For further information on conditions and to see more tests see ?

5 

The savevars command

Variables only retain their values until Arbortext APP has been shut down.  Variables that need to be preserved until a Arbortext APP session has started can be saved in a file and reread the next time they are needed.  The macro to save variables is savevars and it takes two parameters:

Wildcards can contain ? to match a single character or * to match all remaining characters, for example:

See savevars for more information.

6 

The freevars command

There may be times when variables need to be reset during a Arbortext APP session.  The macro freevars can execute this and is particularly useful if the exact names of the variables are not known as a wildcard can be used like the savevars macro, for example:

This will clear all variables that begin with 'var'.

See freevars for more information.

7 

Regular variables

Regular Arbortext APP variables are the same as Perl's scalar variables as shown below:

For further information on Perl see the Perl in 3B2 chapter.

8 

Indexed variables

Arbortext APP indexed variables are the same as Perl's array of scalar variables:

9 

Attribute variables

Attribute variables are used to access attributes applied to style and reference tags. The syntax is as follows:

Attribute variables can only be used where this is applicable.  This will usually be during the formatting of text that contains tags with attributes for example:

Whenever an attribute variable is referenced, Arbortext APP will re-scan the relevant style tag markup to find the value of the attribute. Relevant markup will consist of all tags which resulted in the current format nesting level. It may also include tags (elements) that are higher in the hierarchy of a well-formed XML document. Relevant markup is re-scanned in reverse order so that only the most recent definition of an attribute will be found.  This allows for attributes to be overridden at any formatting or hierarchical level.  Below is an example of how a jump can be applied within a tag to identify the attribute value:

Like regular variable names, attribute names consist of alphabetic, underscore and numeric characters [a-zA-Z0-9_] but cannot start with a number.  However, it is common for SGML and XML files from external sources to have attribute names containing period (.) and hyphen (-) characters and sometimes other unusual characters. Unusual names syntax described later can be used to refer to these variables.  An older method of accessing such variables is also available for backwards compatibility. Any attribute name containing underscore characters which does match any of the rescanned markup will alternatively match markup which contains period or hyphen in place of the underscores, for example:

attribute variables will match within <elem> as follows:

Only the quoted variants are compatible with XML.  Single quoted attribute values are only recognised for non-XML streams if the relevant option is enabled in the XML ▶ tab of the Document Preferences dialogue box (see tdpref), for example:

The single quote in John's is paired or 'doubled-up' so that Arbortext APP can undersatnd and process the information.

The double quotes around autoexec are paired or 'doubled-up' so that Arbortext APP can undersatnd and process the information.

10 

Special attribute variables

There are three special attribute variables identified by their names of one, two or three underscores as shown below:

Below are some examples of special attribute variables:

The <?attr> command can be used to adjust Arbortext APP's idea of the current formatting position in each currently nested style tag.  It is this formatting position which determines the relevant markup that is re-scanned, so <?attr> can also be used to scan other markup tags for attributes.

11 

Indexed attributes

The syntax for an indexed attribute variable is:

In the above example 'attr' is the attribute.

For example, if:

Then attribute variables will match within <elem> as follows:

As can be seen from that example, index 0 refers to the whole attribute value, as if no index were present at all.  If any value contains spaces, it can be placed in quotes. Another markup/values example is illustrated below:

If:

Then:

The special ^__# variable can also be indexed.  In this way, styles can be renamed without needing internal changes.

For example, if:

Then:

12 

Unusual names

Sometimes it is necessary to refer to variables or attribute variables which do not conform to Arbortext APP's standard naming convention. This is particularly true when data is imported from external sources, or if Perl's special punctuation variables need to be referred to. The way to access such variables is simply to enclose the name part of the entire variable in single quotes, for example:

Arbortext APP does not interpret or evaluate anything inside the quotes, but simply passes the name (without the quotes) to the relevant system (such as Perl).

13 

Stream variables

Arbortext APP text streams can be accessed as though they were variables by using double quotes around the stream name, for example:

Some useful examples are shown (as macros) in the table below:

14 

Miniscripts - ^"*script"

Below is an example of a Arbortext APP miniscript in a stream called "weekday":

The following example is a Perl equivalent, also in a stream called "weekday":

Both of the above scripts will result in the regular variable ^weekday containing the first three characters of today's day name.  That same variable will be used as the result of the miniscript reference.  So, for either script, the show string command shown below will result in the current day name being shown:

A special variation on the name allows Arbortext APP miniscripts to be sourced from a Arbortext APP string instead of a document stream.  One advantage of this is that miniscripts can be written that are available to any open document or even when no documents are open.

The syntax for special names for string access to miniscripts is:

The above syntax runs miniscript in string 12345.

In this case, a regular Arbortext APP variable, ^_str_12345_ would have to be populated with any desired return value.

For more information see the 3B2 Scripting chapter.

15 

System variables

System variables enable the user to extract information from Arbortext APP about the setup and/or state of the current document. Some basic examples of system varaibles include: the full document name, the number of pages and the position in the text stream. For more information see the System Variables chapter.

System variables standardise access to getvars from scripts, showstrings and expressions. System variables are also referred to as getvars For more information see getvar

There are several variations of syntax that can be used to use system variables. System variables or getvars can be accessed as though they were variables.  To some extent, this is a convenience feature which makes the getvar macro somewhat redundant.

However, getvar is still useful for increased readability and to access several consecutive variables at the same time.  This is usually much faster, but also more reliable for things like the 'time' getvars which could change between getvar calls.

Below are some examples of different kinds of system variable use:

16 

Indexed system variables

Many of the new system variables or getvars require a parameter to provide the context of the request.  This is supplied as the index of the getvar variable. Indices can be any valid Arbortext APP expression and an index of (0) is the same as having no index at all. The syntax for indexed system variables is as follows:

In the above example syntax ^12345 is a getvar variable and the (n) is the index of the getvar variable.

Below are some examples of indexed system variables:

^11830(0) name of current stream.

^11830(1) name of parent stream/style.

^11830(2) name of grandparent stream/style.

17 

Named Getvars

Getvars also have an alternative method of access via a name. Using this method results in syntax that is easier to read. For example, the three different versions of syntax below all achieve the same result of retrieving the document filename, but the third version is much easier to identify and understand:

The system variable examples below all return the same value:

Alternatively the string function can be used more efficiently like this:

The getvar macro also understands the new names, for example:

The above example can also be specified as:

18 

Expressions

Any valid Arbortext APP expression can be used as a variable by enclosing it in parentheses, such as:

In the above example 'expr' is the expression. For example, an expression could be ^(^var1+^var2)

If the expression variable is used in a context where a string is required then the number will be converted to a string, for example, the insert macro can only take a string. So, in the following example the number 304 is automatically converted to a string:

Consider the following example. The variable assignments will result in '0' being assigned to ^test as will any other variable which contains a string that cannot be converted to a valid number.

This conversion to a number can be useful in a Arbortext APP condition macro, for example:

The above syntax is comparing two strings (a string compare).

Due to the expression brackets and because Arbortext APP expressions always return number, the above syntax is is comparing two numbers (a numeric compare).

19 

Indirect variables

Arbortext APP's indirect variables are identified by any string of characters within curly braces, for example:

The curly braces force Arbortext APP to evaluate the string using standard Arbortext APP variable interpolation and the result string is then re-parsed as the full variable name, except for the leading ^ character.  The small script below demonstrates this:

20 

Function Variables

Function variables enable you to call functions by name.  An example of the syntax is given below:

21 

Functions to access variables

23 

Function Parameters

Most functions will take exactly one parameter and that consists of everything up to the next unmatched ] character. Matched [ and ] pairs may appear in the parameter.

Embedded strings in single or double quotes may contain ] characters without terminating the parameter, for example:

Rarely the parameter may consist of multiple sub-parameters.  For example, the ^[prop xxx] function's parameter may be split when requesting font properties as shown below:

l=long name

s=short name

It is still important to consider the parameter as one parameter that may be subdivided depending on the function.  The reason is because one single Arbortext APP variable can be used as the parameter, for example:

More than one variable is not presently allowed

And if there is a variable, it must not have sub parameters

But it can be done by using the curly braces which evaluates all the variables first before the function is processed:

Alternatively use the indirect function which effectively is the equivalent of ^{....}

Or prepare the compound parameter before a syntax similar to the following examples:

24 

Further Information and References

For more information on the ^ macro see ^

For more information on scripting in Arbortext APP, go to 3B2 Scripting

For more information on system variables see the System Variables chapter.

For further information on Perl see the Perl in 3B2 chapter.

For further information on Show strings see the Show strings chapter.