A simple multi-format pretty-printer for Menhir.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
docs
misc
src
tests
.gitignore
.merlin
.travis.yml
LICENSE
Makefile
README.md
infos.env
myocamlbuild.ml
opam
opam.in
travis.in

README.md

Obelisk Build Status Mentioned in Awesome OCaml

Obelisk is a simple tool which produces pretty-printed output from a Menhir parser file (.mly).

It is inspired from yacc2latex and is also written in OCaml, but is aimed at supporting features from Menhir instead of only those of ocamlyacc.

The code is documented.

Table of Contents

Installation

Dependencies

  • OCaml
  • OCamlbuild
  • Menhir

The Makefile also uses imagemagick and wkhtmltopdf to build documentation images.

OPAM

If you use OPAM, just type:

opam install obelisk

Manual installation

Just git clone to clone the Obelisk repository, then type:

make

This will provide you with a obelisk executable which you can feed .mly files with.

If you want to install obelisk, you can type:

make install BINDIR=<the destination directory>

Usage

obelisk [latex|html] [options] <files>

If multiple files are specified, Obelisk will output a concatenated result, without consistency checks, so the user is responsible for avoiding eg. name clashes between the several files.

By default Obelisk defaults to standard output, use -o <file> to specify an output file.

Pattern recognition

Obelisk can infer some common patterns (possibly parameterized):

  • options
  • lists and non-empty lists
  • separated lists and non-empty separated lists

Once recognized, if the -i switch is specified the rules are deleted and their instances are replaced with default constructions (eg. _*, _+, [_]). Without the -i flag, only the productions of the recognized rules are replaced, the total amount of rules remaining the same.

For example, on these simple rules (from this file):

my_option(X, Y):
  |     {}
  | Y X {}

my_list(A):
  |              {}
  | A my_list(A) {}

my_nonempty_list(C):
  | C                     {}
  | C my_nonempty_list(C) {}

my_separated_nonempty_list(X,Y):
  | X                                   {}
  | X Y my_separated_nonempty_list(X,Y) {}

my_separated_list(X,S):
  |                                 {}
  | my_separated_nonempty_list(X,S) {}

my_rule(E,F,S1,S2):
  | my_option(E, F)                    {}
  | my_list(E)                         {}
  | my_nonempty_list(F)                {}
  | my_separated_nonempty_list(E,S1)   {}
  | my_separated_list(F,S2)            {}

Obelisk outputs:

<my_option(X, Y)> ::= [Y X]

<my_list(A)> ::= A*

<my_nonempty_list(C)> ::= C+

<my_separated_nonempty_list(X, Y)> ::= X (Y X)*

<my_separated_list(X, S)> ::= [X (S X)*]

<my_rule(E, F, S1, S2)> ::= <my_option(E, F)>
                          | <my_list(E)>
                          | <my_nonempty_list(F)>
                          | <my_separated_nonempty_list(E, S1)>
                          | <my_separated_list(F, S2)>

And with the -i switch:

<my_rule(E, F, S1, S2)> ::= [F E]
                          | E*
                          | F+
                          | E (S1 E)*
                          | [F (S2 F)*]

Multi-format output

By default the output format is a simple text format close to the BNF syntax. You can use the subcommands latex or html to get a LaTeX (resp. HTML) file.

LaTeX

Use the following options to tweak the LaTeX:

  • -tabular: a tabular-based format from the tabu package (default)
  • -syntax: use the syntax package
  • -backnaur: use the backnaur package (not recommended: manual line-wrapping through this trick)

In either cases, the output may be customized via the use of LaTeX commands that you can redefine to fit your needs. The commands names are auto-generated from the terminal names, and because of LaTeX limitations, underscore are removed and numbers are converted into their roman form.

By default in LaTeX mode, the -o <grammar.tex> switch will produce the standalone LaTeX file <grammar.tex> which you can directly compile (eg. with pdflatex).

But in conjunction with -o <grammar.tex>, you can use -package <definitions> to output two files:

  1. a LaTeX file <grammar.tex> containing only the grammar contents ;
  2. a package file <definitions.sty> (the .sty extension is added automatically) containing the necessary extra packages requirements and command definitions.

These two files are then intended to be included in a non-supplied main LaTeX file following this example skeleton:

\documentclass[preview]{standalone}

\usepackage{definitions}

\begin{document}

\include{grammar}

\end{document}

To avoid name clashes, in particular when using the -package option and eg. importing multiple grammars with the same LaTeX commands names, or in the case where one of the syntax construction name matches one already defined LaTeX macro, you can specify a common prefix for the commands with the option -prefix <myprefix>.

As end-beginning commands are forbidden in LaTeX, commands creating from rules with names beginning with end are automatically prefixed with zzz.

HTML

The HTML file uses internal CSS stylesheet which allows one to customize the output (in a poorer way than in the latex mode).

Example

Here are the different formats output obtained by Obelisk from its own parser.

Default

<specification> ::= <rule>* EOF

<rule> ::= [<flags>] <ident> ATTRIBUTE* <parameters(<ident>)> COLON
           <optional_bar> <group> (BAR <group>)*

<flags> ::= PUBLIC
          | INLINE
          | PUBLIC INLINE
          | INLINE PUBLIC

<optional_bar> ::= [BAR]

<group> ::= <production> (BAR <production>)* ACTION [<precedence>]

<production> ::= <producer>* [<precedence>]

<producer> ::= [LID EQ] <actual> ATTRIBUTE*

<generic_actual(A, B)> ::= <ident> <parameters(A)>
                         | B <modifier>

<actual> ::= <generic_actual(<lax_actual>, <actual>)>

<lax_actual> ::= <generic_actual(<lax_actual>, <actual>)>
               | <group> (BAR <group>)*

<modifier> ::= OPT
             | PLUS
             | STAR

<precedence> ::= PREC <ident>

<parameters(X)> ::= [LPAR [X (COMMA X)*] RPAR]

<ident> ::= UID
          | LID

LaTeX

Tabular

Tabular

Syntax

Syntax

Backnaur

Backnaur

HTML

HTML