The CC0 license can “weaken patent infringement defenses available to users of software released under CC0” https://opensource.org/faq#cc-zero

The affirmers may not have “all the necessary rights to grant permission to use the CC0’d work” https://wiki.creativecommons.org/wiki/CC0_FAQ#How_can_I_be_sure_that_I_have_all_the_rights_I_need_to_use_the_work.3F

I wonder if MIT or another top-5 OSI approved license could help in easing the legal worries in adopters.

Rendering an SVG image generated by the Python port of railroad-diagrams, using librsvg causes this error:

gi.repository.GLib.Error: rsvg-error-quark: Error domain 1 code 9 on line 32 column 158 of data: xmlParseCharRef: invalid xmlChar value 0
 (0)

The file, at this point, contains:

     370  3d 22 32 30 22 3e 3c 2f  72 65 63 74 3e 3c 74 65  ="20"></rect><te
     380  78 74 20 78 3d 22 37 34  2e 32 35 22 20 79 3d 22  xt x="74.25" y="
     390  33 35 22 3e 26 23 39 31  2d 39 26 23 39 33 3c 2f  35">&#91-9&#93</                                   
     3a0  74 65 78 74 3e 3c 2f 67  3e 3c 70 61 74 68 20 64  text></g><path d                                   

or, in pain text:
<text x="74.25" y="35">&#91-9&#93</text>
which I suspect is missing the ';' after the entities (at least I suspect the entity syntax is the same as HTML's).

railroads.py, on line 22:
..., lambda c: "&#{0}".format(ord(c.group(0))), unicode(text))
seems to lack the ';' (I had to remove the initial characters of the line to avoid Markdown issues)

No expert in SVG - less in parsing. Am I correct here?

railroad.svg.txt

We packagers find git tags very convenient for fetching release versions from GitHub. Could you please create and push tags corresponding to releases (or at least the most recent release)?

I've got a pretty complicated "syntax grammar" made up of a whole bunch of railroad diagrams (25 of them!). I'm using the Python version of railroad-diagrams to generate all the diagrams in SVG format which I then display on an autogenerated HTML page.

Some of the "tokens" are keywords with no arguments, some of them are keywords which take a single numeric argument, some of them are keywords which take a single-word argument, and some of them are keywords which take a double-quoted string argument.
Currently, I differentiate between these different types with e.g.:

Terminal('high')

Sequence(Terminal('count'), NonTerminal('count_number'))

Sequence(Terminal('name'), NonTerminal('name_string'))

Sequence(Terminal('description'), NonTerminal('"description_string"'))

This all works fine, but I was wondering if it would be possible for the NonTerminal and Terminal objects to have an optional background_colour= parameter, so that I could give each of these different "types" of keywords / arguments a different background colour (rather than just the default light green), to make them easier to differentiate?

I didn't design this grammar, I "inherited" it on a big project, and I'm using railroad-diagrams to help me reverse-engineer the syntax and fully document it. Thanks for such a useful project 👍

Currently each item in a "Choice" is always centered. I'd like the option to left justify the items. Sometimes left justification makes the syntax easier to understand.

Below is an example. The first image is generated by "railroad-diagrams" (with some additional coloring). The second is a photoshopped example of the same SVG with the "Choice" items left justified.

Image 1

Image 2

When entering ` backtick characters into the terminals the SVG output in Chrome doesn't render completely (I didn't test any other browsers).

Replacing the backtick with ` in the SVG output works however entering that into the terminal comes out as a literal ` rather than the backtick.

Using the Python port, if you use a Stack(...), the path doesn't connect to the next DiagramItem in the sequence (such as the End). This is because the next path is pushed down farther than it should be.

This is a really simple bug, len(self.items) just needs to be len(self.items) - 1 to match the JS version. PR for this coming in a second.

The example file contains a bunch of <script> element, each with Diagram(…).addTo();. This suggests that the diagram will be added at the "current position", just after the <script> element. But this is not the case: addTo() default to something like document.body.appendChild(…).

A test case:

<!DOCTYPE html>
<body>
  <p>
    a
    <script>
      var el = document.createElement("span");
      el.textContent = 'b';
      document.body.appendChild(el);
    </script>
    c
  </p>
  <p>
    d
  </p>
</body>

Here, the span element is appended to body, after the child of <body> that is being parsed. (The paragraph, here.) The final DOM order is a c b d. Is it possible in JS to get the <script> element being executed? The goal is to append just after that, so that the DOM order becomes a b c d.

It appears that the manifest is missing at least one file necessary to build
from the sdist for version 1.0.3. You're in good company, about 5% of other
projects updated in the last year are also missing files.

+ /tmp/venv/bin/pip3 wheel --no-binary railroad-diagrams -w /tmp/ext railroad-diagrams==1.0.3
Looking in indexes: http://10.10.0.139:9191/root/pypi/+simple/
Collecting railroad-diagrams==1.0.3
  Downloading http://10.10.0.139:9191/root/pypi/%2Bf/342/d1b9e4bfc335d/railroad-diagrams-1.0.3.tar.gz (19 kB)
    ERROR: Command errored out with exit status 1:
     command: /tmp/venv/bin/python3 -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'/tmp/pip-wheel-6_btpu_e/railroad-diagrams/setup.py'"'"'; __file__='"'"'/tmp/pip-wheel-6_btpu_e/railroad-diagrams/setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();exec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base /tmp/pip-wheel-6_btpu_e/railroad-diagrams/pip-egg-info
         cwd: /tmp/pip-wheel-6_btpu_e/railroad-diagrams/
    Complete output (5 lines):
    Traceback (most recent call last):
      File "<string>", line 1, in <module>
      File "/tmp/pip-wheel-6_btpu_e/railroad-diagrams/setup.py", line 3, in <module>
        with open("README-py.md", "r") as fh:
    FileNotFoundError: [Errno 2] No such file or directory: 'README-py.md'
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.

Allow setting SVG title(ref) for Terminal and NonTerminal elements. This would show the title as a tooltip for the elements.

eg.
Terminal(text, href, title)
where title is optional

Would be very nice if the python library could be put on Python Package Index (PYPI) for usual method of downloading modules and including in other applications.

It looks like Group() was added to railroad.js, but not railroad-diagrams.js.

Hi,
Is it possible to publish the latest version of railroad-diagrams to npm?

On npm version 1.0.0, the NonTerminal function is

function NonTerminal(text)

however in the git repository it is

function NonTerminal(text, href)

Hi Tab,
Love the diagrams, thanks for porting to Python.
There seems to be an anomaly when drawing OptionalSequence containers where there's a break in the main line which grows the more items you have in the sequence.

I have tried to find out why it's happening to see if I could fix it and contribute the fix, but the logic in the .format() method (where I think it might be happening) is beyond my capability to track I'm afraid. I think the value of the x coordinate is getting out of step with the width of the items somewhere in there but I can't see through all the needsSpace, itemSpace, itemWidth and AR adjustments to work it out.

I don't know if you're still interested in this project but I thought I'd mention it to see if you can fix it or perhaps point me in the right direction. It may be something in my environment I guess but I would have thought that would cause problems with the other containers, and I haven't seen any of that.

I've attached an image of the Chrome rendering python generated by:
Diagram(
OptionalSequence(
"Optional", "Optional",
"Optional",
),
)

Plus, the svg code snipped from the html page and the same from the js generator web page.
os_from_generator.txt
os_from_python.txt

Cheers,
IP

I am not a JS dev by nature, and only understand basic functions.

How to actually pass options like DIAGRAM_CLASS?

Diagram(
Terminal("Default Job","FLOW-COM-JOB1-147"),
Terminal("App 1","FLOW-COM-APP1-147"),
options={DIAGRAM_CLASS:"foo"}
).addTo();

Diagram({items:[
Terminal("Default Job","FLOW-COM-JOB1-147"),
Terminal("App 1","FLOW-COM-APP1-147")
],

options:[DIAGRAM_CLASS:"foo"]
).addTo();

For both a11y purposes and just general usefulness, would be good to be able to generate ABNF out of a diagram, and to automatically include that ABNF in a <title> in the diagram.

The following JS piece of code, on execution, fails:

window.setTimeout(function () {
    var strict = Optional(Terminal("strict"));
    var graph = Choice(Terminal("graph"), Terminal("digraph"));
    var id = Optional(NonTerminal("ID"));
    var stmtList = NonTerminal("stmt_list");
    var seq = Sequence(strict, graph, id, Terminal("{"), stmtList, Terminal("}"));  
    var o = Diagram(seq);
    o.addTo(window.document.body);
}, 1000);

And, this other one (is an equivalent of the preceding) also:

Diagram(
    Sequence(
        Optional(Terminal("strict")),
        Choice(Terminal("graph"), Terminal("digraph")),
        Optional(NonTerminal("ID")),
        Terminal("{"),
        NonTerminal("stmt_list"),
        Terminal("}")))
.addTo();   

Error details:

Message:
    Uncaught TypeError: Cannot read property 'format' of undefined 
File:
    railroad-diagrams.js
Line:
    291

I try to learn by run the script on jSFiddle: https://jsfiddle.net/chetabahana/a9dxv3fb/5/

Diagram is not show up whereas it is ok on generator page as well the example from the forked repo.

Would you please advise what I have been missing?

Each of the railroad diagrams on http://json.org/ has a 'label' or 'title' above the start of the railroad diagram. For example, the first railroad diagram is labelled 'object'.

Please either document how to add those labels to the diagram or (preferably) provide a way to specify the diagram's label, maybe as an optional extra parameter to the Diagram function.

Originally reported in speced/bikeshed#1184.

It's currently hard to express the concept of "an alternating sequence of two nodes, which can start and end with either node". You can get close with a Plus(MultipleChoice("all", ...)) node, but it doesn't express the same constraints (it allows the same node to be adjacent to itself, if it's the end of one repetition and the beginning of the next). The only ways to express it correctly with the existing constructs are hard to read and write, and require duplicating one of the nodes at least 3 times.

This seems like a useful and common sort of construct, and should be easier to express.

Suggested rendering:

It would be helpful to people like me who do not work with JavaScript and CSS on a daily basis if you could show the code that is used to generate the images in the README.md.

It would be great to add a new container, Group(child, label), allowing to render Regular expression groups, as in the following diagram for the RegExp /a(b)*c/:

For diagrams not about regexps, it may be used to comment parts of the diagram.

It would be great that the label had the same width as the box, and that there both label and box had classes, for easy styling.

Hello,

the following diagram description:

Diagram(
  ZeroOrMore(
    NonTerminal('DucumentLine')
  )
)

generates an incorrect diagram:

A star rule (zero-or-more) has only two paths not three:

Alternately, you can call ComplexDiagram(); it's identical to Diagram(), but has slightly different start/end shapes, same as what JSON.org does to distinguish between "leaf" types like number (ordinary Diagram()) and "container" types like Array (ComplexDiagram()).

I think on json.org the different start/end shapes indicate what are valid start symbols. They are used for value too by now.

My sincere apologies if this isn't an actual issue. I can not figure out how to accomplish the following branching logic based on the documentation provided in the README:

|-Promise--then-----------------|
         \     \             /
          \     throw---catch
           \__________/

Any help appreciated.

Whilst messing about with railroad-diagrams I ended doing a diagram essentially for the regex (A B? C?)+
When the components of the regex are Stack()ed everything seems fine, when not stacked C is missing.
The regex (A B? C?) renders as I would expect in both cases. HTML illustrating this below:

<!DOCTYPE html>
<style>
body {
    background-color: hsl(30,20%, 95%);
}
h1 {
    font-family: sans-serif;
    font-size: 1em;
}
script {
    display: none;
    white-space: pre;
    margin-top: -1em;
}
</style>
<link rel='stylesheet' href='railroad-diagrams.css'>
<script src='railroad-diagrams.js'></script>
<title>bug?</title><body>
<h2><pre>(A B? C?)+</pre></h2>

<p>stacked </p>
<script>
Diagram(
    OneOrMore
    (
        Stack
        (
            NonTerminal('A'),
            Optional
            (
                NonTerminal('B')
            ), 
            Optional
            (
                NonTerminal('C')
            )
        )
    )
).addTo();
</script>

<p>not stacked. huh?</p>
<script>
Diagram(
    OneOrMore
    (
        NonTerminal('A'),
        Optional
        (
            NonTerminal('B')
        ), 
        Optional
        (
            NonTerminal('C')
        )
    )
).addTo();
</script>

<hr>

<h2><pre>A B? C?</pre></h2>

<p>stacked </p>
<script>
Diagram(
    NonTerminal('A'),
    Optional
    (
        NonTerminal('B')
    ), 
    Optional
    (
        NonTerminal('C')
    )
).addTo();
</script>

<p>not stacked. fine.</p>
<script>
Diagram(
    Stack(
        NonTerminal('A'),
        Optional
        (
            NonTerminal('B')
        ), 
        Optional
        (
            NonTerminal('C')
        )
    )
).addTo();
</script>

</body>
</html>

Please advise.

Might be useful to allow generating a standalone SVG document - #35 requested it. Right now I just generate an <svg> suitable for inserting into an HTML doc.

Just need to output the <svg> with the right namespace decls, and inline the style.

I’m working on a Python port of this, to use in Bikeshed. I’d like to use node.js for testing (comparing the output of the two implementations), which currently fails because window is undefined.

It would be nice to use some kind of "universal module" pattern, but I don’t know which flavor to pick.

In the following diagram, choice 1 & 2 are aligned while 3 is not.

Diagram.INTERNAL_ALIGNMENT = 'left';
Diagram(
  Choice(0,
    Terminal('choice 1'),
    Terminal('choice 2'),
    Sequence(
      Terminal('choice 3'),
      Terminal('and more')
    )
  )
)

Same problem with right alignment.

Maybe Sequence should not add leading and trailing paths (but only between 2 consecutive elements in a Sequence).

Hello!

I'm interested in the possibility of rendering railroad diagrams in text for use in neovim or other terminal-bound editors. Is that something that could be done with this library? Would it involve subclassing the various entities?

Cheers

Hello,

how can we visualize this type of logic:

(A & (C | D)) | (B & D)

It would look like this in railroad:

Hello, I have made an F# port to the Python version of the library. I would like to make a PR to add it to this repo, so people can use this library in .Net and see how useful it would be. If I have time, I will rework it for WebSharper :D but that is not sure yet.
Have a nice day!

Testing example.html in Safari 8.0.4 yields blank <text> elements.

There is a bug in the Python port that make things collide that shouldn’t.

https://dvcs.w3.org/hg/csswg/raw-file/4b4a27d69aa5/css-syntax/Overview.html#token-diagrams

In <number-token>, the + for scientific notation collides with the line for skipping scientific notation.

Are you aware of work to extend this library into a simple workflow diagram generator?

I've always liked railroad diagrams for their cleannes and would love to use them as a basis for simple flowchart-type process maps.

The only problem is that railroad diagrams have a couple of assumptions and clash with diagram flows:

• They assume you'll always reach a single end rather than having multiple outcomes
• They don't contemplate going "back"

Of the two the second poses a visual challenge, and probably would require being able to optionally reference individual sections to be able to point to them from other points.

Other limitations are more aesthetic (diferentiating a decision point visually, for example). And other requirements from a workflow are already covered (repetition, selection, etc.)

(This might be a feature for Bikeshed rather than for the diagram renderer.)

Many non-terminals in CSS Syntax diagrams refer to other diagrams. I’d like to have links so that eg. clicking on "escape" in the diagram shows the escape diagram.

http://dev.w3.org/csswg/css-syntax/#ident-token-diagram
http://dev.w3.org/csswg/css-syntax/#escape-diagram

Preferably, these links would be generated automatically or with minimal markup. (Maybe NT: <a>escape</a> and hooking into Bikeshed’s auto-linking?)

Commit: aaa704d

Test code:
Diagram(
OptionalSequence(
NonTerminal('TestBlock1'),
NonTerminal('TestBlock2')
)
).addTo();

Result:

Possible solution:
File: railroad-diagrams.js line: 382
Change this.width = Diagram.ARC_RADIUS*4; to this.width = Diagram.ARC_RADIUS*2;

I wanted to take the generated svgs and place them in .svg files. Putting the XML in a file an referencing it from the browser just causes a broken image icon. Additionally, trying to open the .svg file with InkScape (an open source svg editor), does open it, but everything is black and messed up. I tried comparing the generated svgs to svgs saved by InkScape and other examples I found online. It was missing an xml declaration like <?xml version="1.0" encoding="UTF-8"?> but that didn't fix the problem. Adding version="1.0" xmlns="http://www.w3.org/2000/svg" attributes to the <svg> element made the browser render them the same messed up thing as InkScape did.

Seems like there is something not quite compliant about the generated svg, but I don't know svg well enough to say what it is.

While working on a recent PR, I noticed that there was an AlternatingSequence class, but there's no mention of this in the README file. Could you add an example with a matching screenshot please? 🙂

Hi - it looks like when you retired the non-modular version of railroad-diagram.js in Jan 2022, it broke the example.html file (last updated in Feb 2018). It would be great to have that file updated. The immediate issue is that it refers to the retired versions rather than the current versions. But it also needs to be adapted to import the module appropriately.

FYI we are using it in our our project work at https://github.com/GetPoplog/Grammar

Steve

Thanks so much for this. I have wrapped it as an htmlwidget for R.

http://www.buildingwidgets.com/blog/2015/10/16/week-41-railroadr
https://github.com/timelyportfolio/railroadR

class AlternatingSequence(DiagramMultiContainer):
	def __new__(cls, *items):
		if len(items) == 2:
			return super(AlternatingSequence, cls).__new__(cls)
		else:
			raise Exception("AlternatingSequence takes exactly two arguments got " + len(items))

raises:

TypeError: can only concatenate str (not "int") to str

Last line should use "str(len(items))" (or do proper format call:

raise Exception("AlternatingSequence takes exactly two arguments got {0}".format(len(items)))

( I will try to create a PR for this myself later)

Currently choices are always vertical, but if you have an EBNF that has a choice for all 'letters' (upcase and downcase) you get a really long vertical list of elements (52 of them)

If we support horizontal choices as well, you can mix horizontal and vertical choices and make this more into a grid.

I was thinking about the following syntax:

HorizontalChoice(...children)

so without the first argument of what should be considered as the default path.

As @zcorpan noted on the Twitters: http://software.hixie.ch/utilities/js/live-dom-viewer/?saved=1746

Chrome/Firefox:

Opera:

It would be great if you could select whether to have single or doulbe lines as the begin and end indicators.
I am not completely sure but I think that the authors of json.org used this to highlight which of the non-terminals can have whitespace between the components.

With the update containing the HorizontalChoice, the online diagram generator does not work anymore

Why "ZeroOrMore", "Choice", etc. are nested JS function calls?
Why are you not implemented it as JSON (JS objects)?

I did some research and this comes from the fact Stack "returns" hide some underlying nodes.
Correction I made into the Stack.prototype.format, where I add path bit by bits instead of the full "return".
I changed

Path(x, y)
	.arc('ne').down(Math.max(0, item.down + Diagram.VERTICAL_SEPARATION - Diagram.ARC_RADIUS*2))
	.arc('es').left(innerWidth)
	.arc('nw').down(Math.max(0, this.items[i+1].up + Diagram.VERTICAL_SEPARATION - Diagram.ARC_RADIUS*2))
	.arc('ws').addTo(this);

With

var temp =y;
Path(x, y).arc('ne').down(Math.max(0, item.down + Diagram.VERTICAL_SEPARATION - Diagram.ARC_RADIUS*2)).addTo(this);
y+=Diagram.ARC_RADIUS+Math.max(0, item.down + Diagram.VERTICAL_SEPARATION - Diagram.ARC_RADIUS*2); 
x+=Diagram.ARC_RADIUS;
Path(x, y).arc('es').left(innerWidth).addTo(this);
y+=Diagram.ARC_RADIUS;x=x-innerWidth-Diagram.ARC_RADIUS;;
Path(x, y).arc('nw').down(Math.max(0, this.items[i+1].up + Diagram.VERTICAL_SEPARATION - Diagram.ARC_RADIUS*2)).addTo(this);
y+=Diagram.ARC_RADIUS+Math.max(0, this.items[i+1].up + Diagram.VERTICAL_SEPARATION - Diagram.ARC_RADIUS*2);
x=x-Diagram.ARC_RADIUS;
Path(x, y).arc('ws').addTo(this);
y = temp + Math.max(item.down + Diagram.VERTICAL_SEPARATION, Diagram.ARC_RADIUS*2) + Math.max(this.items[i+1].up + Diagram.VERTICAL_SEPARATION, Diagram.ARC_RADIUS*2);