Antlr4SyntaxRailroadDiagram Gradle Plugin

Generates Railroad-style syntax diagrams as a single HTML file from Antlr4 grammars in your project.
Provides a single new task, antlr4SyntaxRailroadDiagram. The task is not automatically inserted into your build. You must add it as a dependency on whichever task makes sense for your project e.g.

    tasks.shadowDistZip {
        dependsOn(tasks["antlr4SyntaxRailroadDiagram"])
    }

The task is configured with a matching antlr4SyntaxRailroadDiagram extension

antlr4SyntaxRailroadDiagram {
    inputGrammarName = "parsergrammar"
    inputGrammarDirectory: File? = null
    sourceSetName = "main"
    documentTitle = "Railroad Syntax Diagram"
    documentName = "railroadsyntaxdiagram.html"
    curveRadius = 10f
    innerPadding = 10f
    pathWidth = 3f
    ruleStartCharSize = 14f
    ruleCharSize = 12f
    literalCharSize = 12f
    embedStyleFile: File? = null
    outputDirectory = ""
}

Example: A typical configuration

antlr4SyntaxRailroadDiagram {
    inputGrammarName="DomainLanguageParser" // Our grammar is defined in "DomainLanguageParser.g4" and "DomainLanguageLexer.g4"
    documentTitle = "Specialised Language for Expressing a Solution in a Particular Domain"
    documentName="DomainLanguageSyntaxDiagram.html"
    outputDirectory = "$buildDir/distribution/docs"
}

Grammar Location

The plugin will search the sourceset with the name specified in sourceSetName for a file named <inputGrammarName>.g4. Grammar includes (including lexical grammars) are expected to be relative to the directory containing the specified grammar file.

Examples

• Kotlin Syntax Diagram
• Swift 5 Syntax Diagram
• Typescript Syntax Diagram

Extension Parameters

inputGrammarName

Name of the parser or combined grammar to process. All grammars are assumed to have a g4 file extension.

inputGrammarDirectory

Explicity specify the directory where the Antlr gammars can be found. If set, this will override the directory found in the search method described in Grammar Location.

sourceSetName

Name of the sourceset to search for the path containing the grammar identified by inputGrammarName.

documentTitle

Title of the document. The title and h1 elements will be set to this value in the generated document.

documentName

Name of the file that will be generated in the output directory.

curveRadius

Radius of curves in diagram paths. This value is used to calculate diagram positioning and may also be used in the embedded styles.

innerPadding

Padding inside rule references. This value is used to calculate diagram positioning and may also be used in the embedded style.

pathWidth

Width of path lines. This value is used to calculate diagram positioning and may also be used in the embedded styles.

ruleStartCharSize

Estimated width of character in rule start symbol. This value is used to calculate diagram positioning and may also be used in the embedded styles.

ruleCharSize

Estimated width of character in a parser or lexer rule reference symbol. This value is used to calculate diagram positioning and may also be used in the embedded styles.

literalCharSize

Estimated width of character in a lexer literal symbol. This value is used to calculate diagram positioning and may also be used in the embedded styles.

outputDirectory

Path to the directory that the document will be generated in. The name of the document is specified by documentName.

embedStyleFile

A File containing HTML Style definitions to use instead of the default styles.
Some of the values configured in the antlr4SyntaxRailroadDiagram extension can be used in the style definitions by including replacement tags.

Note that the units for these values are defined by the style.

Available Replacement Tags

Default Styles

h1 {
    font:21px sans-serif;
    }

div.rule-section {
    border-radius: 10px;
    border: 1px solid rgba(0,0,0,0.2);
    padding: 6px;
    margin-bottom: 8px;
    width:fit-content;
    min-width: 100%;
    }

div.cross-reference {
    border-radius: 5px;
    background: rgba(0,0,0,0.05);
    padding: 6px;
    margin:4px;
    }

a.cross-reference {
    font: italic 14px sans-serif;
    }

p.cross-reference {
    font: 14px sans-serif;
    }

svg.rrd line {
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:rgba(0,0,0,0);
        }

svg.rrd path {
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:rgba(0,0,0,0);
        }

svg.rrd path.symbol {
        stroke-width:1;
        stroke:black;
        fill:black;
        }

svg.rrd circle.rule-start{
    stroke-width:${PATH_WIDTH};
    stroke:black;
    fill:rgb(246, 200, 200);
    }

 svg.rrd rect.rule-start{
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:rgb(246, 200, 200);
    }

svg.rrd text.rule-start {
        font:italic ${RULE_START_CHAR_SIZE}px monospace;
        text-anchor:middle;
        }

svg.rrd path.rule-end {
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:rgba(0,0,0,0);
        }

svg.rrd rect.lexer {
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:rgb(246, 255, 204);
        }

svg.rrd text.lexer {
        font:italic ${RULE_CHAR_SIZE}px monospace;
        text-anchor:middle;
        }

svg.rrd rect.lexer-literal {
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:rgb(246, 255, 204);
        }

svg.rrd circle.lexer-literal {
    stroke-width:${PATH_WIDTH};
    stroke:black;
    fill:rgb(246, 255, 204);
    }

svg.rrd text.lexer-literal {
    font:bold ${LITERAL_CHAR_SIZE}px monospace;
    text-anchor:middle;
    }

svg.rrd rect.parser {
        stroke-width:${PATH_WIDTH};
        stroke:black;
        fill:hsl(120,100%,90%);
        }

svg.rrd text.parser {
        font:italic ${RULE_CHAR_SIZE}px monospace;
        text-anchor:middle;
        }