//////////////////////////////////////////////////////////////////////////////
// Copyright (c) 2021, 2026 Contributors to the Eclipse Foundation
//
// See the NOTICE file(s) distributed with this work for additional
// information regarding copyright ownership.
//
// This program and the accompanying materials are made available
// under the terms of the MIT License which is available at
// https://opensource.org/licenses/MIT
//
// SPDX-License-Identifier: MIT
//////////////////////////////////////////////////////////////////////////////

include::_part_attributes.asciidoc[]
include::_local_attributes.asciidoc[]

:leveloffset: -2

[[rail-examples]]
== Examples

A number of examples are provided for those that hate reading.
The input of the program is similar to EBNF with an extra feature for repetition.

=== Diagrams and sequences

[source, raildiagram]
----
include::{incdir-rail}/sequence.rr[]
----

A diagram starts with its name, a colon, the syntax that should be shown (in this case the sequence `A`, `B`, `C`), and finally, a semicolon as terminator.
This gives the following result.

image::{rail-imgsdir}/sequence.rr.png[Sequence]

As rail diagrams are read from left to right, following a line without taking a sharp turn, the resulting image is not a surprise.

=== Choices

The second primitive is choice, where you pick one of the given alternatives.
As with EBNF, this is written with the pipe symbol `|`, like:

[source, raildiagram]
----
include::{incdir-rail}/choice.rr[]
----

This results in:

image::{rail-imgsdir}/choice.rr.png[Choice]

Note that as sequence has higher priority than choice, the `B` and `C` sequence forms one alternative.
You can use parentheses to break the priority chain, e.g.:

[source, raildiagram]
----
include::{incdir-rail}/choice2.rr[]
----

This gives a sequence of choices:

image::{rail-imgsdir}/choice2.rr.png[Sequence of choice]

=== Optional

An optional part of the syntax can be described in multiple ways:

[source, raildiagram]
----
include::{incdir-rail}/optional.rr[]
----

This results in:

image::{rail-imgsdir}/optional.rr.png[Optional]

The dedicated optional syntax (`?`) is often more convenient than using the choice syntax.

=== Repetition

The core repetition primitive is alternating between two nodes:

[source, raildiagram]
----
include::{incdir-rail}/alternating.rr[]
----

This results in:

image::{rail-imgsdir}/alternating.rr.png[Alternating between A and B]

You can make one (or both) of the paths empty, which results in the normal EBNF repetition semantics.
Below, node `A` must occur at least once, while node `B` may also be skipped.

[source, raildiagram]
----
include::{incdir-rail}/emptyalternating.rr[]
----

This gives:

image::{rail-imgsdir}/emptyalternating.rr.png[A+ and B*]

The third repetition is an alternative for the `B` sequence.
It avoids the caveat with repetition due to the right-to-left visiting order of the bottom path, made more clearly visible in the following example:

[source, raildiagram]
----
include::{incdir-rail}/abcd.rr[]
----

It results in:

image::{rail-imgsdir}/abcd.rr.png[ABCD]

It describes EBNF `AB(CDAB)*`, and the tool translates it correctly, but the bottom path does not read nicely, as you have to read that part from right to left.

It is advised to avoid this case by changing the diagram.
Limit the second part of the `+` operator to one node, possibly by introducing an additional non-terminal.

=== Splitting long sequences

For rules that have a long sequence, the width of the diagram grows quickly beyond the width of the page.
The best way to deal with that is to change the diagram, for example by moving a part of the sequence to a new non-terminal.

The program however does offer a quick fix around the problem at the cost of a less readable diagram.
An example is shown below:

[source, raildiagram]
----
include::{incdir-rail}/abcdefgh.rr[]
----

This gives:

image::{rail-imgsdir}/abcdefgh.rr.png[ABCDEFGH]

The double backslash breaks the '`line`' and it continues below on the next line.
You cannot break the empty sequence, and each row must have at least one node.

=== Referencing a path in the diagram

When explaining a diagram, it can be useful to refer to a path in the diagram.
The program has a bracketed string for that:

[source, raildiagram]
----
include::{incdir-rail}/refpath.rr[]
----

image::{rail-imgsdir}/refpath.rr.png[Recursion]

Now you can say that the `[nest]` path recursively applies the rule, while the `[exit]` path ends the recursion.

=== Terminals

Until now, all names in the diagrams have a rectangular box around them which means (by default) it is a non-terminal.
The name used in the diagram input file is also the name displayed in the output.

Terminals in the diagram do not have a name, but show the concrete syntax instead.
The simplest way to write a terminal is shown in the first and second alternative.
They state the literal concrete syntax of the terminal surrounded by single or double quotes.
The third alternative introduces the internal name `OTHER` for the terminal and uses the properties file to translate the name to the actual syntax for that name.

[source, raildiagram]
----
include::{incdir-rail}/terminals.rr[]
----

Fragment of the properties file related to this diagram that says the terminal named `OTHER` should display `else` in its box:

[source, properties]
----
include::{incdir-rail}/terminals.rr.props[]
----

And the generated output is then:

image::{rail-imgsdir}/terminals.rr.png[Terminals]

=== Meta-terminals

While grammars only have terminals and non-terminals, we found use for a third form in explaining the syntax of a language.
In almost every language a few non-terminals are too trivial or too large to define precisely in a rail diagram.
Common cases include literal numbers, literal strings, and sets of names that can be used for identifiers.
Instead of defining the syntax of such a non-terminal in a diagram in full detail, the accompanying text of a diagram can define it in a few compact sentences.
Such non-terminals thus have no defining rule and also no concrete syntax.
We name these hybrid forms _meta-terminals_.

They are added in the diagram much like the third alternative above.
A name is given to it in the diagram input file, and the properties file defines the associated displayed text.
For example:

[source, raildiagram]
----
include::{incdir-rail}/meta_terminals.rr[]
----

Fragment of the properties file related to this diagram stating the displayed text should be `VariableName`:

[source, properties]
----
include::{incdir-rail}/meta_terminals.rr.props[]
----

And the generated output is then:

image::{rail-imgsdir}/meta_terminals.rr.png[Terminals]

The text around the diagram should describe the allowed syntax of `VariableName`.

Meta-terminals have a rounded box around the name indicating lack of a definition elsewhere, but use the non-terminal font for its name indicating the written name is not taken to be as the literal text.

=== Further reading

In this section a hands-on explanation was given to get started making diagrams without spending a lot of time grasping all the details.

In the <<rail-grammar>> section the grammar of the rail diagram is explained in more detail.

If default behavior is not to your liking, layout and many other settings can be overridden in a properties file, see the <<rail-customizing-output>> section for details.
