How to read syntax diagrams

The syntactical structure of commands described in this document is shown by means of syntax diagrams.

Figure 1 shows a sample syntax diagram that includes the various notations used to indicate such things as whether:
  • An item is a keyword or a variable.
  • An item is required or optional.
  • A choice is available.
  • A default applies if you do not specify a value.
  • You can repeat an item.
Figure 1. Sample syntax diagram
Figure 1. Syntax

1  COMMAND_NAME required_variable?  OPTIONAL_KEYWORD=variable
1! KEYWORD=default_choice
1 KEYWORD=
2.1 choice2
2.1 choice3
2 +  repeatable_item1
2?  %fragment_name
1 optional_choice1
1 optional_choice2
1 required_choice1
1 required_choice2
1 required_choice3
4 + , repeatable_item2
1! DEFAULT_KEYWORD
1 KEYword
fragment_name

1! DEFAULT_KEYWORD
1 KEYWORD1
1 KEYWORD2
2.1 (+  variable1)
2.2.1!  KEYWORD3 KEYWORD4
2.2.1?  variable2 variable3
1 (+ , variable4 - variable5)
2.1 OPTIONAL_KEYWORD1
2.1 OPTIONAL_KEYWORD2
2.1 OPTIONAL_KEYWORD3

Here are some tips for reading and understanding syntax diagrams:

Order of reading
Read the syntax diagrams from left to right, from top to bottom, following the path of the line.

The ►►─── symbol indicates the beginning of a statement.

The ───► symbol indicates that a statement is continued on the next line.

The ►─── symbol indicates that a statement is continued from the previous line.

The ───►◄ symbol indicates the end of a statement.

Keywords
Keywords appear in uppercase letters. 

1  COMMAND_NAME

Sometimes you only need to type the first few letters of a keyword, The required part of the keyword appears in uppercase letters.


1! DEFAULT_KEYWORD
1 KEYword

In this example, you could type "KEY", "KEYW", "KEYWO", "KEYWOR" or "KEYWORD".

The abbreviated or whole keyword you enter must be spelled exactly as shown.

Variables
Variables appear in lowercase letters. They represent user-supplied names or values. 

1  required_variable
Required items
Required items appear on the horizontal line (the main path). 

1  COMMAND_NAME required_variable
Optional items
Optional items appear below the main path. 

1?  OPTIONAL_KEYWORD=variable
Choice of items
If you can choose from two or more items, they appear vertically, in a stack.

If you must choose one of the items, one item of the stack appears on the main path.


1 required_choice1
1 required_choice2
1 required_choice3

If choosing one of the items is optional, the entire stack appears below the main path.


1 optional_choice1
1 optional_choice2

If a default value applies when you do not choose any of the items, the default value appears above the main path.


1! DEFAULT_KEYWORD
1 KEYWORD1
1 KEYWORD2
Repeatable items
An arrow returning to the left above the main line indicates an item that can be repeated. 

1 +  repeatable_item1

If you need to specify a separator character (such as a comma) between repeatable items, the line with the arrow returning to the left shows the separator character you must specify.


1 + , repeatable_item2
Fragments
Where it makes the syntax diagram easier to read, a section or fragment of the syntax is sometimes shown separately. 

1?  %fragment_name
fragment_name

1! DEFAULT_KEYWORD
1 KEYWORD1
1 KEYWORD2
2  …