Predefined Variables
Some variables are predefined by Arbortext Editor. This following is a list of predefined variables and what they represent. All of these variables are automatically maintained by Arbortext Editor.
• $ENV — An associative array in the main package defining the current environment. For example, to refer to the environment variable APTCATPATH in any package, use main::ENV["APTCATPATH"]. In the main package, $APTCATPATH can be used directly, although this use is not encouraged since it is not clear whether you are referring to a Arbortext Editor or system environment variable.
Changes to the $ENV associative array will be inherited by child processes. For example, the following expression changes the value of the TMPDIR environment variable.
$ENV["TMPDIR"] = "c:\arbortemp"
The environment is affected only if the associative array is changed by direct assignment. The environment will not be changed if the array value is modified by function (for example, used as a value in a call to the
chop function).
You can delete an environment variable by setting its value in the $ENV associative array to a null string. For example, the following expression removes the TMPDIR environment variable from the current environment without removing the $ENV["TMPDIR"] item in the array.
$ENV["TMPDIR"] = ""
To delete $ENV["TMPDIR"] from the $ENV associative array, use the following function:
delete($ENV["TMPDIR"])
• $ERROR — The syntax or run-time error message for the last command executed. It is set to the null string before any command or expression (including those from the
execute and
eval built-in functions) is compiled.
• $ERRORS — The array that holds the last few errors that were stored in
$ERROR. The number of stored errors is determined by the value of
$ERRORS_SIZE. An entry can added to this array either by an error in a function or command (such as
doc_open) or by any ACL command or function which explicitly assigns a value to
$ERROR.
To clear all previous entries from
$ERRORS, follow the
delete function example:
delete(main::ERRORS)
The $ERRORS variable is automatically recreated when the next error is generated.
An example of a function to retrieve the array stored in $ERRORS:
function get_last_errors()
{
local errors = "";
if (defined(main::ERRORS)) {
local lbound = low_bound(main::ERRORS);
local hbound = high_bound(main::ERRORS);
if (hbound >= lbound) {
# Build a string with the errors (newest to oldest).
local i;
for (i = hbound; i >= lbound; i--) {
errors .= main::ERRORS[i] . "\n";
}
}
}
return errors;
}
• $ERRORS_SIZE — Controls how many errors are stored in $ERRORS. If a new entry to $ERRORS exceeds the limit of $ERRORS_SIZE, the oldest entry is removed. The default is 10.
• $is_compact_install — Determines if the version of Arbortext Editor running is the compact installation. If Arbortext Editor is the full installation, returns zero. It always returns value zero.
• $is_e3 — Determines if the Arbortext Publishing Engine is running in server-mode (no user interface) and, if true, returns any value other than zero.
• $is_e3_interactive — Determines if the Arbortext Publishing Engine is running in Arbortext Publishing Engine Interactive mode (has user interface) and, if true, returns any value other than zero. Used with $is_e3, as in the following example, to determine the mode in which the Arbortext Publishing Engine is running:
if (main::is_e3) {
# I'm running in PE lights-out (server) mode.
}
else if (main::is_e3_interactive) {
# I'm running in PE Interactive.
}
else {
# I'm running in Editor.
}
• $OFS — The output field separator used by eval command to separate expressions. The default value is a single blank.
• $ORS — The output record separator used by eval command to terminate an expression list. The default value is a single newline.
• $PCS — The separator that separates parts of a path. It is a read-only variable equal to “\”.
• $PLS — The path list separator, that is, the character that separates path names in a list of path names. It is a read-only variable equal to “;”.
• $RESPONSES — The array that holds the last few responses that were stored in
$RESPONSE. The number of stored responses is determined by the value of
$RESPONSES_SIZE. An entry can be added to this array either by a response from the
response function, the
message command or by any ACL command or function which explicitly assigns a value to
$RESPONSE.
To clear all previous entries from
$RESPONSES, follow the
delete function example:
delete(main::RESPONSES)
The $RESPONSES variable is automatically recreated when the next error is generated.
An example of a function to retrieve the array stored in $RESPONSES:
Function get_last_responses()
{
local responses = "";
if (defined(main::RESPONSES)) {
local lbound = low_bound(main::RESPONSES);
local hbound = high_bound(main::RESPONSES);
if (hbound >= lbound) {
# Build a string with the responses (newest to oldest).
local i;
for (i = hbound; i >= lbound; i--) {
responses .= main::RESPONSES[i] . "\n";
}
return responses;
}
• $RESPONSES_SIZE — Controls how many responses are stored in $RESPONSES. If a new entry to $RESPONSES exceeds the limit of $RESPONSES_SIZE, the oldest entry is removed. The default is 0 for Arbortext Editor and 10 for the Arbortext Publishing Engine.
• $OFS — The output field separator used by eval command to separate expressions. The default value is a single blank.
• $SYMTAB — An associative array giving the symbol table for global variables in the current package. SYMTAB[ expr] is equivalent to the variable named by the result of expr, for example, SYMTAB["x"] is a synonym for the variable x. Note, one way to test for the existence of a variable "var" is to use the expression (var in SYMTAB). This is equivalent to defined(var). SYMTAB is the only predefined variable which exists in all packages. All other predefined variables are only in the main package.
• $appdata — The path name of the application data directory. This is the same value as returned by the get_appdata_dir function called with no arguments. $appdata is a read-only variable.
• $aptpath — A read-only variable which specifies the location of the directory that contains the program files needed to run the software.
• $arch — A read-only variable that specifies the architecture of the host running the software.
• $comproot — The installation directory used for publishing. If Arbortext Publishing Engine is being used for publishing, this is the path name on the Arbortext Publishing Engine server. Otherwise, the value is the same as the value of $aptpath. $comproot is a read-only variable.
• $currentcolumn — The number of the column where the cursor is positioned. This variable is valid only if the current document is displayed in a window. This is a read-only variable.
• $currentline — The number of the line where the cursor is positioned. This variable is valid only if the current document is displayed in a window. This is a read-only variable.
• $dirname — The directory name of the current document if it is attached to an edit class window, or the document attached to the Edit window that last had focus.
• $dirselect — The name of the currently selected file name in the directory display (if no file name is selected, its value is null). This is a read-only variable.
• $docname — The name of the current document if it is attached to an edit class window, or the document attached to the Edit window that last had focus. It is the name without any leading path name components. For example: /jdoe/mydoc.sgm becomes mydoc.sgm.
• $filename — The path name of the file being edited including any leading path name components and the file name. It refers to the current document if it is attached to an edit class window, or the document attached to the Edit window that last had focus.
• $home — A read-only variable that holds the value of the user's home directory. $home defaults to the value of the HOME environment variable. Otherwise, $home uses the home directory as specified by the operating system. If no home directory can be determined, $home is set to the Arbortext Editor startup directory.
The tilde character (~) can be used with ACL commands to represent the home directory. For example:
edit -newwindow ~/report.xml
• $progname — The full name of the program being executed, for example, Arbortext Editor.
• $selection — A string representing the selected region in the current window (if no selection exists in that window, its value is null). If sgmlselection=on, the string includes any SGML codes. Otherwise, tags and other SGML are not included in the string. This is a read-only variable.
• $sh_status — The exit status of the process executed by the last sh command or backquote expression.
• $status — A number representing the status of the last command executed: 0 means successful completion. 1 means failure. 2 (which only applies to conditional commands) indicates a syntax error.
• $system — A string specifying the type of system on which Arbortext Editor is running. $system is a read-only variable.
• $tagname — The name of the tag to the left of the cursor in the Edit view (in ASCII documents its value is null). End tags start with slash (/). Angle brackets are not included in the value. This is a read-only variable.
|
|
In the Document Map view, the process for determining $tagname is controlled by the set docmapcurrenttag command. |
• $topline — The vertical position in the document of the line at the top of the window. This variable is valid only if the current document is displayed in a window. This is a read-only variable.
• $version_build — The current build number of Arbortext Editor. This is a read-only variable.
• $version_date — The date of the current version of Arbortext Editor. This is a read-only variable.
• $version_date_code — The current software date code. For example, “M020”. This is a read-only variable.
• $version_number — The current version number of the software. This is a read-only variable.
• $version_release — The current software release number. For example, “5.4”. This is a read-only variable.
• $winsys — A string specifying the type of windows system for which this version of Arbortext Editor was created. (For example, "Windows".) $winsys is a read-only variable.
• $wintype — A string specifying the internal windows system implementation type for which this version of Arbortext Editor was created. (For example, "MFC" or "Galaxy".) $wintype is a read-only variable.
• _STRICT_ — A variable that controls how variables are declared in ACL packages. If you declare the _STRICT_ variable at the top of your package file, all variables must be explicitly declared. The default behavior is for variables to automatically declare themselves the first time they are referenced.
If the statement global _STRICT_ appears after the package statement in an ACL file, then the ACL interpreter will flag as errors or warnings any of the following variable uses.
◦ A reference or an assignment to a variable not previously declared on a
local or
global statement, or not declared as a formal argument to a function.
◦ An attempt to redefine a global variable with another global statement.
◦ A reference to a undeclared variable on a
readvar command.
An error is flagged only if you have set stricterrors=on. If the stricterrors option is set to off, a warning is displayed only if you have debug set to 1. Otherwise, no error or warning is given.
Most implicit declaration warnings will be detected when the package is sourced. However, some will not be detected until the offending ACL statement is executed (for example, the variable specified on a readvar command).
A package file declaring the _STRICT_ variable may be sourced more than once in a session. A global variable declared the first time a package is sourced will not be flagged as a duplicate definition the second and subsequent times the package is read. Once the “strict” behavior is turned on for a package, it cannot be turned off in the same session by undefining the _STRICT_ variable or deleting its definition in subsequent versions of the package file.
The _STRICT_ variable may not be declared in the main package as it would break existing ACL code. When developing new packages, use the _STRICT_ directive as it's helpful for detecting mistakes in variable names.
Arbortext Editor also recognizes environment variables. The associative array $ENV is the preferred way to access environment variables. However, for variable references used in the main package, if Arbortext Editor cannot find a variable of the name you supply, and an operating system environment variable of the same name exists, its value is used.
Use the command
show variables or
show vars to display a list of the variables defined in the main package.
Related Topics
