Declaring objects¶

Objects¶

.. syntax:grammar:: name¶

Directive for documenting grammars:

.. syntax:grammar:: MyGrammar

    Description.

Grammars can’t be nested, they also can’t appear inside production rules.

Options:

:no-index:¶
:no-index-entry:¶
:no-contents-entry:¶
:no-typesetting:¶: The standard Sphinx options available to all object descriptions.

:name: <text>¶

Sets a human readable name for a rule or a grammar.

The primary name is used to refer to an object in documentation; it’s used in HTML paths, anchors, and serves as a unique object identifier.

The human readable name is used to display object to a user; it’s used when rendering documentation and cross-references.

Example:

.. syntax:grammar:: PrimaryName
    :name: Human readable name

    Notice that anchor for this grammar uses its primary name.

When referring to an object, we use primary name: :syntax:g:`PrimaryName`.
When this cross-reference is rendered, though,
it will use a human readable name.

:imports: <list of diagram names>¶

If your parser generators allows importing grammars, you can use imports option to specify which diagrams are imported from the documented one.

This will affect object resolution for cross-references and diagrams.

Example:

.. syntax:grammar:: BaseGrammar

    .. syntax:rule:: BaseRule

.. syntax:grammar:: DownstreamGrammar
    :imports: BaseGrammar

    This grammar imports :syntax:g:`BaseGrammar`, so it can reference
    its rules without prefixing them with grammar name:
    :syntax:r:`BaseRule`.

    This also works in diagrams:

    .. syntax:diagram:: BaseRule

:root-rule: <rule> | <grammar>.<rule> | <path> <rule>¶

Specifies root rule of the diagram.

Setting a root rule has two effects:

If mark-root-rule is enabled, syntax diagrams for the root rule will use use complex line endings, while syntax diagrams for all other rules will use simple ones.
syntax:autogrammar will not display rules that aren’t reachable from the root rule.

See example in syntax:autogrammar.

The value should be either name of a rule from the grammar that’s being documented, a grammar name and a rule name separated by a dot, or a grammar file and a rule name separated by a space.

:mark-root-rule:¶

:no-mark-root-rule:¶

If enabled, diagrams in the root-rule will use complex line endings, while diagrams in other rules will use simple ones (see end-class).

With this option turned off, root-rule only affects how syntax:autogrammar filters displayed rules.

:diagrams:¶

:no-diagrams:¶

:cc-to-dash:¶

:no-cc-to-dash:¶

:bison-c-char-literals:¶

:no-bison-c-char-literals:¶

:literal-rendering:¶

Same as corresponding options from syntax:autogrammar.

When used on syntax:grammar, these options override defaults for any nested syntax:autorule, syntax:lexer-diagram or syntax:parser-diagram.

:diagram-*:¶

These options override defaults for any syntax:diagram used within this grammar.

Example:

.. syntax:grammar:: MyGrammar
    :diagram-end-class: simple

    All diagrams in this grammar will use simple end class:

    .. syntax:diagram:: Simple end class

    Unless they override it manually:

    .. syntax:diagram:: Complex end class
        :end-class: complex

.. syntax:rule:: name¶

Directive for documenting production rules:

.. syntax:rule:: MyRule

    Description.

Rules can’t be nested.

Options:

:no-index:¶
:no-index-entry:¶
:no-contents-entry:¶
:no-typesetting:¶: The standard Sphinx options available to all object descriptions.

:name: <text>¶

Sets a human readable name for a rule or a grammar.

See syntax:grammar:name for more info.

:diagram-*:¶
:diagrams:¶
:no-diagrams:¶
:cc-to-dash:¶
:no-cc-to-dash:¶
:bison-c-char-literals:¶
:no-bison-c-char-literals:¶
:literal-rendering:¶: Same as corresponding options from syntax:grammar and syntax:autogrammar.

Diagrams¶

.. syntax:diagram::¶

This directive renders a syntax diagram. Its contents should be a valid YAML document containing a description of a diagram element.

Full specification with examples is available in documentation for the syntax-diagrams library. You can also use an online diagram editor.

Example:

.. syntax:diagram::

    - "class"
    - non_terminal: "name"
    - optional:
      - "("
      - non_terminal: "class-bases"
      - ")"
    - ":"

Options:

:alt: <text>¶: Alternate text: a short description of the image, displayed by applications that cannot display images, or spoken by applications for visually impaired users.

:align: top | middle | bottom | left | center | right¶: The alignment of the image, equivalent to the HTML <img> tag’s "align" attribute or the corresponding vertical-align and text-align CSS properties.

:class: <text>¶: Adds a CSS class to the corresponding <svg> or <img> element.

:end-class: simple | complex¶

Changes how ends of the diagram are rendered.

Simple	Complex

:reverse:¶
:no-reverse:¶: Switches diagram direction to right-to-left.

:svg-*:¶

:text-*:¶

Any other option from syntax_diagrams_svg_settings or syntax_diagrams_text_settings can be overridden as well. Replace all underscores in option name with dashes and add svg- or text- prefix:

Example:

.. syntax:diagram::
    :svg-padding: 15 10 15 10
    :svg-arc-margin: 15
    :svg-arrow-style: triangle

    choice:
    -
    - statement
    - expression
    default: 2

Simplified diagram directives¶

You can use ANTLR 4 syntax for simple diagrams. It’s quicker, but allows less customization.

.. syntax:lexer-diagram::¶

The body of this directive should contain a valid ANTLR 4 lexer rule description.

Example:

.. syntax:lexer-diagram:: ('+' | '-')? ([1-9][0-9]* | '0')

Options:

All options from the syntax:diagram directive ara available, as well as syntax:autogrammar:cc-to-dash and syntax:autogrammar:literal-rendering.

.. syntax:parser-diagram::¶

The body of this directive should contain a valid ANTLR 4 parser rule description.

Example:

.. syntax:parser-diagram::

    SELECT DISTINCT? (
        '*' | expression (AS row_name)? (',' expression (AS row_name)?)*
    )

Options:

All options from the syntax:diagram directive ara available, as well as syntax:autogrammar:cc-to-dash and syntax:autogrammar:literal-rendering.