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


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.


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


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


>>-required_variable-------------------------------------------><

Required items

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


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

Optional items

Optional items appear below the main path.


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


>>-+-required_choice1-+----------------------------------------><
   +-required_choice2-+   
   '-required_choice3-'

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


>>-+------------------+----------------------------------------><
   +-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.


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

Repeatable items

An arrow returning to the left above the main line indicates an item that can be repeated.


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


   .-,----------------.   
   V                  |   
>>---repeatable_item2-+----------------------------------------><

Fragments

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


>>-+-------------------+---------------------------------------><
   '-| fragment_name |-'

⋮


fragment_name

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