Syntax diagram structure

Pipelines v2.1

The argument structure of a stage is expressed by a syntax diagram. The diagram defines the stage argument keywords and operands and the order in which they are specified.

Home

To read a syntax diagram, follow the path of the line, reading from left to right and top to bottom

●	The >>─────── symbol indicates the beginning of a syntax diagram.
●	The ────────> symbol, at the end of a line, indicates that the syntax diagram continues on the next line.
●	The >──────── symbol, at the beginning of a line, indicates that the syntax diagram continues from the previous line.
●	The ───────>< symbol indicates the end of the syntax diagram.
●	The ├──────── symbol indicates the start of a syntax fragment.
●	The ────────┤ symbol indicates the end of a syntax fragment.

Syntax items (for example, a keyword or operand) may be:

●	Directly on the line (required)
●	Above the line (default)
●	Below the line (optional)

Abbreviations

 
>>──KEYWOrd────────────────────────────────────><

Uppercase letters denote the shortest acceptable abbreviation. If an item appears entirely in uppercase letters, it cannot be abbreviated. You can specify the item in uppercase letters, lowercase letters, or a combination.

In this example, you can specify KEYWO or KEYWORD in any combination of uppercase and lowercase letters.

Symbols

 
* Asterisk
: Colon
, Comma
= Equal Sign
- Hyphen
() Parentheses
. Full-stop/Period

You must code these symbols exactly as they appear in the syntax diagram.

Variables

 
>>──KEYWOrd──varname───────────────────────────><

Highlighted lowercase items (like_this) denote operands.

In this example, varname represents an operand which you must specify when you specify KEYWORD.

Repetitions

 
 ┌─<──────┐
>>──┴─repeat─┴─────────────────────────────────><

An arrow returning to the left means that the item can be repeated.

 ┌─<─,────┐
>>──┴─repeat─┴─────────────────────────────────><

A character within the arrow means you must separate repeated items with that character.

Required Choices

 
>>──┬─A─┬──────────────────────────────────────><
 ├─B─┤
 └─C─┘

When two or more items are in a stack and one of them is on the line, you must specify one of them.

In this example, you must choose A, B or C.

Optional Choices

 
>>──┬───┬──────────────────────────────────────><
 └─A─┘

When an item is below the line, the item is optional.

In this example, you can choose A or nothing at all.

>>──┬───┬──────────────────────────────────────><
 ├─A─┤
 ├─B─┤
 └─C─┘

When two or more items are in a stack below the line, all of them are optional.

In this example, you can choose A, B, C, or nothing at all.

Defaults

 
 ┌─A─┐
>>──┼───┼──────────────────────────────────────><
 ├─B─┤
 └─C─┘

Defaults are above the line. The stage uses the default unless you override it. You can override the default by coding an option from the stack below the line.

In this example, A is the default. You can override A by choosing B or C.

Repeatable Choices

┌─<─────┐

>>──┴─┬─A─┬─┴──────────────────────────────────><
 ├─B─┤
 └─C─┘

A stack of items followed by an arrow returning to the left means that you can select more than one item or, in some cases, repeat a single item.

In this example, you can choose any combination of A, B, or C.

Syntax Fragments

 
>>──┤ A Fragment ├─────────────────────────────><
 
A Fragment:
 
 ┌─A─┐
├───┼───┼───────────────────────────────────────┤
 ├─B─┤
 └─C─┘

Some diagrams, because of their length, must fragment the syntax. The fragment name appears between vertical bars in the diagram. The expanded fragment appears in the diagram after a heading with same fragment name.

In this example, the fragment is named “A Fragment”.