Understanding Syntax Descriptions




Each chapter that describes a PERCY command begins by spelling out the syntax of the command: that is, the rules by which you can construct valid forms of the command.

The syntax of each command is expressed in a language called Meta/2. The following sections will describe the various constructs that make up a Meta/2 specification. After reading them, you should be able to make sense of any syntax specification in the Command Reference.



Keywords



Each command must begin with a keyword. Keywords define the structure of the command: for the most part, a command is a collection of keywords, some of which are modified by non-keyword arguments. The keywords of a Meta/2 syntax description are the words that do not begin with 

   "("   the left parenthesis
   "@"   the "at" sign
   "|"   the vertical bar
   "}"    the right  brace
Keywords in Meta/2 always appear in uppercase. The simplest Meta/2 expressions consist entirely of keywords. Some MOSS commands that fall into this category are shown below. 

   DEMO
 
   SET AUTOERASE OFF
 
   SET OVERLAYS ON ALL
 
   NOECHO


Class templates



Keywords can be modified by non-keyword values. The values associated with a keyword always immediately follow keyword. A collection of values is terminated by another keyword, or by the end of the command.

Class templates are used to indicate that the values associated with a particular keyword belong to a class of values. For example, the Meta/2 expression of the rule that the keyword FIND is to be followed by the name of a schedule looks like this. 

   FIND @schedule ...
Given this rule, a command that begins 

   FIND 13 ...
is clearly in error.

Class templates are very much like the wild card templates used in operating systems like Unix and VMS, except that they are a little more specialized. The class templates recognized by Meta/2 are listed below, along with descriptions of the values that match them. Class templates in a Meta/2 description begin with a backslash.



number



This template matches any number. Examples are 

   1
   3.14
   0.7495D-7


int



This template matches only integral values. Examples are 

   -3
   2122344576
   0.24E6


word



This template matches any string of contiguous non-blank characters. Examples are 

   alpine
   B7401-22129.45
   ^&HAHKH((*(JALJSAS


name



This template matches any word that begins with a letter and contains up to 32 letters, numbers, underscores, and hyphens. Examples are 

   Andrea
   BRORSEN-METCALF
   schedule_1
   X


calendar



The rules for matching this template are somewhat complicated : for the most part, a program will accept virtually any unambiguous format. Examples are 

   21 Jun 1983 2:00:01
   3/19/1987
   12-1-1984
(See the chapter on Conventions for more details about acceptable time strings.)



Derived templates



Some additional class templates, derived from those shown above, are used to describe the syntax of some commands. They are used to make the syntax expressions more nearly self-documenting. For example, the expression 

   SET ATTRIBUTES BODY @body (0:5){ ILLUMINATED @color ...
conveys more information than the equivalent expression 

   SET ATTRIBUTES BODY @int (0:5){ ILLUMINATED @int ...
The derived templates are listed below.

body

is an integer associated with an ephemeris body or designated object.
schedule

is equivalent to name, but is used only to refer to schedule names.
file

is equivalent to word, but is used only to refer to file names.
symbol

is equivalent to name, but is used only to refer to symbol names.
text

is any collection of zero or more words.
template

is equivalent to text, but is used only to refer to collections of wild card templates (to match schedule names, for instance).


Template quantifiers



The construct 

   LONGITUDE (2:5)@int
matches the keyword LONGITUDE followed by between two and five integers. The quantifier 

   (n:m)
when prefixed to any class template has a similar meaning. The lower bound is always present, and is always nonnegative. The upper bound is optional: for example, the quantifier 

   (2:)@int
mathces any sequence of two or more integer words.



Numeric qualifiers



The construct 

   DESIGNATE @int(1001:1099)
matches the keyword DESIGNATE followed by an integer between 1001 and 1099. The qualifier 

   (n:m)
when suffixed to any numeric class template has a similar meaning. Both bounds are optional: for example, the templates 

   @number(2:)
   @number(:1000)
are matched by numeric words whose values are greater than or equal to two and less than or equal to 1000 respectively.



Character qualifiers



The construct 

   DIRECTORY @template([*]|*%:[*]|*:)
matches any string that matches any of the individual wildcard templates 

   [*]
 
   *%:[*]
 
   *:
The wild card characters (asterisk and percent sign) have the same meanings as in DCL. An asterisk matches any substring; the percent sign matches any character.

The qualifier 

   (t |...|t )
     1      n
when suffixed to any character class template has a similar meaning.



Combining quantifiers with qualifiers



Quantifiers and qualifiers may be combined in any combination. The following ar 

   @int(-5:5)
 
   (3:)@name(A*|B*|*X)
 
   (1:3)@name(John|Bobby|Teddy)


Switches



The construct 

   (1:1){ ON ALL
        | OFF ALL
        | ON (1:15)@int(1:15) }
is called a switch. It is the final construct that you need to know. Although it looks forbidding, it is really quite simple. A switch is a list of keyword-template phrases, separated by vertical bars, and surrounded by braces. The left brace is prefixed with a quantifier, 

   (n:m){ ... }
Whenever you see a switch, it means that at least n and not more than m of the phrases separated by vertical bars must appear; however, they may appear in any order. Thus, the syntax 

   SET FIELD OF VIEW (1:4){   V2MIN @number
                            | V2MAX @number
                            | V3MIN @number
                            | V3MAX @number }
matches all of the following commands 

   SET FIELD OF VIEW V3MAX 66 V2MAX 75;
 
   SET FIELD OF VIEW V2MIN -5 V2MAX 15 V3MAX 0;
 
   SET FIELD OF VIEW V2MIN -20 V3MIN -20 V2MAX 20 V3MAX 20;
unlike the syntax 

   SET FIELD OF VIEW V2MIN @number
                     V2MAX @number
                     V3MIN @number
                     V3MAX @number
which does not match any of them.

When you see the special token 

   @options
within a switch, it means that the phrases following the token are optional, whereas the phrases preceding the token are required. For example, the construct 

   (2:3){          LATITUDE  @number
        |          LONGITUDE @number
        | @options
        |          HEIGHT    @number }
means that the phrases beginning with the keywords LATITUDE and LONGITUDE must appear, while the phrase beginning with keyword HEIGHT is optional.



Nesting switches



You can't do it. The construct 

   (a:b){ ... (c:d){ ... } ... }
is illegal.



Examples



Given the syntax description 

   FIND @schedule (0:1){ UMBRAL
                     | PENUMBRAL } ECLIPSE
 
                (3:3){ OF   @body
                     | BY   @body
                     | FROM @body }
 
                (0:1){ WITHIN @schedule }
convince yourself that the following are valid FIND ECLIPSE commands. 

   FIND ECL ECLIPSE OF 501 BY 599 FROM 399;
 
   FIND ECL UMBRAL ECLIPSE FROM 399 OF 501 BY 599;
 
   FIND ECL PENUMBRAL ECLIPSE OF 501 FROM 399 BY 599;
 
   FIND ECL ECLIPSE OF 501 BY 599 FROM 399 WITHIN CLEAR;
 
   FIND ECL UMBRAL ECLIPSE BY 599 OF 501 FROM 399 WITHIN CLEAR;
Convince yourself as well that the following are not valid commands. 

   FIND ECL ECLIPSE OF 501.5 BY 599 FROM 399;
 
   FIND ECLIPSE OF 501 BY 599 FROM 399;
 
   FIND 501_ECLIPSE ECLIPSE OF 501 BY 599 FROM 599;
 
   FIND ECL UMBRAL PENUMBRAL ECLIPSE OF 501 BY 599 FROM 399;
 
   FIND ECL ECLIPSE OF 501 FROM 399;
 
   FIND ECL ECLIPSE OF 501 502 BY 599 FROM 399;
 
   FIND ECL ECLIPSE OF BY 501 502 FROM 399;
 
   FIND ECL UMBRAL ECLIPSE OF 501 BY 599 FROM 399 WITHIN;
Next, given the syntax description 

   SET GRAPHICS   BODY @body  (1:5){ ILLUMINATED @integer
                                   |  TERMINATOR  @integer
                                   |  SHADOW      @integer
                                   |  MERIDIANS   @integer
                                   |  LATITUDES   @integer }
convince yourself that the following are valid SET ATTRIBUTE commands. 

   SET ATTRIBUTE  BODY 599 ILLUMINATED 12  SHADOW  13;
 
   SET ATTRIBUTE  BODY 599 SHADOW 13 ILLUMINATED 12;
 
   SET ATTRIBUTE  BODY 599 LATITUDES 5 MERIDIANS 3 TERMINATOR 0;
Convince yourself as well that the following are not valid commands. 

   SET ATTRIBUTE BODY 599;
 
   SET ATTRIBUTE ILLUMINATED 12  SHADOW  13;
 
   SET ATTRIBUTE ILLUMINATED 12  SHADOW  13  BODY 599;


Related Topics



  1. The Percy Help System