Category Archives: railroad diagrams

JMESPath is represented using Railroad diagrams

31 Monday Oct 2022

Posted by in development, General, railroad diagrams, Technology

≈ Leave a comment

Tags

, , , , , ,

JMESPath is a mature syntax for traversing and manipulating JSON objects. The syntax is also supported with multiple language implementations available through GitHub (and other implementations exist). As a result, it has been very widely adopted; just a few examples include:

  • Azure CLI
  • AWS CLI and Lambda
  • Oracle Cloud WAF
  • Splunk

As the syntax is very flexible and recursive in its use following the documented notation can be a little tricky to start with. So following the syntax can be rather tricky. The complete definition runs to 97 lines, of which 32 lines focus on the syntactical structure. The others describe the base types such as numbers, characters, accepted escaped characters, and so on. Nothing wrong with this, as the exhaustive definition is necessary to build parsers. But for the majority of the time it is those 32 lines that we need to understand.

As the expression goes – ‘a picture says a thousand words’, there might not be a thousand words, but there is enough to suggest a visual representation will help. Even if the visual only helps us traverse the use of the detailed syntax. So we’ve use our favoured visual representation – the railroad diagram and the tool produced by Tab Akins to create the representation. We’ve put the code and created images for the syntax in my GitHub repository here, continuing the pattern previously adopted.

Here is the resulting diagram …

To make it easy to trace back to the original syntax document we’ve included groupings on the diagram that have names from the original speciofication.

Parts of the diagram make the expressions look rather simple, but you’ll note that it is possible for the sections to be iterative which allows for the expression to traverse a JSON object of undefined depth. But what can be really challenging is that an in many areas it is possible to nest expressions within expressions. Visually there is no simple way to represent the expression possibilities of this in a linear manner. Other than be clear about where the nesting can take place.

Interpreting Railroad diagrams

16 Friday Sep 2022

Posted by in General, railroad diagrams, Technology

≈ Leave a comment

Tags

, , , ,

Having previously blogged about being a fan of Railroad diagrams (here) as a means to communicate language syntax, I have been asked about some of the ways details should be represented. I’ve looked around and not actually found an easy-to-read for ‘newbies’ guide to reading railroad diagrams. A lot of content either focuses on the generator tools or how the representation compares to BNF (Backus Naur Form) – all very distracting. So, I thought as an advocate, I should help address the gap (the documentation with TabAkins tool does a good job of explaining things, but its focus is on the features provided rather than understanding the notation).

Reading Railroad Diagrams

The following table provides all the information to help you interpret the Railroad Diagrams, and create syntax representations.

  • If you’re only interested in understanding the notation, read just the first two columns.
  • If you want to see examples of how to create the diagram, then the 3rd column will help.

Note: Clicking on the diagrams will result in a bigger version of the image being displayed.

How to Interpret the RailroadRailroad RepresentationCode using tabakins tool
The start and end of an expression are shown with vertical bars.
The expression is read from left to right following a path defined by the line(s).		Diagram(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Terminal(' mp3monster '),
Terminal(' blog ')
)
Larger diagrams may need to be read both across and down the page to make it sensibly fit a page like this.Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Terminal(' mp3monster '),
Terminal(' blog '))
)
We can differentiate between literal values and ‘variables’ by shape. A square shape should denote a variable, and a lozenge represents a literal.
I have to admit to sometimes getting these the wrong way around, but as long as the notation is used consistently in an expression, it isn’t too critical. In this example, we have replaced mp3monster with the name of a variable called domain-name. So if I set the variable domain-name = mp3monster then I’d read the same result.		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
NonTerminal(' domain-name'),
Terminal(' blog '))
)
We can make parts of an expression optional. This can be seen by following an alternate path around the optional element.
In this case, we’ve made the domain-name optional. Assuming domain-name = mp3monster, we could get either:
– This is a mp3monster blog OR
– This is a blog		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Optional(
NonTerminal(' domain-name')),
Terminal(' blog '))
)
We can represent optionality by having the flow split to multiple values. Those values could be either literal values or variables. In this case, we now have several possible names in the blog with the choices being mp3monster, phil-wilkins, cloud-native, or the contents of the variable domain-name. So the expression here could resolve to (assuming domain-name = something-else):
– This is a mp3monster blog OR
– This is a phil-wilkins blog OR
– This is a cloud-native blog OR
– This is a something-else blog
It is typical for the option most likely to be selected to be the value that is directly in line with the choice. Here that would mean the default would be phil-wilkins		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
Choice(1,
' mp3monster',
' phil-wilkins ',
' cloud-native ',
NonTerminal('domain-name')),
Terminal(' blog '))
)
We can have variations on a choice where we can express the choice as being any of the options (one or more e.g. mp3monster and cloud-native) or all of the choices. These scenarios are differentiated by the additional symbols before and after the choice.
Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
MultipleChoice(1,
'any',' mp3monster',
' phil-wilkins ',
' cloud-native ',
NonTerminal('domain-name')),
Terminal(' blog '))
)
We can represent the looping with the inclusion of an additional literal(s) or variable(s) by having a second line from the right (exit) of a literal or variable and flowing back into the left (entry) of a literal or variable. Then in the loop of the flow below are the variable(s) or literal(s) that go around between each occurrence of the loop. If our variable was a list now i.e. domain-name = [‘ mp3monster’, ‘cloud-native’] then this would resolve to :
This is a mp3monster and cloud-native blog		Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),
OneOrMore(
NonTerminal('domain-name'),
[' and '])),
Terminal(' blog ')
)
We can group literals and variables together with a label. These groupings are denoted with a dashed line and usually include some sort of label. In our example, we’ve grouped two literal values together and called that group the blog name.Diagram( Stack(
Terminal('This '),
Terminal(' is '),
Terminal(' a '),),
Group(Sequence(
Terminal(' mp3monster '),
Terminal(' blog ')),
['blog name'])
)

All of these constructs can be combined so you can do things like making choices optional, and iterate over multiple variables and literals.

Tips & Tricks to Consider

TipsRailroad RepresentationCode using tabakins tool
Sometimes the number of options in a choice can get impractically large to show in a Railroad diagram. One way to overcome this is to show the first and last options and an ellipsis.
We can then wrap it with a comment that directs the reader to the complete list of choices.
This way the diagram continues to be readable – the most valuable part of the diagram and easy to locate the specific fine details.		Diagram( Stack(
Terminal(‘This ‘),
Terminal(‘ is ‘),
Terminal(‘ a ‘),
Group(Choice(1,
‘ mp3monster’,
‘ … ‘,
‘ cloud-native ‘), [‘ See Section X for full list’]),
Terminal(‘ blog ‘))
)

Railroad diagram for OCI Policies

01 Friday Jul 2022

Posted by in General, Oracle, railroad diagrams, Technology

≈ 1 Comment

Tags

, , , , ,

I’ve been a fan of Railroad syntax diagrams for a long time. I’ve always found them an easy way to understand the syntactical options and the reserved/keywords in an efficient manner.

Example of Railroad Syntax diagram

I have been digging around in the documentation to find a keyword in the OCI Policies syntax that the common cases don’t use. After a bit of rooting around, I found what I needed. But a Railroad representation would have helped me get the expression correct effortlessly and without so much effort.

The policy documentation can be found at:

Once I solved my problem, I decided to see if I could find something that could easily create the railroad diagrams and encountered a fantastic bit of code on GitHub from Tab Atkins Jr. It’s a neat bit of JavaScript, which can even be run from their GitHub pages – go here. Tab has taken the time to document the tool well, so working out the syntax to define the diagram is straightforward (not that you need to read it much as the tool is well written).

The following diagrams show the syntax for writing OCI Policies in a single image and with the full syntax broken into 2 images to make it a little easier to read on the screen. But also address the fact often you don’t need the Where clause.

If the diagrams need to be updated the source to use with the tools is in my GitHub repository. But a really cool feature of the utility is that the information to populate the editor view is included in the URL (does make for a long URL) but it means this link will take you directly to the view & editor if you want to tinker with the definition. So the links are:

Single diagram View

OCI Policies syntax

Split (2 Part) View

1st part of the expression – not optional
2nd Part covers the Where clause