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