2 ARD Description Syntax

An ARD description consists of a stream of fields, optionally separated by one or more spaces, or tabs. There are three types of fields:

(1)

Keyword fields: These specify the basic shapes known to ARD (CIRCLE, BOX, etc.) from which more complex shapes are constructed.

(2)

Operator fields: These are logical operators, as in Fortran (.AND., .OR., .XOR., .NOT. etc.).

(3)

Statement fields: These are fields which effect the way that the keyword fields are interpreted, e.g. setting up the dimensionality of the system (DIMENSION), the recognized coordinate systems (COFRAME), etc.

Some keyword and statement fields require argument lists, and these are enclosed within parentheses following the keyword or statement. Arguments are delimited by commas.

keywords and statements can be abbreviated to three characters (operators cannot be abbreviated). ARD descriptions are case-insensitive, and white space (eg spaces, blank records in a file, blank group expressions) is ignored.

2.1 Restrictions on the Order of Fields

An ARD description is basically an algebraic expression in which the operators are logical operators (.AND., .OR., etc.) and the operands are represented by keywords (CIRCLE, BOX, etc.) which notionally take true or false values depending on whether or not the current pixel is inside or outside the specified region. Therefore, all the usual restrictions exist on the placing of operators and operands in algebraic expressions; binary operators (e.g. .AND.) must have an operand or bracketed expression on each side, unary operators (e.g. .NOT.) must be followed by an operand or bracketed expression, opening and closing parentheses must balance, etc.

There are, however, certain ways in which an ARD description can depart from this syntax:

• Statement fields can be embedded within an ARD description at any point. They are always removed before evaluating the ARD description as an algebraic expression.
• If .TRUE. is supplied for ARD_WORK argument CONCAT, then a single operator field may appear before the first keyword field. In this case the “missing” operand value to the left of the first operator is defined by the initial mask supplied to routine ARD_WORK. If CONCAT is supplied .TRUE. and no operator field is found before the first keyword field, then an implicit .OR. operator is assumed.
• If two keyword fields do not have an intervening operator field, then an implicit .OR. operator is assumed. This allows a simple list of regions to be specified such as:
       #
       #  ARD description file
       #
       POLYGON( 20, 20, 50, 50, 25, 75)      # A triangle
       ELLIPSE( 10.0, 10.0, 8.0, 5.0, 45.0 )
       CIRCLE( 22, 22, 40 )

  This is effectively equivalent to:

       POLYGON( 20, 20, 50, 50, 25, 75) .OR.
       ELLIPSE( 10.0, 10.0, 8.0, 5.0, 45.0 ) .OR.
       CIRCLE( 22, 22, 40 )

  The returned integer mask will contain positive values within the union of the three regions, and zero outside.

• If an operand is directly followed by a .NOT. operator then an implicit .OR. will be inserted in front of the .NOT. This allows lists of regions such as the following to be given:
       POLYGON( 20, 20, 50, 50, 25, 75)
       .NOT.ELLIPSE( 10.0, 10.0, 8.0, 5.0, 45.0 )
       .NOT.CIRCLE( 22, 22, 40 )

  The returned mask will contain positive values for all pixels which are either within the polygon, or are not within the ellipse, or are not within the circle. It may need to be emphasised here that .OR. operators are inserted and not .AND. operators.

2.2 Group Expression Control Characters

The following two sub-sections supply details of the interaction of ARD with the GRP package, and may safely be skipped over on an initial reading through this document.

The stream of ARD fields is supplied in the form of a GRP group expression (and stored in a normal GRP group) with the following control characters (see SUN/150):

• “^” is used to mark the start of an indirection file, from which further ARD fields should be read.
• “#” is used to initiate a comment.
• “;” is used to delimit GRP elements. A GRP element may contain any number of ARD fields (within the restrictions on string length set by GRP). Argument lists for keyword and statement fields can be split between elements. An element may consist of a single reference to an indirection file (using the “^” character). In this case the element must not contain any explicit ARD fields. Note, GRP elements cannot span records. Thus, carriage returns (either in a file or entered at a prompt) also act as GRP element delimiters, in addition to the “;” character.
• “*” is used as the token which represents basis names within a modification element.
• “|” is used to separate old and new substitution strings when editing names.
• The “OPEN_NEST” and “CLOSE_NEST” control characters are not used (they are set “null”).
• “-” is used as the flag character. If a group expression is supplied which ends with “-”, then the user is re-prompted for a further group expression, which will be appended to the end of the earlier ones. The interpretation of “-” as the GRP flag character takes precedence over it’s interpretation as a synonym for the .NOT. operator.
• “{” is used to open a new kernel.
• “}” is used to close a kernel. A typical use of the kernel characters is to allow the contents of an indirection file to be edited before being used. An element such as “{^file1.ard}|100|200|” would cause the contents of file1.ard to be read, and then all occurrences of 100 would be replaced by 200.

A complete ARD description can be broken across several lines of an indirection file, or across several directly supplied group expressions (each one terminated with the flag character “-”). However, breaks must occur either between fields or between values in a keyword or statement argument list.

2.3 Use of GRP Modification Elements

The GRP system provides a facility which allows a user to modify the contents of a group previously created by the calling application. To do this, a “modification element” is included in the supplied ARD description (or “group expression” to use GRP parlance). A GRP identifier for an existing group can be supplied to the routines ARD_GROUP and ARD_GRPEX (argument IGRP1). If the ARD description supplied by the user contains a modification element, then the contents of the group identified by IGRP1 will be modified according to the instructions in the modification element, and the results incorporated into the returned group. Note, the specified editing is applied separately to each element in the existing group, to produce the corresponding element for the new group. Elements are delimited in ARD descriptions by the “;” character, and by carriage returns.

For instance, suppose that the application has already created a group containing the following ARD description:

If the GRP identifier for this group is supplied as argument IGRP1 to routine ARD_GROUP, the user may supply an ARD description including a modification element such as:

The asterisk is replaced in turn by each element of the contents of the group identified by IGRP1 (the “basis” group). Thus, the above ARD description is equivalent to the following:

Note, the original ARD description was supplied on a single line, and was thus stored as a single element in the group. If it had spanned lines, then each line would have been edited separately. For instance, if the original ARD description had been supplied as follows, on two lines:

then the modified ARD description would be :

This group expression would not be accepted by ARD_WORK because of the missing operand after the .OR. operator.

If the user has supplied the ARD description on a single line, and then modified it using the following ARD description:

then the basis group would be edited by replacing all occurrences of the string “10” by the string “5”, before being included in the final ARD description. Thus the above would be equivalent to:

The syntax of such modification elements is described fully in SUN/150.