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.

Running as a server

To start the diagram server, run make server. The service runs on port 1314 @ /ebnf. The service can be reached as curl "localhost:1314/ebnf?mode=diagram&rules=select". These are the parameters supported.

Argument	Description
api	Language API name. One of - ysql, ycql. Support for ycql will be added soon (Default: ysql)
version	YB Release version. One of - preview, stable, v2.12, v2.14, v2.16, v2.8. This ensures that the correct EBNF file is looked up for generating Grammar/Diagrams for a specific version. (Default: preview)
mode	Method to execute. One of - reference, grammar, diagram (Mandatory) - reference: Will return the grammar and diagrams for all the rules in the EBNF (Typically used to generate the reference file, i.e. grammar_diagrams.md) - grammar: Will return diagram definitions in plain text - diagram: Will return the diagram in SVG format
depth	The depth (wrt to the doc root) at which the generated diagrams/definition will be embedded. This is used to generate the correct relative link to the reference file. (Optional)
rules	Comma-separated names of rules for which syntax diagrams or diagram definitions need to be generated (eg: rules=select,select_start). (Mandatory for grammar and diagram modes)
local	Comma-separated names of rules for which the definition will be xref'ed to the same page instead of pointing to the definition in the reference file. This is to be used when multiple grammar/diagram tabs are embedded on the same page and one diagram refers to the other. (eg: local=select_options). Invalid rules are ignored.

Build

1make

Publishing to the npm registry

1. Update the version number in package.json
2. Build the npm package using make package
3. You need an account on npm to publish. If you don't have one, go to www.npmjs.com and create a free account.
4. Authenticate on the command line with npm login
5. Publish using make publish

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.