2 ARD Description Syntax

 2.1 Restrictions on the Order of Fields
 2.2 Group Expression Control Characters
 2.3 Use of GRP Modification Elements

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

Keyword fields: These specify the basic shapes known to ARD (CIRCLE, BOX, etc.) from which more complex shapes are constructed.
Operator fields: These are logical operators, as in Fortran (.AND., .OR., .XOR., .NOT. etc.).
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:

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):

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:

        CIRCLE( 0, 10, 10 ) .OR. CIRCLE( 0, -10, 10 )

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:

        ( * ) .AND. BOX( 0, 0, 5, 5 )

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:

        ( CIRCLE( 0, 10, 10 ) .OR. CIRCLE( 0, -10, 10 ) ) .AND. BOX( 0, 0, 5, 5 )

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:

        CIRCLE( 0, 10, 10 ) .OR.
        CIRCLE( 0, -10, 10 )

then the modified ARD description would be :

        ( CIRCLE( 0, 10, 10 ) .OR. ) .AND. BOX( 0, 0, 5, 5 )
        ( CIRCLE( 0, -10, 10 ) ) .AND. BOX( 0, 0, 5, 5 )

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:

        ( *|10|5| ) .AND. BOX( 0, 0, 5, 5 )

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:

        ( CIRCLE( 0, 5, 5 ) .OR. CIRCLE( 0, -5, 5 ) ) .AND. BOX( 0, 0, 5, 5 )

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