Commit 7b4aa208 authored by POTTIER Francois's avatar POTTIER Francois
Browse files

Saved and published documentation for release 20200211.

parent 056b435c
Pipeline #119780 passed with stages
in 26 seconds
This source diff could not be displayed because it is too large. You can view the blob instead.
......@@ -58,13 +58,13 @@ font-size: 1rem;
}
</style>
<title>Menhir Reference Manual
(version 20200123)
(version 20200211)
</title>
</head>
<body >
<!--HEVEA command line is: hevea -fix manual.tex -->
<!--CUT STYLE article--><!--CUT DEF section 1 --><table class="title"><tr><td style="padding:1ex"><h1 class="titlemain">Menhir Reference Manual<br>
(version 20200123)</h1><h3 class="titlerest">François Pottier and Yann Régis-Gianas<br>
(version 20200211)</h1><h3 class="titlerest">François Pottier and Yann Régis-Gianas<br>
INRIA<br>
<span style="font-family:monospace">{Francois.Pottier, Yann.Regis-Gianas}@inria.fr</span></h3></td></tr>
</table><!--TOC section id="sec1" Contents-->
......@@ -299,7 +299,8 @@ into your executable program. The <span style="font-family:monospace">--suggest-
above, help do this.</p><p>The code-based back-end compiles the LR automaton directly into a nest of
mutually recursive OCaml functions. In that case, <span style="font-family:monospace">MenhirLib</span> is not required.</p><p>The incremental API (§<a href="#sec%3Aincremental">9.2</a>) and the inspection API
<a href="#sec%3Ainspection">9.3</a>) are made available only by the table-based back-end.</p><p><span style="font-family:monospace">--timings</span>.  This switch causes internal timing information to
be sent to the standard error channel.</p><p><span style="font-family:monospace">--trace</span>.  This switch causes tracing code to be inserted into
be sent to the standard error channel.</p><p><span style="font-family:monospace">--timings-to</span> <span style="font-style:italic">filename</span>.  This switch causes internal timing
information to be written to the file <span style="font-style:italic">filename</span>.</p><p><span style="font-family:monospace">--trace</span>.  This switch causes tracing code to be inserted into
the generated parser, so that, when the parser is run, its actions are
logged to the standard error channel. This is analogous to <span style="font-family:monospace">ocamlrun</span>’s
<span style="font-family:monospace">p=1</span> parameter, except this switch must be enabled at compile time:
......@@ -784,8 +785,8 @@ The use of <span style="font-family:sans-serif"><span style="font-weight:bold"><
i.e., an <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> nonterminal symbol (see §<a href="#sec%3Ainline">5.3</a>).
The identity semantic action <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;&gt;</span></span> is here synonymous with
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>.</p><p>Other illustrations of the new syntax can be found in
the directories <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-new-syntax-dune"><span style="font-family:monospace">demos/calc-new-syntax-dune</span></a>
and <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-ast-dune"><span style="font-family:monospace">demos/calc-ast-dune</span></a>.</p>
the directories <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-new-syntax"><span style="font-family:monospace">demos/calc-new-syntax</span></a>
and <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-ast"><span style="font-family:monospace">demos/calc-ast</span></a>.</p>
<!--TOC section id="sec25" Advanced features-->
<h2 id="sec25" class="section">5  Advanced features</h2><!--SEC END -->
<!--TOC subsection id="sec26" Splitting specifications over multiple files-->
......@@ -2927,7 +2928,7 @@ OCaml type inference and its repercussions on dependency analysis
This material should be of interest only to authors of build systems
who wish to build support for Menhir into their system.
Ordinary users should skip this section and use a build system that knows
about Menhir, such as <span style="font-family:monospace">dune</span> (preferred) or <span style="font-family:monospace">ocamlbuild</span>.</p>
about Menhir, such as <a href="#dune"><span style="font-family:monospace">dune</span></a> (preferred) or <span style="font-family:monospace">ocamlbuild</span>.</p>
<!--TOC subsection id="sec83" OCaml type inference and dependency analysis-->
<h3 id="sec83" class="subsection">14.1  OCaml type inference and dependency analysis</h3><!--SEC END --><p>
<a id="sec:build:infer"></a></p><p>In an ideal world, the semantic actions in a <span style="font-family:monospace">.mly</span> file should be well-typed
......@@ -3093,7 +3094,7 @@ time spent in the lexer and in the semantic actions.</p><p><br>
<span style="font-weight:bold">How do I write </span><span style="font-weight:bold"><span style="font-family:monospace">Makefile</span></span><span style="font-weight:bold"> rules for Menhir?</span>
This can a bit tricky. If you must do this, see §<a href="#sec%3Abuild">14</a>.
It is recommended instead to use a build system
with built-in support for Menhir, such as <span style="font-family:monospace">dune</span> (preferred)
with built-in support for Menhir, such as <a href="#dune"><span style="font-family:monospace">dune</span></a> (preferred)
or <span style="font-family:monospace">ocamlbuild</span>.</p><p><br>
<span style="font-weight:bold">How do I use Menhir with </span><span style="font-weight:bold"><span style="font-family:monospace">ocamlbuild</span></span><span style="font-weight:bold">?</span>
Pass <code>-use-menhir</code> to <span style="font-family:monospace">ocamlbuild</span>.
......@@ -3109,29 +3110,40 @@ into a single parser,
say <code>parser.{ml,mli}</code>,
create a file named <code>parser.mlypack</code>
that contains the module names <code>A B</code>.
See the <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos"><span style="font-family:monospace">demos</span></a> directory for examples.
See the directory <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/ocamlbuild"><span style="font-family:monospace">demos/ocamlbuild</span></a> for examples.
To deal with <span style="font-family:monospace">.messages</span> files (§<a href="#sec%3Aerrors%3Anew">11</a>),
use the rules provided in the file <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/ocamlbuild/myocamlbuild.ml"><span style="font-family:monospace">demos/ocamlbuild/myocamlbuild.ml</span></a>.</p><p><br>
<span style="font-weight:bold">How do I use Menhir with </span><span style="font-weight:bold"><span style="font-family:monospace">dune</span></span><span style="font-weight:bold">?</span> Please use <span style="font-family:monospace">dune</span> version 1.4.0
use the rules provided in the file <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/ocamlbuild/myocamlbuild.ml"><span style="font-family:monospace">demos/ocamlbuild/myocamlbuild.ml</span></a>.</p><p><a id="dune"><br>
<span style="font-weight:bold">How do I use Menhir with </span><span style="font-weight:bold"><span style="font-family:monospace">dune</span></span><span style="font-weight:bold">?</span></a> Please use <span style="font-family:monospace">dune</span> version 1.4.0
or newer, as it has appropriate built-in rules for Menhir parsers. In the
simplest scenario, where the parser resides in a single source
file <span style="font-family:monospace">parser.mly</span>, the <span style="font-family:monospace">dune-project</span> file should contain a
“stanza” along the following lines:
</p><pre class="verbatim">(menhir (
(modules (parser))
(flags ("--explain" "--dump"))
</p><pre class="verbatim">(menhir
(modules parser)
(flags --explain --dump)
(infer true)
))
)
</pre><p>
Ordinary command line switches, like <span style="font-family:monospace">--explain</span> and <span style="font-family:monospace">--dump</span>, are passed as part
of the <span style="font-family:monospace">flags</span> line, as done above.
The <span style="font-family:monospace">--infer</span> switch has special status and should not be used directly;
instead, write <span style="font-family:monospace">(infer true)</span> or <span style="font-family:monospace">(infer false)</span>, as done above.
(The default is <span style="font-family:monospace">true</span>.) Ordinary command line switches, like <span style="font-family:monospace">--explain</span> and <span style="font-family:monospace">--dump</span>, are passed as part of the <span style="font-family:monospace">flags</span> line, as done above.
The directory <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-dune"><span style="font-family:monospace">demos/calc-dune</span></a>
offers an example.
(The default is <span style="font-family:monospace">true</span>.)
The <span style="font-family:monospace">--table</span> switch can also be listed as part of the <span style="font-family:monospace">flags</span> line; if
you do so, then you must add <span style="font-family:monospace">menhirLib</span> to the list of libraries that
your code requires, as in the following example:
</p><pre class="verbatim">(executable
(name myexecutable)
(libraries menhirLib)
)
</pre><p>
The directory <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos"><span style="font-family:monospace">demos</span></a>
offers several examples.
For more details, see
<a href="https://jbuilder.readthedocs.io/en/latest/menhir.html"><span style="font-family:monospace">dune</span>’s documentation</a>.
<a href="
https://dune.readthedocs.io/en/stable/dune-files.html#menhir"><span style="font-family:monospace">dune</span>’s documentation</a>.
To deal with <span style="font-family:monospace">.messages</span> files (§<a href="#sec%3Aerrors%3Anew">11</a>),
use and adapt the rules found in the file <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/src/stage2/dune"><span style="font-family:monospace">src/stage2/dune</span></a>.</p><p><br>
please use and adapt the rules found in the file <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/src/stage2/dune"><span style="font-family:monospace">src/stage2/dune</span></a>.</p><p><br>
<span style="font-weight:bold">Menhir reports </span><span style="font-weight:bold"><em>more</em></span><span style="font-weight:bold"> shift/reduce conflicts than
</span><span style="font-weight:bold"><span style="font-family:monospace">ocamlyacc</span></span><span style="font-weight:bold">! How come?</span> <span style="font-family:monospace">ocamlyacc</span> sometimes merges two states
of the automaton that Menhir considers distinct. This happens
......
No preview for this file type
www/doc/manual001.png

4.33 KB | W: | H:

www/doc/manual001.png

6.5 KB | W: | H:

www/doc/manual001.png
www/doc/manual001.png
www/doc/manual001.png
www/doc/manual001.png
  • 2-up
  • Swipe
  • Onion skin
www/doc/manual002.png

4.14 KB | W: | H:

www/doc/manual002.png

6.31 KB | W: | H:

www/doc/manual002.png
www/doc/manual002.png
www/doc/manual002.png
www/doc/manual002.png
  • 2-up
  • Swipe
  • Onion skin
www/doc/manual003.png

5.14 KB | W: | H:

www/doc/manual003.png

7.22 KB | W: | H:

www/doc/manual003.png
www/doc/manual003.png
www/doc/manual003.png
www/doc/manual003.png
  • 2-up
  • Swipe
  • Onion skin
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment