RRDiagram

Tool for generating railroad diagrams and doc-style grammar for Yugabyte API docs.

Tool is based on: https://github.com/Chrriis/RRDiagram.

Example

This is the kind of grammar and syntax diagrams that can get generated: https://docs.yugabyte.com/preview/api/ysql/commands/cmd_copy/

Usage

See the Yugabyte docs contributors guide.

Build

1mvn package -DskipTests=true

Internals

The diagram model represents the actual constructs visible on the diagram. To convert a diagram model to SVG:

1RRDiagram rrDiagram = new RRDiagram(rrElement);
2RRDiagramToSVG rrDiagramToSVG = new RRDiagramToSVG();
3String svg = rrDiagramToSVG.convert(rrDiagram);

The grammar model represents a BNF-like grammar. It can be converted to a diagram model:

1Grammar grammar = new Grammar(rules);
2GrammarToRRDiagram grammarToRRDiagram = new GrammarToRRDiagram();
3for(Rule rule: grammar.getRules()) {
4  RRDiagram rrDiagram = grammarToRRDiagram.convert(rule);
5  // Do something with diagram, like get the SVG.
6}

The grammar model can be created from code, or can read BNF syntax:

1BNFToGrammar bnfToGrammar = new BNFToGrammar();
2Grammar grammar = bnfToGrammar.convert(reader);
3// Do something with grammar, like get the diagram for SVG output.

The grammar model can also be saved to BNF syntax:

1GrammarToBNF grammarToBNF = new GrammarToBNF();
2// Set options on the grammarToBNF object
3String bnf = grammarToBNF.convert(grammar);

BNF Syntax

The supported BNF subset when reading is the following:

- definition
    =
    :=
    ::=
- concatenation
    ,
    <whitespace>
- termination
    ;
- alternation
    |
- option
    [ ... ]
    ?
- repetition
    { ... } => 0..N
    expression* => 0..N
    expression+ => 1..N
    <digits> * expression => <digits>...<digits>
    <digits> * [expression] => <0>...<digits>
    <digits> * expression? => <0>...<digits>
- grouping
    ( ... )
- literal
    " ... " or ' ... '
- special characters
    (? ... ?)
- comments
    (* ... *)

When getting the BNF syntax from the grammar model, it is possible to tweak the kind of BNF to get by changing some options on the converter.

License

This library is provided under the ASL 2.0.