Block elements¶

Block elements helps you structure your diagram logically and/or spatially. The spatial elements are: Sequence, Stack and Group; Logical elements are OptionalSequence, Choice, MultipleChoice, Optional, OneOrMore, ZeroOrMore, AlternatingSequence, and finally HorizontalChoice combines both spatial and logic.

Sequence¶

Sequence is a concatenation of other elements and requires at least one child element.

Syntax¶

DSLJSONYAML

Sequence:
    ...

{
    "element": "Sequence",
    "items": [
        ...
    ]
}

element: Sequence
items:
- ...

Properties¶

items: an array/list of elements

Output¶

Sequence of three Terminals 1, 2 and 3

Stack¶

Identical to a Sequence, but the items are stacked vertically rather than horizontally. Best used when a simple Sequence would be too wide; instead, you can break the items up into a Stack of Sequences of an appropriate width.

Syntax¶

DSLJSONYAML

Stack:
    ...

{
    "element": "Stack",
    "items": [
        ...
    ]
}

element: Stack
items:
- ...

Properties¶

items: an array/list of elements

Output¶

Stack of three Terminals 1, 2 and 3

Group¶

Highlights its child with a dashed outline, and optionally labels it. Passing a string as the label constructs a Comment, or you can build one yourself (to give an href or title). The DSL parser only accepts text labels, the JSON and YAML parsers accept any element as well as text.

Syntax¶

DSLJSONYAML

Without a label:

Group:
    ...

With a label:

Group: label
    ...

Without a label:

{
    "element": "Group",
    "item": {
        ...
    }
}

With a label:

{
    "element": "Group",
    "label": ...
    "item": {
        ...
    }
}

Without a label:

element: Group
item:
  ...

With a label:

element: Group
label: ...
item:
  ...

Properties¶

label: optional, can be a string, or when using the JSON or YAML parsers, any element. The most likely case is using a Comment but any element will work.
item : a single element, mandatory.

Output¶

Group with no label

Group with a (Comment) label

Choice¶

An exclusive choice among all branches.

Syntax¶

DSLJSONYAML

Without default:

Choice:
    ...
    ...

With a default branch:

Choice: value
    ...
    ...

Without default:

{
    "element": "Choice",
    "items": [
        ...
        ...
    ]
}

With a default branch:

{
    "element": "Choice",
    "default": value,
    "items": [
        ...
        ...
    ]
}

Without default:

element: Choice
items:
  ...
  ...

With a default branch:

element: Choice
default: value
items:
  ...
  ...

Properties¶

default: int, optional (if not set: 0). Specifies which child is the "normal" choice and should go in the middle (starting from 0 for the first child).
items: an array/list of elements. Each element will have its own line.

Output¶

Choice between three values

HorizontalChoice¶

Identical to Choice, but the items are stacked horizontally rather than vertically. There's no "straight-line" choice, so it just takes a list of children. Best used when a simple Choice would be too tall; instead, you can break up the items into a HorizontalChoice of Choices of an appropriate height.

Syntax¶

DSLJSONYAML

HorizontalChoice:
    ...
    ...

{
    "element": "HorizontalChoice",
    "items": [
        ...
        ...
    ]
}

element: HorizontalChoice
items:
  ...
  ...

Properties¶

items: an array/list of elements. Each element will have its own "column".

Output¶

Choice between six values, broken in two blocks

MultipleChoice¶

Similar to a Choice, but more than one branch can be taken.

Syntax¶

DSLJSONYAML

MultipleChoice: value any|all
    ...
    ...

{
    "element": "MultipleChoice",
    "default": value,
    "type": "any|all",
    "items": [
        ...
        ...
    ]
}

element: MultipleChoice
default: value
type: any|all
items:
  ...
  ...

Properties¶

All properties are mandatory.

default: int, specifies which child is the "normal" choice and should go in the middle
type: either any (1+ branches can be taken) or all (all branches must be taken).
items: an array/list of elements. Each element will have its own line.

Output¶

MultipleChoice: any of three

MultipleChoice: all of three

Optional¶

A shorthand for Choice(0|1, Skip(), child).

Syntax¶

DSLJSONYAML

Don't skip:

Optional:
    ...

Skip:

Optional: skip
    ...

Don't skip:

{
    "element": "Optional",
    "item": {
        ...
    }
}

Skip:

{
    "element": "Optional",
    "skip": true,
    "item": {
        ...
    }
}

Don't skip:

element: Optional
item:
  ...

Skip:

element: Optional
skip: true
item:
  ...

Properties¶

skip: with DSL, this is either empty or the string "skip" ; in JSON/YAML, this is an optional boolean (false if not specified).
item: an element, mandatory.

Output¶

Optional without skip

Optional with skip

OptionalSequence¶

A Sequence where every item is individually optional, but at least one item must be chosen.

DSLJSONYAML

OptionalSequence:
    ...

{
    "element": "OptionalSequence",
    "items": [
        ...
    ]
}

element: OptionalSequence
items:
- ...

Properties¶

items: an array/list of elements

Output¶

OptionalSequence of three Terminals 1, 2 and 3

OneOrMore¶

A loop that requires taking the first element at least once. The loop is typically a Comment but can be any element.

Syntax¶

DSLJSONYAML

Simple repeat:

OneOrMore:
    ...

Labelled repeat:

OneOrMore: label
    ...

Simple repeat:

{
    "element": "OneOrMore",
    "item": {
        ...
    }
}

Repeat with an element:

{
    "element": "OneOrMore",
    "item": {
        ...
    },
    "repeat": {
        ...
    }
}

Simple repeat:

element: OneOrMore
item:
  ...

Repeat with an element:

element: OneOrMore
item:
  ...
repeat:
  ...

Properties¶

item : a single element, mandatory.
repeat: if empty, will just draw a line, else will insert the element on the loop. With the DSL parser, this is a string.

Output¶

Simple OneOrMore

OneOrMore with a label or Comment

OneOrMore with a Terminal (",")

ZeroOrMore¶

A shorthand for Optional(OneOrMore(child, repeat), skip). Like OneOrMore, this is a loop, but it can be skipped.

Syntax¶

DSLJSONYAML

Simple ZeroOrMore:

ZeroOrMore:
    ...

ZeroOrMore with an element and skip as default::

OneOrMore: skip
    ...
    ... (repeat)

Simple ZeroOrMore:

{
    "element": "ZeroOrMore",
    "item": {
        ...
    }
}

ZeroOrMore with an element and skip as default:

{
    "element": "ZeroOrMore",
    "item": {
        ...
    },
    "skip": true,
    "repeat": {
        ...
    }
}

Simple ZeroOrMore:

element: ZeroOrMore
item:
  ...

ZeroOrMore with an element and skip as default:

element: OneOrMore
skip: true
item:
  ...
repeat:
  ...

Properties¶

item : a single element, mandatory.
repeat: if omitted, will just draw a line, else will insert the element on the loop. With the DSL parser, this is a string.
skip: with DSL, this is either empty or the string "skip" ; in JSON/YAML, this is an optional boolean (false if not specified).

Output¶

Simple ZeroOrMore

ZeroOrMore with skip and a label

AlternatingSequence¶

Similar to a OneOrMore, where you must alternate between the two choices, but allows you to start and end with either element (OneOrMore requires you to start and end with the "child" node).

Syntax¶

DSLJSONYAML

AlternatingSequence:
    ...
    ...

{
    "element": "AlternatingSequence",
    "items": [
        ...
        ...
    ]
}

element: AlternatingSequence
items:
- ...
- ...

Properties¶

items: an array/list of exactly two elements

Output¶

AlternatingSequence