How to read the syntax diagrams

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

Figure 1 shows a sample syntax diagram that includes the various notations that are 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
Read syntax diagramSkip visual syntax diagram
Syntax

>>-COMMAND_NAME--required_variable------------------------------>

                                  .-KEYWORD=default_choice-.   
>--+---------------------------+--+------------------------+---->
   '-OPTIONAL_KEYWORD=variable-'  '-KEYWORD=-+-choice2-+---'   
                                             '-choice3-'       

   .------------------.                          
   V                  |                          
>----repeatable_item1-+--+-------------------+------------------>
                         '-| fragment_name |-'   

>--+------------------+--+-required_choice1-+------------------->
   +-optional_choice1-+  +-required_choice2-+   
   '-optional_choice2-'  '-required_choice3-'   

   .-,----------------.                        
   V                  |  .-DEFAULT_KEYWORD-.   
>----repeatable_item2-+--+-----------------+-------------------><
                         '-KEYword---------'   

   .-DEFAULT_KEYWORD-.   
|--+-----------------+------------------------------------------>
   +-KEYWORD1--------+   
   '-KEYWORD2--------'   

         .-----------.                                          
         V           |   .-KEYWORD3--KEYWORD4---.               
>--+---(---variable1-+-)-+----------------------+-----------+---|
   |                     '-variable2--variable3-'           |   
   |   .-,------------------------.                         |   
   |   V                          |                         |   
   '-(---variable4-- ---variable5-+-)-+-------------------+-'   
                                      +-OPTIONAL_KEYWORD1-+     
                                      +-OPTIONAL_KEYWORD2-+     
                                      '-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.
Read syntax diagramSkip visual syntax diagram
>>-COMMAND_NAME------------------------------------------------><

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

Read syntax diagramSkip visual syntax diagram
   .-DEFAULT_KEYWORD-.   
>>-+-----------------+-----------------------------------------><
   '-KeyWord---------'   

In this example, you could type "KW" 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.
Read syntax diagramSkip visual syntax diagram
>>-required_variable-------------------------------------------><

Required
items
Required items appear on the horizontal line (the main path).
Read syntax diagramSkip visual syntax diagram
>>-COMMAND_NAME--required_variable-----------------------------><

Optional
items
Optional items appear below the main path.
Read syntax diagramSkip visual syntax diagram
>>-+---------------------------+-------------------------------><
   '-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.

Read syntax diagramSkip visual syntax diagram
>>-+-required_choice1-+----------------------------------------><
   +-required_choice2-+   
   '-required_choice3-'   

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

Read syntax diagramSkip visual syntax diagram
>>-+------------------+----------------------------------------><
   +-optional_choice1-+   
   '-optional_choice2-'   

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

Read syntax diagramSkip visual syntax diagram
   .-DEFAULT_KEYWORD-.   
>>-+-----------------+-----------------------------------------><
   +-KEYWORD1--------+   
   '-KEYWORD2--------'   

Repeatable
items
An arrow returning to the left above the main line indicates an item that can be repeated.
Read syntax diagramSkip visual syntax diagram
   .------------------.   
   V                  |   
>>---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.

Read syntax diagramSkip visual syntax diagram
   .-,----------------.   
   V                  |   
>>---repeatable_item2-+----------------------------------------><

Fragments
Where it makes the syntax diagram easier to read, a section or fragment of the syntax is sometimes shown separately.
Read syntax diagramSkip visual syntax diagram
>>-+-------------------+---------------------------------------><
   '-| fragment_name |-'   

Read syntax diagramSkip visual syntax diagram
fragment_name

   .-DEFAULT_KEYWORD-.      
|--+-----------------+--…---------------------------------------|
   +-KEYWORD1--------+      
   '-KEYWORD2--------'