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
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---------'   

fragment_name

   .-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 the first few letters 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 "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.
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--------'