kevinpt / syntrax

Railroad syntax diagram generator

Syntrax

Syntrax is a railroad diagram generator. It creates a visual illustration of the grammar used for programming languages. A specification file describes the syntax as a hierarchy of basic elements. This is processed into an image representing the same syntax with interconnected bubbles.

The specification is a set of nested Python function calls:

indentstack(10,
  line(opt('-'), choice('0', line('1-9', loop(None, '0-9'))),
    opt('.', loop('0-9', None))),

  line(opt(choice('e', 'E'), choice(None, '+', '-'), loop('0-9', None)))
)

This is processed by Syntrax to generate an SVG image:

JSON number syntax

Syntrax can render to PNG bitmap images or SVG, PDF, PS, and EPS vector images. The SVG output can have hyperlinked text allowing users to quickly navigate to documentation of different syntax elements.

Syntrax is a heavily modified version of the railroad diagram generator used for the SQLite documentation. The generator has been ported to Python, converted to use the Cairo rendering backend, and enhanced with configurable layout options.

Requirements

Syntrax requires either Python 2.7 or Python 3.x, Pycairo, and Pango.

The installation script depends on setuptools which will be installed if it isn't currently present in your Python distribution. The source is written in Python 2.7 syntax but will convert cleanly to Python 3 when the installer passes it through 2to3.

The Pango library is used compute the dimensions of a text layout. There is no standard package to get the Pango Python bindings installed. It is a part of the Gtk+ library which is accessed either through the PyGtk or PyGObject APIs, both of which are supported by Syntrax. You should make sure that one of these libraries is available before installing Syntrax. A Windows installer is available. For Linux distributions you should install the relevant libraries with your package manager.

Download

You can access the Syntrax Git repository from Github. You can install direct from PyPI with the "pip" command if you have it available.

Documentation

The full documentation is available online at the main Syntrax site.

syntrax's Issues

Document Python API

Users (including myself) will want to know how to generate an entire diagram from within Python. The constructor functions like loop() are documented, but it would be nice if render_railroad() were also documented.

Make the title (optional) part of the spec-file

Feature request:
Make the title (optional) part of the spec-file. Of course, it is possible to write a script, which takes the title from the filename, but not every useful attribute of a title is fine as filename. We like filenames to be short, but titles might sometimes be more verbose. If I work in an editor like Geany, I can configure it, so that it will produce a PNG when I hit the compile button, but the title has to be set manually, which makes it a less productive workflow.

The implementation might use an additional, optional key-value notation in the file, to keep all old spec files compatibel, or use an annotation in the comment section, to create a title.

Add cairo as a dependency

It seems that cairo is a hard, non-conditional dependency:

syntrax/syntrax.py

Line 16 in eecc271

import cairo

However, it's not listed as a dependency:

syntrax/setup.py

Line 33 in eecc271

install_requires = [],

Thus, simply installing and then importing syntrax gives me:

Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/tmp/tmp.GgRTr2Nt4J/venv/lib/python3.6/site-packages/syntrax.py", line 16, in <module>
    import cairo
ModuleNotFoundError: No module named 'cairo'

Multiple productions in single definition

Is it possible to define multiple graphs in a single source file? I.e., I'd like to get multiple productions in a single output file. Something like

line( '/sign', choice(None, '+', '-') ),
line( '/digit', 'test' )

and get two separate graphs in the output image.

Error on optional loops

On the following spec file:

opt(loop('A',None))

syntrax 1.0 throws:

Rendering to test.png using cairo backend
Traceback (most recent call last):
  File "/usr/local/bin/syntrax", line 11, in <module>
    load_entry_point('syntrax==1.0', 'console_scripts', 'syntrax')()
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 2028, in main
    render_railroad(spec, args.title, url_map, args.output, backend, styles, args.scale, args.transparent)
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1747, in render_railroad
    layout.draw_diagram(spec)
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1678, in draw_diagram
    return self.draw_line(spec[1:])
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1287, in draw_line
    t, texx, texy = self.draw_diagram(term) # Draw each element
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1695, in draw_diagram
    return self.draw_or([None, args])
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1604, in draw_or
    m[i] = mx = self.draw_diagram(term)
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1673, in draw_diagram
    return self.draw_bubble(spec[0])
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1206, in draw_bubble
    txt, node_style = self.format_text(txt)
  File "/usr/local/lib/python2.7/dist-packages/syntrax.py", line 1182, in format_text
    if re.match(ns.pattern, txt):
  File "/usr/lib/python2.7/re.py", line 141, in match
    return _compile(pattern, flags).match(string)
TypeError: expected string or buffer

Rounded bubble with "/" as content

Hi,

is it possible to create a rounded bubble with a slash ("/") as text?

Cheers,
Ronny

Can Syntrax be used with Sphinx?

Hello Kevin,

can Syntrax be used with Sphinx?

We are currently using Railroad Diagrams in our online documentation rendered with Sphinx on ReadTheDocs. It uses in-line JavaScript/JSON to describe the syntax diagram.

.. raw:: html

   <style>
   ddiv svg.railroad-diagram {
     width: 80%;    /* Scale to the width of the parent */
     height: 100%;  /* Preserve the ratio. Could be related to https://bugs.webkit.org/show_bug.cgi?id=82489 */
   }
   </style>
   <link rel="stylesheet" href="../../_static/css/railroad-diagrams.css" />
   <script type="text/javascript" src="../../_static/javascript/railroad-diagrams.js" ></script>

*.ini Format
############

.. raw:: html

   <div>
     <script type="text/javascript">
     ComplexDiagram(
       Choice(0,
         NonTerminal('Section'),
         Sequence(
           Choice(0,
             Sequence('#', NonTerminal('CommentText')),
             Sequence(NonTerminal('WhiteSpace'))
           ),
           Choice(0, '\\n', '\\r\\n', '\\r')
         )
       )
     ).addTo(this.parentElement);
     </script>
   </div>

GitHub: https://github.com/tabatkins/railroad-diagrams
Online editor: https://tabatkins.github.io/railroad-diagrams/generator.html

Kind regards
Patrick

Unreasonable example in documentation

On the main page, section "Toploop", there is this example:

toploop(line('(', 'forward', ')'), line(')', 'backward', '('))

which looks pretty, but it would mean, that after the forward part, with its closing brace, you close another brace, then comes the word "backward", then an opening brace.

Since the example might be completely made up, this could be valid syntax, but I guess what was meant was: toploop(line('(', 'forward', ')'), line('(', 'backward', ')')) which looks awkward in the diagram, because of our habit to read from left to right, but more reasonable.

`gi` is an unsupported dependency

Problem Statement

I was attempting to use a separate library (syntrax) and ran into the problem that gi is still using the old print statement. This isn't a problem in the larger sense. Normally when I run into projects like this I write a pull request to port the dependency to python3.

In this case, however, I discovered that gi isn't a supported package anymore and the last release was in 2014.

If you look at the gi dependency on pypi you'll find that it has a home page listed. If you look look at the project home page you'll see that the page is down and that inconditus doesn't have it listed under their repositories anymore.

I would suggest moving to a new dependency if possible. I don't know enough about this space right now to suggest an alternative but if you'd like help I can find the time later to look into it.

Error in Question

syntrax
Traceback (most recent call last):
  File "/Users/alexlord/.virtualenvs/presentations/lib/python3.6/site-packages/syntrax.py", line 20, in <module>
    import pango
ModuleNotFoundError: No module named 'pango'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/Users/alexlord/.virtualenvs/presentations/bin/syntrax", line 7, in <module>
    from syntrax import main
  File "/Users/alexlord/.virtualenvs/presentations/lib/python3.6/site-packages/syntrax.py", line 24, in <module>
    from gi.repository import Pango as pango
  File "/Users/alexlord/.virtualenvs/presentations/lib/python3.6/site-packages/gi/__init__.py", line 39
    print url
            ^
SyntaxError: Missing parentheses in call to 'print'. Did you mean print(t url)?