How to Read the Syntax Diagrams

The syntax diagrams are read from left to right, and from top to bottom. The syntax diagrams are text-based with symbols to indicate valid usage of the statement. Words that are shown in italics, are descriptive placeholders. They are not part of the syntax but they describe the type of information it should be replaced with. Words that are in normal face, represent the actual syntax that the user should use. The following table is a summary of the symbols used in the syntax diagrams throughout the online help.

  Symbol Description
item no symbol To indicate that the item is required as part of the syntax.
Given   Possibilities
statement required_item   statement required_item
[ item ] brackets To indicate that the item between the left and right brackets is optional.
Given   Possibilities
statement [optional_item]   statement
statement optional_item
[ item ]* brackets with asterisk To indicate that if the optional item is included in the statement, the item or item-type can be repeated 0 or more times in sequential order.
Given   Possibilities
statement [optional_item]*   statement
statement optional_item, ...
( item )* parentheses with asterisk To indicate that the mandatory item or item-type can be repeated 0 or more times in sequential order. This is rarely part of a syntax.
Given   Possibilities
statement item1(, required_item)*   statement item1
statement item1, required_item, ...
[ item ]+ brackets with 'addition' symbol To indicate that if the optional item is included in the statement, the item or item-type can be repeated 1 or more times in sequential order.
Given   Possibilities
statement [optional_item]+   statement
statement optional_item
statement optional_item, ...
( item )+ parentheses with 'addition' symbol To indicate that the mandatory item or item-type can be be repeated 1 or more times in sequential order.
Given   Possibilities
statement (required_item)+   statement required_item
statement required_item, ...
item1 | item2 pipe To indicate that you have the option of choosing item1 or item2. If the choices are enclosed in brackets, then the choices are optional. If the choices are enclosed in parentheses, then the one of the options must be selected.
Given   Possibilities
statement (choice1 | choice2 | choice3)   statement choice1
statement choice2
statement choice3

Note: if the parentheses were replaced with brackets, another option would be statement (by itself) in addition to the other possibilities.

... three periods in sequence To indicate that the syntax continues on the next line. It is not part of the syntax. Usually if the syntax is too long for the display width, it will be divided into two parts.
Given   Possibility
statement1 ...
statement2_follows
  statement1 statement2_follows

Example

|- 1 -| |--- 2 ---||------- 3 -------| |---------- 4 -----------|
#define identifier [( [identifier]* )] [ identifier | character ]

The example shown above, is the syntax for using the macro definition and expansion directive. The syntax is divided into four parts. A step by step interpretation of this syntax diagram would begin with:

  1. part 1 is #define. The characters are displayed in normal face, therefore the term #define is an actual part of the syntax. To first part of our syntax is:
    #define
  2. part 2 is identifier. The characters are displayed in italics, therefore it is a descriptive placeholder. An identifier may be a variable or macro name, such as ADDNUM. Adding this to the syntax would give us:
    #define ADDNUM
  3. part 3 is [( [identifier]* )]. The outermost set of brackets indicate that the content ( ([identifier]*) ) is optional. If we look at the content alone ( [identifier]* ), the set of parentheses is not accented with a * or +. Therefore, the parentheses is a required part of the syntax (see no symbol in table above). The innermost set of brackets is the [ ]*. From the table above, the identifier is optional and may be repeated 0 or more times. So, if we defined ADDNUM as a macro that accepted two numbers and added them, then the syntax would be:
    #define ADDNUM(x, y) // where x and y are the parameters for addition

    If ADDNUM was a variable, then part 3 can be ignored. The syntax would appear as in step 2.

  4. part 4 is an optional part of the syntax. If we decide to include part 4 in the syntax, then we have two choices: identifier or character. Since ADDNUM is a macro that adds two numbers, then we must define the action to take place. The syntax would be completed as:
    #define ADDNUM(x, y) (x + y)