Commit e81e3149 authored by POTTIER Francois's avatar POTTIER Francois
Browse files

Saved and published documentation for release 20200121.

parent d7aee078
Pipeline #114920 passed with stages
in 25 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 20190924)
(version 20200121)
</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 20190924)</h1><h3 class="titlerest">François Pottier and Yann Régis-Gianas<br>
(version 20200121)</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-->
......@@ -2927,7 +2927,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">ocamlbuild</span> or <span style="font-family:monospace">dune</span>.</p>
about Menhir, such as <span style="font-family:monospace">dune</span> (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
......@@ -3018,29 +3018,21 @@ help message and terminate with a nonzero exit code.</p>
compilation flags should be passed to the OCaml compiler and linker.</p><p><span style="font-family:monospace">--suggest-comp-flags</span>.  This switch causes Menhir to print a set of
suggested compilation flags, and exit. These flags are intended to be passed
to the OCaml compilers (<span style="font-family:monospace">ocamlc</span> or <span style="font-family:monospace">ocamlopt</span>) when compiling and linking the
parser generated by Menhir. What are these flags? In the absence of the
<span style="font-family:monospace">--table</span> switch, they are empty. When <span style="font-family:monospace">--table</span> is set, these flags ensure that
<span style="font-family:monospace">MenhirLib</span> is visible to the OCaml compiler. If the support library
<span style="font-family:monospace">MenhirLib</span> was installed via <span style="font-family:monospace">ocamlfind</span>, a <span style="font-family:monospace">-package</span> directive is
issued; otherwise, a <span style="font-family:monospace">-I</span> directive is used.
</p><p><span style="font-family:monospace">--suggest-link-flags-byte</span>.  This switch causes Menhir to print a set of
parser generated by Menhir. What flags are suggested? In the absence of the
<span style="font-family:monospace">--table</span> switch, no flags are suggested. When <span style="font-family:monospace">--table</span> is set, a <span style="font-family:monospace">-I</span>
flag is suggested, so as to ensure that <span style="font-family:monospace">MenhirLib</span> is visible to the OCaml compiler.</p><p><span style="font-family:monospace">--suggest-link-flags-byte</span>.  This switch causes Menhir to print a set of
suggested link flags, and exit. These flags are intended to be passed to
<span style="font-family:monospace">ocamlc</span> when producing a bytecode executable. What are these flags? In
the absence of the <span style="font-family:monospace">--table</span> switch, they are empty. When <span style="font-family:monospace">--table</span> is set, these
flags ensure that <span style="font-family:monospace">MenhirLib</span> is linked in. If the support library <span style="font-family:monospace">MenhirLib</span> was installed via <span style="font-family:monospace">ocamlfind</span>, a <span style="font-family:monospace">-linkpkg</span> directive is issued;
otherwise, the object file <span style="font-family:monospace">menhirLib.cmo</span> is named.
</p><p><span style="font-family:monospace">--suggest-link-flags-opt</span>.  This switch causes Menhir to print a set of
<span style="font-family:monospace">ocamlc</span> when producing a bytecode executable. What flags are
suggested? In the absence of the <span style="font-family:monospace">--table</span> switch, no flags are suggested. When
<span style="font-family:monospace">--table</span> is set, the object file <span style="font-family:monospace">menhirLib.cmo</span> is suggested, so as to
ensure that <span style="font-family:monospace">MenhirLib</span> is linked in.</p><p><span style="font-family:monospace">--suggest-link-flags-opt</span>.  This switch causes Menhir to print a set of
suggested link flags, and exit. These flags are intended to be passed to
<span style="font-family:monospace">ocamlopt</span> when producing a native code executable. What are these
flags? In the absence of the <span style="font-family:monospace">--table</span> switch, they are empty. When <span style="font-family:monospace">--table</span> is
set, these flags ensure that <span style="font-family:monospace">MenhirLib</span> is linked in. If the support library
<span style="font-family:monospace">MenhirLib</span> was installed via <span style="font-family:monospace">ocamlfind</span>, a <span style="font-family:monospace">-linkpkg</span> directive is
issued; otherwise, the object file <span style="font-family:monospace">menhirLib.cmx</span> is named.
</p><p><span style="font-family:monospace">--suggest-menhirLib</span>.  This switch causes Menhir to print (the
absolute path of) the directory where <span style="font-family:monospace">MenhirLib</span> was installed. If <span style="font-family:monospace">MenhirLib</span> was installed via <span style="font-family:monospace">ocamlfind</span>, this is equivalent to calling <span style="font-family:monospace">ocamlfind
query menhirLib</span>.</p><p><span style="font-family:monospace">--suggest-ocamlfind</span>.  This switch causes Menhir to print a Boolean
value (i.e., either <span style="font-family:monospace">true</span> or <span style="font-family:monospace">false</span>), which indicates whether
<span style="font-family:monospace">MenhirLib</span> was installed via <span style="font-family:monospace">ocamlfind</span>.</p>
<span style="font-family:monospace">ocamlopt</span> when producing a native code executable. What flags are
suggested? In the absence of the <span style="font-family:monospace">--table</span> switch, no flags are suggested. When
<span style="font-family:monospace">--table</span> is set, the object file <span style="font-family:monospace">menhirLib.cmx</span> is suggested, so as to
ensure that <span style="font-family:monospace">MenhirLib</span> is linked in.</p><p><span style="font-family:monospace">--suggest-menhirLib</span>.  This switch causes Menhir to print (the
absolute path of) the directory where <span style="font-family:monospace">MenhirLib</span> was installed.</p><p><span style="font-family:monospace">--suggest-ocamlfind</span>.  This switch is deprecated and may be removed in
the future. It always prints <span style="font-family:monospace">false</span>.</p>
<!--TOC section id="sec88" Comparison with <span style="font-family:monospace">ocamlyacc</span>-->
<h2 id="sec88" class="section">15  Comparison with <span style="font-family:monospace">ocamlyacc</span></h2><!--SEC END --><p>Roughly speaking, Menhir is 90% compatible with <span style="font-family:monospace">ocamlyacc</span>. Legacy <span style="font-family:monospace">ocamlyacc</span> grammar specifications are accepted and compiled by Menhir. The resulting
parsers run and produce correct parse trees. However, parsers that explicitly
......@@ -3101,9 +3093,10 @@ 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">ocamlbuild</span> or <span style="font-family:monospace">dune</span>.</p><p><br>
with built-in support for Menhir, such as <span style="font-family:monospace">dune</span> (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-ocamlfind -use-menhir</code> to <span style="font-family:monospace">ocamlbuild</span>.
Pass <code>-use-menhir</code> to <span style="font-family:monospace">ocamlbuild</span>.
To pass options to Menhir,
pass <code>-menhir "menhir &lt;options&gt;"</code> to <span style="font-family:monospace">ocamlbuild</span>.
To use Menhir’s table-based back-end,
......@@ -3116,7 +3109,9 @@ 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.</p><p><br>
See the <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos"><span style="font-family:monospace">demos</span></a> directory 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
or newer, as it has appropriate built-in rules for Menhir parsers. In the
simplest scenario, where the parser resides in a single source
......@@ -3134,7 +3129,9 @@ instead, write <span style="font-family:monospace">(infer true)</span> or <span
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.
For more details, see
<a href="https://jbuilder.readthedocs.io/en/latest/menhir.html"><span style="font-family:monospace">dune</span>’s documentation</a>.</p><p><br>
<a href="https://jbuilder.readthedocs.io/en/latest/menhir.html"><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>
<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

4.33 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

4.14 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

5.14 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