Skip to content

Generate railroad diagrams from code or BNF, generate BNF from code

License

Notifications You must be signed in to change notification settings

yugabyte/RRDiagram

 
 

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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

mvn package -DskipTests=true

Internals

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

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

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

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

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

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

The grammar model can also be saved to BNF syntax:

GrammarToBNF grammarToBNF = new GrammarToBNF();
// Set options on the grammarToBNF object
String 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.

About

Generate railroad diagrams from code or BNF, generate BNF from code

Resources

License

Stars

Watchers

Forks

Packages

No packages published

Languages

  • Java 100.0%