File: manual.html

package info (click to toggle)
menhir 20201216-1
links: PTS, VCS
area: main
in suites: bullseye
size: 4,056 kB
sloc: ml: 23,365; makefile: 181; sh: 95; lisp: 8
file content (3502 lines) | stat: -rw-r--r-- 378,479 bytes
<!DOCTYPE html>
<html >
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="generator" content="hevea 2.32">
<style type="text/css">
.li-itemize{margin:1ex 0ex;}
.li-enumerate{margin:1ex 0ex;}
.dd-description{margin:0ex 0ex 1ex 4ex;}
.dt-description{margin:0ex;}
.toc{list-style:none;}
.footnotetext{margin:0ex; padding:0ex;}
div.footnotetext P{margin:0px; text-indent:1em;}
.thefootnotes{text-align:left;margin:0ex;}
.dt-thefootnotes{margin:0em;}
.dd-thefootnotes{margin:0em 0em 0em 2em;}
.footnoterule{margin:1em auto 1em 0px;width:50%;}
.caption{padding-left:2ex; padding-right:2ex; margin-left:auto; margin-right:auto}
.title{margin:2ex auto;text-align:center}
.titlemain{margin:1ex 2ex 2ex 1ex;}
.titlerest{margin:0ex 2ex;}
.center{text-align:center;margin-left:auto;margin-right:auto;}
.flushleft{text-align:left;margin-left:0ex;margin-right:auto;}
.flushright{text-align:right;margin-left:auto;margin-right:0ex;}
div table{margin-left:inherit;margin-right:inherit;margin-bottom:2px;margin-top:2px}
td table{margin:auto;}
table{border-collapse:collapse;}
td{padding:0;}
.cellpadding1 tr td{padding:0;}
.cellpadding1 tr td{padding:1px;}
pre{text-align:left;margin-left:0ex;margin-right:auto;}
blockquote{margin-left:4ex;margin-right:4ex;text-align:left;}
td p{margin:0px;}
.boxed{border:1px solid black}
.textboxed{border:1px solid black}
.vbar{border:none;width:2px;background-color:black;}
.hbar{border:none;height:2px;width:100%;background-color:black;}
.hfill{border:none;height:1px;width:200%;background-color:black;}
.vdisplay{border-collapse:separate;border-spacing:2px;width:auto; empty-cells:show; border:2px solid red;}
.vdcell{white-space:nowrap;padding:0px; border:2px solid green;}
.display{border-collapse:separate;border-spacing:2px;width:auto; border:none;}
.dcell{white-space:nowrap;padding:0px; border:none;}
.dcenter{margin:0ex auto;}
.vdcenter{border:solid #FF8000 2px; margin:0ex auto;}
.minipage{text-align:left; margin-left:0em; margin-right:auto;}
.marginpar{border:solid thin black; width:20%; text-align:left;}
.marginparleft{float:left; margin-left:0ex; margin-right:1ex;}
.marginparright{float:right; margin-left:1ex; margin-right:0ex;}
.theorem{text-align:left;margin:1ex auto 1ex 0ex;}
.part{margin:2ex auto;text-align:center}
body{max-width:800px;
width: 85%;
margin: auto;
font-size: 1rem;
}
pre, .quote{margin-left: 2em;
font-size: 1rem;
}
</style>
<title>Menhir Reference Manual 
(version 20201216)
</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 20201216)</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-->
<h2 id="sec1" class="section">Contents</h2><!--SEC END --><ul class="toc"><li class="li-toc">
<a href="#sec2">1  Foreword</a>
</li><li class="li-toc"><a href="#sec3">2  Usage</a>
</li><li class="li-toc"><a href="#sec4">3  Lexical conventions</a>
</li><li class="li-toc"><a href="#sec5">4  Syntax of grammar specifications</a>
<ul class="toc"><li class="li-toc">
<a href="#sec6">4.1  Declarations</a>
<ul class="toc"><li class="li-toc">
<a href="#sec7">4.1.1  Headers</a>
</li><li class="li-toc"><a href="#sec8">4.1.2  Parameters</a>
</li><li class="li-toc"><a href="#sec9">4.1.3  Tokens</a>
</li><li class="li-toc"><a href="#sec10">4.1.4  Priority and associativity</a>
</li><li class="li-toc"><a href="#sec11">4.1.5  Types</a>
</li><li class="li-toc"><a href="#sec12">4.1.6  Start symbols</a>
</li><li class="li-toc"><a href="#sec13">4.1.7  Attribute declarations</a>
</li><li class="li-toc"><a href="#sec14">4.1.8  Extra reductions on error</a>
</li></ul>
</li><li class="li-toc"><a href="#sec15">4.2  Rules—old syntax</a>
<ul class="toc"><li class="li-toc">
<a href="#sec16">4.2.1  Production groups</a>
</li><li class="li-toc"><a href="#sec20">4.2.2  Productions</a>
</li><li class="li-toc"><a href="#sec21">4.2.3  Producers</a>
</li><li class="li-toc"><a href="#sec22">4.2.4  Actuals</a>
</li></ul>
</li><li class="li-toc"><a href="#sec23">4.3  Rules—new syntax</a>
</li></ul>
</li><li class="li-toc"><a href="#sec25">5  Advanced features</a>
<ul class="toc"><li class="li-toc">
<a href="#sec26">5.1  Splitting specifications over multiple files</a>
</li><li class="li-toc"><a href="#sec30">5.2  Parameterizing rules</a>
</li><li class="li-toc"><a href="#sec35">5.3  Inlining</a>
</li><li class="li-toc"><a href="#sec36">5.4  The standard library</a>
</li></ul>
</li><li class="li-toc"><a href="#sec37">6  Conflicts</a>
<ul class="toc"><li class="li-toc">
<a href="#sec38">6.1  When is a conflict benign?</a>
</li><li class="li-toc"><a href="#sec39">6.2  How are severe conflicts explained?</a>
</li><li class="li-toc"><a href="#sec45">6.3  How are severe conflicts resolved in the end?</a>
</li><li class="li-toc"><a href="#sec46">6.4  End-of-stream conflicts</a>
</li></ul>
</li><li class="li-toc"><a href="#sec50">7  Positions</a>
</li><li class="li-toc"><a href="#sec51">8  Using Menhir as an interpreter</a>
<ul class="toc"><li class="li-toc">
<a href="#sec52">8.1  Sentences</a>
</li><li class="li-toc"><a href="#sec53">8.2  Outcomes</a>
</li><li class="li-toc"><a href="#sec54">8.3  Remarks</a>
</li></ul>
</li><li class="li-toc"><a href="#sec55">9  Generated API</a>
<ul class="toc"><li class="li-toc">
<a href="#sec56">9.1  Monolithic API</a>
</li><li class="li-toc"><a href="#sec57">9.2  Incremental API</a>
<ul class="toc"><li class="li-toc">
<a href="#sec58">9.2.1  Starting the parser</a>
</li><li class="li-toc"><a href="#sec59">9.2.2  Driving the parser</a>
</li><li class="li-toc"><a href="#sec60">9.2.3  Inspecting the parser’s state</a>
</li><li class="li-toc"><a href="#sec61">9.2.4  Updating the parser’s state</a>
</li></ul>
</li><li class="li-toc"><a href="#sec62">9.3  Inspection API</a>
</li></ul>
</li><li class="li-toc"><a href="#sec63">10  Error handling: the traditional way</a>
</li><li class="li-toc"><a href="#sec67">11  Error handling: the new way</a>
<ul class="toc"><li class="li-toc">
<a href="#sec68">11.1  The <span style="font-family:monospace">.messages</span> file format</a>
</li><li class="li-toc"><a href="#sec72">11.2  Maintaining <span style="font-family:monospace">.messages</span> files</a>
</li><li class="li-toc"><a href="#sec77">11.3  Writing accurate diagnostic messages</a>
</li><li class="li-toc"><a href="#sec84">11.4  A working example</a>
</li></ul>
</li><li class="li-toc"><a href="#sec85">12  Coq back-end</a>
</li><li class="li-toc"><a href="#sec86">13  Building grammarware on top of Menhir</a>
<ul class="toc"><li class="li-toc">
<a href="#sec87">13.1  Menhir’s SDK</a>
</li><li class="li-toc"><a href="#sec88">13.2  Attributes</a>
</li></ul>
</li><li class="li-toc"><a href="#sec89">14  Interaction with build systems</a>
<ul class="toc"><li class="li-toc">
<a href="#sec90">14.1  OCaml type inference and dependency analysis</a>
<ul class="toc"><li class="li-toc">
<a href="#sec91">14.1.1  Running without OCaml type information</a>
</li><li class="li-toc"><a href="#sec92">14.1.2  Obtaining OCaml type information by calling the OCaml compiler</a>
</li><li class="li-toc"><a href="#sec93">14.1.3  Obtaining OCaml type information without calling the OCaml compiler</a>
</li></ul>
</li><li class="li-toc"><a href="#sec94">14.2  Compilation flags</a>
</li></ul>
</li><li class="li-toc"><a href="#sec95">15  Comparison with <span style="font-family:monospace">ocamlyacc</span></a>
</li><li class="li-toc"><a href="#sec96">16  Questions and Answers</a>
</li><li class="li-toc"><a href="#sec97">17  Technical background</a>
</li><li class="li-toc"><a href="#sec98">18  Acknowledgements</a>
</li></ul>
<!--TOC section id="sec2" Foreword-->
<h2 id="sec2" class="section">1  Foreword</h2><!--SEC END --><p>Menhir is a parser generator. It turns high-level grammar specifications,
decorated with semantic actions expressed in the OCaml programming
language [<a href="#ocaml">18</a>], into parsers, again expressed in OCaml. It is
based on Knuth’s LR(1) parser construction technique [<a href="#knuth-lr-65">15</a>]. It is
strongly inspired by its precursors: <span style="font-family:monospace">yacc</span> [<a href="#johnson-yacc-79">11</a>],
<span style="font-family:monospace">ML-Yacc</span> [<a href="#tarditi-appel-00">22</a>], and <span style="font-family:monospace">ocamlyacc</span> [<a href="#ocaml">18</a>],
but offers a large number of minor and major improvements that make it a more
modern tool.</p><p>This brief reference manual explains how to use Menhir. It does not attempt to
explain context-free grammars, parsing, or the LR technique. Readers who have
never used a parser generator are encouraged to read about these ideas
first [<a href="#aho-86">1</a>,<a href="#appel-tiger-98">2</a>,<a href="#hopcroft-motwani-ullman-00">8</a>]. They are also
invited to have a look at the <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos"><span style="font-family:monospace">demos</span></a> directory in Menhir’s
distribution.</p><p>Potential users of Menhir should be warned that Menhir’s feature set is not
completely stable. There is a tension between preserving a measure of
compatibility with <span style="font-family:monospace">ocamlyacc</span>, on the one hand, and introducing new ideas, on
the other hand. Some aspects of the tool, such as the error handling
mechanism, are still potentially subject to incompatible changes: for
instance, in the future, the current error handling mechanism (which is based
on the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token, see §<a href="#sec%3Aerrors">10</a>) could be removed and replaced with
an entirely different mechanism.</p><p>There is room for improvement in the tool and in this reference manual. Bug
reports and suggestions are welcome!</p>
<!--TOC section id="sec3" Usage-->
<h2 id="sec3" class="section">2  Usage</h2><!--SEC END --><p>Menhir is invoked as follows:
</p><blockquote class="quote">
<span style="font-family:monospace">menhir</span> <span style="font-style:italic">option</span> …<span style="font-style:italic">option</span> <span style="font-style:italic">filename</span> …<span style="font-style:italic">filename</span>
</blockquote><p>
Each of the file names must end with <span style="font-family:monospace">.mly</span> (unless <span style="font-family:monospace">--coq</span> is used,
in which case it must end with <span style="font-family:monospace">.vy</span>) and denotes a partial
grammar specification. These partial grammar specifications are joined
(§<a href="#sec%3Asplit">5.1</a>) to form a single, self-contained grammar specification,
which is then processed. The following optional command line switches allow
controlling many aspects of the process.</p><p><span style="font-family:monospace">--base</span> <span style="font-style:italic">basename</span>.  This switch controls the base name
of the <span style="font-family:monospace">.ml</span> and <span style="font-family:monospace">.mli</span> files that are produced. That is, the tool will produce
files named <span style="font-style:italic">basename</span><span style="font-family:monospace">.ml</span> and <span style="font-style:italic">basename</span><span style="font-family:monospace">.mli</span>. Note
that <span style="font-style:italic">basename</span> can contain occurrences of the <span style="font-family:monospace">/</span> character, so it
really specifies a path and a base name. When only one <span style="font-style:italic">filename</span> is
provided on the command line, the default <span style="font-style:italic">basename</span> is obtained by
depriving <span style="font-style:italic">filename</span> of its final <span style="font-family:monospace">.mly</span> suffix. When multiple file
names are provided on the command line, no default base name exists, so that
the <span style="font-family:monospace">--base</span> switch <em>must</em> be used.</p><p><span style="font-family:monospace">--cmly</span>.  This switch causes Menhir to produce a <span style="font-family:monospace">.cmly</span> file in
addition to its normal operation. This file contains a (binary-form)
representation of the grammar and automaton (see §<a href="#sec%3Asdk">13.1</a>).</p><p><span style="font-family:monospace">--comment</span>.  This switch causes a few comments to be inserted into the
OCaml code that is written to the <span style="font-family:monospace">.ml</span> file.</p><p><span style="font-family:monospace">--compare-errors</span> <span style="font-style:italic">filename1</span> <span style="font-family:monospace">--compare-errors</span> <span style="font-style:italic">filename2</span>.  Two
such switches must always be used in conjunction so as to specify the names of
two <span style="font-family:monospace">.messages</span> files, <span style="font-style:italic">filename1</span> and <span style="font-style:italic">filename2</span>. Each file is read and
internally translated to a mapping of states to messages. Menhir then checks
that the left-hand mapping is a subset of the right-hand mapping. This feature
is typically used in conjunction with <span style="font-family:monospace">--list-errors</span> to check that <span style="font-style:italic">filename2</span>
is complete (that is, covers all states where an error can occur).
For more information, see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--compile-errors</span> <span style="font-style:italic">filename</span>.  This switch causes Menhir to read the
file <span style="font-style:italic">filename</span>, which must obey the <span style="font-family:monospace">.messages</span> file format, and to compile
it to an OCaml function that maps a state number to a message. The OCaml code
is sent to the standard output channel. At the same time, Menhir checks that
the collection of input sentences in the file <span style="font-style:italic">filename</span> is correct and
irredundant. For more information, see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--coq</span>.  This switch causes Menhir to produce Coq code. See §<a href="#sec%3Acoq">12</a>.</p><p><span style="font-family:monospace">--coq-lib-path</span> <span style="font-style:italic">path</span>.  This switch allows specifying under what
name (or path) the Coq support library is known to Coq. When Menhir runs in
<span style="font-family:monospace">--coq</span> mode, the generated parser contains references to several modules in
this library. This path is used to qualify these references. Its default value
is <span style="font-family:monospace">MenhirLib</span>.</p><p><span style="font-family:monospace">--coq-lib-no-path</span>.  This switch indicates that references to the Coq
library <span style="font-family:monospace">MenhirLib</span> should <em>not</em> be qualified. This was the default
behavior of Menhir prior to 2018/05/30. This switch is provided for
compatibility, but normally should not be used.</p><p><span style="font-family:monospace">--coq-no-actions</span>.  (Used in conjunction with <span style="font-family:monospace">--coq</span>.) This switch
causes the semantic actions present in the <span style="font-family:monospace">.vy</span> file to be ignored and
replaced with <code>tt</code>, the unique inhabitant of Coq’s <code>unit</code> type. This
feature can be used to test the Coq back-end with a standard grammar, that is, a
grammar that contains OCaml semantic actions. Just rename the file from
<span style="font-family:monospace">.mly</span> to <span style="font-family:monospace">.vy</span> and set this switch.</p><p><span style="font-family:monospace">--coq-no-complete</span>.  (Used in conjunction with <span style="font-family:monospace">--coq</span>.) This switch
disables the generation of the proof of completeness of the parser
(§<a href="#sec%3Acoq">12</a>). This can be necessary because the proof of completeness is
possible only if the grammar has no conflict (not even a benign one, in the
sense of §<a href="#sec%3Aconflicts%3Abenign">6.1</a>). This can be desirable also because, for
a complex grammar, completeness may require a heavy certificate and its
validation by Coq may take time.</p><p><span style="font-family:monospace">--coq-no-version-check</span>.  (Used in conjunction with <span style="font-family:monospace">--coq</span>.) This switch
prevents the generation of the check that verifies that the versions of
Menhir and <span style="font-family:monospace">MenhirLib</span> match.</p><p><span style="font-family:monospace">--depend</span>.  See §<a href="#sec%3Abuild">14</a>.</p><p><span style="font-family:monospace">--dump</span>.  This switch causes a description of the automaton to be
written to the file <span style="font-style:italic">basename</span><span style="font-family:monospace">.automaton</span>. This description is written after
benign conflicts have been resolved, before severe conflicts are resolved
(§<a href="#sec%3Aconflicts">6</a>), and before extra reductions are introduced
(§<a href="#sec%3Aonerrorreduce">4.1.8</a>).</p><p><span style="font-family:monospace">--dump-resolved</span>.  This command line switch causes a description of
the automaton to be written to the file <span style="font-style:italic">basename</span><span style="font-family:monospace">.automaton.resolved</span>. This
description is written after all conflicts have been resolved
(§<a href="#sec%3Aconflicts">6</a>) and after extra reductions have been introduced
(§<a href="#sec%3Aonerrorreduce">4.1.8</a>).</p><p><span style="font-family:monospace">--echo-errors</span> <span style="font-style:italic">filename</span>.  This switch causes Menhir to
read the <span style="font-family:monospace">.messages</span> file <span style="font-style:italic">filename</span> and to produce on the standard output
channel just the input sentences. (That is, all messages, blank lines, and
comments are filtered out.) For more information, see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--echo-errors-concrete</span> <span style="font-style:italic">filename</span>.  This switch causes Menhir to
read the <span style="font-family:monospace">.messages</span> file <span style="font-style:italic">filename</span> and to produce on the standard output
channel just the input sentences. Each sentence is followed with a comment of
the form <code>## Concrete syntax: ...</code> that shows this sentence in concrete
syntax. This comment is printed only if the user has defined an alias for
every token (§<a href="#sec%3Atokens">4.1.3</a>).</p><p><span style="font-family:monospace">--explain</span>.  This switch causes conflict explanations to be
written to the file <span style="font-style:italic">basename</span><span style="font-family:monospace">.conflicts</span>. See also §<a href="#sec%3Aconflicts">6</a>.</p><p><span style="font-family:monospace">--external-tokens</span> <span style="font-style:italic">T</span>.  This switch causes the definition of
the <span style="font-family:monospace">token</span> type to be omitted in <span style="font-style:italic">basename</span><span style="font-family:monospace">.ml</span> and
<span style="font-style:italic">basename</span><span style="font-family:monospace">.mli</span>. Instead, the generated parser relies on
the type <span style="font-style:italic">T</span><span style="font-family:monospace">.</span><span style="font-family:monospace">token</span>, where <span style="font-style:italic">T</span> is an OCaml module name. It is up to
the user to define module <span style="font-style:italic">T</span> and to make sure that it exports a suitable
<span style="font-family:monospace">token</span> type. Module <span style="font-style:italic">T</span> can be hand-written. It can also be automatically generated
out of a grammar specification using the <span style="font-family:monospace">--only-tokens</span> switch.</p><p><span style="font-family:monospace">--fixed-exception</span>.  This switch causes the exception <span style="font-family:monospace">Error</span> to be
internally defined as a synonym for <span style="font-family:monospace">Parsing.Parse_error</span>. This means
that an exception handler that catches <span style="font-family:monospace">Parsing.Parse_error</span> will also
catch the generated parser’s <span style="font-family:monospace">Error</span>. This helps increase Menhir’s
compatibility with <span style="font-family:monospace">ocamlyacc</span>. There is otherwise no reason to use this switch.</p><p><span style="font-family:monospace">--graph</span>.  This switch causes a description of the grammar’s
dependency graph to be written to the file <span style="font-style:italic">basename</span><span style="font-family:monospace">.dot</span>. The graph’s
vertices are the grammar’s nonterminal symbols. There is a directed edge from
vertex <span style="font-style:italic">A</span> to vertex <span style="font-style:italic">B</span> if the definition of <span style="font-style:italic">A</span> refers to <span style="font-style:italic">B</span>. The file is
in a format that is suitable for processing by the <em>graphviz</em> toolkit.</p><p><span style="font-family:monospace">--infer</span>, <span style="font-family:monospace">--infer-write-query</span>, <span style="font-family:monospace">--infer-read-reply</span>.  See §<a href="#sec%3Abuild">14</a>.</p><p><span style="font-family:monospace">--inspection</span>.  This switch requires <span style="font-family:monospace">--table</span>. It causes Menhir to generate
not only the monolithic and incremental APIs (§<a href="#sec%3Amonolithic">9.1</a>,
§<a href="#sec%3Aincremental">9.2</a>), but also the inspection API (§<a href="#sec%3Ainspection">9.3</a>).
Activating this switch causes a few more tables to be produced, resulting in
somewhat larger code size.</p><p><span style="font-family:monospace">--interpret</span>.  This switch causes Menhir to act as an interpreter,
rather than as a compiler. No OCaml code is generated. Instead, Menhir reads sentences off the standard input channel, parses them, and displays
outcomes. This switch can be usefully combined with <span style="font-family:monospace">--trace</span>.
For more information, see §<a href="#sec%3Ainterpret">8</a>.</p><p><span style="font-family:monospace">--interpret-error</span>.  This switch is analogous to <span style="font-family:monospace">--interpret</span>, except
Menhir expects every sentence to cause an error on its last token, and
displays information about the state in which the error is detected, in
the <span style="font-family:monospace">.messages</span> file format. For more information, see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--interpret-show-cst</span>.  This switch, used in conjunction with <span style="font-family:monospace">--interpret</span>,
causes Menhir to display a concrete syntax tree when a sentence is successfully
parsed. For more information, see §<a href="#sec%3Ainterpret">8</a>.</p><p><span style="font-family:monospace">--list-errors</span>.  This switch causes Menhir to produce (on the standard
output channel) a complete list of input sentences that cause an error, in the
<span style="font-family:monospace">.messages</span> file format. For more information, see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--log-automaton</span> <span style="font-style:italic">level</span>.  When <span style="font-style:italic">level</span> is nonzero, this switch
causes some information about the automaton to be logged to the standard error
channel.</p><p><span style="font-family:monospace">--log-code</span> <span style="font-style:italic">level</span>.  When <span style="font-style:italic">level</span> is nonzero, this switch
causes some information about the generated OCaml code to be logged to the
standard error channel.</p><p><span style="font-family:monospace">--log-grammar</span> <span style="font-style:italic">level</span>.  When <span style="font-style:italic">level</span> is nonzero, this switch
causes some information about the grammar to be logged to the standard error
channel. When <span style="font-style:italic">level</span> is 2, the <em>nullable</em>, <em>FIRST</em>, and
<em>FOLLOW</em> tables are displayed.</p><p><span style="font-family:monospace">--merge-errors</span> <span style="font-style:italic">filename1</span> <span style="font-family:monospace">--merge-errors</span> <span style="font-style:italic">filename2</span>.  Two such
switches must always be used in conjunction so as to specify the names of two
<span style="font-family:monospace">.messages</span> files, <span style="font-style:italic">filename1</span> and <span style="font-style:italic">filename2</span>. This command causes
Menhir to merge these two <span style="font-family:monospace">.messages</span> files and print the result on the
standard output channel. For more information, see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--no-dollars</span>.  This switch disallows the use of positional keywords
of the form <span style="font-family:sans-serif"><span style="font-weight:bold">$i</span></span>.</p><p><span style="font-family:monospace">--no-inline</span>.  This switch causes all <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keywords in the
grammar specification to be ignored. This is especially useful in order
to understand whether these keywords help solve any conflicts.</p><p><span style="font-family:monospace">--no-stdlib</span>.  This switch instructs Menhir to <em>not</em> use
its standard library (§<a href="#sec%3Alibrary">5.4</a>).</p><p><span style="font-family:monospace">--ocamlc</span> <span style="font-style:italic">command</span>.  See §<a href="#sec%3Abuild">14</a>.</p><p><span style="font-family:monospace">--ocamldep</span> <span style="font-style:italic">command</span>.  See §<a href="#sec%3Abuild">14</a>.</p><p><span style="font-family:monospace">--only-preprocess</span>.  This switch causes the grammar specifications
to be transformed up to the point where the automaton’s construction can
begin. The grammar specifications whose names are provided on the command line
are joined (§<a href="#sec%3Asplit">5.1</a>); all parameterized nonterminal symbols are
expanded away (§<a href="#sec%3Atemplates">5.2</a>); type inference is performed, if <span style="font-family:monospace">--infer</span> is enabled; all nonterminal symbols marked <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> are expanded away
(§<a href="#sec%3Ainline">5.3</a>). This yields a single, monolithic grammar specification,
which is printed on the standard output channel.</p><p><span style="font-family:monospace">--only-tokens</span>.  This switch causes the <span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> declarations in
the grammar specification to be translated into a definition of the <span style="font-family:monospace">token</span> type, which is written to the files <span style="font-style:italic">basename</span><span style="font-family:monospace">.ml</span> and
<span style="font-style:italic">basename</span><span style="font-family:monospace">.mli</span>. No code is generated. This is useful when
a single set of tokens is to be shared between several parsers. The directory
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-two"><span style="font-family:monospace">demos/calc-two</span></a> contains a demo that illustrates the use of this switch.</p><p><span style="font-family:monospace">--raw-depend</span>.  See §<a href="#sec%3Abuild">14</a>.</p><p><span style="font-family:monospace">--require-aliases</span>.  This switch causes Menhir to check that a token
alias (§<a href="#sec%3Atokens">4.1.3</a>) has been defined for every token. There is no
requirement for this alias to be actually used; it must simply exist. A
missing alias gives rise to a warning (and, in <span style="font-family:monospace">--strict</span> mode, to an error).</p><p><span style="font-family:monospace">--stdlib</span> <span style="font-style:italic">directory</span>.  This switch exists only for
backwards compatibility and is ignored. It may be removed in the future.</p><p><span style="font-family:monospace">--strategy</span> <span style="font-style:italic">strategy</span>.  This switch selects an error handling
strategy, to be used by the code back-end, the table back-end, and the
reference interpreter. The available strategies are <span style="font-family:monospace">legacy</span> and
simplified. (However, at the time of writing, the code back-end does
not yet support the simplified strategy.) When this switch is
omitted, the <span style="font-family:monospace">legacy</span> strategy is used. The choice of a strategy
matters only if the grammar uses the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token. For more details, see
§<a href="#sec%3Aerrors">10</a>.</p><p><span style="font-family:monospace">--strict</span>.  This switch causes several warnings about the grammar
and about the automaton to be considered errors. This includes warnings about
useless precedence declarations, non-terminal symbols that produce the empty
language, unreachable non-terminal symbols, productions that are never
reduced, conflicts that are not resolved by precedence declarations,
end-of-stream conflicts, and missing token aliases.</p><p><span style="font-family:monospace">--suggest-*</span>.  See §<a href="#sec%3Abuild">14</a>.</p><p><span style="font-family:monospace">--table</span>.  This switch causes Menhir to use its table-based
back-end, as opposed to its (default) code-based back-end. When <span style="font-family:monospace">--table</span> is
used, Menhir produces significantly more compact and somewhat slower parsers.
See §<a href="#sec%3Aqa">16</a> for a speed comparison.</p><p>The table-based back-end produces rather compact tables, which are analogous
to those produced by <span style="font-family:monospace">yacc</span>, <span style="font-family:monospace">bison</span>, or <span style="font-family:monospace">ocamlyacc</span>. These tables are not quite
stand-alone: they are exploited by an interpreter, which is shipped as part of
the support library <span style="font-family:monospace">MenhirLib</span>. For this reason, when <span style="font-family:monospace">--table</span> is used,
<span style="font-family:monospace">MenhirLib</span> must be made visible to the OCaml compilers, and must be linked
into your executable program. The <span style="font-family:monospace">--suggest-*</span> switches, described
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">--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:
one cannot selectively enable or disable tracing at runtime.</p><p><span style="font-family:monospace">--unused-precedence-levels</span>.  This switch suppresses all warnings about
useless <span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span> and <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> declarations.</p><p><span style="font-family:monospace">--unused-token</span> <span style="font-style:italic">symbol</span>.  This switch suppresses the warning that
is normally emitted when Menhir finds that the terminal symbol <span style="font-style:italic">symbol</span> is
unused.</p><p><span style="font-family:monospace">--unused-tokens</span>.  This switch suppresses all of the warnings that are
normally emitted when Menhir finds that some terminal symbols are unused.</p><p><span style="font-family:monospace">--update-errors</span> <span style="font-style:italic">filename</span>.  This switch causes Menhir to
read the <span style="font-family:monospace">.messages</span> file <span style="font-style:italic">filename</span> and to produce on the standard output
channel a new <span style="font-family:monospace">.messages</span> file that is identical, except the auto-generated
comments have been re-generated. For more information,
see §<a href="#sec%3Aerrors%3Anew">11</a>.</p><p><span style="font-family:monospace">--version</span>.  This switch causes Menhir to print its own version
number and exit.</p>
<!--TOC section id="sec4" Lexical conventions-->
<h2 id="sec4" class="section">3  Lexical conventions</h2><!--SEC END --><p>A semicolon character (<span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span>) <em>may</em> appear after a declaration
(§<a href="#sec%3Adecls">4.1</a>).</p><p>An old-style rule (§<a href="#sec%3Aold%3Arules">4.2</a>) <em>may</em> be terminated with a
semicolon. Also, within an old-style rule, each producer
(§<a href="#sec%3Aproducers">4.2.3</a>) <em>may</em> be terminated with a semicolon.</p><p>A new-style rule (§<a href="#sec%3Anew%3Arules">4.3</a>) <em>must not</em> be terminated with a
semicolon. Within such a rule, the elements of a sequence <em>must</em> be
separated with semicolons.</p><p>Semicolons are not allowed to appear anywhere except in the places mentioned
above. This is in contrast with <span style="font-family:monospace">ocamlyacc</span>, which views semicolons as
insignificant, just like whitespace.</p><p>Identifiers (<span style="font-style:italic">id</span>) coincide with OCaml identifiers, except they are not
allowed to contain the quote (<span style="font-family:sans-serif"><span style="font-weight:bold">’</span></span>) character. Following
OCaml, identifiers that begin with a lowercase letter
(<span style="font-style:italic">lid</span>) or with an uppercase letter (<span style="font-style:italic">uid</span>) are distinguished.</p><p>A quoted identifier <span style="font-style:italic">qid</span> is a string enclosed in double quotes.
Such a string cannot contain a double quote or a backslash.
Quoted identifiers are used as token aliases (§<a href="#sec%3Atokens">4.1.3</a>).</p><p>Comments are C-style (surrounded with <span style="font-family:sans-serif"><span style="font-weight:bold">/*</span></span> and <span style="font-family:sans-serif"><span style="font-weight:bold">*/</span></span>, cannot be nested),
C++-style (announced by <span style="font-family:sans-serif"><span style="font-weight:bold">//</span></span> and extending until the end of the line), or
OCaml-style (surrounded with <span style="font-family:sans-serif"><span style="font-weight:bold">(*</span></span> and <span style="font-family:sans-serif"><span style="font-weight:bold">*)</span></span>, can be nested). Of course,
inside OCaml code, only OCaml-style comments are allowed.</p><p>OCaml type expressions are surrounded with <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> and <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span>. Within such expressions,
all references to type constructors (other than the built-in <span style="font-style:italic">list</span>, <span style="font-style:italic">option</span>, etc.)
must be fully qualified.</p>
<!--TOC section id="sec5" Syntax of grammar specifications-->
<h2 id="sec5" class="section">4  Syntax of grammar specifications</h2><!--SEC END --><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:right;white-space:nowrap" >
<span style="font-style:italic">specification</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">declaration</span> … <span style="font-style:italic">declaration</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> <span style="font-style:italic">rule</span> … <span style="font-style:italic">rule</span>
[ <span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> <span style="font-style:italic">OCaml code</span> ] </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<span style="font-style:italic">declaration</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%{</span></span> <span style="font-style:italic">OCaml code</span> <span style="font-family:sans-serif"><span style="font-weight:bold">%}</span></span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">uid</span> <span style="font-family:sans-serif"><span style="font-weight:bold">:</span></span> <span style="font-style:italic">OCaml module type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> ] <span style="font-style:italic">uid</span> [ <span style="font-style:italic">qid</span> ] … <span style="font-style:italic">uid</span> [ <span style="font-style:italic">qid</span> ] </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span> <span style="font-style:italic">uid</span> … <span style="font-style:italic">uid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> <span style="font-style:italic">uid</span> … <span style="font-style:italic">uid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span> <span style="font-style:italic">uid</span> … <span style="font-style:italic">uid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">lid</span> … <span style="font-style:italic">lid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> ] <span style="font-style:italic">lid</span> … <span style="font-style:italic">lid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%attribute</span></span> <span style="font-style:italic">actual</span> … <span style="font-style:italic">actual</span> <span style="font-style:italic">attribute</span> … <span style="font-style:italic">attribute</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%</span></span> <span style="font-style:italic">attribute</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> <span style="font-style:italic">lid</span> … <span style="font-style:italic">lid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">attribute</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">[@</span></span> <span style="font-style:italic">name</span> <span style="font-style:italic">payload</span> <span style="font-family:sans-serif"><span style="font-weight:bold">]</span></span>
</td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<em>old syntax</em> —
<span style="font-style:italic">rule</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" >[ <span style="font-family:sans-serif"><span style="font-weight:bold">%public</span></span> ] [ <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> ]
<span style="font-style:italic">lid</span>
[ <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">id</span>, …, <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> ]
<span style="font-family:sans-serif"><span style="font-weight:bold">:</span></span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> ] <span style="font-style:italic">group</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">group</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<span style="font-style:italic">group</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">production</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">production</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>  [ <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span> ] </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<span style="font-style:italic">production</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">producer</span> … <span style="font-style:italic">producer</span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span> ] </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<span style="font-style:italic">producer</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" >[ <span style="font-style:italic">lid</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> ] <span style="font-style:italic">actual</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<span style="font-style:italic">actual</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">id</span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">actual</span>, …, <span style="font-style:italic">actual</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> ] </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">actual</span> ( <span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span>  ∣ <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span>  ∣ <span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span> )</td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">group</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">group</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >
<em>new syntax</em> —
<span style="font-style:italic">rule</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" >[ <span style="font-family:sans-serif"><span style="font-weight:bold">%public</span></span> ]
<span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">lid</span>
[ <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">id</span>, …, <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> ]
( <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">:=</span></span></span>  ∣ <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">==</span></span></span> )
<span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">expression</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" >[ <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> ] <span style="font-style:italic">expression</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" > [ <span style="font-style:italic">pattern</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> ] <span style="font-style:italic">expression</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" > <span style="font-style:italic">id</span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression</span> , …, <span style="font-style:italic">expression</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> ]
</td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" > <span style="font-style:italic">expression</span> ( <span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span>  ∣ <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span>  ∣ <span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span> )</td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" > <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>  [ <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span> ]
</td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" > <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span>
[ <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span> ]
</td></tr>
<tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">pattern</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">lid</span>
  ∣  
<span style="font-family:sans-serif"><span style="font-weight:bold">_</span></span>   ∣  
<span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span>   ∣  
<span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">pattern</span> , …, <span style="font-style:italic">pattern</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> </td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 1: Syntax of grammar specifications</td></tr>
</table></div>
<a id="fig:syntax"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>The syntax of grammar specifications appears in Figure <a href="#fig%3Asyntax">1</a>.
The places where attributes can be attached are not shown; they
are documented separately (§<a href="#sec%3Aattributes">13.2</a>).
A grammar specification begins with a sequence of declarations
(§<a href="#sec%3Adecls">4.1</a>), ended by a mandatory <span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> keyword.
Following this keyword, a sequence of rules is expected.
Each rule defines a nonterminal symbol <span style="font-style:italic">lid</span>,
whose name must begin with a lowercase letter.
A rule is expressed either in the “old syntax” (§<a href="#sec%3Aold%3Arules">4.2</a>) or in the
“new syntax” (§<a href="#sec%3Anew%3Arules">4.3</a>), which is slightly more elegant and
powerful.</p>
<!--TOC subsection id="sec6" Declarations-->
<h3 id="sec6" class="subsection">4.1  Declarations</h3><!--SEC END --><p>
<a id="sec:decls"></a></p>
<!--TOC subsubsection id="sec7" Headers-->
<h4 id="sec7" class="subsubsection">4.1.1  Headers</h4><!--SEC END --><p>
<a id="sec:decls:headers"></a></p><p>A header is a piece of OCaml code, surrounded with <span style="font-family:sans-serif"><span style="font-weight:bold">%{</span></span> and <span style="font-family:sans-serif"><span style="font-weight:bold">%}</span></span>. It is
copied verbatim at the beginning of the <span style="font-family:monospace">.ml</span> file. It typically contains OCaml <span style="font-family:sans-serif"><span style="font-weight:bold">open</span></span> directives and function definitions for use by the semantic
actions. If a single grammar specification file contains multiple headers,
their order is preserved. However, when two headers originate in distinct
grammar specification files, the order in which they are copied to the <span style="font-family:monospace">.ml</span> file is unspecified.</p><p>It is important to note that the header is copied by Menhir only to the <span style="font-family:monospace">.ml</span> file, <em>not</em> to the <span style="font-family:monospace">.mli</span> file. Therefore, it should not contain
declarations that affect the meaning of the types that appear in the <span style="font-family:monospace">.mli</span> file. Here are two problems that people commonly run into:
</p><ul class="itemize"><li class="li-itemize">
Placing an <span style="font-family:sans-serif"><span style="font-weight:bold">open</span></span> directive that is required for a <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declaration
to make sense. For instance, writing <code>open Foo</code> in the header and
declaring <code>%type&lt;t&gt; bar</code>, where the type <code>t</code> is defined in the
module <code>Foo</code>, will not work. You must write <code>%type&lt;Foo.t&gt; bar</code>.
</li><li class="li-itemize">Declaring a module alias that affects a (declared or inferred) type. For
instance, writing <code>module F = Foo</code> in the header and declaring
<code>%type&lt;Foo.t&gt; bar</code> may not work (from
2020/05/25 on). The reason is, OCaml may infer that the symbol <code>bar</code> has
type <code>F.t</code>, and Menhir will rely on this information without realizing
that <code>F</code> is a local name, so in the end, the <span style="font-family:monospace">.mli</span> file contains a
reference to <code>F.t</code> that does not make sense.
</li></ul>
<!--TOC subsubsection id="sec8" Parameters-->
<h4 id="sec8" class="subsubsection">4.1.2  Parameters</h4><!--SEC END --><p>
<a id="sec:parameter"></a></p><p>A declaration of the form:
</p><blockquote class="quote">
<span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">uid</span> <span style="font-family:sans-serif"><span style="font-weight:bold">:</span></span> <span style="font-style:italic">OCaml module type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> </blockquote><p>
causes the entire parser to become parameterized over the OCaml module
<span style="font-style:italic">uid</span>, that is, to become an OCaml functor. The directory
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-param"><span style="font-family:monospace">demos/calc-param</span></a> contains a demo that illustrates the use of this switch.</p><p>If a single specification file
contains multiple <span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> declarations, their order is preserved, so that
the module name <span style="font-style:italic">uid</span> introduced by one declaration is effectively in scope
in the declarations that follow. When two <span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> declarations originate
in distinct grammar specification files, the order in which they are processed
is unspecified. Last, <span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> declarations take effect before <span style="font-family:sans-serif"><span style="font-weight:bold">%{</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">%}</span></span>,
<span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span>, or <span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> declarations are considered, so that the module name
<span style="font-style:italic">uid</span> introduced by a <span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> declaration is effectively in scope in
<em>all</em> <span style="font-family:sans-serif"><span style="font-weight:bold">%{</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">%}</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span>, or <span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> declarations,
regardless of whether they precede or follow the <span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> declaration.
This means, in particular, that the side effects of an OCaml header are
observed only when the functor is applied, not when it is defined.</p>
<!--TOC subsubsection id="sec9" Tokens-->
<h4 id="sec9" class="subsubsection">4.1.3  Tokens</h4><!--SEC END --><p>
<a id="sec:tokens"></a></p><p>A declaration of the form:
</p><blockquote class="quote">
<span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> ]
<span style="font-style:italic">uid</span><sub>1</sub> [ <span style="font-style:italic">qid</span><sub>1</sub> ]  … 
<span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub> [ <span style="font-style:italic">qid</span><sub><span style="font-style:italic">n</span></sub> ]
</blockquote><p>
defines the identifiers <span style="font-style:italic">uid</span><sub>1</sub>, …, <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub> as tokens, that is,
as terminal symbols in the grammar specification and as data constructors in
the <span style="font-style:italic">token</span> type.</p><p>If an OCaml type <span style="font-style:italic">t</span> is present, then these tokens are considered to carry a
semantic value of type <span style="font-style:italic">t</span>, otherwise they are considered to carry no semantic
value.</p><p>If a quoted identifier <span style="font-style:italic">qid</span><sub><span style="font-style:italic">i</span></sub> is present, then it is considered an alias
for the terminal symbol <span style="font-style:italic">uid</span><sub><span style="font-style:italic">i</span></sub>. (This feature, known as “token
aliases”, is borrowed from Bison.)
Throughout the grammar, the quoted identifier <span style="font-style:italic">qid</span><sub><span style="font-style:italic">i</span></sub> is then
synonymous with the identifier <span style="font-style:italic">uid</span><sub><span style="font-style:italic">i</span></sub>.
For example, if one declares:
</p><pre class="verbatim">%token PLUS "+"
</pre><p>
then the quoted identifier <span style="font-family:monospace">"+"</span> stands for the terminal symbol
<span style="font-family:monospace">PLUS</span> throughout the grammar. An example of the use of token aliases
appears in the directory <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-alias"><span style="font-family:monospace">demos/calc-alias</span></a>.
Token aliases can be used to improve the readability of a grammar. One must
keep in mind, however, that they are just syntactic sugar: they are not
interpreted in any way by Menhir or conveyed to tools like <span style="font-family:monospace">ocamllex</span>.
They could be considered confusing by a reader who mistakenly believes that
they are interpreted as string literals.</p>
<!--TOC subsubsection id="sec10" Priority and associativity-->
<h4 id="sec10" class="subsubsection">4.1.4  Priority and associativity</h4><!--SEC END --><p>
<a id="sec:assoc"></a></p><p>A declaration of one of the following forms:
</p><blockquote class="quote">
<span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span> <span style="font-style:italic">uid</span><sub>1</sub> … <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub> <br>
<span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> <span style="font-style:italic">uid</span><sub>1</sub> … <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub> <br>
<span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span> <span style="font-style:italic">uid</span><sub>1</sub> … <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub>
</blockquote><p>
assigns both a <em>priority level</em> and an <em>associativity status</em> to
the symbols <span style="font-style:italic">uid</span><sub>1</sub>, …, <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub>. The priority level assigned to
<span style="font-style:italic">uid</span><sub>1</sub>, …, <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub> is not defined explicitly: instead, it is
defined to be higher than the priority level assigned by the previous
<span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span>, or <span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span> declaration, and lower than that assigned by the next
<span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span>, or <span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span> declaration. The symbols <span style="font-style:italic">uid</span><sub>1</sub>, …, <span style="font-style:italic">uid</span><sub><span style="font-style:italic">n</span></sub>
can be tokens (defined elsewhere by a <span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> declaration) or dummies (not
defined anywhere). Both can be referred to as part of <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotations.
Associativity status and priority levels allow shift/reduce conflicts to be
silently resolved (§<a href="#sec%3Aconflicts">6</a>).</p>
<!--TOC subsubsection id="sec11" Types-->
<h4 id="sec11" class="subsubsection">4.1.5  Types</h4><!--SEC END --><p>
<a id="sec:type"></a></p><p>A declaration of the form:
</p><blockquote class="quote">
<span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">lid</span><sub>1</sub> … <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub>
</blockquote><p>
assigns an OCaml type to each of the nonterminal symbols <span style="font-style:italic">lid</span><sub>1</sub>, …, <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub>.
For start symbols, providing an OCaml type is mandatory, but is usually done as part of the
<span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> declaration. For other symbols, it is optional. Providing type information can improve
the quality of OCaml’s type error messages.</p><p>A <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declaration may concern not only a nonterminal symbol, such as, say,
<span style="font-family:monospace">expression</span>, but also a fully applied parameterized nonterminal
symbol, such as <span style="font-family:monospace">list(expression)</span> or <span style="font-family:monospace">separated_list(COMMA,
option(expression))</span>.</p><p>The types provided as part of <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declarations are copied verbatim to the
<span style="font-family:monospace">.ml</span> and <span style="font-family:monospace">.mli</span> files. In contrast, headers (§<a href="#sec%3Adecls%3Aheaders">4.1.1</a>) are copied
to the <span style="font-family:monospace">.ml</span> file only. For this reason, the types provided as part of <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declarations must make sense both in the presence and in the absence of these
headers. They should typically be fully qualified types.</p>
<!--TOC subsubsection id="sec12" Start symbols-->
<h4 id="sec12" class="subsubsection">4.1.6  Start symbols</h4><!--SEC END --><p>
<a id="sec:start"></a></p><p>A declaration of the form:
</p><blockquote class="quote">
<span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> [ <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml type</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> ] <span style="font-style:italic">lid</span><sub>1</sub> … <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub>
</blockquote><p>
declares the nonterminal symbols <span style="font-style:italic">lid</span><sub>1</sub>, …, <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub> to be
start symbols. Each such symbol must be assigned an OCaml type either as
part of the <span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> declaration or via separate <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declarations. Each
of <span style="font-style:italic">lid</span><sub>1</sub>, …, <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub> becomes the name of a function whose
signature is published in the <span style="font-family:monospace">.mli</span> file and that can be used to invoke
the parser.</p>
<!--TOC subsubsection id="sec13" Attribute declarations-->
<h4 id="sec13" class="subsubsection">4.1.7  Attribute declarations</h4><!--SEC END --><p>Attribute declarations
of the form
<span style="font-family:sans-serif"><span style="font-weight:bold">%attribute</span></span> <span style="font-style:italic">actual</span> … <span style="font-style:italic">actual</span> <span style="font-style:italic">attribute</span> … <span style="font-style:italic">attribute</span>
and
<span style="font-family:sans-serif"><span style="font-weight:bold">%</span></span> <span style="font-style:italic">attribute</span>
are explained
in §<a href="#sec%3Aattributes">13.2</a>.</p>
<!--TOC subsubsection id="sec14" Extra reductions on error-->
<h4 id="sec14" class="subsubsection">4.1.8  Extra reductions on error</h4><!--SEC END --><p>
<a id="sec:onerrorreduce"></a></p><p>A declaration of the form:
</p><blockquote class="quote">
<span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> <span style="font-style:italic">lid</span><sub>1</sub> … <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub>
</blockquote><p>
marks the nonterminal symbols <span style="font-style:italic">lid</span><sub>1</sub>, …, <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub> as
potentially eligible for reduction when an invalid token is found.
This may cause one or more extra reduction steps to be performed
before the error is detected.</p><p>More precisely, this declaration affects the automaton as follows. Let us say
that a production <span style="font-style:italic">lid</span> → … is “reducible on error” if
its left-hand symbol <span style="font-style:italic">lid</span> appears in a <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declaration. After
the automaton has been constructed and after any conflicts have been resolved,
in every state <span style="font-style:italic">s</span>, the following algorithm is applied:
</p><ol class="enumerate" type=1><li class="li-enumerate">
Construct the set of all productions that are ready to be reduced in
state <span style="font-style:italic">s</span> and are reducible on error;
</li><li class="li-enumerate">Test if one of them, say <span style="font-style:italic">p</span>, has higher “on-error-reduce-priority”
than every other production in this set;
</li><li class="li-enumerate">If so, in state <span style="font-style:italic">s</span>, replace every error action with a reduction of the
production <span style="font-style:italic">p</span>.
(In other words, for every terminal symbol <span style="font-style:italic">t</span>, if the action table
says: “in state <span style="font-style:italic">s</span>, when the next input symbol is <span style="font-style:italic">t</span>, fail”, then this
entry is replaced with: “in state <span style="font-style:italic">s</span>, when the next input symbol
is <span style="font-style:italic">t</span>, reduce production <span style="font-style:italic">p</span>”.)
</li></ol><p>If step 3 above is executed in state <span style="font-style:italic">s</span>, then an error can never be detected
in state <span style="font-style:italic">s</span>, since all error actions in state <span style="font-style:italic">s</span> are replaced with reduce
actions. Error detection is deferred: at least one reduction takes place
before the error is detected. It is a “spurious” reduction: in a canonical
LR(1) automaton, it would not take place.</p><p>An <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declaration does not affect the language that is accepted
by the automaton. It does not affect the location where an error is detected.
It is used to control in which state an error is detected. If used wisely, it
can make errors easier to report, because they are detected in a state for
which it is easier to write an accurate diagnostic message
(§<a href="#sec%3Aerrors%3Adiagnostics">11.3</a>).</p><p>Like a <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declaration, an <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declaration may concern not only
a nonterminal symbol, such as, say, <span style="font-family:monospace">expression</span>, but also a fully
applied parameterized nonterminal symbol, such as <span style="font-family:monospace">list(expression)</span> or
<span style="font-family:monospace">separated_list(COMMA, option(expression))</span>.</p><p>The “on-error-reduce-priority” of a production is that of its left-hand
symbol. The “on-error-reduce-priority” of a nonterminal symbol is determined
implicitly by the order of <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declarations. In the declaration
<span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span>  <span style="font-style:italic">lid</span><sub>1</sub> … <span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub>, the symbols <span style="font-style:italic">lid</span><sub>1</sub>, …,
<span style="font-style:italic">lid</span><sub><span style="font-style:italic">n</span></sub> have the same “on-error-reduce-priority”. They have higher
“on-error-reduce-priority” than the symbols listed in previous
<span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declarations, and lower “on-error-reduce-priority”
than those listed in later <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declarations.</p>
<!--TOC subsection id="sec15" Rules—old syntax-->
<h3 id="sec15" class="subsection">4.2  Rules—old syntax</h3><!--SEC END --><p>
<a id="sec:old:rules"></a></p><p>In its simplest
form, a rule begins with the nonterminal symbol <span style="font-style:italic">lid</span>,
followed by a colon character (<span style="font-family:sans-serif"><span style="font-weight:bold">:</span></span>),
and continues with a sequence of production groups
(§<a href="#sec%3Aproductiongroups">4.2.1</a>). Each production group is preceded with a
vertical bar character (<span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>); the very first bar is optional. The meaning
of the bar is choice: the nonterminal symbol <span style="font-style:italic">id</span> develops to either of the
production groups. We defer explanations of the keyword <span style="font-family:sans-serif"><span style="font-weight:bold">%public</span></span> (§<a href="#sec%3Asplit">5.1</a>), of the keyword <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> (§<a href="#sec%3Ainline">5.3</a>), and of the
optional formal parameters <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">id</span>, …, <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> 
(§<a href="#sec%3Atemplates">5.2</a>).</p>
<!--TOC subsubsection id="sec16" Production groups-->
<h4 id="sec16" class="subsubsection">4.2.1  Production groups</h4><!--SEC END --><p>
<a id="sec:productiongroups"></a></p><p>In its simplest form, a production group consists of a single production (§<a href="#sec%3Aproductions">4.2.2</a>),
followed by an OCaml semantic action (§<a href="#sec%3Aactions">4.2.1</a>) and an optional
<span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotation (§<a href="#sec%3Aprec">4.2.1</a>). A production specifies a sequence of terminal and
nonterminal symbols that should be recognized, and optionally binds
identifiers to their semantic values.</p>
<!--TOC paragraph id="sec17" Semantic actions-->
<h4 id="sec17" class="paragraph">Semantic actions</h4><!--SEC END --><p>
<a id="sec:actions"></a></p><p>A semantic action is a piece of OCaml code that is executed in order to
assign a semantic value to the nonterminal symbol with which this production
group is associated. A semantic action can refer to the (already computed)
semantic values of the terminal or nonterminal symbols that appear in the
production via the semantic value identifiers bound by the production.</p><p>For compatibility with <span style="font-family:monospace">ocamlyacc</span>, semantic actions can also refer to
unnamed semantic values via positional keywords of the form
<span style="font-family:sans-serif"><span style="font-weight:bold">$1</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">$2</span></span>, etc. This style is discouraged.
(It is in fact forbidden if <span style="font-family:monospace">--no-dollars</span> is turned on.)
Furthermore, as
a positional keyword of the form <span style="font-family:sans-serif"><span style="font-weight:bold">$i</span></span> is internally rewritten as
<span style="font-style:italic">_i</span>, the user should not use identifiers of the form <span style="font-style:italic">_i</span>.</p>
<!--TOC paragraph id="sec18" <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotations-->
<h4 id="sec18" class="paragraph"><span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotations</h4><!--SEC END --><p>
<a id="sec:prec"></a></p><p>An annotation of the form <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span> indicates that the precedence level
of the production group is the level assigned to the symbol <span style="font-style:italic">id</span> via a
previous <span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span>, or <span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span> declaration (§<a href="#sec%3Aassoc">4.1.4</a>). In the
absence of a
<span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotation, the precedence level assigned to each production is the
level assigned to the rightmost terminal symbol that appears in it. It is
undefined if the rightmost terminal symbol has an undefined precedence level
or if the production mentions no terminal symbols at all. The precedence level
assigned to a production is used when resolving shift/reduce conflicts
(§<a href="#sec%3Aconflicts">6</a>).</p>
<!--TOC paragraph id="sec19" Multiple productions in a group-->
<h4 id="sec19" class="paragraph">Multiple productions in a group</h4><!--SEC END --><p>If multiple productions are present in a single group, then the semantic
action and precedence annotation are shared between them. This short-hand
effectively allows several productions to share a semantic action and
precedence annotation without requiring textual duplication. It is legal only
when every production binds exactly the same set of semantic value identifiers
and when no positional semantic value keywords (<span style="font-family:sans-serif"><span style="font-weight:bold">$1</span></span>, etc.) are used.</p>
<!--TOC subsubsection id="sec20" Productions-->
<h4 id="sec20" class="subsubsection">4.2.2  Productions</h4><!--SEC END --><p>
<a id="sec:productions"></a></p><p>A production is a sequence of producers (§<a href="#sec%3Aproducers">4.2.3</a>), optionally
followed by a <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotation (§<a href="#sec%3Aprec">4.2.1</a>). If a precedence annotation
is present, it applies to this production alone, not to other productions in
the production group. It is illegal for a production and its production group
to both carry <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotations.</p>
<!--TOC subsubsection id="sec21" Producers-->
<h4 id="sec21" class="subsubsection">4.2.3  Producers</h4><!--SEC END --><p>
<a id="sec:producers"></a></p><p>A producer is an actual (§<a href="#sec%3Aactual">4.2.4</a>), optionally preceded with a
binding of a semantic value identifier, of the form <span style="font-style:italic">lid</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span>. The
actual specifies which construction should be recognized and how a semantic
value should be computed for that construction. The identifier <span style="font-style:italic">lid</span>, if
present, becomes bound to that semantic value in the semantic action that
follows. Otherwise, the semantic value can be referred to via a positional
keyword (<span style="font-family:sans-serif"><span style="font-weight:bold">$1</span></span>, etc.).</p>
<!--TOC subsubsection id="sec22" Actuals-->
<h4 id="sec22" class="subsubsection">4.2.4  Actuals</h4><!--SEC END --><p>
<a id="sec:actual"></a></p><p>In its simplest form, an actual is just a terminal or nonterminal symbol
<span style="font-style:italic">id</span>. If it is a parameterized non-terminal symbol (see
§<a href="#sec%3Atemplates">5.2</a>), then it should be applied:
<span style="font-style:italic">id</span><span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">actual</span>, …, <span style="font-style:italic">actual</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> .</p><p>An actual may be followed with a modifier (<span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span>, or
<span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span>). This is explained further on (see §<a href="#sec%3Atemplates">5.2</a> and
Figure <a href="#fig%3Asugar">2</a>).</p><p>An actual may also be an “anonymous rule”. In that case, one writes
just the rule’s right-hand side, which takes the form <span style="font-style:italic">group</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> 
… <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> 
<span style="font-style:italic">group</span>.
(This form is allowed only as an argument in an application.)
This form is expanded on the fly to a definition of a fresh non-terminal
symbol, which is declared <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span>.
For instance, providing an anonymous rule as an argument to <span style="font-style:italic">list</span>:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">list</span> <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expression</span>; <span style="font-style:italic">SEMICOLON</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> </td></tr>
</table>
</blockquote><p>
is equivalent to writing this:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">list</span> <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression_SEMICOLON</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> </td></tr>
</table>
</blockquote><p>
where the non-terminal symbol <span style="font-style:italic">expression_SEMICOLON</span> is chosen fresh and is defined as follows:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> <span style="font-style:italic">expression_SEMICOLON</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expression</span>; <span style="font-style:italic">SEMICOLON</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote>
<!--TOC subsection id="sec23" Rules—new syntax-->
<h3 id="sec23" class="subsection">4.3  Rules—new syntax</h3><!--SEC END --><p>
<a id="sec:new:rules"></a></p><p>Please be warned that <span style="font-weight:bold">the new syntax is considered experimental</span>
and is subject to change in the future.
</p><p>In its simplest form,
a rule takes the form
<span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">lid</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">:=</span></span></span> <span style="font-style:italic">expression</span>.
Its left-hand side <span style="font-style:italic">lid</span> is a nonterminal symbol;
its right-hand side is an expression.
Such a rule defines an ordinary nonterminal symbol,
while the alternate form
<span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">lid</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">==</span></span></span> <span style="font-style:italic">expression</span> defines an <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> nonterminal symbol (§<a href="#sec%3Ainline">5.3</a>),
that is, a macro.
A rule can be preceded with the keyword <span style="font-family:sans-serif"><span style="font-weight:bold">%public</span></span> (§<a href="#sec%3Asplit">5.1</a>)
and can be parameterized with a tuple of formal parameters
<span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">id</span>, …, <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span>  (§<a href="#sec%3Atemplates">5.2</a>).
The various forms of expressions, listed in Figure <a href="#fig%3Asyntax">1</a>, are:
</p><ul class="itemize"><li class="li-itemize">
A <span style="font-weight:bold">choice</span> between several expressions,
[ <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> ]
<span style="font-style:italic">expression</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">expression</span><sub><span style="font-style:italic">n</span></sub>.
The leading bar is optional.</li><li class="li-itemize">A <span style="font-weight:bold">sequence</span> of two expressions,
<span style="font-style:italic">pattern</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">expression</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">expression</span><sub>2</sub>.
The semantic value produced by <span style="font-style:italic">expression</span><sub>1</sub>
is decomposed according to the pattern <span style="font-style:italic">pattern</span>.
The OCaml variables introduced by <span style="font-style:italic">pattern</span> may appear in a semantic action
that ends the sequence <span style="font-style:italic">expression</span><sub>2</sub>.</li><li class="li-itemize">A sequence <span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">id</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">expression</span><sub>2</sub>,
which is sugar for <span style="font-style:italic">id</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">id</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">expression</span><sub>2</sub>.
This is a <span style="font-weight:bold">pun</span>.
</li><li class="li-itemize">A sequence <span style="font-style:italic">expression</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">expression</span><sub>2</sub>,
which is sugar for
<span style="font-family:sans-serif"><span style="font-weight:bold">_</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">expression</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">expression</span><sub>2</sub>.</li><li class="li-itemize">A <span style="font-weight:bold">symbol</span> <span style="font-style:italic">id</span>, possibly applied to
a tuple of expressions
<span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression</span><sub>1</sub>, …, <span style="font-style:italic">expression</span><sub><span style="font-style:italic">n</span></sub>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span>.
It is worth noting that such an expression <em>can</em> form the
end of a sequence: <span style="font-style:italic">id</span> at the end of a sequence stands for
<span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <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>
for some fresh variable <span style="font-style:italic">x</span>.
Thus, a sequence need not end with a semantic action.</li><li class="li-itemize">An expression followed with <span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span>, or <span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span>. This is sugar
for the previous form: see §<a href="#sec%3Atemplates">5.2</a> and Figure <a href="#fig%3Asugar">2</a>.</li><li class="li-itemize">A <span style="font-weight:bold">semantic action</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> ,
possibly followed with a precedence annotation <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span>.
This OCaml code can refer to the variables that have been bound
earlier in the sequence that this semantic action ends.
These include all variables named by the user as well as all
variables introduced by a <span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span>  pattern as part of a pun.
The notation <span style="font-family:sans-serif"><span style="font-weight:bold">$</span></span><span style="font-style:italic">i</span>, where <span style="font-style:italic">i</span> is an integer, is forbidden.</li><li class="li-itemize">A <span style="font-weight:bold">point-free semantic action</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">OCaml id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span>,
possibly followed with a precedence annotation <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> <span style="font-style:italic">id</span>.
The OCaml identifier <span style="font-style:italic">id</span> must denote a function or a data
constructor. It is applied to a tuple of the variables that have
been bound earlier in the sequence that this semantic action ends.
Thus, <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span>  <span style="font-style:italic">id</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span>  is sugar for
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span>  <span style="font-style:italic">id</span>  (<span style="font-style:italic">x</span><sub>1</sub>, …, <span style="font-style:italic">x</span><sub><span style="font-style:italic">n</span></sub>)  <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> ,
where <span style="font-style:italic">x</span><sub>1</sub>, …, <span style="font-style:italic">x</span><sub><span style="font-style:italic">n</span></sub> are the variables bound earlier.
These include all variables named by the user as well as all
variables introduced by a <span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span>  pattern.</li><li class="li-itemize">An identity semantic action <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;&gt;</span></span>. This is sugar for
<span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">identity</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span>, where <span style="font-style:italic">identity</span> is OCaml’s
identity function.
Therefore, it is sugar for
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span>  (<span style="font-style:italic">x</span><sub>1</sub>, …, <span style="font-style:italic">x</span><sub><span style="font-style:italic">n</span></sub>)  <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> ,
where <span style="font-style:italic">x</span><sub>1</sub>, …, <span style="font-style:italic">x</span><sub><span style="font-style:italic">n</span></sub> are the variables bound earlier.
</li></ul><p>The syntax of expressions, as presented in Figure <a href="#fig%3Asyntax">1</a>, seems more
permissive than it really is. In reality, a choice cannot be nested inside a
sequence;
a sequence cannot be nested in the left-hand side of a sequence; a semantic
action cannot appear in the left-hand side of a sequence. (Thus, there is a
stratification in three levels: choice expressions, sequence expressions, and
atomic expressions, which corresponds roughly to the stratification of rules,
productions, and producers in the old syntax.)
Furthermore, an expression between parentheses
<span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span>  is <em>not</em> a valid expression.
To surround an expression with parentheses, one must write either
<span style="font-style:italic">midrule</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span>  or
<span style="font-style:italic">endrule</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> ;
see §<a href="#sec%3Alibrary">5.4</a> and Figure <a href="#fig%3Astandard">3</a>.</p><p>When a complex expression (e.g., a choice or a sequence) is placed
in parentheses, as in <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">expression</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span>, this is
equivalent to using <span style="font-style:italic">id</span> <span style="font-family:sans-serif"><span style="font-weight:bold">(</span></span>  <span style="font-style:italic">s</span> <span style="font-family:sans-serif"><span style="font-weight:bold">)</span></span> , where the fresh
symbol <span style="font-style:italic">s</span> is declared as a synonym for this expression, via the
declaration
<span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">s</span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">==</span></span></span> <span style="font-style:italic">expression</span>.
This idiom is also known as an anonymous rule (§<a href="#sec%3Aactual">4.2.4</a>).</p>
<!--TOC paragraph id="sec24" Examples-->
<h4 id="sec24" class="paragraph">Examples</h4><!--SEC END --><p>As an example of a rule in the new syntax,
the parameterized nonterminal symbol <span style="font-style:italic">option</span>,
which is part of Menhir’s standard library (§<a href="#sec%3Alibrary">5.4</a>),
can be defined as follows:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" > <span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">option</span>(<span style="font-style:italic">x</span>) <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">:=</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">None</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <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 style="font-size:small">=</span></span></span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">Some x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
Using a pun, it can also be written as follows:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" > <span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">option</span>(<span style="font-style:italic">x</span>) <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">:=</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">None</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">Some x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
Using a pun and a point-free semantic action,
it can also be expressed as follows:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" > <span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">option</span>(<span style="font-style:italic">x</span>) <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">:=</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">None</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">Some</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span>
</td></tr>
</table>
</blockquote><p>
As another example, the parameterized symbol <span style="font-style:italic">delimited</span>,
also part of Menhir’s standard library (§<a href="#sec%3Alibrary">5.4</a>),
can be defined in the new syntax as follows:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" > <span style="font-family:sans-serif"><span style="font-weight:bold">let</span></span> <span style="font-style:italic">delimited</span>(<span style="font-style:italic">opening</span>, <span style="font-style:italic">x</span>, <span style="font-style:italic">closing</span>) <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">==</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-style:italic">opening</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">~</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">=</span></span></span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-style:italic">closing</span> <span style="font-family:sans-serif"><span style="font-weight:bold">;</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;&gt;</span></span> </td></tr>
</table>
</blockquote><p>
The use of <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">==</span></span></span>  indicates that this is a macro,
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"><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-->
<h3 id="sec26" class="subsection">5.1  Splitting specifications over multiple files</h3><!--SEC END --><p>
<a id="sec:split"></a></p>
<!--TOC paragraph id="sec27" Modules-->
<h4 id="sec27" class="paragraph">Modules</h4><!--SEC END --><p>Grammar specifications can be split over multiple files. When Menhir is
invoked with multiple argument file names, it considers each of these files as
a <em>partial</em> grammar specification, and <em>joins</em> these partial
specifications in order to obtain a single, complete specification.</p><p>This feature is intended to promote a form a modularity. It is hoped that, by
splitting large grammar specifications into several “modules”, they can be
made more manageable. It is also hoped that this mechanism, in conjunction
with parameterization (§<a href="#sec%3Atemplates">5.2</a>), will promote sharing and reuse.
It should be noted, however, that this is only a weak form of
modularity. Indeed, partial specifications cannot be independently processed
(say, checked for conflicts). It is necessary to first join them, so as to
form a complete grammar specification, before any kind of grammar analysis can
be done.</p><p>This mechanism is, in fact, how Menhir’s standard library (§<a href="#sec%3Alibrary">5.4</a>)
is made available: even though its name does not appear on the command line,
it is automatically joined with the user’s explicitly-provided grammar
specifications, making the standard library’s definitions globally visible.</p><p>A partial grammar specification, or module, contains declarations and rules,
just like a complete one: there is no visible difference. Of course, it can
consist of only declarations, or only rules, if the user so chooses. (Don’t
forget the mandatory <span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> keyword that separates declarations and
rules. It must be present, even if one of the two sections is empty.)</p>
<!--TOC paragraph id="sec28" Private and public nonterminal symbols-->
<h4 id="sec28" class="paragraph">Private and public nonterminal symbols</h4><!--SEC END --><p>It should be noted that joining is <em>not</em> a purely textual process. If two
modules happen to define a nonterminal symbol by the same name, then it is
considered, by default, that this is an accidental name clash. In that case,
each of the two nonterminal symbols is silently renamed so as to avoid the
clash. In other words, by default, a nonterminal symbol defined in module <span style="font-style:italic">A</span>
is considered <em>private</em>, and cannot be defined again, or referred to, in
module <span style="font-style:italic">B</span>.</p><p>Naturally, it is sometimes desirable to define a nonterminal symbol <span style="font-style:italic">N</span> in
module <span style="font-style:italic">A</span> and to refer to it in module <span style="font-style:italic">B</span>. This is permitted if <span style="font-style:italic">N</span> is
public, that is, if either its definition carries the keyword <span style="font-family:sans-serif"><span style="font-weight:bold">%public</span></span> or
<span style="font-style:italic">N</span> is declared to be a start symbol. A public nonterminal symbol is never
renamed, so it can be referred to by modules other than its defining module.</p><p>In fact, it is permitted to split the definition of a <em>public</em> nonterminal
symbol, over multiple modules and/or within a single module.
That is, a public nonterminal symbol <span style="font-style:italic">N</span> can
have multiple definitions, within one module and/or in distinct modules.
All of these definitions are joined using the choice (<span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>) operator.
For instance, in the grammar of a
programming language, the definition of the nonterminal symbol <span style="font-style:italic">expression</span>
could be split into multiple modules, where one module groups the expression
forms that have to do with arithmetic, one module groups those that concern
function definitions and function calls, one module groups those that concern
object definitions and method calls, and so on.</p>
<!--TOC paragraph id="sec29" Tokens aside-->
<h4 id="sec29" class="paragraph">Tokens aside</h4><!--SEC END --><p>Another use of modularity consists in placing all <span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> declarations in one
module, and the actual grammar specification in another module. The module
that contains the token definitions can then be shared, making it easier to
define multiple parsers that accept the same type of tokens. (On this topic,
see <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-two"><span style="font-family:monospace">demos/calc-two</span></a>.)</p>
<!--TOC subsection id="sec30" Parameterizing rules-->
<h3 id="sec30" class="subsection">5.2  Parameterizing rules</h3><!--SEC END --><p>
<a id="sec:templates"></a></p><p>A rule (that is, the definition of a nonterminal symbol) can be parameterized
over an arbitrary number of symbols, which are referred to as formal
parameters.</p>
<!--TOC paragraph id="sec31" Example-->
<h4 id="sec31" class="paragraph">Example</h4><!--SEC END --><p>For instance, here is the definition of the parameterized
nonterminal symbol <span style="font-style:italic">option</span>, taken from the standard library (§<a href="#sec%3Alibrary">5.4</a>):
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%public</span></span> <span style="font-style:italic">option</span>(<span style="font-style:italic">X</span>):
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">None</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">x</span> = <span style="font-style:italic">X</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">Some</span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
This definition states that <span style="font-style:italic">option</span>(<span style="font-style:italic">X</span>) expands to either the empty
string, producing the semantic value <span style="font-style:italic">None</span>, or to the string <span style="font-style:italic">X</span>,
producing the semantic value <span style="font-style:italic">Some</span> <span style="font-style:italic">x</span>, where <span style="font-style:italic">x</span> is the
semantic value of <span style="font-style:italic">X</span>. In this definition, the symbol <span style="font-style:italic">X</span> is
abstract: it stands for an arbitrary terminal or nonterminal symbol. The
definition is made public, so <span style="font-style:italic">option</span> can be referred to within client
modules.</p><p>A client who wishes to use <span style="font-style:italic">option</span> simply refers to it, together with
an actual parameter – a symbol that is intended to replace <span style="font-style:italic">X</span>. For
instance, here is how one might define a sequence of declarations, preceded
with optional commas:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">declarations</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> [] <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">ds</span> = <span style="font-style:italic">declarations</span>; <span style="font-style:italic">option</span>(<span style="font-style:italic">COMMA</span>); <span style="font-style:italic">d</span> = <span style="font-style:italic">declaration</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span>  <span style="font-style:italic">d</span> :: <span style="font-style:italic">ds</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
This definition states that <span style="font-style:italic">declarations</span> expands either to the empty
string or to <span style="font-style:italic">declarations</span> followed by an optional comma followed by
<span style="font-style:italic">declaration</span>. (Here, <span style="font-style:italic">COMMA</span> is presumably a terminal symbol.)
When this rule is encountered, the definition of <span style="font-style:italic">option</span> is instantiated:
that is, a copy of the definition, where <span style="font-style:italic">COMMA</span> replaces <span style="font-style:italic">X</span>,
is produced. Things behave exactly as if one had written:</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">optional_comma</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">None</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">x</span> = <span style="font-style:italic">COMMA</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">Some</span> <span style="font-style:italic">x</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >
<span style="font-style:italic">declarations</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> [] <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">ds</span> = <span style="font-style:italic">declarations</span>; <span style="font-style:italic">optional_comma</span>; <span style="font-style:italic">d</span> = <span style="font-style:italic">declaration</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span>  <span style="font-style:italic">d</span> :: <span style="font-style:italic">ds</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
Note that, even though <span style="font-style:italic">COMMA</span> presumably has been declared as a token
with no semantic value, writing <span style="font-style:italic">x</span> = <span style="font-style:italic">COMMA</span> is legal, and binds
<span style="font-style:italic">x</span> to the unit value. This design choice ensures that the definition
of <span style="font-style:italic">option</span> makes sense regardless of the nature of <span style="font-style:italic">X</span>: that is, <span style="font-style:italic">X</span>
can be instantiated with a terminal symbol, with or without a semantic value,
or with a nonterminal symbol.</p>
<!--TOC paragraph id="sec32" Parameterization in general-->
<h4 id="sec32" class="paragraph">Parameterization in general</h4><!--SEC END --><p>In general, the definition of a nonterminal symbol <span style="font-style:italic">N</span> can be
parameterized with an arbitrary number of formal parameters. When
<span style="font-style:italic">N</span> is referred to within a production, it must be applied
to the same number of actuals. In general, an actual is:
</p><ul class="itemize"><li class="li-itemize">
either a single symbol, which can be a terminal symbol, a nonterminal symbol, or a formal parameter;
</li><li class="li-itemize">or an application of such a symbol to a number of actuals.
</li></ul><p>For instance, here is a rule whose single production consists of a single
producer, which contains several, nested actuals. (This example is discussed
again in §<a href="#sec%3Alibrary">5.4</a>.)
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">plist</span>(<span style="font-style:italic">X</span>):
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">xs</span> = <span style="font-style:italic">loption</span>(<span style="font-style:italic">delimited</span>(<span style="font-style:italic">LPAREN</span>,
<span style="font-style:italic">separated_nonempty_list</span>(<span style="font-style:italic">COMMA</span>, <span style="font-style:italic">X</span>),
<span style="font-style:italic">RPAREN</span>))
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">xs</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">actual</span><span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span> </td><td style="text-align:center;white-space:nowrap" > </td><td style="text-align:center;white-space:nowrap" >is syntactic sugar for</td><td style="text-align:center;white-space:nowrap" > </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">option</span>(<span style="font-style:italic">actual</span>) </td></tr>
<tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">actual</span><span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span> </td><td style="text-align:center;white-space:nowrap" > </td><td style="text-align:center;white-space:nowrap" >is syntactic sugar for</td><td style="text-align:center;white-space:nowrap" > </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">nonempty_list</span>(<span style="font-style:italic">actual</span>) </td></tr>
<tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">actual</span><span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span> </td><td style="text-align:center;white-space:nowrap" > </td><td style="text-align:center;white-space:nowrap" >is syntactic sugar for</td><td style="text-align:center;white-space:nowrap" > </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">list</span>(<span style="font-style:italic">actual</span>)
</td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 2: Syntactic sugar for simulating regular expressions, also known as EBNF</td></tr>
</table></div>
<a id="fig:sugar"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>
Applications of the parameterized nonterminal symbols <span style="font-style:italic">option</span>,
<span style="font-style:italic">nonempty_list</span>, and <span style="font-style:italic">list</span>, which are defined in
the standard library (§<a href="#sec%3Alibrary">5.4</a>), can be written using
a familiar, regular-expression like syntax (Figure <a href="#fig%3Asugar">2</a>).</p>
<!--TOC paragraph id="sec33" Higher-order parameters-->
<h4 id="sec33" class="paragraph">Higher-order parameters</h4><!--SEC END --><p>A formal parameter can itself expect parameters. For instance, here is a rule
that defines the syntax of procedures in an imaginary programming language:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">procedure</span>(<span style="font-style:italic">list</span>):
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">PROCEDURE</span> <span style="font-style:italic">ID</span> <span style="font-style:italic">list</span>(<span style="font-style:italic">formal</span>) <span style="font-style:italic">SEMICOLON</span> <span style="font-style:italic">block</span> <span style="font-style:italic">SEMICOLON</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
This rule states that the token <span style="font-style:italic">ID</span>, which represents the name of the
procedure, should be followed with a list of formal parameters. (The
definitions of the nonterminal symbols <span style="font-style:italic">formal</span> and <span style="font-style:italic">block</span> are not
shown.) However, because <span style="font-style:italic">list</span> is a formal parameter, as opposed to a
concrete nonterminal symbol defined elsewhere, this definition does not
specify how the list is laid out: which token, if any, is used to separate, or
terminate, list elements? is the list allowed to be empty? and so on. A more
concrete notion of procedure is obtained by instantiating the formal parameter
<span style="font-style:italic">list</span>: for instance, <span style="font-style:italic">procedure</span>(<span style="font-style:italic">plist</span>), where <span style="font-style:italic">plist</span> is the
parameterized nonterminal symbol defined earlier, is a valid application.</p>
<!--TOC paragraph id="sec34" Consistency-->
<h4 id="sec34" class="paragraph">Consistency</h4><!--SEC END --><p> Definitions and uses of parameterized nonterminal
symbols are checked for consistency before they are expanded away. In short,
it is checked that, wherever a nonterminal symbol is used, it is supplied with
actual arguments in appropriate number and of appropriate nature. This
guarantees that expansion of parameterized definitions terminates and produces
a well-formed grammar as its outcome.</p>
<!--TOC subsection id="sec35" Inlining-->
<h3 id="sec35" class="subsection">5.3  Inlining</h3><!--SEC END --><p>
<a id="sec:inline"></a></p><p>It is well-known that the following grammar of arithmetic expressions does not
work as expected: that is, in spite of the priority declarations, it has
shift/reduce conflicts.
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">int</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">INT</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> <span style="font-style:italic">PLUS</span> <span style="font-style:italic">TIMES</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> <span style="font-style:italic">PLUS</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> <span style="font-style:italic">TIMES</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">i</span> = <span style="font-style:italic">INT</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expression</span>; <span style="font-style:italic">o</span> = <span style="font-style:italic">op</span>; <span style="font-style:italic">f</span> = <span style="font-style:italic">expression</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">o</span> <span style="font-style:italic">e</span> <span style="font-style:italic">f</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">op</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">PLUS</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> ( + ) <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">TIMES</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> ( * ) <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
The trouble is, the precedence level of the production <span style="font-style:italic">expression</span>
→ <span style="font-style:italic">expression</span> <span style="font-style:italic">op</span> <span style="font-style:italic">expression</span> is undefined, and
there is no sensible way of defining it via a <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> declaration, since
the desired level really depends upon the symbol that was recognized by
<span style="font-style:italic">op</span>: was it <span style="font-style:italic">PLUS</span> or <span style="font-style:italic">TIMES</span>?</p><p>The standard workaround is to abandon the definition of <span style="font-style:italic">op</span> as a
separate nonterminal symbol, and to inline its definition into the
definition of <span style="font-style:italic">expression</span>, like this:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">i</span> = <span style="font-style:italic">INT</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expression</span>; <span style="font-style:italic">PLUS</span>; <span style="font-style:italic">f</span> = <span style="font-style:italic">expression</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e</span> + <span style="font-style:italic">f</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expression</span>; <span style="font-style:italic">TIMES</span>; <span style="font-style:italic">f</span> = <span style="font-style:italic">expression</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e</span> * <span style="font-style:italic">f</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>This avoids the shift/reduce conflict, but gives up some of the original
specification’s structure, which, in realistic situations, can be damageable.
Fortunately, Menhir offers a way of avoiding the conflict without manually
transforming the grammar, by declaring that the nonterminal symbol <span style="font-style:italic">op</span>
should be inlined:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">i</span> = <span style="font-style:italic">INT</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expression</span>; <span style="font-style:italic">o</span> = <span style="font-style:italic">op</span>; <span style="font-style:italic">f</span> = <span style="font-style:italic">expression</span>
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">o</span> <span style="font-style:italic">e</span> <span style="font-style:italic">f</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> <span style="font-style:italic">op</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">PLUS</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> ( + ) <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">TIMES</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> ( * ) <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
The <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword causes all references to <span style="font-style:italic">op</span> to be replaced with its
definition. In this example, the definition of <span style="font-style:italic">op</span> involves two
productions, one that develops to <span style="font-style:italic">PLUS</span> and one that expands to
<span style="font-style:italic">TIMES</span>, so every production that refers to <span style="font-style:italic">op</span> is effectively
turned into two productions, one that refers to <span style="font-style:italic">PLUS</span> and one that refers to
<span style="font-style:italic">TIMES</span>. After inlining, <span style="font-style:italic">op</span> disappears and <span style="font-style:italic">expression</span> has three
productions: that is, the result of inlining is exactly the manual workaround
shown above.</p><p>In some situations, inlining can also help recover a slight efficiency margin.
For instance, the definition:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> <span style="font-style:italic">plist</span>(<span style="font-style:italic">X</span>):
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">xs</span> = <span style="font-style:italic">loption</span>(<span style="font-style:italic">delimited</span>(<span style="font-style:italic">LPAREN</span>,
<span style="font-style:italic">separated_nonempty_list</span>(<span style="font-style:italic">COMMA</span>, <span style="font-style:italic">X</span>),
<span style="font-style:italic">RPAREN</span>))
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">xs</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
effectively makes <span style="font-style:italic">plist</span>(<span style="font-style:italic">X</span>) an alias for the right-hand side
<span style="font-style:italic">loption</span>(…). Without the <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword, the language
recognized by the grammar would be the same, but the LR automaton
would probably have one more state and would perform one more
reduction at run time.</p><p>The <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword does not affect the computation of positions
(§<a href="#sec%3Apositions">7</a>). The same positions are computed, regardless of
where <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keywords are placed.</p><p>If the semantic actions have side effects, the <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword <em>can</em>
affect the order in which these side effects take place. In the example of
<span style="font-style:italic">op</span> and <span style="font-style:italic">expression</span> above, if for some reason the semantic action
associated with <span style="font-style:italic">op</span> has a side effect (such as updating a global variable,
or printing a message), then, by inlining <span style="font-style:italic">op</span>, we delay this side effect,
which takes place <em>after</em> the second operand has been recognized, whereas
in the absence of inlining it takes place as soon as the operator has been
recognized.</p>
<!--TOC subsection id="sec36" The standard library-->
<h3 id="sec36" class="subsection">5.4  The standard library</h3><!--SEC END --><p>
<a id="sec:library"></a></p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;white-space:nowrap" >Name</td><td style="vertical-align:top;text-align:left;" >Recognizes</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >Produces</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >Comment </td></tr>
<tr><td class="hbar" colspan=4></td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">endrule</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α, if <span style="font-style:italic">X</span> : α</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(inlined) </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">midrule</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α, if <span style="font-style:italic">X</span> : α </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">option</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >є <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">option</span>, if <span style="font-style:italic">X</span> : α</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(also <span style="font-style:italic">X</span><span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span>) </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">ioption</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >є <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">option</span>, if <span style="font-style:italic">X</span> : α</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(inlined) </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">boption</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >є <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">bool</span> </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">loption</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >є <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α <span style="font-style:italic">list</span> </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">pair</span>(<span style="font-style:italic">X</span>, <span style="font-style:italic">Y</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span> <span style="font-style:italic">Y</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α×β, if <span style="font-style:italic">X</span> : α and <span style="font-style:italic">Y</span> : β </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">separated_pair</span>(<span style="font-style:italic">X</span>, <span style="font-style:italic">sep</span>, <span style="font-style:italic">Y</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span> <span style="font-style:italic">sep</span> <span style="font-style:italic">Y</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α×β,
if <span style="font-style:italic">X</span> : α and <span style="font-style:italic">Y</span> : β </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">preceded</span>(<span style="font-style:italic">opening</span>, <span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">opening</span> <span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α, if <span style="font-style:italic">X</span> : α </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">terminated</span>(<span style="font-style:italic">X</span>, <span style="font-style:italic">closing</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span> <span style="font-style:italic">closing</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α, if <span style="font-style:italic">X</span> : α </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">delimited</span>(<span style="font-style:italic">opening</span>, <span style="font-style:italic">X</span>, <span style="font-style:italic">closing</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">opening</span> <span style="font-style:italic">X</span> <span style="font-style:italic">closing</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α, if <span style="font-style:italic">X</span> : α </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">list</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >a possibly empty sequence of <span style="font-style:italic">X</span>’s</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(also <span style="font-style:italic">X</span><span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span>) </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">nonempty_list</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >a nonempty sequence of <span style="font-style:italic">X</span>’s</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(also <span style="font-style:italic">X</span><span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span>) </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">separated_list</span>(<span style="font-style:italic">sep</span>, <span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >a possibly empty sequence of <span style="font-style:italic">X</span>’s separated with <span style="font-style:italic">sep</span>’s</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">separated_nonempty_list</span>(<span style="font-style:italic">sep</span>, <span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" >a nonempty sequence of <span style="font-style:italic">X</span>’s   separated with <span style="font-style:italic">sep</span>’s</td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α </td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">rev</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α <span style="font-style:italic">list</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(inlined)
</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">flatten</span>(<span style="font-style:italic">X</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span> : α <span style="font-style:italic">list</span> <span style="font-style:italic">list</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(inlined)
</td></tr>
<tr><td style="vertical-align:top;text-align:left;white-space:nowrap" ><span style="font-style:italic">append</span>(<span style="font-style:italic">X</span>, <span style="font-style:italic">Y</span>)</td><td style="vertical-align:top;text-align:left;" ><span style="font-style:italic">X</span> <span style="font-style:italic">Y</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >α <span style="font-style:italic">list</span>, if <span style="font-style:italic">X</span>, <span style="font-style:italic">Y</span> : α <span style="font-style:italic">list</span></td><td style="vertical-align:top;text-align:left;white-space:nowrap" >(inlined)
</td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 3: Summary of the standard library; see <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/src/standard.mly"><span style="font-family:monospace">standard.mly</span></a> for details</td></tr>
</table></div>
<a id="fig:standard"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>Once equipped with a rudimentary module system (§<a href="#sec%3Asplit">5.1</a>),
parameterization (§<a href="#sec%3Atemplates">5.2</a>), and inlining (§<a href="#sec%3Ainline">5.3</a>), it
is straightforward to propose a collection of commonly used definitions, such
as options, sequences, lists, and so on. This <em>standard library</em> is
joined, by default, with every grammar specification. A summary of the
nonterminal symbols offered by the standard library appears in
Figure <a href="#fig%3Astandard">3</a>. See also the short-hands documented in
Figure <a href="#fig%3Asugar">2</a>.</p><p>By relying on the standard library, a client module can concisely define
more elaborate notions. For instance, the following rule:
</p><blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> <span style="font-style:italic">plist</span>(<span style="font-style:italic">X</span>):
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">xs</span> = <span style="font-style:italic">loption</span>(<span style="font-style:italic">delimited</span>(<span style="font-style:italic">LPAREN</span>,
<span style="font-style:italic">separated_nonempty_list</span>(<span style="font-style:italic">COMMA</span>, <span style="font-style:italic">X</span>),
<span style="font-style:italic">RPAREN</span>))
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">xs</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote><p>
causes <span style="font-style:italic">plist</span>(<span style="font-style:italic">X</span>) to recognize a list of <span style="font-style:italic">X</span>’s, where the empty
list is represented by the empty string, and a non-empty list is delimited
with parentheses and comma-separated.</p><p>The standard library is stored in a file named <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/src/standard.mly"><span style="font-family:monospace">standard.mly</span></a>, which is
embedded inside Menhir when it is built.
The command line switch <span style="font-family:monospace">--no-stdlib</span> instructs Menhir to <em>not</em> load the
standard library.</p><p>The meaning of the symbols defined in the standard library
(Figure <a href="#fig%3Astandard">3</a>) should be clear in most cases. Yet, the
symbols <span style="font-style:italic">endrule</span>(<span style="font-style:italic">X</span>) and <span style="font-style:italic">midrule</span>(<span style="font-style:italic">X</span>) deserve an explanation.
Both take an argument <span style="font-style:italic">X</span>, which typically will be instantiated with an
anonymous rule (§<a href="#sec%3Aactual">4.2.4</a>). Both are defined as a synonym
for <span style="font-style:italic">X</span>. In both cases, this allows placing an anonymous subrule in the
middle of a rule.</p><p>For instance, the following is a well-formed production:
</p><table class="display dcenter"><tr style="vertical-align:middle"><td class="dcell"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" >  <span style="font-style:italic">cat</span>   
<span style="font-style:italic">endrule</span>(<span style="font-style:italic">dog</span>    <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>)   
<span style="font-style:italic">cow</span>   
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>2</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table></td></tr>
</table><p>
This production consists of three producers, namely
<span style="font-style:italic">cat</span> and
<span style="font-style:italic">endrule</span>(<span style="font-style:italic">dog</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>) and
<span style="font-style:italic">cow</span>,
and a semantic action <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>2</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>.
Because <span style="font-style:italic">endrule</span>(<span style="font-style:italic">X</span>) is declared as an <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> synonym for <span style="font-style:italic">X</span>,
the expansion of anonymous rules (§<a href="#sec%3Aactual">4.2.4</a>), followed with the
expansion of <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> symbols (§<a href="#sec%3Ainline">5.3</a>), transforms the above
production into the following:
</p><table class="display dcenter"><tr style="vertical-align:middle"><td class="dcell"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" >  <span style="font-style:italic">cat</span>   
<span style="font-style:italic">dog</span>   
<span style="font-style:italic">cow</span>   
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>1</sub><span style="font-style:italic">; OCaml code</span><sub>2</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table></td></tr>
</table><p>
Note that <span style="font-style:italic">OCaml code</span><sub>1</sub> moves to the end of the rule, which means that
this code is executed only after <span style="font-style:italic">cat</span>, <span style="font-style:italic">dog</span> and <span style="font-style:italic">cow</span> have
been recognized. In this example, the use of <span style="font-style:italic">endrule</span> is rather pointless,
as the expanded code is more concise and clearer than the original code. Still,
<span style="font-style:italic">endrule</span> can be useful when its actual argument is an anonymous rule with
multiple branches.</p><p><span style="font-style:italic">midrule</span> is used in exactly the same way as <span style="font-style:italic">endrule</span>, but its expansion
is different. For instance, the following is a well-formed production:
</p><table class="display dcenter"><tr style="vertical-align:middle"><td class="dcell"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" >  <span style="font-style:italic">cat</span>   
<span style="font-style:italic">midrule</span>(<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>)   
<span style="font-style:italic">cow</span>   
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>2</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table></td></tr>
</table><p>
(There is no <span style="font-style:italic">dog</span> in this example; this is intentional.)
Because <span style="font-style:italic">midrule</span>(<span style="font-style:italic">X</span>) is a synonym for <span style="font-style:italic">X</span>, but is not declared
<span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span>, the expansion of anonymous rules (§<a href="#sec%3Aactual">4.2.4</a>), followed
with the expansion of <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> symbols (§<a href="#sec%3Ainline">5.3</a>), transforms the
above production into the following:
</p><table class="display dcenter"><tr style="vertical-align:middle"><td class="dcell"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" >  <span style="font-style:italic">cat</span>   
<span style="font-style:italic">xxx</span>   
<span style="font-style:italic">cow</span>   
<span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>2</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table></td></tr>
</table><p>
where the fresh nonterminal symbol <span style="font-style:italic">xxx</span> is separately defined by the
rule <span style="font-style:italic">xxx</span>: <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">OCaml code</span><sub>1</sub> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> . Thus, <span style="font-style:italic">xxx</span> recognizes
the empty string, and as soon as it is recognized, <span style="font-style:italic">OCaml code</span><sub>1</sub>
is executed. This is known as a “mid-rule action”.</p>
<!--TOC section id="sec37" Conflicts-->
<h2 id="sec37" class="section">6  Conflicts</h2><!--SEC END --><p>
<a id="sec:conflicts"></a></p><p>When a shift/reduce or reduce/reduce conflict is detected, it is classified as
either benign, if it can be resolved by consulting user-supplied precedence
declarations, or severe, if it cannot. Benign conflicts are not reported.
Severe conflicts are reported and, if the <span style="font-family:monospace">--explain</span> switch is on, explained.</p>
<!--TOC subsection id="sec38" When is a conflict benign?-->
<h3 id="sec38" class="subsection">6.1  When is a conflict benign?</h3><!--SEC END --><p>
<a id="sec:conflicts:benign"></a></p><p>A shift/reduce conflict involves a single token (the one that one might wish
to shift) and one or more productions (those that one might wish to
reduce). When such a conflict is detected, the precedence level
(§<a href="#sec%3Aassoc">4.1.4</a>, §<a href="#sec%3Aprec">4.2.1</a>) of these entities are looked up and
compared as follows:
</p><ol class="enumerate" type=1><li class="li-enumerate">
if only one production is involved, and if it has higher priority
than the token, then the conflict is resolved in favor of reduction.
</li><li class="li-enumerate">if only one production is involved, and if it has the same priority
as the token, then the associativity status of the token is looked up:
<ol class="enumerate" type=a><li class="li-enumerate">
if the token was declared nonassociative, then the conflict is
resolved in favor of neither action, that is, a syntax error
	 will be signaled if this token shows up when this production
	 is about to be reduced;
</li><li class="li-enumerate">if the token was declared left-associative, then the conflict
is resolved in favor of reduction;
</li><li class="li-enumerate">if the token was declared right-associative, then the conflict
is resolved in favor of shifting.
</li></ol>
</li><li class="li-enumerate"><a id="multiway"></a>
if multiple productions are involved, and if, considered one by one,
they all cause the conflict to be resolved in the same way (that is,
either in favor in shifting, or in favor of neither), then the conflict
is resolved in that way.
</li></ol><p>
In either of these cases, the conflict is considered benign. Otherwise, it is
considered severe. Note that a reduce/reduce conflict is always considered
severe, unless it happens to be subsumed by a benign multi-way shift/reduce
conflict (item <a href="#multiway">3</a> above).</p>
<!--TOC subsection id="sec39" How are severe conflicts explained?-->
<h3 id="sec39" class="subsection">6.2  How are severe conflicts explained?</h3><!--SEC END --><p>When the <span style="font-family:monospace">--dump</span> switch is on, a description of the automaton is written to the
<span style="font-family:monospace">.automaton</span> file. Severe conflicts are shown as part of this description.
Fortunately, there is also a way of understanding conflicts in terms of the
grammar, rather than in terms of the automaton. When the <span style="font-family:monospace">--explain</span> switch is
on, a textual explanation is written to the <span style="font-family:monospace">.conflicts</span> file.</p><p><em>Not all conflicts are explained</em> in this file: instead, <em>only one conflict per
automaton state is explained</em>. This is done partly in the interest of brevity,
but also because Pager’s algorithm can create artificial conflicts in a state
that already contains a true LR(1) conflict; thus, one cannot hope in general
to explain all of the conflicts that appear in the automaton. As a result of
this policy, once all conflicts explained in the <span style="font-family:monospace">.conflicts</span> file have been
fixed, one might need to run Menhir again to produce yet more conflict
explanations.</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> <span style="font-style:italic">IF THEN ELSE</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">expression</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  …
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">IF b</span> = <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN e</span> = <span style="font-style:italic">expression</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">IF b</span> = <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN e</span> = <span style="font-style:italic">expression</span> <span style="font-style:italic">ELSE f</span> = <span style="font-style:italic">expression</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> … <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  …
</td></tr>
</table>
</blockquote>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 4: Basic example of a shift/reduce conflict</td></tr>
</table></div>
<a id="fig:basicshiftreduce"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote>
<!--TOC paragraph id="sec40" How the conflict state is reached-->
<h4 id="sec40" class="paragraph">How the conflict state is reached</h4><!--SEC END --><p>Figure <a href="#fig%3Abasicshiftreduce">4</a> shows a grammar specification
with a typical shift/reduce conflict.
When this specification is analyzed, the conflict is detected, and an
explanation is written to the <span style="font-family:monospace">.conflicts</span> file. The explanation first indicates
in which state the conflict lies by showing how that state is reached. Here,
it is reached after recognizing the following string of terminal and
nonterminal symbols—the <em>conflict string</em>:
</p><blockquote class="quote">
<span style="font-style:italic">IF expression THEN IF expression THEN expression</span>
</blockquote><p>Allowing the conflict string to contain both nonterminal and terminal symbols
usually makes it shorter and more readable. If desired, a conflict string
composed purely of terminal symbols could be obtained by replacing each
occurrence of a nonterminal symbol <span style="font-style:italic">N</span> with an arbitrary <span style="font-style:italic">N</span>-sentence.</p><p>The conflict string can be thought of as a path that leads from one of the
automaton’s start states to the conflict state. When multiple such paths
exist, the one that is displayed is chosen shortest. Nevertheless, it may
sometimes be quite long. In that case, artificially (and temporarily)
declaring some existing nonterminal symbols to be start symbols has the effect
of adding new start states to the automaton and can help produce shorter
conflict strings. Here, <span style="font-style:italic">expression</span> was declared to be a start symbol,
which is why the conflict string is quite short.</p><p>In addition to the conflict string, the <span style="font-family:monospace">.conflicts</span> file also states that the
<em>conflict token</em> is <span style="font-style:italic">ELSE</span>. That is, when the automaton has recognized
the conflict string and when the lookahead token (the next token on the input
stream) is <span style="font-style:italic">ELSE</span>, a conflict arises. A conflict corresponds to a
choice: the automaton is faced with several possible actions, and does not
know which one should be taken. This indicates that the grammar is not LR(1).
The grammar may or may not be inherently ambiguous.</p><p>In our example, the conflict string and the conflict token are enough to
understand why there is a conflict: when two <span style="font-style:italic">IF</span> constructs are nested,
it is ambiguous which of the two constructs the
<span style="font-style:italic">ELSE</span> branch should be associated with. Nevertheless, the <span style="font-family:monospace">.conflicts</span> file
provides further information: it explicitly shows that there exists a
conflict, by proving that two distinct actions are possible. Here, one of
these actions consists in <em>shifting</em>, while the other consists in
<em>reducing</em>: this is a <em>shift/reduce</em> conflict.</p><p>A <em>proof</em> takes the form of a <em>partial derivation tree</em> whose
<em>fringe</em> begins with the conflict string, followed by the conflict
token. A derivation tree is a tree whose nodes are labeled with symbols. The
root node carries a start symbol. A node that carries a terminal symbol is
considered a leaf, and has no children. A node that carries a nonterminal
symbol <span style="font-style:italic">N</span> either is considered a leaf, and has no children; or is not
considered a leaf, and has <span style="font-style:italic">n</span> children, where <span style="font-style:italic">n</span>≥ 0, labeled
<span style="font-style:italic">x</span><sub>1</sub>,…,<span style="font-style:italic">x</span><sub><span style="font-style:italic">n</span></sub>, where <span style="font-style:italic">N</span> →
<span style="font-style:italic">x</span><sub>1</sub>,…,<span style="font-style:italic">x</span><sub><span style="font-style:italic">n</span></sub> is a production. The fringe of a partial
derivation tree is the string of terminal and nonterminal symbols carried by
the tree’s leaves. A string of terminal and nonterminal symbols that is the
fringe of some partial derivation tree is a <em>sentential form</em>.</p>
<!--TOC paragraph id="sec41" Why shifting is legal-->
<h4 id="sec41" class="paragraph">Why shifting is legal</h4><!--SEC END --><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>



<div class="center">


<img src="manual001.png">

</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 5: A partial derivation tree that justifies shifting</td></tr>
</table></div>
<a id="fig:shifting:tree"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border:0;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left;white-space:nowrap" >
</td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">IF</span> <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN</span> </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">IF</span> <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN</span> <span style="font-style:italic">expression</span>
. <span style="font-style:italic">ELSE</span> <span style="font-style:italic">expression</span>
</td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 6: A textual version of the tree in Figure <a href="#fig%3Ashifting%3Atree">5</a></td></tr>
</table></div>
<a id="fig:shifting:text"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>In our example, the proof that shifting is possible is the derivation tree
shown in Figures <a href="#fig%3Ashifting%3Atree">5</a> and <a href="#fig%3Ashifting%3Atext">6</a>. At the
root of the tree is the grammar’s start symbol, <span style="font-style:italic">expression</span>. This symbol
develops into the string <span style="font-style:italic">IF expression THEN expression</span>, which forms the
tree’s second level. The second occurrence of <span style="font-style:italic">expression</span> in that string
develops into <span style="font-style:italic">IF expression THEN expression ELSE expression</span>, which forms
the tree’s last level. The tree’s fringe, a sentential form, is the string
<span style="font-style:italic">IF expression THEN IF expression THEN expression ELSE expression</span>. As
announced earlier, it begins with the conflict string <span style="font-style:italic">IF expression THEN
IF expression THEN expression</span>, followed with the conflict token
<span style="font-style:italic">ELSE</span>.</p><p>In Figure <a href="#fig%3Ashifting%3Atext">6</a>, the end of the conflict string is materialized
with a dot. Note that this dot does not occupy the rightmost position in the
tree’s last level. In other words, the conflict token (<span style="font-style:italic">ELSE</span>) itself
occurs on the tree’s last level. In practical terms, this means that, after
the automaton has recognized the conflict string and peeked at the conflict
token, it makes sense for it to <em>shift</em> that token.</p>
<!--TOC paragraph id="sec42" Why reducing is legal-->
<h4 id="sec42" class="paragraph">Why reducing is legal</h4><!--SEC END --><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>



<div class="center">


<img src="manual002.png">

</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 7: A partial derivation tree that justifies reducing</td></tr>
</table></div>
<a id="fig:reducing:tree"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border:0;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left;white-space:nowrap" >
</td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">IF</span> <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN</span> </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expression</span> <span style="font-style:italic">ELSE</span> <span style="font-style:italic">expression</span>
      <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead token appears</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">IF</span> <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN</span> <span style="font-style:italic">expression</span> .
</td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 8: A textual version of the tree in Figure <a href="#fig%3Areducing%3Atree">7</a></td></tr>
</table></div>
<a id="fig:reducing:text"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>In our example, the proof that reducing is possible is the derivation tree
shown in Figures <a href="#fig%3Areducing%3Atree">7</a> and <a href="#fig%3Areducing%3Atext">8</a>. Again,
the sentential form found at the fringe of the tree begins with the conflict
string, followed with the conflict token.</p><p>Again, in Figure <a href="#fig%3Areducing%3Atext">8</a>, the end of the conflict string is
materialized with a dot. Note that, this time, the dot occupies the rightmost
position in the tree’s last level. In other words, the conflict token
(<span style="font-style:italic">ELSE</span>) appeared on an earlier level (here, on the second level). This
fact is emphasized by the comment <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead token appears</span></span></span>
found at the second level. In practical terms, this means that, after the
automaton has recognized the conflict string and peeked at the conflict token,
it makes sense for it to <em>reduce</em> the production that corresponds to the
tree’s last level—here, the production is <span style="font-style:italic">expression</span> →
<span style="font-style:italic">IF</span> <span style="font-style:italic">expression</span> <span style="font-style:italic">THEN</span> <span style="font-style:italic">expression</span>.</p>
<!--TOC paragraph id="sec43" An example of a more complex derivation tree-->
<h4 id="sec43" class="paragraph">An example of a more complex derivation tree</h4><!--SEC END --><p>Figures <a href="#fig%3Axreducing%3Atree">9</a> and <a href="#fig%3Axreducing%3Atext">10</a> show a partial
derivation tree that justifies reduction in a more complex situation. (This
derivation tree is relative to a grammar that is not shown.) Here, the
conflict string is <span style="font-style:italic">DATA UIDENT EQUALS UIDENT</span>; the conflict token is
<span style="font-style:italic">LIDENT</span>. It is quite clear that the fringe of the tree begins with the
conflict string. However, in this case, the fringe does not explicitly
exhibit the conflict token. Let us examine the tree more closely and answer
the question: following <span style="font-style:italic">UIDENT</span>, what’s the next terminal symbol on the
fringe?</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>



<div class="center">


<img src="manual003.png">

</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 9: A partial derivation tree that justifies reducing</td></tr>
</table></div>
<a id="fig:xreducing:tree"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border:0;border-spacing:0" class="cellpadding1"><tr><td style="text-align:left;white-space:nowrap" >
</td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">decls</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">decl</span> <span style="font-style:italic">opt_semi</span> <span style="font-style:italic">decls</span>
      <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead token appears because </span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"><span style="font-style:italic">opt_semi</span></span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"> can vanish
and </span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"><span style="font-style:italic">decls</span></span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"> can begin with </span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"><span style="font-style:italic">LIDENT</span></span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">DATA UIDENT</span> <span style="font-style:italic">EQUALS</span> </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">tycon_expr</span>
      <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead token is inherited</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">tycon_item</span>       <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead token is inherited</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">UIDENT</span> </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">opt_type_exprs</span>       <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead token is inherited</span></span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" ></td><td style="text-align:left;white-space:nowrap" >.
</td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 10: A textual version of the tree in Figure <a href="#fig%3Axreducing%3Atree">9</a></td></tr>
</table></div>
<a id="fig:xreducing:text"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>First, note that <span style="font-style:italic">opt_type_exprs</span> is <em>not</em> a leaf node, even though
it has no children. The grammar contains the production <span style="font-style:italic">opt_type_exprs</span>
→ є: the nonterminal symbol <span style="font-style:italic">opt_type_exprs</span> develops
to the empty string. (This is made clear in Figure <a href="#fig%3Axreducing%3Atext">10</a>, where a
single dot appears immediately below <span style="font-style:italic">opt_type_exprs</span>.) Thus,
<span style="font-style:italic">opt_type_exprs</span> is not part of the fringe.</p><p>Next, note that <span style="font-style:italic">opt_type_exprs</span> is the rightmost symbol within its
level. Thus, in order to find the next symbol on the fringe, we have to look
up one level. This is the meaning of the comment <span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// lookahead
token is inherited</span></span></span>. Similarly, <span style="font-style:italic">tycon_item</span> and <span style="font-style:italic">tycon_expr</span> appear
rightmost within their level, so we again have to look further up.</p><p>This brings us back to the tree’s second level. There, <span style="font-style:italic">decl</span> is <em>not</em>
the rightmost symbol: next to it, we find <span style="font-style:italic">opt_semi</span> and <span style="font-style:italic">decls</span>. Does
this mean that <span style="font-style:italic">opt_semi</span> is the next symbol on the fringe? Yes and no.
<span style="font-style:italic">opt_semi</span> is a <em>nonterminal</em> symbol, but we are really interested in finding
out what the next <em>terminal</em> symbol on the fringe could be. The partial
derivation tree shown in Figures <a href="#fig%3Axreducing%3Atree">9</a>
and <a href="#fig%3Axreducing%3Atext">10</a> does not explicitly answer this question. In
order to answer it, we need to know more about <span style="font-style:italic">opt_semi</span> and <span style="font-style:italic">decls</span>.</p><p>Here, <span style="font-style:italic">opt_semi</span> stands (as one might have guessed) for an optional
semicolon, so the grammar contains a production <span style="font-style:italic">opt_semi</span> →
є. This is indicated by the comment
<span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// </span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"><span style="font-style:italic">opt_semi</span></span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"> can vanish</span></span></span>. (Nonterminal symbols
that generate є are also said to be <em>nullable</em>.) Thus, one could
choose to turn this partial derivation tree into a larger one by developing
<span style="font-style:italic">opt_semi</span> into є, making it a non-leaf node. That would yield
a new partial derivation tree where the next symbol on the fringe, following
<span style="font-style:italic">UIDENT</span>, is <span style="font-style:italic">decls</span>.</p><p>Now, what about <span style="font-style:italic">decls</span>? Again, it is a <em>nonterminal</em> symbol, and we
are really interested in finding out what the next <em>terminal</em> symbol on
the fringe could be. Again, we need to imagine how this partial derivation
tree could be turned into a larger one by developing <span style="font-style:italic">decls</span>. Here, the
grammar happens to contain a production of the form <span style="font-style:italic">decls</span> →
<span style="font-style:italic">LIDENT</span> … This is indicated by the comment
<span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small">// </span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"><span style="font-style:italic">decls</span></span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"> can begin with </span></span></span><span style="font-style:italic"><span style="font-weight:bold"><span style="font-size:small"><span style="font-style:italic">LIDENT</span></span></span></span>.
Thus, by developing <span style="font-style:italic">decls</span>, it is possible to construct a partial
derivation tree where the next symbol on the fringe, following
<span style="font-style:italic">UIDENT</span>, is <span style="font-style:italic">LIDENT</span>. This is precisely the conflict
token.</p><p>To sum up, there exists a partial derivation tree whose
fringe begins with the conflict string, followed with the conflict token.
Furthermore, in that derivation tree, the dot occupies the rightmost position
in the last level. As in our previous example, this means that, after the
automaton has recognized the conflict string and peeked at the conflict token,
it makes sense for it to <em>reduce</em> the production that corresponds to the
tree’s last level—here, the production is <span style="font-style:italic">opt_type_exprs</span>
→ є.</p>
<!--TOC paragraph id="sec44" Greatest common factor among derivation trees-->
<h4 id="sec44" class="paragraph">Greatest common factor among derivation trees</h4><!--SEC END --><p>Understanding conflicts requires comparing two (or more) derivation trees. It
is frequent for these trees to exhibit a common factor, that is, to exhibit
identical structure near the top of the tree, and to differ only below a
specific node. Manual identification of that node can be tedious, so Menhir performs this work automatically. When explaining a <span style="font-style:italic">n</span>-way conflict, it first
displays the greatest common factor of the <span style="font-style:italic">n</span> derivation trees. A question
mark symbol <span style="font-style:italic">(?)</span> is used to identify the node where the trees begin
to differ. Then, Menhir displays each of the <span style="font-style:italic">n</span> derivation trees,
<em>without their common factor</em> – that is, it displays <span style="font-style:italic">n</span> sub-trees that
actually begin to differ at the root. This should make visual comparisons
significantly easier.</p>
<!--TOC subsection id="sec45" How are severe conflicts resolved in the end?-->
<h3 id="sec45" class="subsection">6.3  How are severe conflicts resolved in the end?</h3><!--SEC END --><p>It is unspecified how severe conflicts are resolved. Menhir attempts to mimic
<span style="font-family:monospace">ocamlyacc</span>’s specification, that is, to resolve shift/reduce conflicts in favor
of shifting, and to resolve reduce/reduce conflicts in favor of the production
that textually appears earliest in the grammar specification. However, this
specification is inconsistent in case of three-way conflicts, that is,
conflicts that simultaneously involve a shift action and several reduction
actions. Furthermore, textual precedence can be undefined when the grammar
specification is split over multiple modules. In short, Menhir’s philosophy is
that
</p><div class="center">
severe conflicts should not be tolerated,
</div><p>
so you should not care how they are resolved.</p>
<!--TOC subsection id="sec46" End-of-stream conflicts-->
<h3 id="sec46" class="subsection">6.4  End-of-stream conflicts</h3><!--SEC END --><p>
<a id="sec:eos"></a></p><p>Menhir’s treatment of the end of the token stream is (believed to be) fully compatible
with <span style="font-family:monospace">ocamlyacc</span>’s. Yet, Menhir attempts to be more user-friendly by warning
about a class of so-called “end-of-stream conflicts”.</p>
<!--TOC paragraph id="sec47" How the end of stream is handled-->
<h4 id="sec47" class="paragraph">How the end of stream is handled</h4><!--SEC END --><p>In many textbooks on parsing, it is assumed that the lexical analyzer, which
produces the token stream, produces a special token, written <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span>, to signal
that the end of the token stream has been reached. A parser generator can take
advantage of this by transforming the grammar: for each start symbol <span style="font-style:italic">S</span>
in the original grammar, a new start symbol <span style="font-style:italic">S’</span> is defined, together
with the production <span style="font-style:italic">S</span>′→ <span style="font-style:italic">S</span><span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> . The symbol <span style="font-style:italic">S</span> is no longer a start
symbol in the new grammar. This means that the parser will accept a sentence
derived from <span style="font-style:italic">S</span> only if it is immediately followed by the end of the token
stream.</p><p>This approach has the advantage of simplicity. However, <span style="font-family:monospace">ocamlyacc</span> and Menhir do not follow it, for several reasons. Perhaps the most convincing one is that
it is not flexible enough: sometimes, it is desirable to recognize a sentence
derived from <span style="font-style:italic">S</span>, <em>without</em> requiring that it be followed by the end of
the token stream: this is the case, for instance, when reading commands, one
by one, on the standard input channel. In that case, there is no end of stream:
the token stream is conceptually infinite. Furthermore, after a command has
been recognized, we do <em>not</em> wish to examine the next token, because
doing so might cause the program to block, waiting for more input.</p><p>In short, <span style="font-family:monospace">ocamlyacc</span> and Menhir’s approach is to recognize a sentence derived
from <span style="font-style:italic">S</span> and to <em>not look</em>, if possible, at what follows. However, this
is possible only if the definition of <span style="font-style:italic">S</span> is such that the end of an
<span style="font-style:italic">S</span>-sentence is identifiable without knowledge of the lookahead token. When
the definition of <span style="font-style:italic">S</span> does not satisfy this criterion, and <em>end-of-stream
conflict</em> arises: after a potential <span style="font-style:italic">S</span>-sentence has been read, there can be a
tension between consulting the next token, in order to determine whether the
sentence is continued, and <em>not</em> consulting the next token, because the
sentence might be over and whatever follows should not be read. Menhir warns
about end-of-stream conflicts, whereas <span style="font-family:monospace">ocamlyacc</span> does not.</p>
<!--TOC paragraph id="sec48" A definition of end-of-stream conflicts-->
<h4 id="sec48" class="paragraph">A definition of end-of-stream conflicts</h4><!--SEC END --><p>Technically, Menhir proceeds as follows. A <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> symbol is introduced. It is,
however, only a <em>pseudo-</em>token: it is never produced by the lexical
analyzer. For each start symbol <span style="font-style:italic">S</span> in the original grammar, a new start
symbol <span style="font-style:italic">S’</span> is defined, together with the production <span style="font-style:italic">S</span>′→ <span style="font-style:italic">S</span>.
The corresponding start state of the LR(1) automaton is composed of the LR(1)
item <span style="font-style:italic">S</span>′ → .  <span style="font-style:italic">S</span>  [<span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> ]. That is, the pseudo-token <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> initially
appears in the lookahead set, indicating that we expect to be done after
recognizing an <span style="font-style:italic">S</span>-sentence. During the construction of the LR(1) automaton,
this lookahead set is inherited by other items, with the effect that, in the
end, the automaton has:
</p><ul class="itemize"><li class="li-itemize">
<em>shift</em> actions only on physical tokens; and
</li><li class="li-itemize"><em>reduce</em> actions either on physical tokens or on the pseudo-token <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span>.
</li></ul><p>
A state of the automaton has a reduce action on <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> if, in that state, an
<span style="font-style:italic">S</span>-sentence has been read, so that the job is potentially finished. A state
has a shift or reduce action on a physical token if, in that state, more
tokens potentially need to be read before an <span style="font-style:italic">S</span>-sentence is recognized. If a
state has a reduce action on <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span>, then that action should be taken
<em>without</em> requesting the next token from the lexical analyzer. On the
other hand, if a state has a shift or reduce action on a physical token, then
the lookahead token <em>must</em> be consulted in order to determine if that
action should be taken.</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">int</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">INT</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> <span style="font-style:italic">PLUS TIMES</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> PLUS </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> TIMES </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">int</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">expr</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expr</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">i</span> = <span style="font-style:italic">INT</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e1</span> = <span style="font-style:italic">expr</span> <span style="font-style:italic">PLUS</span> <span style="font-style:italic">e2</span> = <span style="font-style:italic">expr</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e1 + e2</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e1</span> = <span style="font-style:italic">expr</span> <span style="font-style:italic">TIMES</span> <span style="font-style:italic">e2</span> = <span style="font-style:italic">expr</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e1 * e2</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span>
</td></tr>
</table>
</blockquote>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 11: Basic example of an end-of-stream conflict</td></tr>
</table></div>
<a id="fig:basiceos"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">State 6:
expr -&gt; expr . PLUS expr [ # TIMES PLUS ]
expr -&gt; expr PLUS expr . [ # TIMES PLUS ]
expr -&gt; expr . TIMES expr [ # TIMES PLUS ]
-- On TIMES shift to state 3
-- On # PLUS reduce production expr -&gt; expr PLUS expr

State 4:
expr -&gt; expr . PLUS expr [ # TIMES PLUS ]
expr -&gt; expr . TIMES expr [ # TIMES PLUS ]
expr -&gt; expr TIMES expr . [ # TIMES PLUS ]
-- On # TIMES PLUS reduce production expr -&gt; expr TIMES expr

State 2:
expr' -&gt; expr . [ # ]
expr -&gt; expr . PLUS expr [ # TIMES PLUS ]
expr -&gt; expr . TIMES expr [ # TIMES PLUS ]
-- On TIMES shift to state 3
-- On PLUS shift to state 5
-- On # accept expr
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 12: Part of an LR automaton for the grammar in Figure <a href="#fig%3Abasiceos">11</a></td></tr>
</table></div>
<a id="fig:basiceosdump"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<blockquote class="quote">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" >…</td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> <span style="font-style:italic">END</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> <span style="font-family:sans-serif"><span style="font-weight:bold">&lt;</span></span> <span style="font-style:italic">int</span> <span style="font-family:sans-serif"><span style="font-weight:bold">&gt;</span></span> <span style="font-style:italic">main</span>     <span style="font-style:italic">// instead of </span><span style="font-style:italic">expr</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">%%</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">main</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  <span style="font-style:italic">e</span> = <span style="font-style:italic">expr</span> <span style="font-style:italic">END</span> <span style="font-family:sans-serif"><span style="font-weight:bold">{</span></span> <span style="font-style:italic">e</span> <span style="font-family:sans-serif"><span style="font-weight:bold">}</span></span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">expr</span>:
</td></tr>
<tr><td style="text-align:left;white-space:nowrap" >   <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span>  …</td></tr>
</table>
</blockquote>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 13: Fixing the grammar specification in Figure <a href="#fig%3Abasiceos">11</a></td></tr>
</table></div>
<a id="fig:basiceos:sol"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>An end-of-stream conflict arises when a state has distinct actions on <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> and
on at least one physical token. In short, this means that the end of an
<span style="font-style:italic">S</span>-sentence cannot be unambiguously identified without examining one extra
token. Menhir’s default behavior, in that case, is to suppress the action on
<span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span>, so that more input is <em>always</em> requested.</p>
<!--TOC paragraph id="sec49" Example-->
<h4 id="sec49" class="paragraph">Example</h4><!--SEC END --><p>Figure <a href="#fig%3Abasiceos">11</a> shows a grammar that has end-of-stream conflicts.
When this grammar is processed, Menhir warns about these conflicts,
and further warns that <span style="font-style:italic">expr</span> is never accepted. Let us explain.</p><p>Part of the corresponding automaton, as described in the <span style="font-family:monospace">.automaton</span> file, is
shown in Figure <a href="#fig%3Abasiceosdump">12</a>. Explanations at the end of the <span style="font-family:monospace">.automaton</span> file (not shown) point out that states 6 and 2 have an end-of-stream
conflict. Indeed, both states have distinct actions on <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> and on the
physical token <span style="font-style:italic">TIMES</span>.
It is interesting to note that, even though state 4 has actions on <span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> and on
physical tokens, it does not have an end-of-stream conflict. This is because
the action taken in state 4 is always to reduce the production <span style="font-style:italic">expr</span>
→ <span style="font-style:italic">expr</span> <span style="font-style:italic">TIMES</span> <span style="font-style:italic">expr</span>, regardless of the lookahead
token.</p><p>By default, Menhir produces a parser where end-of-stream conflicts are
resolved in favor of looking ahead: that is, the problematic reduce actions on
<span style="font-family:sans-serif"><span style="font-weight:bold">#</span></span> are suppressed. This means, in particular, that the <em>accept</em> action
in state 2, which corresponds to reducing the production <span style="font-style:italic">expr</span>
→ <span style="font-style:italic">expr’</span>, is suppressed. This explains why the symbol <span style="font-style:italic">expr</span>
is never accepted: because expressions do not have an unambiguous end marker,
the parser will always request one more token and will never stop.</p><p>In order to avoid this end-of-stream conflict, the standard solution is to
introduce a new token, say <span style="font-style:italic">END</span>, and to use it as an end marker for
expressions. The <span style="font-style:italic">END</span> token could be generated by the lexical analyzer
when it encounters the actual end of stream, or it could correspond to a piece
of concrete syntax, say, a line feed character, a semicolon, or an
<span style="font-family:monospace">end</span> keyword. The solution is shown in Figure <a href="#fig%3Abasiceos%3Asol">13</a>.</p>
<!--TOC section id="sec50" Positions-->
<h2 id="sec50" class="section">7  Positions</h2><!--SEC END --><p>
<a id="sec:positions"></a></p><p>When an <span style="font-family:monospace">ocamllex</span>-generated lexical analyzer produces a token, it updates
two fields, named <code>lex_start_p</code> and <code>lex_curr_p</code>, in its environment
record, whose type is <code>Lexing.lexbuf</code>. Each of these fields holds a value
of type <code>Lexing.position</code>. Together, they represent the token’s start and
end positions within the text that is being scanned. These fields are read by
Menhir after calling the lexical analyzer, so <span style="font-weight:bold">it is the lexical
analyzer’s responsibility</span> to correctly set these fields.</p><p>A position consists
mainly of an offset (the position’s <code>pos_cnum</code> field), but also holds
information about the current file name, the current line number, and the
current offset within the current line. (Not all <span style="font-family:monospace">ocamllex</span>-generated analyzers
keep this extra information up to date. This must be explicitly programmed by
the author of the lexical analyzer.)</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<div class="center">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><code>$startpos</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >start position of the first symbol in the production’s right-hand side, if there is one; </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" > end position of the most recently parsed symbol, otherwise </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$endpos</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >end position of the last symbol in the production’s right-hand side, if there is one; </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" > end position of the most recently parsed symbol, otherwise </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$startpos(</code> <code>$</code><span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">id</span> <code>)</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >start position of the symbol named <code>$</code><span style="font-style:italic">i</span> or <span style="font-style:italic">id</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$endpos(</code> <code>$</code><span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">id</span> <code>)</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >end position of the symbol named <code>$</code><span style="font-style:italic">i</span> or <span style="font-style:italic">id</span> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><span style="font-family:monospace">$symbolstartpos</span> </td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >start position of the leftmost symbol <span style="font-style:italic">id</span> such that
<code>$startpos(</code><span style="font-style:italic">id</span><code>)</code> <code>!=</code>  <code>$endpos(</code><span style="font-style:italic">id</span><code>)</code>; </td></tr>
<tr><td style="text-align:left;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" > if there is no such symbol, <code>$endpos</code> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$startofs</code> </td><td style="text-align:center;white-space:nowrap" >  </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$endofs</code> </td><td style="text-align:center;white-space:nowrap" >  </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$startofs(</code> <code>$</code><span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">id</span> <code>)</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >same as above, but produce an integer offset instead of a position </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$endofs(</code> <code>$</code><span style="font-style:italic">i</span> <span style="font-family:sans-serif"><span style="font-weight:bold">|</span></span> <span style="font-style:italic">id</span> <code>)</code> </td><td style="text-align:center;white-space:nowrap" >  </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$symbolstartofs</code> </td><td style="text-align:center;white-space:nowrap" >  </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$loc</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >stands for the pair <code>($startpos, $endpos)</code> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>$loc(</code> <span style="font-style:italic">id</span> <code>)</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >stands for the pair <code>($startpos(</code> <span style="font-style:italic">id</span> <code>), $endpos(</code> <span style="font-style:italic">id</span> <code>))</code> </td></tr>
<tr><td style="text-align:left;white-space:nowrap" > <code>$sloc</code></td><td style="text-align:center;white-space:nowrap" >  </td><td style="text-align:left;white-space:nowrap" >stands for the pair <code>($symbolstartpos, $endpos)</code> </td></tr>
</table>
</div>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 14: Position-related keywords</td></tr>
</table></div>
<a id="fig:pos"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:left;white-space:nowrap" ><code>symbol_start_pos()</code></td><td style="text-align:left;white-space:nowrap" ><span style="font-family:monospace">$symbolstartpos</span> </td><td style="text-align:center;white-space:nowrap" >      </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>symbol_end_pos()</code></td><td style="text-align:left;white-space:nowrap" ><code>$endpos</code> </td><td style="text-align:center;white-space:nowrap" >      </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>rhs_start_pos i</code></td><td style="text-align:left;white-space:nowrap" ><code>$startpos($i)</code></td><td style="text-align:center;white-space:nowrap" >      </td><td style="text-align:left;white-space:nowrap" >(1 ≤ <span style="font-style:italic">i</span> ≤ <span style="font-style:italic">n</span>) </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>rhs_end_pos i</code></td><td style="text-align:left;white-space:nowrap" ><code>$endpos($i)</code></td><td style="text-align:center;white-space:nowrap" >      </td><td style="text-align:left;white-space:nowrap" >(1 ≤ <span style="font-style:italic">i</span> ≤ <span style="font-style:italic">n</span>) </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>symbol_start()</code></td><td style="text-align:left;white-space:nowrap" ><code>$symbolstartofs</code> </td><td style="text-align:center;white-space:nowrap" >      </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>symbol_end()</code></td><td style="text-align:left;white-space:nowrap" ><code>$endofs</code> </td><td style="text-align:center;white-space:nowrap" >      </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>rhs_start i</code></td><td style="text-align:left;white-space:nowrap" ><code>$startofs($i)</code></td><td style="text-align:center;white-space:nowrap" >      </td><td style="text-align:left;white-space:nowrap" >(1 ≤ <span style="font-style:italic">i</span> ≤ <span style="font-style:italic">n</span>) </td></tr>
<tr><td style="text-align:left;white-space:nowrap" ><code>rhs_end i</code></td><td style="text-align:left;white-space:nowrap" ><code>$endofs($i)</code></td><td style="text-align:center;white-space:nowrap" >      </td><td style="text-align:left;white-space:nowrap" >(1 ≤ <span style="font-style:italic">i</span> ≤ <span style="font-style:italic">n</span>) </td></tr>
</table>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 15: Translating position-related incantations from <span style="font-family:monospace">ocamlyacc</span> to Menhir </td></tr>
</table></div>
<a id="fig:pos:mapping"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>This mechanism allows associating pairs of positions with terminal symbols. If
desired, Menhir automatically extends it to nonterminal symbols as well. That
is, it offers a mechanism for associating pairs of positions with terminal or
nonterminal symbols. This is done by making a set of keywords available to
semantic actions (Figure <a href="#fig%3Apos">14</a>). These keywords are
<em>not</em> available outside of a semantic action:
in particular, they cannot be used within an OCaml header.</p><p>OCaml’s standard library module <span style="font-family:monospace">Parsing</span> is deprecated. The functions
that it offers <em>can</em> be called, but will return dummy positions.</p><p>We remark that, if the current production has an empty right-hand side, then
<code>$startpos</code> and <code>$endpos</code> are equal, and (by convention) are the end
position of the most recently parsed symbol (that is, the symbol that happens
to be on top of the automaton’s stack when this production is reduced). If
the current production has a nonempty right-hand side, then
<code>$startpos</code> is the same as <code>$startpos($1)</code> and
<code>$endpos</code> is the same as <code>$endpos($</code><span style="font-style:italic">n</span><code>)</code>,
where <span style="font-style:italic">n</span> is the length of the right-hand side.</p><p>More generally, if the current production has matched a sentence of length
zero, then <code>$startpos</code> and <code>$endpos</code> will be equal, and conversely.
</p><p>The position <code>$startpos</code> is sometimes “further towards the left” than
one would like. For example, in the following production:
</p><pre class="verbatim">  declaration: modifier? variable { $startpos }
</pre><p>
the keyword <code>$startpos</code> represents the start position of the optional
modifier <code>modifier?</code>. If this modifier turns out to be absent, then its
start position is (by definition) the end position of the most recently parsed
symbol. This may not be what is desired: perhaps the user would prefer in this
case to use the start position of the symbol <code>variable</code>. This is achieved by
using <span style="font-family:monospace">$symbolstartpos</span> instead of <code>$startpos</code>. By definition,
<span style="font-family:monospace">$symbolstartpos</span> is the start position of the leftmost symbol whose
start and end positions differ. In this example, the computation of
<span style="font-family:monospace">$symbolstartpos</span> skips the absent <code>modifier</code>, whose start and end
positions coincide, and returns the start position of the symbol <code>variable</code>
(assuming this symbol has distinct start and end positions).</p><p>There is no keyword <code>$symbolendpos</code>. Indeed, the problem
with <code>$startpos</code> is due to the asymmetry in the definition
of <code>$startpos</code> and <code>$endpos</code> in the case of an empty right-hand
side, and does not affect <code>$endpos</code>.</p><p>The positions computed by Menhir are exactly the same as those computed by
<code>ocamlyacc</code><sup><a id="text1" href="#note1">1</a></sup>. More precisely, Figure <a href="#fig%3Apos%3Amapping">15</a> sums up how
to translate a call to the <span style="font-family:monospace">Parsing</span> module, as used in an <span style="font-family:monospace">ocamlyacc</span> grammar, to a Menhir keyword.</p><p>We note that Menhir’s <code>$startpos</code> does not appear in the right-hand
column in Figure <a href="#fig%3Apos%3Amapping">15</a>. In other words, Menhir’s <code>$startpos</code>
does not correspond exactly to any of the <span style="font-family:monospace">ocamlyacc</span> function calls.
An exact <span style="font-family:monospace">ocamlyacc</span> equivalent of <code>$startpos</code> is <code>rhs_start_pos 1</code>
if the current production has a nonempty right-hand side and
<code>symbol_start_pos()</code> if it has an empty right-hand side.</p><p>Finally, we remark that Menhir’s <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword (§<a href="#sec%3Ainline">5.3</a>)
does not affect the computation of positions. The same positions are computed,
regardless of where <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keywords are placed.</p>
<!--TOC section id="sec51" Using Menhir as an interpreter-->
<h2 id="sec51" class="section">8  Using Menhir as an interpreter</h2><!--SEC END --><p>
<a id="sec:interpret"></a></p><p>When <span style="font-family:monospace">--interpret</span> is set, Menhir no longer behaves as a compiler. Instead,
it acts as an interpreter. That is, it repeatedly:
</p><ul class="itemize"><li class="li-itemize">
reads a sentence off the standard input channel;
</li><li class="li-itemize">parses this sentence, according to the grammar;
</li><li class="li-itemize">displays an outcome.
</li></ul><p>
This process stops when the end of the input channel is reached.</p>
<!--TOC subsection id="sec52" Sentences-->
<h3 id="sec52" class="subsection">8.1  Sentences</h3><!--SEC END --><p>
<a id="sec:sentences"></a></p><p>The syntax of sentences is as follows:
</p><div class="center">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">sentence</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" >[ <span style="font-style:italic">lid</span> <span style="font-family:sans-serif"><span style="font-weight:bold">:</span></span> ] <span style="font-style:italic">uid</span> … <span style="font-style:italic">uid</span>  <span style="font-family:sans-serif"><span style="font-weight:bold">\n</span></span> </td></tr>
</table>
</div><p>Less formally, a sentence is a sequence of zero or more terminal symbols
(<span style="font-style:italic">uid</span>’s), separated with whitespace, terminated with a newline character,
and optionally preceded with a non-terminal start symbol (<span style="font-style:italic">lid</span>). This
non-terminal symbol can be omitted if, and only if, the grammar only has one
start symbol.</p><p>For instance, here are four valid sentences for the grammar of arithmetic
expressions found in the directory <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc"><span style="font-family:monospace">demos/calc</span></a>:
</p><pre class="verbatim">main: INT PLUS INT EOL
INT PLUS INT
INT PLUS PLUS INT EOL
INT PLUS PLUS
</pre><p>
In the first sentence, the start symbol <span style="font-family:monospace">main</span> was explicitly
specified. In the other sentences, it was omitted, which is permitted, because
this grammar has no start symbol other than <span style="font-family:monospace">main</span>. The first sentence
is a stream of four terminal symbols, namely <span style="font-family:monospace">INT</span>, <span style="font-family:monospace">PLUS</span>,
<span style="font-family:monospace">INT</span>, and <span style="font-family:monospace">EOL</span>. These terminal symbols must be provided under
their symbolic names. Writing, say, “<span style="font-family:monospace">12+32\n</span>” instead
of <span style="font-family:monospace">INT PLUS INT EOL</span> is not permitted. Menhir would not be able to
make sense of such a concrete notation, since it does not have a lexer for it.</p>
<!--TOC subsection id="sec53" Outcomes-->
<h3 id="sec53" class="subsection">8.2  Outcomes</h3><!--SEC END --><p>
<a id="sec:outcomes"></a></p><p>As soon as Menhir is able to read a complete sentence off the standard input
channel (that is, as soon as it finds the newline character that ends the
sentence), it parses the sentence according to whichever grammar was specified
on the command line, and displays an outcome.</p><p>An outcome is one of the following:
</p><ul class="itemize"><li class="li-itemize">
<span style="font-family:monospace">ACCEPT</span>: a prefix of the sentence was successfully parsed;
a parser generated by Menhir would successfully stop and produce
a semantic value;
</li><li class="li-itemize"><span style="font-family:monospace">OVERSHOOT</span>: the end of the sentence was reached before it
could be accepted; a parser generated by Menhir would request a
non-existent “next token” from the lexer, causing it to fail or
block;
</li><li class="li-itemize"><span style="font-family:monospace">REJECT</span>: the sentence was not accepted; a parser generated
by Menhir would raise the exception <span style="font-family:monospace">Error</span>.
</li></ul><p>When <span style="font-family:monospace">--interpret-show-cst</span> is set, each <span style="font-family:monospace">ACCEPT</span> outcome is followed with
a concrete syntax tree. A concrete syntax tree is either a leaf or a node. A
leaf is either a terminal symbol or <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span>. A node is annotated with a
non-terminal symbol, and carries a sequence of immediate descendants that
correspond to a valid expansion of this non-terminal symbol. Menhir’s
notation for concrete syntax trees is as follows:
</p><div class="center">
<table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="text-align:right;white-space:nowrap" ><span style="font-style:italic">cst</span> </td><td style="text-align:center;white-space:nowrap" > ::= </td><td style="text-align:left;white-space:nowrap" ><span style="font-style:italic">uid</span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> </td></tr>
<tr><td style="text-align:right;white-space:nowrap" >&nbsp;</td><td style="text-align:center;white-space:nowrap" >&nbsp;</td><td style="text-align:left;white-space:nowrap" ><span style="font-family:monospace">[</span> <span style="font-style:italic">lid</span> <span style="font-family:sans-serif"><span style="font-weight:bold">:</span></span> <span style="font-style:italic">cst</span> … <span style="font-style:italic">cst</span> <span style="font-family:monospace">]</span>
</td></tr>
</table>
</div><p>For instance, if one wished to parse the example sentences of
§<a href="#sec%3Asentences">8.1</a> using the grammar of arithmetic expressions in
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc"><span style="font-family:monospace">demos/calc</span></a>, one could invoke Menhir as follows:
</p><pre class="verbatim">$ menhir --interpret --interpret-show-cst demos/calc/parser.mly
main: INT PLUS INT EOL
ACCEPT
[main: [expr: [expr: INT] PLUS [expr: INT]] EOL]
INT PLUS INT
OVERSHOOT
INT PLUS PLUS INT EOL
REJECT
INT PLUS PLUS
REJECT
</pre><p>
(Here, Menhir’s input—the sentences provided by the user on the standard
input channel— is shown intermixed with Menhir’s output—the outcomes
printed by Menhir on the standard output channel.) The first sentence is
valid, and accepted; a concrete syntax tree is displayed. The second sentence
is incomplete, because the grammar specifies that a valid expansion of
<span style="font-family:monospace">main</span> ends with the terminal symbol <span style="font-family:monospace">EOL</span>; hence, the outcome
is <span style="font-family:monospace">OVERSHOOT</span>. The third sentence is invalid, because of the repeated
occurrence of the terminal symbol <span style="font-family:monospace">PLUS</span>; the outcome is
<span style="font-family:monospace">REJECT</span>. The fourth sentence, a prefix of the third one, is rejected
for the same reason.</p>
<!--TOC subsection id="sec54" Remarks-->
<h3 id="sec54" class="subsection">8.3  Remarks</h3><!--SEC END --><p>Using Menhir as an interpreter offers an easy way of debugging your grammar.
For instance, if one wished to check that addition is considered
left-associative, as requested by the <span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span> directive found in the file
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc/parser.mly"><span style="font-family:monospace">demos/calc/parser.mly</span></a>, one could submit the following sentence:
</p><pre class="verbatim">$ ./menhir --interpret --interpret-show-cst ../demos/calc/parser.mly
INT PLUS INT PLUS INT EOL
ACCEPT
[main:
  [expr: [expr: [expr: INT] PLUS [expr: INT]] PLUS [expr: INT]]
  EOL
]
</pre><p>
The concrete syntax tree displayed by Menhir is skewed towards the left,
as desired.</p><p>The switches <span style="font-family:monospace">--interpret</span> and <span style="font-family:monospace">--trace</span> can be used in conjunction. When
<span style="font-family:monospace">--trace</span> is set, the interpreter logs its actions to the standard error
channel.</p>
<!--TOC section id="sec55" Generated API-->
<h2 id="sec55" class="section">9  Generated API</h2><!--SEC END --><p>When Menhir processes a grammar specification, say <span style="font-family:monospace">parser.mly</span>, it
produces one OCaml module, <span style="font-family:monospace">Parser</span>, whose code resides in the file
<span style="font-family:monospace">parser.ml</span> and whose signature resides in the file
<span style="font-family:monospace">parser.mli</span>. We now review this signature. For simplicity,
we assume that the grammar specification has just one start symbol
<code>main</code>, whose OCaml type is <code>thing</code>.</p>
<!--TOC subsection id="sec56" Monolithic API-->
<h3 id="sec56" class="subsection">9.1  Monolithic API</h3><!--SEC END --><p>
<a id="sec:monolithic"></a></p><p>The monolithic API defines the type <code>token</code>, the exception <code>Error</code>,
and the parsing function <code>main</code>, named after the start symbol of the
grammar.</p><p>The type <code>token</code> is an algebraic data type. A value of type <code>token</code>
represents a terminal symbol and its semantic value. For instance, if the
grammar contains the declarations <code>%token A</code> and <code>%token&lt;int&gt; B</code>,
then the generated file <span style="font-family:monospace">parser.mli</span> contains the following definition:
</p><pre class="verbatim">  type token =
  | A
  | B of int
</pre><p>
If <span style="font-family:monospace">--only-tokens</span> is specified on the command line, the type <code>token</code> is
generated, and the rest is omitted. On the contrary, if <span style="font-family:monospace">--external-tokens</span> is
used, the type <code>token</code> is omitted, but the rest (described below) is
generated.</p><p>The exception <code>Error</code> carries no argument. It is raised by the parsing
function <code>main</code> (described below) when a syntax error is detected.
</p><pre class="verbatim">  exception Error
</pre><p>Next comes one parsing function for each start symbol of the grammar. Here, we
have assumed that there is one start symbol, named <code>main</code>, so the
generated file <span style="font-family:monospace">parser.mli</span> contains the following declaration:
</p><pre class="verbatim">  val main: (Lexing.lexbuf -&gt; token) -&gt; Lexing.lexbuf -&gt; thing
</pre><p>
This function expects two arguments, namely: a lexer, which typically is produced by
<span style="font-family:monospace">ocamllex</span> and has type <code>Lexing.lexbuf -&gt; token</code>; and a lexing buffer,
which has type <code>Lexing.lexbuf</code>. This API is compatible with
<span style="font-family:monospace">ocamlyacc</span>. (For information on using Menhir without <span style="font-family:monospace">ocamllex</span>, please
consult §<a href="#sec%3Aqa">16</a>.)
This API is “monolithic” in the sense that there is just one function, which
does everything: it pulls tokens from the lexer, parses, and eventually
returns a semantic value (or fails by throwing the exception <span style="font-family:monospace">Error</span>).</p>
<!--TOC subsection id="sec57" Incremental API-->
<h3 id="sec57" class="subsection">9.2  Incremental API</h3><!--SEC END --><p>
<a id="sec:incremental"></a></p><p>If <span style="font-family:monospace">--table</span> is set, Menhir offers an incremental API in addition to the
monolithic API. In this API, control is inverted. The parser does not have
access to the lexer. Instead, when the parser needs the next token, it stops
and returns its current state to the user. The user is then responsible for
obtaining this token (typically by invoking the lexer) and resuming the parser
from that state.
The directory <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-incremental"><span style="font-family:monospace">demos/calc-incremental</span></a> contains a demo that
illustrates the use of the incremental API.</p><p>This API is “incremental” in the sense that the user has access to a
sequence of the intermediate states of the parser. Assuming that semantic
values are immutable, a parser state is a persistent data structure: it can be
stored and used multiple times, if desired. This enables applications such as
“live parsing”, where a buffer is continuously parsed while it is being
edited. The parser can be re-started in the middle of the buffer whenever the
user edits a character. Because two successive parser states share most of
their data in memory, a list of <span style="font-style:italic">n</span> successive parser states occupies only
<span style="font-style:italic">O</span>(<span style="font-style:italic">n</span>) space in memory.</p>
<!--TOC subsubsection id="sec58" Starting the parser-->
<h4 id="sec58" class="subsubsection">9.2.1  Starting the parser</h4><!--SEC END --><p>In this API, the parser is started by invoking
<code>Incremental.main</code>. (Recall that we assume that <code>main</code> is
the name of the start symbol.) The generated file <span style="font-family:monospace">parser.mli</span> contains
the following declaration:
</p><pre class="verbatim">  module Incremental : sig
    val main: position -&gt; thing MenhirInterpreter.checkpoint
  end
</pre><p>
The argument is the initial position. If the lexer is based on an OCaml lexing buffer, this argument should be <code>lexbuf.lex_curr_p</code>.
In §<a href="#sec%3Aincremental">9.2</a> and §<a href="#sec%3Ainspection">9.3</a>,
the type <code>position</code> is a synonym for <code>Lexing.position</code>.</p><p>We emphasize that the function <code>Incremental.main</code> does not parse
anything. It constructs a checkpoint which serves as a <em>starting</em>
point. The functions <code>offer</code> and <code>resume</code>, described below, are used
to drive the parser.</p>
<!--TOC subsubsection id="sec59" Driving the parser-->
<h4 id="sec59" class="subsubsection">9.2.2  Driving the parser</h4><!--SEC END --><p>
<a id="sec:incremental:driving"></a></p><p>The sub-module <span style="font-family:monospace">MenhirInterpreter</span> is also part of the incremental API.
Its declaration, which appears in the generated file <span style="font-family:monospace">parser.mli</span>, is as
follows:
</p><pre class="verbatim">  module MenhirInterpreter : MenhirLib.IncrementalEngine.INCREMENTAL_ENGINE
    with type token = token
</pre><p>
The signature <code>INCREMENTAL_ENGINE</code>, defined in the module
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/lib/IncrementalEngine.ml"><span style="font-family:monospace">MenhirLib.IncrementalEngine</span></a>, contains many types and functions,
which are described in the rest of this section
(§<a href="#sec%3Aincremental%3Adriving">9.2.2</a>) and in the following sections
(§<a href="#sec%3Aincremental%3Ainspecting">9.2.3</a>, §<a href="#sec%3Aincremental%3Aupdating">9.2.4</a>).</p><p>Please keep in mind that, from the outside, these types and functions should be referred
to with an appropriate prefix. For instance, the type <code>checkpoint</code> should be referred
to as <code>MenhirInterpreter.checkpoint</code>, or
<code>Parser.MenhirInterpreter.checkpoint</code>, depending on which modules the user
chooses to open.</p><pre class="verbatim">  type 'a env
</pre><p>The abstract type <code>'a env</code> represents the current state of the
parser. (That is, it contains the current state and stack of the LR
automaton.) Assuming that semantic values are immutable, it is a persistent
data structure: it can be stored and used multiple times, if desired.
The parameter <code>'a</code> is the type of the semantic value that will
eventually be produced if the parser succeeds.</p><pre class="verbatim">  type production
</pre><p>The abstract type <code>production</code> represents a production of the grammar.
The “start productions” (which do not exist in an <span style="font-family:monospace">.mly</span> file, but are
constructed by Menhir internally) are <em>not</em> part of this type.</p><pre class="verbatim">  type 'a checkpoint = private
    | InputNeeded of 'a env
    | Shifting of 'a env * 'a env * bool
    | AboutToReduce of 'a env * production
    | HandlingError of 'a env
    | Accepted of 'a
    | Rejected
</pre><p>The type <code>'a checkpoint</code> represents an intermediate or
final state of the parser. An intermediate checkpoint is a suspension: it records
the parser’s current state, and allows parsing to be resumed. The parameter
<code>'a</code> is the type of the semantic value that will eventually be produced
if the parser succeeds.</p><p><code>Accepted</code> and <code>Rejected</code> are final checkpoints. <code>Accepted</code> carries
a semantic value.</p><p><code>InputNeeded</code> is an intermediate checkpoint. It means that the parser wishes
to read one token before continuing.</p><p><code>Shifting</code> is an intermediate checkpoint. It means that the parser is taking
a shift transition. It exposes the state of the parser before and after the
transition. The Boolean parameter tells whether the parser intends to request
a new token after this transition. (It always does, except when it is about to
accept.)</p><p><code>AboutToReduce</code> is an intermediate checkpoint: it means that the parser is
about to perform a reduction step. <code>HandlingError</code> is also an
intermediate checkpoint: it means that the parser has detected an error and is
about to handle it. (Error handling is typically performed in several steps,
so the next checkpoint is likely to be <code>HandlingError</code> again.) In these two
cases, the parser does not need more input. The parser suspends itself at this
point only in order to give the user an opportunity to observe the parser’s
transitions and possibly handle errors in a different manner, if desired.</p><pre class="verbatim">  val offer:
    'a checkpoint -&gt;
    token * position * position -&gt;
    'a checkpoint
</pre><p>The function <code>offer</code> allows the user to resume the parser after the
parser has suspended itself with a checkpoint of the form <code>InputNeeded env</code>.
This function expects the previous checkpoint <code>checkpoint</code> as well as a new token
(together with the start and end positions of this token). It produces a new
checkpoint, which again can be an intermediate checkpoint or a final checkpoint. It does
not raise any exception. (The exception <span style="font-family:monospace">Error</span> is used only in the
monolithic API.)</p><pre class="verbatim">  val resume:
    ?strategy:[ `Legacy | `Simplified ] -&gt;
    'a checkpoint -&gt;
    'a checkpoint
</pre><p>The function <code>resume</code> allows the user to resume the parser after the
parser has suspended itself with a checkpoint of the form
<code>AboutToReduce (env, prod)</code> or <code>HandlingError env</code>.
This function expects just the previous checkpoint <code>checkpoint</code>. It produces a new
checkpoint. It does not raise any exception.
The optional argument <code>strategy</code> influences the manner in which
<code>resume</code> deals with checkpoints of the form <code>ErrorHandling _</code>. Its
default value is <code>`Legacy</code>. For more details, see §<a href="#sec%3Aerrors">10</a>.</p><p>The incremental API subsumes the monolithic API. Indeed, <code>main</code> can be
(and is in fact) implemented by first using
<code>Incremental.main</code>, then calling <code>offer</code> and
<code>resume</code> in a loop, until a final checkpoint is obtained.</p><pre class="verbatim">  type supplier =
    unit -&gt; token * position * position
</pre><p>A token supplier is a function of no arguments which delivers a new token
(together with its start and end positions) every time it is called. The
function <code>loop</code> and its variants, described below, expect a supplier
as an argument.</p><pre class="verbatim">  val lexer_lexbuf_to_supplier:
    (Lexing.lexbuf -&gt; token) -&gt; Lexing.lexbuf -&gt; supplier
</pre><p>The function <code>lexer_lexbuf_to_supplier</code>, applied to a lexer and to a
lexing buffer, produces a fresh supplier.</p><p>The functions <code>offer</code> and <code>resume</code>, documented above, are sufficient
to write a parser loop. One can imagine many variations of such a loop, which
is why we expose <code>offer</code> and <code>resume</code> in the first place.
Nevertheless, some variations are so common that it is worth providing them,
ready for use. The following functions are implemented on top of <code>offer</code>
and <code>resume</code>.</p><pre class="verbatim">  val loop:
    ?strategy:[ `Legacy | `Simplified ] -&gt;
    supplier -&gt; 'a checkpoint -&gt; 'a
</pre><p><code>loop supplier checkpoint</code> begins parsing from <code>checkpoint</code>, reading
tokens from <code>supplier</code>. It continues parsing until it reaches a
checkpoint of the form <code>Accepted v</code> or <code>Rejected</code>. In the former
case, it returns <code>v</code>. In the latter case, it raises the
exception <code>Error</code>. (By the way, this is how we implement the monolithic
API on top of the incremental API.)
The optional argument <code>strategy</code> influences the manner in which
<code>loop</code> deals with checkpoints of the form <code>ErrorHandling _</code>. Its
default value is <code>`Legacy</code>. For more details, see §<a href="#sec%3Aerrors">10</a>.</p><pre class="verbatim">  val loop_handle:
    ('a -&gt; 'answer) -&gt;
    ('a checkpoint -&gt; 'answer) -&gt;
    supplier -&gt; 'a checkpoint -&gt; 'answer
</pre><p><code>loop_handle succeed fail supplier checkpoint</code> begins parsing from
<code>checkpoint</code>, reading tokens from <code>supplier</code>. It continues until
it reaches a checkpoint of the form <code>Accepted v</code> or <code>HandlingError _</code>
(or <code>Rejected</code>, but that should not happen, as <code>HandlingError _</code>
will be observed first). In the former case, it calls <code>succeed v</code>. In
the latter case, it calls <code>fail</code> with this checkpoint. It cannot
raise <code>Error</code>.</p><p>This means that Menhir’s traditional error-handling procedure (which pops the
stack until a state that can act on the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token is found) does not get a
chance to run. Instead, the user can implement her own error handling code, in
the <code>fail</code> continuation.</p><pre class="verbatim">  val loop_handle_undo:
    ('a -&gt; 'answer) -&gt;
    ('a checkpoint -&gt; 'a checkpoint -&gt; 'answer) -&gt;
    supplier -&gt; 'a checkpoint -&gt; 'answer
</pre><p><code>loop_handle_undo</code> is analogous to <code>loop_handle</code>, but passes a pair
of checkpoints (instead of a single checkpoint) to the failure continuation.
The first (and oldest) checkpoint that is passed to the failure continuation
is the last <code>InputNeeded</code> checkpoint that was encountered before the
error was detected. The second (and newest) checkpoint is where the error was
detected. (This is the same checkpoint that <code>loop_handle</code> would pass to
its failure continuation.) Going back to the first checkpoint can be thought
of as undoing any reductions that were performed after seeing the problematic
token. (These reductions must be default reductions or spurious reductions.)
This can be useful to someone who wishes to implement an error explanation or
error recovery mechanism.</p><p><code>loop_handle_undo</code> must be applied to an <code>InputNeeded</code> checkpoint.
The initial checkpoint produced by <code>Incremental.main</code> is of this form.</p><pre class="verbatim">  val shifts: 'a checkpoint -&gt; 'a env option
</pre><p><code>shifts checkpoint</code> assumes that <code>checkpoint</code> has been obtained by
submitting a token to the parser. It runs the parser from <code>checkpoint</code>,
through an arbitrary number of reductions, until the parser either accepts
this token (i.e., shifts) or rejects it (i.e., signals an error). If the
parser decides to shift, then <code>Some env</code> is returned, where <code>env</code> is
the parser’s state just before shifting. Otherwise, <code>None</code> is returned.
This can be used to test whether the parser is willing to accept a certain
token. This function should be used with caution, though, as it causes
semantic actions to be executed. It is desirable that all semantic actions be
side-effect-free, or that their side-effects be harmless.</p><pre class="verbatim">  val acceptable: 'a checkpoint -&gt; token -&gt; position -&gt; bool
</pre><p><code>acceptable checkpoint token pos</code> requires <code>checkpoint</code> to be an
<code>InputNeeded</code> checkpoint. It returns <code>true</code> iff the parser is
willing to shift this token.
This can be used to test, after an error has been detected, which tokens would
have been accepted at this point. To do this, one would typically use
<code>loop_handle_undo</code> to get access to the last <code>InputNeeded</code>
checkpoint that was encountered before the error was detected, and apply
<code>acceptable</code> to that checkpoint.</p><p><code>acceptable</code> is implemented using <code>shifts</code>, so, like <code>shifts</code>,
it causes certain semantic actions to be executed. It is desirable that all
semantic actions be side-effect-free, or that their side-effects be harmless.</p>
<!--TOC subsubsection id="sec60" Inspecting the parser’s state-->
<h4 id="sec60" class="subsubsection">9.2.3  Inspecting the parser’s state</h4><!--SEC END --><p>
<a id="sec:incremental:inspecting"></a></p><p>Although the type <code>env</code> is opaque, a parser state can be inspected via a
few accessor functions, which are described in this section. The following
types and functions are contained in the <code>MenhirInterpreter</code> sub-module.</p><pre class="verbatim">  type 'a lr1state
</pre><p>The abstract type <code>'a lr1state</code> describes a (non-initial) state of the
LR(1) automaton.
If <code>s</code> is such a state, then <code>s</code> should have at least one incoming
transition, and all of its incoming transitions carry the same (terminal or
non-terminal) symbol, say <span style="font-style:italic">A</span>. We say that <span style="font-style:italic">A</span> is the <em>incoming symbol</em>
of the state <code>s</code>.
The index <code>'a</code> is the type of the semantic values associated with <span style="font-style:italic">A</span>.
The role played by <code>'a</code> is clarified in the definition of the
type <code>element</code>, which appears further on.</p><pre class="verbatim">  val number: _ lr1state -&gt; int
</pre><p>The states of the LR(1) automaton are numbered (from 0 and up).
The function <code>number</code> maps a state to its number.</p><pre class="verbatim">  val production_index: production -&gt; int
  val find_production: int -&gt; production
</pre><p>Productions are numbered. (The set of indices of all productions forms an
interval, which does <em>not</em> necessarily begin at 0.)
The function <code>production_index</code> converts a production to an integer
number, whereas the function <code>find_production</code> carries out the reverse
conversion. It is an error to apply <code>find_production</code> to an invalid
index.</p><pre class="verbatim">  type element =
    | Element: 'a lr1state * 'a * position * position -&gt; element
</pre><p>The type <code>element</code> describes one entry in the stack of the LR(1)
automaton. In a stack element of the form <code>Element (s, v, startp, endp)</code>,
<code>s</code> is a (non-initial) state and <code>v</code> is a semantic value. The
value <code>v</code> is associated with the incoming symbol <span style="font-style:italic">A</span> of the
state <code>s</code>. In other words, the value <code>v</code> was pushed onto the stack
just before the state <code>s</code> was entered. Thus, for some type <code>'a</code>, the
state <code>s</code> has type <code>'a lr1state</code> and the value <code>v</code> has
type <code>'a</code>. The positions <code>startp</code> and <code>endp</code> delimit the
fragment of the input text that was reduced to the symbol <span style="font-style:italic">A</span>.</p><p>In order to do anything useful with the value <code>v</code>, one must gain
information about the type <code>'a</code>, by inspection of the state <code>s</code>. So
far, the type <code>'a lr1state</code> is abstract, so there is no way of
inspecting <code>s</code>. The inspection API (§<a href="#sec%3Ainspection">9.3</a>) offers further
tools for this purpose.</p><pre class="verbatim">  val top: 'a env -&gt; element option
</pre><p><code>top env</code> returns the parser’s top stack element. The state contained in
this stack element is the current state of the automaton. If the stack is
empty, <code>None</code> is returned. In that case, the current state of the
automaton must be an initial state.</p><pre class="verbatim">  val pop_many: int -&gt; 'a env -&gt; 'a env option
</pre><p><code>pop_many i env</code> pops <code>i</code> elements off the automaton’s stack. This
is done via <code>i</code> successive invocations of <code>pop</code>. Thus,
<code>pop_many 1</code> is <code>pop</code>. The index <code>i</code> must be nonnegative. The
time complexity is <span style="font-style:italic">O</span>(<span style="font-style:italic">i</span>).</p><pre class="verbatim">  val get: int -&gt; 'a env -&gt; element option
</pre><p><code>get i env</code> returns the parser’s <code>i</code>-th stack element. The index
<code>i</code> is 0-based: thus, <code>get 0</code> is <code>top</code>. If <code>i</code> is greater
than or equal to the number of elements in the stack, <code>None</code> is returned.
<code>get</code> is implemented using <code>pop_many</code> and <code>top</code>: its time
complexity is <span style="font-style:italic">O</span>(<span style="font-style:italic">i</span>).</p><pre class="verbatim">  val current_state_number: 'a env -&gt; int
</pre><p><code>current_state_number env</code> is the integer number of the automaton’s
current state. Although this number might conceivably be obtained via the
functions <code>top</code> and <code>number</code>, using <code>current_state_number</code> is
preferable, because this method works even when the automaton’s stack is empty
(in which case the current state is an initial state, and <code>top</code> returns
<code>None</code>). This number can be passed as an argument to a <code>message</code>
function generated by <code>menhir --compile-errors</code>.</p><pre class="verbatim">  val equal: 'a env -&gt; 'a env -&gt; bool
</pre><p><code>equal env1 env2</code> tells whether the parser configurations <code>env1</code> and
<code>env2</code> are equal in the sense that the automaton’s current state is the
same in <code>env1</code> and <code>env2</code> and the stack is <em>physically</em> the
same in <code>env1</code> and <code>env2</code>. If <code>equal env1 env2</code> is <code>true</code>,
then the sequence of the stack elements, as observed via <code>pop</code> and
<code>top</code>, must be the same in <code>env1</code> and <code>env2</code>. Also, if
<code>equal env1 env2</code> holds, then the checkpoints <code>input_needed env1</code>
and <code>input_needed env2</code> must be equivalent. (The function
<code>input_needed</code> is documented in §<a href="#sec%3Aincremental%3Aupdating">9.2.4</a>.)
The function <code>equal</code> has time complexity <span style="font-style:italic">O</span>(1).</p><pre class="verbatim">  val positions: 'a env -&gt; position * position
</pre><p>The function <code>positions</code> returns the start and end positions of the
current lookahead token. If invoked in an initial state, this function returns
a pair of twice the initial position that was passed as an argument
to <code>main</code>.</p><pre class="verbatim">  val env_has_default_reduction: 'a env -&gt; bool
  val state_has_default_reduction: _ lr1state -&gt; bool
</pre><p>When applied to an environment <code>env</code> taken from a checkpoint of the form
<code>AboutToReduce (env, prod)</code>, the function
<code>env_has_default_reduction</code> tells whether the reduction that is about to
take place is a default reduction.</p><p><code>state_has_default_reduction s</code> tells whether the state <code>s</code> has a default
reduction. This includes the case where <code>s</code> is an accepting state.</p>
<!--TOC subsubsection id="sec61" Updating the parser’s state-->
<h4 id="sec61" class="subsubsection">9.2.4  Updating the parser’s state</h4><!--SEC END --><p>
<a id="sec:incremental:updating"></a></p><p>The functions presented in the previous section
(§<a href="#sec%3Aincremental%3Ainspecting">9.2.3</a>) allow inspecting parser states of type
<code>'a checkpoint</code> and <code>'a env</code>. However, so far, there are no
functions for manufacturing new parser states, except <code>offer</code> and
<code>resume</code>, which create new checkpoints by feeding tokens, one by one, to
the parser.</p><p>In this section, a small number of functions are provided for manufacturing
new parser states of type <code>'a env</code> and <code>'a checkpoint</code>. These
functions allow going far back into the past and jumping ahead into the
future, so to speak. In other words, they allow driving the parser in other
ways than by feeding tokens into it. The functions <code>pop</code>,
<code>force_reduction</code> and <code>feed</code> (part of the inspection API; see
§<a href="#sec%3Ainspection">9.3</a>) construct values of type <code>'a env</code>. The function
<code>input_needed</code> constructs values of type <code>'a checkpoint</code> and thereby
allows resuming parsing in normal mode (via <code>offer</code>). Together, these
functions can be used to implement error handling and error recovery
strategies.</p><pre class="verbatim">  val pop: 'a env -&gt; 'a env option
</pre><p><code>pop env</code> returns a new environment, where the parser’s top stack cell
has been popped off. (If the stack is empty, <code>None</code> is returned.) This
amounts to pretending that the (terminal or nonterminal) symbol that
corresponds to this stack cell has not been read.</p><pre class="verbatim">  val force_reduction: production -&gt; 'a env -&gt; 'a env
</pre><p><code>force_reduction prod env</code> can be called only if in the state <code>env</code>
the parser is capable of reducing the production <code>prod</code>. If this
condition is satisfied, then this production is reduced, which means that its
semantic action is executed (this can have side effects!) and the automaton
makes a goto (nonterminal) transition. If this condition is not satisfied, an
<code>Invalid_argument</code> exception is raised.</p><pre class="verbatim">  val input_needed: 'a env -&gt; 'a checkpoint
</pre><p><code>input_needed env</code> returns <code>InputNeeded env</code>. Thus, out of a parser
state that might have been obtained via a series of calls to the functions
<code>pop</code>, <code>force_reduction</code>, <code>feed</code>, and so on, it produces a
checkpoint, which can be used to resume normal parsing, by supplying this
checkpoint as an argument to <code>offer</code>.</p><p>This function should be used with some care. It could “mess up the
lookahead” in the sense that it allows parsing to resume in an arbitrary
state <code>s</code> with an arbitrary lookahead symbol <code>t</code>, even though
Menhir’s reachability analysis (which is carried out via the <span style="font-family:monospace">--list-errors</span> switch) might well think that it is impossible to reach this particular
configuration. If one is using Menhir’s new error reporting facility
(§<a href="#sec%3Aerrors%3Anew">11</a>), this could cause the parser to reach an error state
for which no error message has been prepared.</p>
<!--TOC subsection id="sec62" Inspection API-->
<h3 id="sec62" class="subsection">9.3  Inspection API</h3><!--SEC END --><p>
<a id="sec:inspection"></a></p><p>If <span style="font-family:monospace">--inspection</span> is set, Menhir offers an inspection API in addition to the
monolithic and incremental APIs. (The reason why this is not done by default
is that this requires more tables to be generated, thus making the generated
parser larger.) Like the incremental API, the inspection API is found in the
sub-module <span style="font-family:monospace">MenhirInterpreter</span>. It offers the following types and functions.</p><p>The type <code>'a terminal</code> is a generalized algebraic data type (GADT). A
value of type <code>'a terminal</code> represents a terminal symbol (without a
semantic value). The index <code>'a</code> is the type of the semantic values
associated with this symbol. For instance, if the grammar contains the
declarations <code>%token A</code> and <code>%token&lt;int&gt; B</code>, then the generated
module <span style="font-family:monospace">MenhirInterpreter</span> contains the following definition:
</p><pre class="verbatim">  type _ terminal =
  | T_A : unit terminal
  | T_B : int terminal
</pre><p>
The data constructors are named after the terminal symbols, prefixed with “<code>T_</code>”.</p><p>The type <code>'a nonterminal</code> is also a GADT. A value of type
<code>'a nonterminal</code> represents a nonterminal symbol (without a semantic value). The
index <code>'a</code> is the type of the semantic values associated with this
symbol. For instance, if <code>main</code> is the only nonterminal symbol,
then the generated
module <span style="font-family:monospace">MenhirInterpreter</span> contains the following definition:
</p><pre class="verbatim">  type _ nonterminal =
  | N_main : thing nonterminal
</pre><p>
The data constructors are named after the nonterminal symbols, prefixed with “<code>N_</code>”.</p><p>The type <code>'a symbol</code>
is the disjoint union of the types <code>'a terminal</code> and <code>'a nonterminal</code>.
In other words, a value of type <code>'a symbol</code> represents a terminal or nonterminal symbol (without
a semantic value).
This type is (always) defined as follows:
</p><pre class="verbatim">  type 'a symbol =
    | T : 'a terminal -&gt; 'a symbol
    | N : 'a nonterminal -&gt; 'a symbol
</pre><p>The type <code>xsymbol</code> is an existentially quantified version of the
type <code>'a symbol</code>. It is useful in situations where the index <code>'a</code> is
not statically known. It is (always) defined as follows:
</p><pre class="verbatim">  type xsymbol =
    | X : 'a symbol -&gt; xsymbol
</pre><p>The type <code>item</code> describes an LR(0) item, that is, a pair of a production
<code>prod</code> and an index <code>i</code> into the right-hand side of this production.
If the length of the right-hand side is <code>n</code>, then <code>i</code> is
comprised between 0 and <code>n</code>, inclusive.</p><pre class="verbatim">  type item =
      production * int
</pre><p>The following functions implement total orderings on the types
<code>_ terminal</code>, <code>_ nonterminal</code>, <code>xsymbol</code>,
<code>production</code>, and <code>item</code>.</p><pre class="verbatim">  val compare_terminals: _ terminal -&gt; _ terminal -&gt; int
  val compare_nonterminals: _ nonterminal -&gt; _ nonterminal -&gt; int
  val compare_symbols: xsymbol -&gt; xsymbol -&gt; int
  val compare_productions: production -&gt; production -&gt; int
  val compare_items: item -&gt; item -&gt; int
</pre><p>The function <code>incoming_symbol</code> maps a (non-initial) LR(1)
state <code>s</code> to its incoming symbol, that is, the symbol that the parser
must recognize before it enters the state <code>s</code>.
</p><pre class="verbatim">  val incoming_symbol: 'a lr1state -&gt; 'a symbol
</pre><p>
This function can be used to gain access to the semantic value <code>v</code>
in a stack element <code>Element (s, v, _, _)</code>. Indeed, by case analysis on the
symbol <code>incoming_symbol s</code>, one gains information about the type <code>'a</code>,
hence one obtains the ability to do something useful with the value <code>v</code>.</p><p>The function <code>items</code> maps a (non-initial) LR(1) state <code>s</code> to its
LR(0) <em>core</em>, that is, to the underlying set of LR(0) items. This set
is represented as a list, whose elements appear in an arbitrary order. This
set is <em>not</em> closed under є-transitions.
</p><pre class="verbatim">  val items: _ lr1state -&gt; item list
</pre><p>The functions <code>lhs</code> and <code>rhs</code> map a production <code>prod</code> to
its left-hand side and right-hand side, respectively. The left-hand side
is always a nonterminal symbol, hence always of the form <code>N _</code>. The
right-hand side is a (possibly empty) sequence of (terminal or nonterminal)
symbols.
</p><pre class="verbatim">  val lhs: production -&gt; xsymbol
  val rhs: production -&gt; xsymbol list
</pre><p>The function <code>nullable</code>, applied to a non-terminal symbol,
tells whether this symbol is nullable. A nonterminal symbol is nullable if and
only if it produces the empty word є.
</p><pre class="verbatim">  val nullable: _ nonterminal -&gt; bool
</pre><p>The function call <code>first nt t</code> tells whether the <em>FIRST</em> set of the
nonterminal symbol <code>nt</code> contains the terminal symbol <code>t</code>. That is,
it returns <code>true</code> if and only if <code>nt</code> produces a word that begins
with <code>t</code>. The function <code>xfirst</code> is identical to <code>first</code>, except
it expects a first argument of type <code>xsymbol</code> instead of <code>_ terminal</code>.
</p><pre class="verbatim">  val first: _ nonterminal -&gt; _ terminal -&gt; bool
  val xfirst: xsymbol -&gt; _ terminal -&gt; bool
</pre><p>The function <code>foreach_terminal</code> enumerates the terminal symbols, including the special symbol <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span>.
The function <code>foreach_terminal_but_error</code> enumerates the terminal symbols, excluding <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span>.
</p><pre class="verbatim">  val foreach_terminal:           (xsymbol -&gt; 'a -&gt; 'a) -&gt; 'a -&gt; 'a
  val foreach_terminal_but_error: (xsymbol -&gt; 'a -&gt; 'a) -&gt; 'a -&gt; 'a
</pre><p><code>feed symbol startp semv endp env</code> causes the parser to consume the
(terminal or nonterminal) symbol <code>symbol</code>, accompanied with the semantic
value <code>semv</code> and with the start and end positions <code>startp</code> and
<code>endp</code>. Thus, the automaton makes a transition, and reaches a new state.
The stack grows by one cell. This operation is permitted only if the current
state (as determined by <code>env</code>) has an outgoing transition labeled with
<code>symbol</code>. Otherwise, an <code>Invalid_argument</code> exception is raised.
</p><pre class="verbatim">  val feed: 'a symbol -&gt; position -&gt; 'a -&gt; position -&gt; 'b env -&gt; 'b env
</pre>
<!--TOC section id="sec63" Error handling: the traditional way-->
<h2 id="sec63" class="section">10  Error handling: the traditional way</h2><!--SEC END --><p>
<a id="sec:errors"></a></p><p>Menhir’s traditional error handling mechanism is considered deprecated: although
it is still supported for the time being, it might be removed in the future.
We recommend setting up an error handling mechanism using the new tools
offered by Menhir (§<a href="#sec%3Aerrors%3Anew">11</a>).</p>
<!--TOC paragraph id="sec64" Error handling-->
<h4 id="sec64" class="paragraph">Error handling</h4><!--SEC END --><p>Menhir’s error traditional handling mechanism is inspired by that of <span style="font-family:monospace">yacc</span> and
<span style="font-family:monospace">ocamlyacc</span>, but is not identical. A special <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token is made available
for use within productions. The LR automaton is constructed exactly as if
<span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> was a regular terminal symbol. However, <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> is never produced
by the lexical analyzer. Instead, when an error is detected, the current
lookahead token is discarded and replaced with the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token, which becomes
the current lookahead token. At this point, the parser enters <em>error
handling</em> mode.
In error handling mode, the parser behaves as follows:
</p><ul class="itemize"><li class="li-itemize">
If the current state has a shift action on the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token, then this
action takes place. Under the <span style="font-family:monospace">legacy</span> strategy, the parser then
reads the next token and returns to normal mode. Under the
simplified strategy, it does <em>not</em> request the next token, so
the current token remains <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span>, and the parser remains in error handling
mode.
</li><li class="li-itemize">If the current state has a reduce action on the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token, then this
action takes place. (This behavior differs from that of <span style="font-family:monospace">yacc</span> and
<span style="font-family:monospace">ocamlyacc</span>, which do not reduce on <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span>. It is somewhat unclear why not.)
The current token remains <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> and the parser remains in error handling
mode.
</li><li class="li-itemize">If the current state has no action on the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token, then, under the
simplified strategy, the parser rejects the input. Under the
<span style="font-family:monospace">legacy</span> strategy, the parser pops a cell off its stack and remains
in error handling mode. If the stack is empty, then the parser rejects the
input.
</li></ul><p>In the monolithic API, the parser rejects the input by raising the exception
<span style="font-family:monospace">Error</span>. This exception carries no information. The position of the
error can be obtained by reading the lexical analyzer’s environment record. In
the incremental API, the parser rejects the input by returning the checkpoint
<span style="font-family:monospace">Rejected</span>.</p><p>Which strategy should one choose? First, let us note that the difference
between the strategies <span style="font-family:monospace">legacy</span> and <span style="font-family:monospace">simplified</span> matters only if the grammar
uses the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token. The following rule of thumb can be used to select
between them:
</p><ul class="itemize"><li class="li-itemize">
If the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token is used only to catch an error and stop, then the
<span style="font-family:monospace">simplified</span> strategy should be preferred. (In this this restricted style,
the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token always appears at the end of a production, whose semantic
action raises an exception.)
</li><li class="li-itemize">If the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token is used to survive an error and continue parsing,
then the legacy strategy should be selected.
</li></ul>
<!--TOC paragraph id="sec65" Error recovery-->
<h4 id="sec65" class="paragraph">Error recovery</h4><!--SEC END --><p><span style="font-family:monospace">ocamlyacc</span> offers an error recovery mode, which is entered immediately after
an <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token was successfully shifted. In this mode, tokens are repeatedly
taken off the input stream and discarded until an acceptable token is found.
This feature is no longer offered by Menhir.</p>
<!--TOC paragraph id="sec66" Error-related keywords-->
<h4 id="sec66" class="paragraph">Error-related keywords</h4><!--SEC END --><p>The following keyword is made available to semantic actions.</p><p>When the <code>$syntaxerror</code> keyword is evaluated, evaluation of the semantic
action is aborted, so that the current reduction is abandoned; the current
lookahead token is discarded and replaced with the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token; and error
handling mode is entered. Note that there is no mechanism for inserting an
<span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token <em>in front of</em> the current lookahead token, even though this
might also be desirable. It is unclear whether this keyword is useful; it
might be suppressed in the future.</p>
<!--TOC section id="sec67" Error handling: the new way-->
<h2 id="sec67" class="section">11  Error handling: the new way</h2><!--SEC END --><p>
<a id="sec:errors:new"></a></p><p>Menhir’s incremental API (§<a href="#sec%3Aincremental">9.2</a>) allows taking control when
an error is detected. Indeed, as soon as an invalid token is detected, the
parser produces a checkpoint of the form <code>HandlingError _</code>. At this
point, if one decides to let the parser proceed, by just
calling <code>resume</code>, then Menhir enters its traditional error handling mode
(§<a href="#sec%3Aerrors">10</a>). Instead, however, one can decide to take control and
perform error handling or error recovery in any way one pleases. One can, for
instance, build and display a diagnostic message, based on the automaton’s
current stack and/or state. Or, one could modify the input stream, by
inserting or deleting tokens, so as to suppress the error, and resume normal
parsing. In principle, the possibilities are endless.</p><p>An apparently simple-minded approach to error reporting,
proposed by Jeffery [<a href="#jeffery-03">10</a>] and further explored by
Pottier [<a href="#pottier-reachability-cc-2016">20</a>], consists in selecting a diagnostic
message (or a template for a diagnostic message) based purely on the current
state of the automaton.</p><p>In this approach, one determines, ahead of time, which are the “error
states” (that is, the states in which an error can be detected), and one
prepares, for each error state, a diagnostic message. Because state numbers
are fragile (they change when the grammar evolves), an error state is
identified not by its number, but by an input sentence that leads to it: more
precisely, by an input sentence which causes an error to be detected in this
state. Thus, one maintains a set of pairs of an erroneous input sentence and a
diagnostic message.</p><p>Menhir defines a file format, the <span style="font-family:monospace">.messages</span> file format,
for representing this information (§<a href="#sec%3Amessages%3Aformat">11.1</a>), and offers a
set of tools for creating, maintaining, and exploiting <span style="font-family:monospace">.messages</span> files
(§<a href="#sec%3Amessages%3Atools">11.2</a>). Once one understands these tools, there remains
to write a collection of diagnostic messages, a more subtle task than one
might think (§<a href="#sec%3Aerrors%3Adiagnostics">11.3</a>), and to glue everything together
(§<a href="#sec%3Aerrors%3Aexample">11.4</a>).</p><p>In this approach to error handling, as in any other approach, one must
understand exactly when (that is, in which states) errors are detected.
This in turn requires understanding how the automaton is constructed.
Menhir’s construction technique is not Knuth’s canonical LR(1)
technique [<a href="#knuth-lr-65">15</a>], which is usually too expensive to be practical.
Instead, Menhir <em>merges</em> states [<a href="#pager-77">19</a>] and introduces so-called <em>default
reductions</em>. These techniques <em>defer</em> error detection by allowing
extra reductions to take place before an error is detected.
The impact of these alterations must be taken into account when writing
diagnostic messages (§<a href="#sec%3Aerrors%3Adiagnostics">11.3</a>).</p><p>In this approach to error handling, the special <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token is not used. It
should not appear in the grammar. Similarly, the <code>$syntaxerror</code> keyword
should not be used.</p>
<!--TOC subsection id="sec68" The <span style="font-family:monospace">.messages</span> file format-->
<h3 id="sec68" class="subsection">11.1  The <span style="font-family:monospace">.messages</span> file format</h3><!--SEC END --><p>
<a id="sec:messages:format"></a></p>
<!--TOC paragraph id="sec69" Definition-->
<h4 id="sec69" class="paragraph">Definition</h4><!--SEC END --><p>A <span style="font-family:monospace">.messages</span> file is a text file. It is composed of a list of entries. Each
entry consists of one or more input sentences, followed with one or more blank
lines, followed with a message. Two entries are separated by one or more blank
lines. The syntax of an input sentence is described in §<a href="#sec%3Asentences">8.1</a>.
A message is an arbitrary piece of text, but cannot cannot a blank line.</p><p>Blank lines are significant: they are used as separators, both between
entries, and (within an entry) between the sentences and the message. Thus,
there cannot be a blank line between two sentences. (If there is one, Menhir becomes confused and may complain about some word not being “a known
non-terminal symbol”). There also cannot be a blank line inside a message.</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">grammar: TYPE UID
# This hand-written comment concerns just the sentence above.
grammar: TYPE OCAMLTYPE UID PREC
# This hand-written comment concerns just the sentence above.

# This hand-written comment concerns both sentences above.

Ill-formed declaration.
Examples of well-formed declarations:
  %type &lt;Syntax.expression&gt; expression
  %type &lt;int&gt; date time
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 16: An entry in a <span style="font-family:monospace">.messages</span> file</td></tr>
</table></div>
<a id="fig:messages:entry"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">grammar: TYPE UID
##
## Ends in an error in state: 1.
##
## declaration -&gt; TYPE . OCAMLTYPE separated_nonempty_list(option(COMMA),
##   strict_actual) [ TYPE TOKEN START RIGHT PUBLIC PERCENTPERCENT PARAMETER
##   ON_ERROR_REDUCE NONASSOC LEFT INLINE HEADER EOF COLON ]
##
## The known suffix of the stack is as follows:
## TYPE
##
# This hand-written comment concerns just the sentence above.
#
grammar: TYPE OCAMLTYPE UID PREC
##
## Ends in an error in state: 5.
##
## strict_actual -&gt; symbol . loption(delimited(LPAREN,separated_nonempty_list
##   (COMMA,strict_actual),RPAREN)) [ UID TYPE TOKEN START STAR RIGHT QUESTION
##   PUBLIC PLUS PERCENTPERCENT PARAMETER ON_ERROR_REDUCE NONASSOC LID LEFT
##   INLINE HEADER EOF COMMA COLON ]
##
## The known suffix of the stack is as follows:
## symbol
##
# This hand-written comment concerns just the sentence above.

# This hand-written comment concerns both sentences above.

Ill-formed declaration.
Examples of well-formed declarations:
  %type &lt;Syntax.expression&gt; expression
  %type &lt;int&gt; date time
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 17: An entry in a <span style="font-family:monospace">.messages</span> file, decorated with auto-generated comments</td></tr>
</table></div>
<a id="fig:messages:entry:decorated"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>As an example, Figure <a href="#fig%3Amessages%3Aentry">16</a> shows a valid entry, taken
from Menhir’s own <span style="font-family:monospace">.messages</span> file. This entry contains two input sentences,
which lead to errors in two distinct states. A single message is associated
with these two error states.</p>
<!--TOC paragraph id="sec70" Comments-->
<h4 id="sec70" class="paragraph">Comments</h4><!--SEC END --><p>Comment lines, which begin with a <code>#</code> character, are ignored everywhere.
However, users who wish to take advantage of Menhir’s facility for merging
two <span style="font-family:monospace">.messages</span> files (§<a href="#sec%3Amessages%3Amerge">11.2</a>) should follow certain
conventions regarding the placement of comments:
</p><ul class="itemize"><li class="li-itemize">
If a comment concerns a specific sentence and should remain attached
to this sentence, then it must immediately follow this sentence
(without a blank line in between).
</li><li class="li-itemize">If a comment concerns all sentences in an entry, then it should appear
between the sentences and the message, with blank lines in between.
</li><li class="li-itemize">One should avoid placing comments between two entries, as the merging
algorithm will not be able to handle them in a satisfactory way.
</li></ul>
<!--TOC paragraph id="sec71" Auto-generated comments-->
<h4 id="sec71" class="paragraph">Auto-generated comments</h4><!--SEC END --><p>Several commands, described next (§<a href="#sec%3Amessages%3Atools">11.2</a>),
produce <span style="font-family:monospace">.messages</span> files where each input sentence is followed with an
auto-generated comment, marked with <code>##</code>. This special comment indicates
in which state the error is detected, and is supposed to help the reader
understand what it means to be in this state: What has been read so far? What
is expected next?</p><p>As an example, the previous entry, decorated with auto-generated comments, is
shown in Figure <a href="#fig%3Amessages%3Aentry%3Adecorated">17</a>. (We have manually wrapped the
lines that did not fit in this document.)</p><p>An auto-generated comment begins with the number of the error state that is
reached via this input sentence.</p><p>Then, the auto-generated comment shows the LR(1) items that compose this
state, in the same format as in an <span style="font-family:monospace">.automaton</span> file. these items offer a
description of the past (that is, what has been read so far) and the future
(that is, which terminal symbols are allowed next).</p><p>Finally, the auto-generated comment shows what is known about the stack when
the automaton is in this state. (This can be deduced from the LR(1) items, but
is more readable if shown separately.)
</p><p>In a canonical LR(1) automaton, the LR(1) items offer an exact description of
the past and future. However, in a noncanonical automaton, which is by default
what Menhir produces, the situation is more subtle. The lookahead sets can be
over-approximated, so the automaton can perform one or more “spurious
reductions” before an error is detected. As a result, the LR(1) items in the
error state offer a description of the future that may be both incorrect (that
is, a terminal symbol that appears in a lookahead set is not necessarily a
valid continuation) and incomplete (that is, a terminal symbol that does not
appear in any lookahead set may nevertheless be a valid continuation). More
details appear further on (§<a href="#sec%3Aerrors%3Adiagnostics">11.3</a>).</p><p>In order to attract the user’s attention to this issue, if an input sentence
causes one or more spurious reductions, then the auto-generated comment
contains a warning about this fact. This mechanism is not completely
foolproof, though, as it may be the case that one particular sentence does not
cause any spurious reductions (hence, no warning appears), yet leads to an
error state that can be reached via other sentences that do involve spurious
reductions.
</p>
<!--TOC subsection id="sec72" Maintaining <span style="font-family:monospace">.messages</span> files-->
<h3 id="sec72" class="subsection">11.2  Maintaining <span style="font-family:monospace">.messages</span> files</h3><!--SEC END --><p>
<a id="sec:messages:tools"></a></p><p>Ideally, the set of input sentences in a <span style="font-family:monospace">.messages</span> file should be correct
(that is, every sentence causes an error on its last token), irredundant (that
is, no two sentences lead to the same error state), and complete (that is,
every error state is reached by some sentence).</p>
<!--TOC paragraph id="sec73" Verifying correctness and irredundancy-->
<h4 id="sec73" class="paragraph">Verifying correctness and irredundancy</h4><!--SEC END --><p>The correctness and irredundancy of a <span style="font-family:monospace">.messages</span> file are checked by supplying
<span style="font-family:monospace">--compile-errors</span> <span style="font-style:italic">filename</span> on the command line, where <span style="font-style:italic">filename</span> is the
name of the <span style="font-family:monospace">.messages</span> file. (These arguments must be supplied in addition to
the other usual arguments, such as the name of the <span style="font-family:monospace">.mly</span> file.) This command
fails if a sentence does not cause an error at all, or causes an error too
early. It also fails if two sentences lead to the same error state.
If the file is correct and irredundant, then (as its name suggests) this
command compiles the <span style="font-family:monospace">.messages</span> file down to an OCaml function, whose code
is printed on the standard output channel. This function, named <code>message</code>,
has type <code>int -&gt; string</code>, and maps a state number to a message. It
raises the exception <code>Not_found</code> if its argument is not the number of
a state for which a message has been defined. If the set of input sentences
is complete, then it cannot raise <code>Not_found</code>.</p>
<!--TOC paragraph id="sec74" Verifying completeness-->
<h4 id="sec74" class="paragraph">Verifying completeness</h4><!--SEC END --><p>The completeness of a <span style="font-family:monospace">.messages</span> file is checked via the commands <span style="font-family:monospace">--list-errors</span> and <span style="font-family:monospace">--compare-errors</span>. The former produces, from scratch, a complete set of
input sentences, that is, a set of input sentences that reaches all error
states. The latter compares two sets of sentences (more precisely, the two
underlying sets of error states) for inclusion.</p><p>The command <span style="font-family:monospace">--list-errors</span> first computes all possible ways of causing an error.
From this information, it deduces a list of all error states, that is, all
states where an error can be detected. For each of these states, it computes a
(minimal) input sentence that causes an error in this state. Finally, it
prints these sentences, in the <span style="font-family:monospace">.messages</span> file format, on the standard output
channel. Each sentence is followed with an auto-generated comment and with a
dummy diagnostic message. The user should be warned that this algorithm may
require large amounts of time (typically in the tens of seconds, possibly
more) and memory (typically in the gigabytes, possibly more). It requires a
64-bit machine. (On a 32-bit machine, it works, but quickly hits a built-in
size limit.) At the verbosity level <span style="font-family:monospace">--log-automaton</span> <span style="font-family:monospace">2</span>, it displays
some progress information and internal statistics on the standard error
channel.</p><p>The command <span style="font-family:monospace">--compare-errors</span> <span style="font-style:italic">filename1</span> <span style="font-family:monospace">--compare-errors</span> <span style="font-style:italic">filename2</span>
compares the <span style="font-family:monospace">.messages</span> files <span style="font-style:italic">filename1</span> and <span style="font-style:italic">filename2</span>. Each file is
read and internally translated to a mapping of states to messages. Menhir then checks that the left-hand mapping is a subset of the right-hand mapping.
That is, if a state <span style="font-style:italic">s</span> is reached by some sentence in <span style="font-style:italic">filename1</span>, then it
should also be reached by some sentence in <span style="font-style:italic">filename2</span>. Furthermore, if the
message associated with <span style="font-style:italic">s</span> in <span style="font-style:italic">filename1</span> is not a dummy message, then the
same message should be associated with <span style="font-style:italic">s</span> in <span style="font-style:italic">filename2</span>.</p><p>To check that the sentences in <span style="font-style:italic">filename2</span> cover all error states, it
suffices to (1) use <span style="font-family:monospace">--list-errors</span> to produce a complete set of sentences,
which one stores in <span style="font-style:italic">filename1</span>, then (2) use <span style="font-family:monospace">--compare-errors</span> to
compare <span style="font-style:italic">filename1</span> and <span style="font-style:italic">filename2</span>.</p><p>In the case of a grammar that evolves fairly often, it can take significant
human time and effort to update the <span style="font-family:monospace">.messages</span> file and ensure correctness,
irredundancy, and completeness. A tempting way of reducing this effort is to abandon
completeness. This implies that the auto-generated <code>message</code> function can
raise <code>Not_found</code> and that a generic “syntax error” message must be
produced in that case. We prefer to discourage this approach, as it implies
that the end user is exposed to a mixture of specific and generic syntax error
messages, and there is no guarantee that the specific (hand-written) messages
will appear in <em>all</em> situations where they are expected to appear.
Instead, we recommend waiting for the grammar to become stable and enforcing
completeness.</p>
<!--TOC paragraph id="sec75" Merging <span style="font-family:monospace">.messages</span> files-->
<h4 id="sec75" class="paragraph">Merging <span style="font-family:monospace">.messages</span> files</h4><!--SEC END --><p>
<a id="sec:messages:merge"></a></p><p>The command <span style="font-family:monospace">--merge-errors</span> <span style="font-style:italic">filename1</span> <span style="font-family:monospace">--merge-errors</span> <span style="font-style:italic">filename2</span> attempts
to merge the <span style="font-family:monospace">.messages</span> files <span style="font-style:italic">filename1</span> and <span style="font-style:italic">filename2</span>, and prints the
result on the standard output channel. This command can be useful if two users
have worked independently and each of them has produced a <span style="font-family:monospace">.messages</span> file that
covers a subset of all error states. The merging algorithm works roughly as
follows:
</p><ul class="itemize"><li class="li-itemize">
All entries in <span style="font-style:italic">filename2</span> are preserved literally.
</li><li class="li-itemize">An entry in <span style="font-style:italic">filename1</span> that contains the dummy message
<code>&lt;YOUR SYNTAX ERROR MESSAGE HERE&gt;</code> is ignored.
</li><li class="li-itemize">An entry in <span style="font-style:italic">filename1</span> that leads to a state for which
there is no entry in <span style="font-style:italic">filename2</span> is copied to <span style="font-style:italic">filename2</span>.
</li><li class="li-itemize">An entry in <span style="font-style:italic">filename1</span> that leads to a state for which
there is also an entry in <span style="font-style:italic">filename2</span>, with a distinct message,
gives rise to a conflict. It is inserted into <span style="font-style:italic">filename2</span>
together with a comment that signals the conflict.
</li></ul><p>
The algorithm is asymmetric: the content of <span style="font-style:italic">filename1</span> is inserted into or
appended to <span style="font-style:italic">filename2</span>. For this reason, if one of the files is a large
“reference” file and the other file is a small “delta”, then it is
recommended to provide the “delta” as <span style="font-style:italic">filename1</span> and the “reference”
as <span style="font-style:italic">filename2</span>.</p>
<!--TOC paragraph id="sec76" Other commands-->
<h4 id="sec76" class="paragraph">Other commands</h4><!--SEC END --><p>The command <span style="font-family:monospace">--update-errors</span> <span style="font-style:italic">filename</span> is used to update the auto-generated
comments in the <span style="font-family:monospace">.messages</span> file <span style="font-style:italic">filename</span>. It is typically used after a
change in the grammar (or in the command line options that affect the
construction of the automaton). A new <span style="font-family:monospace">.messages</span> file is produced on the
standard output channel. It is identical to <span style="font-style:italic">filename</span>, except the
auto-generated comments, identified by <code>##</code>, have been removed and
re-generated.</p><p>The command <span style="font-family:monospace">--echo-errors</span> <span style="font-style:italic">filename</span> is used to filter out all comments,
blank lines, and messages from the <span style="font-family:monospace">.messages</span> file <span style="font-style:italic">filename</span>. The input
sentences, and nothing else, are echoed on the standard output channel. As an
example application, one could then translate the sentences to concrete syntax
and create a collection of source files that trigger every possible syntax
error.</p><p>The command <span style="font-family:monospace">--interpret-error</span> is analogous to <span style="font-family:monospace">--interpret</span>. It causes Menhir to
act as an interpreter. Menhir reads sentences off the standard input channel,
parses them, and displays the outcome. This switch can be usefully combined
with <span style="font-family:monospace">--trace</span>. The main difference between <span style="font-family:monospace">--interpret</span> and <span style="font-family:monospace">--interpret-error</span> is
that, when the latter command is used,
Menhir expects the input sentence to cause an error on its last token, and
displays information about the state in which the error is detected, in the
form of a <span style="font-family:monospace">.messages</span> file entry. This can be used to quickly find out exactly
what error is caused by one particular input sentence.</p>
<!--TOC subsection id="sec77" Writing accurate diagnostic messages-->
<h3 id="sec77" class="subsection">11.3  Writing accurate diagnostic messages</h3><!--SEC END --><p>
<a id="sec:errors:diagnostics"></a></p><p>One might think that writing a diagnostic message for each error state is a
straightforward (if lengthy) task. In reality, it is not so simple.
</p>
<!--TOC paragraph id="sec78" A state, not a sentence-->
<h4 id="sec78" class="paragraph">A state, not a sentence</h4><!--SEC END --><p>The first thing to keep in mind is that a diagnostic message is associated
with a <em>state</em> <span style="font-style:italic">s</span>, as opposed to a sentence. An entry in a <span style="font-family:monospace">.messages</span> file contains a sentence <span style="font-style:italic">w</span> that leads to an error in state <span style="font-style:italic">s</span>. This
sentence is just one way of causing an error in state <span style="font-style:italic">s</span>; there may exist
many other sentences that also cause an error in this state. The diagnostic
message should not be specific of the sentence <span style="font-style:italic">w</span>: it should make sense
regardless of how the state <span style="font-style:italic">s</span> is reached.</p><p>As a rule of thumb, when writing a diagnostic message, one should (as much as
possible) ignore the example sentence <span style="font-style:italic">w</span> altogether, and concentrate on the
description of the state <span style="font-style:italic">s</span>, which appears as part of the auto-generated
comment.</p><p>The LR(1) items that compose the state <span style="font-style:italic">s</span> offer a description of the past
(that is, what has been read so far) and the future (that is, which terminal
symbols are allowed next). A diagnostic message should be designed based on
this description.</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">%token ID ARROW LPAREN RPAREN COLON SEMICOLON
%start&lt;unit&gt; program
%%
typ0: ID | LPAREN typ1 RPAREN {}
typ1: typ0 | typ0 ARROW typ1  {}
declaration: ID COLON typ1    {}
program:
| LPAREN declaration RPAREN
| declaration SEMICOLON       {}
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 18: A grammar where one error state is difficult to explain</td></tr>
</table></div>
<a id="fig:declarations"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">program: ID COLON ID LPAREN
##
## Ends in an error in state: 8.
##
## typ1 -&gt; typ0 . [ SEMICOLON RPAREN ]
## typ1 -&gt; typ0 . ARROW typ1 [ SEMICOLON RPAREN ]
##
## The known suffix of the stack is as follows:
## typ0
##
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 19: A problematic error state in the grammar of Figure <a href="#fig%3Adeclarations">18</a>, due to over-approximation</td></tr>
</table></div>
<a id="fig:declarations:over"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote>
<!--TOC paragraph id="sec79" The problem of over-approximated lookahead sets-->
<h4 id="sec79" class="paragraph">The problem of over-approximated lookahead sets</h4><!--SEC END --><p>As pointed out earlier (§<a href="#sec%3Amessages%3Aformat">11.1</a>), in a noncanonical
automaton, the lookahead sets in the LR(1) items can be both over- and
under-approximated. One must be aware of this phenomenon, otherwise one runs
the risk of writing a diagnostic message that proposes too many or too few
continuations.</p><p>As an example, let us consider the grammar in Figure <a href="#fig%3Adeclarations">18</a>.
According to this grammar, a “program” is either a declaration between
parentheses or a declaration followed with a semicolon. A “declaration” is
an identifier, followed with a colon, followed with a type. A “type” is an
identifier, a type between parentheses, or a function type in the style of
OCaml.</p><p>The (noncanonical) automaton produced by Menhir for this grammar has 17 states.
Using <span style="font-family:monospace">--list-errors</span>, we find that an error can be detected in 10 of these
17 states. By manual inspection of the auto-generated comments, we find that
for 9 out of these 10 states, writing an accurate diagnostic message is easy. However,
one problematic state remains, namely state 8,
shown in Figure <a href="#fig%3Adeclarations%3Aover">19</a>.</p><p>In this state, a (level-0) type has just been read. One valid continuation,
which corresponds to the second LR(1) item in Figure <a href="#fig%3Adeclarations%3Aover">19</a>,
is to continue this type: the terminal symbol <code>ARROW</code>, followed with a
(level-1) type, is a valid continuation. Now, the question is, what other
valid continuations are there? By examining the first LR(1) item
in Figure <a href="#fig%3Adeclarations%3Aover">19</a>, it may look as if both <code>SEMICOLON</code>
and <code>RPAREN</code> are valid continuations. However, this cannot be the case. A
moment’s thought reveals that <em>either</em> we have seen an opening
parenthesis <code>LPAREN</code> at the very beginning of the program, in which case
we definitely expect a closing parenthesis <code>RPAREN</code>; <em>or</em> we have
not seen one, in which case we definitely expect a semicolon <code>SEMICOLON</code>.
It is <em>never</em> the case that <em>both</em> <code>SEMICOLON</code>
and <code>RPAREN</code> are valid continuations!</p><p>In fact, the lookahead set in the first LR(1) item
in Figure <a href="#fig%3Adeclarations%3Aover">19</a> is over-approximated.
State 8 in the noncanonical automaton results from merging two states
in the canonical automaton.</p><p>In such a situation, one cannot write an accurate diagnostic message.
Knowing that the automaton is in state 8 does not give us a
precise view of the valid continuations. Some valuable information (that is,
whether we have seen an opening parenthesis <code>LPAREN</code> at the very
beginning of the program) is buried in the automaton’s stack.</p><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">%token ID ARROW LPAREN RPAREN COLON SEMICOLON
%start&lt;unit&gt; program
%%
typ0: ID | LPAREN typ1(RPAREN) RPAREN          {}
typ1(phantom): typ0 | typ0 ARROW typ1(phantom) {}
declaration(phantom): ID COLON typ1(phantom)   {}
program:
| LPAREN declaration(RPAREN) RPAREN
| declaration(SEMICOLON)  SEMICOLON            {}
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 20: Splitting the problematic state of Figure <a href="#fig%3Adeclarations%3Aover">19</a> via selective duplication</td></tr>
</table></div>
<a id="fig:declarations:phantom"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">%token ID ARROW LPAREN RPAREN COLON SEMICOLON
%start&lt;unit&gt; program
%on_error_reduce typ1
%%
typ0: ID | LPAREN typ1 RPAREN {}
typ1: typ0 | typ0 ARROW typ1  {}
declaration: ID COLON typ1    {}
program:
| LPAREN declaration RPAREN
| declaration SEMICOLON       {}
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 21: Avoiding the problematic state of Figure <a href="#fig%3Adeclarations%3Aover">19</a> via reductions on error</td></tr>
</table></div>
<a id="fig:declarations:onerrorreduce"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><blockquote class="figure"><div class="center"><hr style="width:80%;height:2"></div>
<pre class="verbatim">program: ID COLON ID LPAREN
##
## Ends in an error in state: 15.
##
## program -&gt; declaration . SEMICOLON [ # ]
##
## The known suffix of the stack is as follows:
## declaration
##
## WARNING: This example involves spurious reductions.
## This implies that, although the LR(1) items shown above provide an
## accurate view of the past (what has been recognized so far), they
## may provide an INCOMPLETE view of the future (what was expected next).
## In state 8, spurious reduction of production typ1 -&gt; typ0
## In state 11, spurious reduction of production declaration -&gt; ID COLON typ1
##
</pre>
<div class="caption"><table style="border-spacing:6px;border-collapse:separate;" class="cellpading0"><tr><td style="vertical-align:top;text-align:left;" >Figure 22: A problematic error state in the grammar of Figure <a href="#fig%3Adeclarations%3Aonerrorreduce">21</a>, due to under-approximation</td></tr>
</table></div>
<a id="fig:declarations:under"></a>
<div class="center"><hr style="width:80%;height:2"></div></blockquote><p>How can one work around this problem? Let us suggest three options.</p>
<!--TOC paragraph id="sec80" Blind duplication of states-->
<h4 id="sec80" class="paragraph">Blind duplication of states</h4><!--SEC END --><p>One option would be to build a canonical automaton by using the
<span style="font-family:monospace">--canonical</span> switch. In this example, one would
obtain a 27-state automaton, where the problem has disappeared. However, this
option is rarely viable, as it duplicates many states without good reason.</p>
<!--TOC paragraph id="sec81" Selective duplication of states-->
<h4 id="sec81" class="paragraph">Selective duplication of states</h4><!--SEC END --><p>A second option is to manually cause just enough duplication to remove the
problematic over-approximation. In our example, we wish to distinguish two kinds
of types and declarations, namely those that must be followed with a closing
parenthesis, and those that must be followed with a semicolon. We create
such a distinction by parameterizing <code>typ1</code> and <code>declaration</code> with a
phantom parameter. The modified grammar is shown
in Figure <a href="#fig%3Adeclarations%3Aphantom">20</a>. The phantom parameter does not affect the
language that is accepted: for instance, the nonterminal
symbols <span style="font-family:monospace">declaration(SEMICOLON)</span> and
<span style="font-family:monospace">declaration(RPAREN)</span> generate the same language as <span style="font-family:monospace">declaration</span>
in the grammar of Figure <a href="#fig%3Adeclarations">18</a>. Yet, by giving
distinct names to these two symbols, we force the construction of an
automaton where more states are distinguished. In this example, Menhir produces
a 23-state automaton. Using <span style="font-family:monospace">--list-errors</span>, we find that an error can be
detected in 11 of these 23 states, and by manual inspection of the
auto-generated comments, we find that for each of these 11 states, writing an
accurate diagnostic message is easy. In summary, we have selectively duplicated
just enough states so as to split the problematic error state into two
non-problematic error states.</p>
<!--TOC paragraph id="sec82" Reductions on error-->
<h4 id="sec82" class="paragraph">Reductions on error</h4><!--SEC END --><p>A third and last option is to introduce an <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declaration
(§<a href="#sec%3Aonerrorreduce">4.1.8</a>) so as to prevent the detection of an error in the
problematic state 8. We see in Figure <a href="#fig%3Adeclarations%3Aover">19</a> that, in
state 8, the production <span style="font-family:monospace">typ1</span> → <span style="font-family:monospace">typ0</span> is ready to
be reduced. If we could force this reduction to take place, then the automaton
would move to some other state where it would be clear which
of <code>SEMICOLON</code> and <code>RPAREN</code> is expected. We
achieve this by marking <code>typ1</code> as “reducible on error”.
The modified grammar is shown
in Figure <a href="#fig%3Adeclarations%3Aonerrorreduce">21</a>.
For this grammar, Menhir produces a 17-state automaton.
(This is the exact same automaton as for the grammar of Figure <a href="#fig%3Adeclarations">18</a>,
except 2 of the 17 states have received extra reduction actions.)
Using <span style="font-family:monospace">--list-errors</span>, we find that an error can be detected in 9 of these 17 states.
The problematic state, namely state 8, is no longer an error state!
The problem has vanished.</p>
<!--TOC paragraph id="sec83" The problem of under-approximated lookahead sets-->
<h4 id="sec83" class="paragraph">The problem of under-approximated lookahead sets</h4><!--SEC END --><p>The third option seems by far the simplest of all, and is recommended in many
situations. However, it comes with a caveat. There may now exist states whose
lookahead sets are under-approximated, in a certain sense. Because of this,
there is a danger of writing an incomplete diagnostic message, one that does
not list all valid continuations.</p><p>To see this, let us look again at the sentence
<span style="font-family:monospace">ID COLON ID LPAREN</span>. In the grammar and automaton of Figure <a href="#fig%3Adeclarations">18</a>,
this sentence takes us to the problematic state 8, shown in
Figure <a href="#fig%3Adeclarations%3Aover">19</a>. In the grammar and automaton of
Figure <a href="#fig%3Adeclarations%3Aonerrorreduce">21</a>, because more reduction actions are
carried out before the error is detected, this sentence takes us
to state 15, shown in Figure <a href="#fig%3Adeclarations%3Aunder">22</a>.</p><p>When writing a diagnostic message for state 15, one might be tempted to write:
“Up to this point, a declaration has been recognized. At this point, a
semicolon is expected”. Indeed, by examining the sole LR(1) item in state 15,
it looks as if <code>SEMICOLON</code> is the only permitted continuation. However,
this is not the case. Another valid continuation is <code>ARROW</code>: indeed, the
sentence
<span style="font-family:monospace">ID COLON ID ARROW ID SEMICOLON</span> forms a valid program. In fact, if
the first token following <span style="font-family:monospace">ID COLON ID</span> is <span style="font-family:monospace">ARROW</span>, then in
state 8 this token is shifted, so the two reductions that take us from state 8
through state 11 to state 15 never take place. This is why, even though
<span style="font-family:monospace">ARROW</span> does not appear in state 15 as a valid continuation, it
nevertheless is a valid continuation of <span style="font-family:monospace">ID COLON ID</span>. The warning
produced by Menhir, shown in Figure <a href="#fig%3Adeclarations%3Aunder">22</a>, is supposed to
attract attention to this issue.</p><p>Another way to explain this issue is to point out that, by declaring
<code>%on_error_reduce typ1</code>, we make a choice.
When the parser reads a type and finds an invalid token, it decides that this
type is finished, even though, in reality, this type could be continued
with <code>ARROW</code> …. This in turn causes the parser to perform another
reduction and consider the current declaration finished, even though, in
reality, this declaration could be continued with <code>ARROW</code> ….</p><p>In summary, when writing a diagnostic message for state 15, one should take
into account the fact that this state can be reached via spurious reductions
and (therefore) <code>SEMICOLON</code> may not be the only permitted continuation.
One way of doing this, without explicitly listing all permitted continuations,
is to write: “Up to this point, a declaration has been recognized. If this
declaration is complete, then at this point, a semicolon is expected”.</p>
<!--TOC subsection id="sec84" A working example-->
<h3 id="sec84" class="subsection">11.4  A working example</h3><!--SEC END --><p>
<a id="sec:errors:example"></a></p><p>The demo <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-syntax-errors"><span style="font-family:monospace">demos/calc-syntax-errors</span></a> illustrates this approach to error
handling. It is based on the demo <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc"><span style="font-family:monospace">demos/calc</span></a>, which involves a very
simple grammar of arithmetic expressions. Compared with <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc"><span style="font-family:monospace">demos/calc</span></a>,
one <span style="font-family:sans-serif"><span style="font-weight:bold">%on_error_reduce</span></span> declaration is added so as to reduce the number of error
states. There remain just 9 error states, for which we write 5 distinct syntax
error messages. These messages are stored in the file
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-syntax-errors/parserMessages.messages"><span style="font-family:monospace">demos/calc-syntax-errors/parserMessages.messages</span></a>.
The file <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-syntax-errors/dune"><span style="font-family:monospace">demos/calc-syntax-errors/dune</span></a> instructs the build system to
check this file for correctness, irredundancy and completeness and to compile
this file into an OCaml module <code>parserMessages.ml</code>.
This OCaml module contains a single function, <code>ParserMessages.messages</code>,
which maps a state number to a diagnostic message. It is called from the main
module, <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-syntax-errors/calc.ml"><span style="font-family:monospace">demos/calc-syntax-errors/calc.ml</span></a>.
There, we use the facilities offered by the module
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/lib/ErrorReports.mli"><span style="font-family:monospace">MenhirLib.ErrorReports</span></a> to print a full syntax error message,
which includes the precise location of the error as well as
the diagnostic message returned by
the function <code>ParserMessages.messages</code>.
As icing on the cake, we allow the diagnostic message to contain placeholders
of the form
<code>$i</code>, where <code>i</code> is an integer constant, understood as a 0-based
index into the parser’s stack. We replace such a placeholder with the fragment
of the source text that corresponds to this stack entry.
A number of expected-output files demonstrate the kind of syntax error
messages that we produce; see for instance
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-syntax-errors/calc03.exp"><span style="font-family:monospace">demos/calc-syntax-errors/calc03.exp</span></a> and
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/demos/calc-syntax-errors/calc07.exp"><span style="font-family:monospace">demos/calc-syntax-errors/calc07.exp</span></a>.</p><p>The CompCert verified compiler offers another real-world example. The
“pre-parser” is where syntax errors are detected: see
<a href="https://github.com/AbsInt/CompCert/tree/master/cparser/pre_parser.mly"><span style="font-family:monospace">cparser/pre_parser.mly</span></a>.
A database of erroneous input sentences and (templates for) diagnostic
messages is stored in <a href="https://github.com/AbsInt/CompCert/tree/master/cparser/handcrafted.messages"><span style="font-family:monospace">cparser/handcrafted.messages</span></a>.
</p>
<!--TOC section id="sec85" Coq back-end-->
<h2 id="sec85" class="section">12  Coq back-end</h2><!--SEC END --><p>
<a id="sec:coq"></a></p><p>Menhir is able to generate a parser that whose correctness can be formally
verified using the Coq proof assistant [<a href="#jourdan-leroy-pottier-12">13</a>]. This
feature is used to construct the parser of the CompCert verified
compiler [<a href="#compcert">17</a>].</p><p>Setting the <span style="font-family:monospace">--coq</span> switch on the command line enables the Coq back-end. When
this switch is set, Menhir expects an input file whose name ends
in <span style="font-family:monospace">.vy</span> and generates a Coq file whose name ends
in <span style="font-family:monospace">.v</span>.</p><p>Like a <span style="font-family:monospace">.mly</span> file, a <span style="font-family:monospace">.vy</span> file is a grammar specification,
with embedded semantic actions. The only difference is that the semantic
actions in a <span style="font-family:monospace">.vy</span> file are expressed in Coq instead
of OCaml. A <span style="font-family:monospace">.vy</span> file otherwise uses the same syntax as
a <span style="font-family:monospace">.mly</span> file. CompCert’s
<a href="https://github.com/AbsInt/CompCert/tree/master/cparser/Parser.vy"><span style="font-family:monospace">cparser/Parser.vy</span></a>
serves as an example.</p><p>Several restrictions are imposed when Menhir is used in <span style="font-family:monospace">--coq</span> mode:
</p><ul class="itemize"><li class="li-itemize">
The error handling mechanism (§<a href="#sec%3Aerrors">10</a>) is absent.
The <code>$syntaxerror</code> keyword and the <span style="font-family:sans-serif"><span style="font-weight:bold">error</span></span> token are not supported.
</li><li class="li-itemize">Location information is not propagated. The <code>$start*</code> and <code>$end*</code>
keywords (Figure <a href="#fig%3Apos">14</a>) are not supported.
</li><li class="li-itemize"><span style="font-family:sans-serif"><span style="font-weight:bold">%parameter</span></span> (§<a href="#sec%3Aparameter">4.1.2</a>) is not supported.
</li><li class="li-itemize"><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> (§<a href="#sec%3Ainline">5.3</a>) is not supported.
</li><li class="li-itemize">The standard library (§<a href="#sec%3Alibrary">5.4</a>) is not supported, of course,
because its semantic actions are expressed in OCaml. If desired, the user can define
an analogous library, whose semantic actions are expressed in Coq.
</li><li class="li-itemize">Because Coq’s type inference algorithm is rather unpredictable,
the Coq type of every nonterminal symbol must be provided via a
<span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> or <span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> declaration (§<a href="#sec%3Atype">4.1.5</a>, §<a href="#sec%3Astart">4.1.6</a>).
</li><li class="li-itemize">Unless the proof of completeness has been deactivated using
<span style="font-family:monospace">--coq-no-complete</span>, the grammar must not have a conflict
(not even a benign one, in the sense of §<a href="#sec%3Aconflicts%3Abenign">6.1</a>).
That is, the grammar must be LR(1). Conflict resolution via
priority and associativity declarations (§<a href="#sec%3Aassoc">4.1.4</a>)
is not supported.
The reason is that there is no simple formal specification
of how conflict resolution should work.
</li></ul><p>The generated file contains several modules:</p><ul class="itemize"><li class="li-itemize">
The module <code>Gram</code> defines the terminal and
non-terminal symbols, the grammar, and the semantic actions.
</li><li class="li-itemize">The module <code>Aut</code> contains the automaton
generated by Menhir, together with a certificate that is checked by Coq
while establishing the soundness and completeness of the parser.
</li></ul><p>The type <code>terminal</code> of the terminal symbols is an inductive type, with
one constructor for each terminal symbol. A terminal symbol named <code>Foo</code>
in the <code>.vy</code> file is named <code>Foo't</code> in Coq. A terminal symbol per se
does not carry a the semantic value.</p><p>We also define the type <code>token</code> of tokens, that is, dependent pairs of a
terminal symbol and a semantic value of an appropriate type for this symbol.
We model the lexer as an object of type <code>Streams.Stream token</code>, that is,
an infinite stream of tokens.
</p><p>The type <code>nonterminal</code> of the non-terminal symbols is an inductive type,
with one constructor for each non-terminal symbol. A non-terminal symbol named
<code>Bar</code> in the <code>.vy</code> file is named <code>Bar'nt</code> in Coq.</p><p>The proof of termination of an LR(1) parser in the case of invalid input seems
far from obvious. We did not find such a proof in the literature. In an
application such as CompCert [<a href="#compcert">17</a>], this question is not considered
crucial. For this reason, we did not formally establish the termination of the
parser. Instead, in order to satisfy Coq’s termination requirements, we use
the “fuel” technique: the parser takes an additional parameter
<code>log_fuel</code> of type <code>nat</code> such that 2<sup><code>log_fuel</code></sup> is the
maximum number of steps the parser is allowed to perform. In practice, one
can use a value of e.g., 40 or 50 to make sure the parser will never run out
of fuel in a reasonnable time.</p><p>Parsing can have three different outcomes, represented by the type
<code>parse_result</code>.
(This definition is implicitly parameterized over the initial
state <code>init</code>. We omit the details here.)
</p><pre class="verbatim">  Inductive parse_result :=
  | Fail_pr:    parse_result
  | Timeout_pr: parse_result
  | Parsed_pr:
      symbol_semantic_type (NT (start_nt init)) -&gt;
      Stream token -&gt;
      parse_result.
</pre><p>The outcome <code>Fail_pr</code> means that parsing has failed because of a syntax
error. (If the completeness of the parser with respect to the grammar has been
proved, this implies that the input is invalid). The outcome <code>Timeout_pr</code>
means that the fuel has been exhausted. Of course, this cannot happen if the
parser was given an infinite amount of fuel, as suggested above. The outcome
<code>Parsed_pr</code> means that the parser has succeeded in parsing a prefix of
the input stream. It carries the semantic value that has been constructed for
this prefix, as well as the remainder of the input stream.</p><p>For each entry point <code>entry</code> of the grammar, Menhir generates a
parsing function <code>entry</code>, whose type is
<code>nat -&gt; Stream token -&gt; parse_result</code>.</p><p>Two theorems are provided, named <code>entry_point_correct</code> and
<code>entry_point_complete</code>. The correctness theorem states that, if a word (a
prefix of the input stream) is accepted, then this word is valid (with respect
to the grammar) and the semantic value that is constructed by the parser is
valid as well (with respect to the grammar). The completeness theorem states
that if a word (a prefix of the input stream) is valid (with respect to the
grammar), then (given sufficient fuel) it is accepted by the parser.</p><p>These results imply that the grammar is unambiguous: for every input, there is
at most one valid interpretation. This is proved by another generated theorem,
named <code>Parser.unambiguous</code>.</p><p>The parsers produced by Menhir’s Coq back-end must be linked with a Coq
library. This library can be installed via the command <code>opam install coq-menhirlib</code>.<sup><a id="text2" href="#note2">2</a></sup>
The Coq sources of this library can be found in
the <span style="font-family:monospace">coq-menhirlib</span> directory of the Menhir repository.</p><p>The CompCert verified compiler [<a href="#compcert">17</a>,<a href="#compcert-github">16</a>] can be used as
an example if one wishes to use Menhir to generate a formally verified parser
as part of some other project. See in particular the directory
<a href="https://github.com/AbsInt/CompCert/tree/master/cparser"><span style="font-family:monospace">cparser</span></a>.</p>
<!--TOC section id="sec86" Building grammarware on top of Menhir-->
<h2 id="sec86" class="section">13  Building grammarware on top of Menhir</h2><!--SEC END --><p>
<a id="sec:grammarware"></a></p><p>It is possible to build a variety of grammar-processing tools,
also known as “grammarware” [<a href="#klint-laemmel-verhoef-05">14</a>],
on top of Menhir’s front-end. Indeed, Menhir offers a facility
for dumping a <span style="font-family:monospace">.cmly</span> file, which contains a (binary-form) representation
of the grammar and automaton,
as well as a library, <span style="font-family:monospace">MenhirSdk</span>,
for (programmatically) reading and exploiting a <span style="font-family:monospace">.cmly</span> file.
These facilities are described in §<a href="#sec%3Asdk">13.1</a>.
Furthermore, Menhir allows decorating a grammar with “attributes”,
which are ignored by Menhir’s back-ends,
yet are written to the <span style="font-family:monospace">.cmly</span> file,
thus can be exploited by other tools, via <span style="font-family:monospace">MenhirSdk</span>.
Attributes are described in §<a href="#sec%3Aattributes">13.2</a>.</p>
<!--TOC subsection id="sec87" Menhir’s SDK-->
<h3 id="sec87" class="subsection">13.1  Menhir’s SDK</h3><!--SEC END --><p>
<a id="sec:sdk"></a></p><p>The command line option <span style="font-family:monospace">--cmly</span> causes Menhir to produce a <span style="font-family:monospace">.cmly</span> file in
addition to its normal operation. This file contains a (binary-form)
representation of the grammar and automaton. This is the grammar that
is obtained after the following steps have been carried out:
</p><ul class="itemize"><li class="li-itemize">
joining multiple <span style="font-family:monospace">.mly</span> files, if necessary; </li><li class="li-itemize">eliminating anonymous rules;
</li><li class="li-itemize">expanding away parameterized nonterminal symbols;
</li><li class="li-itemize">removing unreachable nonterminal symbols;
</li><li class="li-itemize">performing OCaml type inference, if the <span style="font-family:monospace">--infer</span> switch is used;
</li><li class="li-itemize">inlining away nonterminal symbols that are decorated with <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span>.
</li></ul><p>The library <span style="font-family:monospace">MenhirSdk</span> offers an API for reading a <span style="font-family:monospace">.cmly</span> file.
The functor <a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/sdk/cmly_read.mli"><span style="font-family:monospace">MenhirSdk.Cmly_read.Read</span></a>
reads such a file and produces a module whose signature is
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/sdk/cmly_api.ml"><span style="font-family:monospace">MenhirSdk.Cmly_api.GRAMMAR</span></a>.
This API is not explained in this document; for details,
the reader is expected to follow the above links.</p>
<!--TOC subsection id="sec88" Attributes-->
<h3 id="sec88" class="subsection">13.2  Attributes</h3><!--SEC END --><p>
<a id="sec:attributes"></a></p><p>Attributes are decorations that can be placed in <span style="font-family:monospace">.mly</span> files.
They are ignored by Menhir’s back-ends,
but are written to <span style="font-family:monospace">.cmly</span> files,
thus can be exploited by other tools, via <span style="font-family:monospace">MenhirSdk</span>.</p><p>An attribute consists of a name and a payload. An attribute name is an OCaml identifier, such as <span style="font-family:monospace">cost</span>, or a list of OCaml identifiers, separated
with dots, such as <span style="font-family:monospace">my.name</span>. An attribute payload is an OCaml expression of arbitrary type, such as <span style="font-family:monospace">1</span> or <code>"&amp;&amp;"</code> or <code>print_int</code>.
Following the syntax of OCaml’s attributes, an attribute’s name and payload
are separated with one or more spaces, and are delimited by <code>[@</code> and
<code>]</code>. Thus, <code>[@cost 1]</code> and <code>[@printer print_int]</code> are examples
of attributes.</p><p>An attribute can be attached at one of four levels:
</p><ol class="enumerate" type=1><li class="li-enumerate">An attribute can be attached with the grammar.
Such an attribute must be preceded with a <code>%</code> sign and must appear
in the declarations section (§<a href="#sec%3Adecls">4.1</a>). For example, the following
is a valid declaration:
<pre class="verbatim">  %[@trace true]
</pre></li><li class="li-enumerate">An attribute can be attached with a terminal symbol.
Such an attribute must follow the declaration of this symbol.
For example, the following is a valid declaration of the terminal symbol <code>INT</code>:
<pre class="verbatim">  %token&lt;int&gt; INT [@cost 0] [@printer print_int]
</pre></li><li class="li-enumerate">An attribute can be attached with a nonterminal symbol.
Such an attribute must appear inside the rule that defines this symbol,
immediately after the name of this symbol. For instance, the following is a valid
definition of the nonterminal symbol <code>expr</code>:
<pre class="verbatim">  expr [@default EConst 0]:
    i = INT                  { EConst i }
  | e1 = expr PLUS e2 = expr { EAdd (e1, e2) }
</pre>
An attribute can be attached with a parameterized nonterminal symbol:
<pre class="verbatim">  option [@default None] (X):
          { None }
  | x = X { Some x }
</pre>
An attribute cannot be attached with a nonterminal symbol that is
decorated with the <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword.</li><li class="li-enumerate">An attribute can be attached with a producer (§<a href="#sec%3Aproducers">4.2.3</a>),
that is, with an occurrence of a terminal or nonterminal symbol in the
right-hand side of a production. Such an attribute must appear immediately
after the producer. For instance, in the following rule,
an attribute is attached with the producer <code>expr*</code>:
<pre class="verbatim">  exprs:
    LPAREN es = expr* [@list true] RPAREN { es }
</pre></li></ol><p>As a convenience, it is possible to attach many attributes with many (terminal
and nonterminal) symbols in one go, via an <span style="font-family:sans-serif"><span style="font-weight:bold">%attribute</span></span> declaration, which must
be placed in the declarations section (§<a href="#sec%3Adecls">4.1</a>).
For instance, the following declaration attaches both of the attributes
<code>[@cost 0]</code> and <code>[@precious false]</code>
with each of the symbols
<code>INT</code> and <code>id</code>:
</p><pre class="verbatim">  %attribute INT id [@cost 0] [@precious false]
</pre><p>
An <span style="font-family:sans-serif"><span style="font-weight:bold">%attribute</span></span> declaration can be considered syntactic sugar: it is desugared
away in terms of the four forms of attributes presented earlier. (The command
line switch <span style="font-family:monospace">--only-preprocess</span> can be used to see how it is desugared.)</p><p>If an attribute is attached with a parameterized nonterminal symbol, then,
when this symbol is expanded away, the attribute is transmitted to every
instance. For instance, in an earlier example, the attribute
<code>[@default None]</code> was attached with the parameterized symbol
<code>option</code>. Then, every instance of <code>option</code>, such as
<code>option(expr)</code>, <code>option(COMMA)</code>, and so on, inherits this
attribute. To attach an attribute with one specific
instance only, one can use an <span style="font-family:sans-serif"><span style="font-weight:bold">%attribute</span></span> declaration. For instance,
the declaration <code>%attribute option(expr) [@cost 10]</code> attaches
an attribute with the nonterminal symbol <code>option(expr)</code>, but
not with the symbol <code>option(COMMA)</code>.</p>
<!--TOC section id="sec89" Interaction with build systems-->
<h2 id="sec89" class="section">14  Interaction with build systems</h2><!--SEC END --><p>
<a id="sec:build"></a></p><p>This section explains some details of the compilation workflow, including
OCaml type inference and its repercussions on dependency analysis
(§<a href="#sec%3Abuild%3Ainfer">14.1</a>) and compilation flags (§<a href="#sec%3Abuild%3Aflags">14.2</a>).
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 <a href="#dune"><span style="font-family:monospace">dune</span></a> (preferred) or <span style="font-family:monospace">ocamlbuild</span>.</p>
<!--TOC subsection id="sec90" OCaml type inference and dependency analysis-->
<h3 id="sec90" 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
according to the OCaml type discipline, and their types should be known to
Menhir, which may need this knowledge. (When <span style="font-family:monospace">--inspection</span> is set, Menhir needs to know the OCaml type of every nonterminal symbol.)
To address this problem, three approaches exist:
</p><ul class="itemize"><li class="li-itemize">
Ignore the problem and let Menhir run without OCaml type information
(§<a href="#sec%3Abuild%3Ainfer%3Anone">14.1.1</a>).
</li><li class="li-itemize">Let Menhir obtain OCaml type information
by invoking the OCaml compiler
(§<a href="#sec%3Abuild%3Ainfer%3Adirect">14.1.2</a>).
</li><li class="li-itemize">Let Menhir request and receive OCaml type information
without invoking the OCaml compiler
(§<a href="#sec%3Abuild%3Ainfer%3Aindirect">14.1.3</a>).
</li></ul>
<!--TOC subsubsection id="sec91" Running without OCaml type information-->
<h4 id="sec91" class="subsubsection">14.1.1  Running without OCaml type information</h4><!--SEC END --><p>
<a id="sec:build:infer:none"></a></p><p>The simplest thing to do is to run Menhir <em>without</em> any of the flags
described in the following (§<a href="#sec%3Abuild%3Ainfer%3Adirect">14.1.2</a>,
§<a href="#sec%3Abuild%3Ainfer%3Aindirect">14.1.3</a>).
Then, the semantic actions are <em>not</em> type-checked,
and their OCaml type is <em>not</em> inferred.
(This is analogous to using <span style="font-family:monospace">ocamlyacc</span>.)
The drawbacks of this approach are as follows:
</p><ul class="itemize"><li class="li-itemize">
A type error in a semantic action is detected only when the <span style="font-family:monospace">.ml</span> file produced by Menhir is type-checked. The location of the
type error, as reported by the OCaml compiler, can be
suboptimal.
</li><li class="li-itemize">Unless a <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declaration for every nonterminal symbol is
given, the inspection API cannot be generated, that is,
<span style="font-family:monospace">--inspection</span> must be turned off.
</li></ul>
<!--TOC subsubsection id="sec92" Obtaining OCaml type information by calling the OCaml compiler-->
<h4 id="sec92" class="subsubsection">14.1.2  Obtaining OCaml type information by calling the OCaml compiler</h4><!--SEC END --><p>
<a id="sec:build:infer:direct"></a></p><p>The second approach is to let Menhir invoke the OCaml compiler so as to
type-check the semantic actions and infer their types. This is done by
invoking Menhir with the <span style="font-family:monospace">--infer</span> switch, as follows.</p><p><span style="font-family:monospace">--infer</span>.  This switch causes the semantic actions to be checked for
type consistency <em>before</em> the parser is generated. To do so, Menhir generates a mock <span style="font-family:monospace">.ml</span> file, which contains just the semantic actions, and
invokes the OCaml compiler, under the form <code>ocamlc -i</code>, so as to
type-check this file and infer the types of the semantic actions. Menhir then
reads this information and produces real <span style="font-family:monospace">.ml</span> and <span style="font-family:monospace">.mli</span> files.</p><p><span style="font-family:monospace">--ocamlc</span> <span style="font-style:italic">command</span>.  This switch controls how <span style="font-family:monospace">ocamlc</span> is invoked.
It allows setting both the name of the executable and the command line options
that are passed to it.</p><p>One difficulty with this approach is that the OCaml compiler usually
needs to consult a few <span style="font-family:monospace">.cm[iox]</span> files. Indeed, if the <span style="font-family:monospace">.mly</span> file
contains a reference to an external OCaml module, say <span style="font-family:monospace">A</span>, then the
OCaml compiler typically needs to read one or more files named
<span style="font-family:monospace">A.cm[iox]</span>.</p><p>This implies that these files must have been created first. But how is one
supposed to know, exactly, which files should be created first? One must scan
the <span style="font-family:monospace">.mly</span> file so as to find out which external modules it depends upon. In
other words, a dependency analysis is required. This analysis can be carried
out by invoking Menhir with the <span style="font-family:monospace">--depend</span> switch, as follows.</p><p><span style="font-family:monospace">--depend</span>.  This switch causes Menhir to generate dependency
information for use in conjunction with <span style="font-family:monospace">make</span>. When invoked in this mode,
Menhir does not generate a parser. Instead, it examines the grammar
specification and prints a list of prerequisites for the targets
<span style="font-style:italic">basename</span><span style="font-family:monospace">.cm[iox]</span>, <span style="font-style:italic">basename</span><span style="font-family:monospace">.ml</span>, and
<span style="font-style:italic">basename</span><span style="font-family:monospace">.mli</span>. This list is intended to be textually included
within a <span style="font-family:monospace">Makefile</span>.
To produce this list, Menhir generates a mock <span style="font-family:monospace">.ml</span> file, which contains just
the semantic actions, invokes <span style="font-family:monospace">ocamldep</span>, and postprocesses its output.</p><p><span style="font-family:monospace">--raw-depend</span>.  This switch is analogous to <span style="font-family:monospace">--depend</span>. However, in this
case, <span style="font-family:monospace">ocamldep</span>’s output is <em>not</em> postprocessed by Menhir: it is echoed
without change. This switch is not suitable for direct use with <span style="font-family:monospace">make</span> ; it is
intended for use with <span style="font-family:monospace">omake</span> or <span style="font-family:monospace">ocamlbuild</span>, which perform their own
postprocessing.</p><p><span style="font-family:monospace">--ocamldep</span> <span style="font-style:italic">command</span>.  This switch controls how <span style="font-family:monospace">ocamldep</span> is
invoked. It allows setting both the name of the executable and the command
line options that are passed to it.</p>
<!--TOC subsubsection id="sec93" Obtaining OCaml type information without calling the OCaml compiler-->
<h4 id="sec93" class="subsubsection">14.1.3  Obtaining OCaml type information without calling the OCaml compiler</h4><!--SEC END --><p>
<a id="sec:build:infer:indirect"></a></p><p>The third approach is to let Menhir request and receive OCaml type
information <em>without</em> allowing Menhir to invoke the OCaml compiler.
There is nothing magic about this: to achieve this, Menhir must be invoked
twice, and the OCaml compiler must be invoked (by the user, or by the build
system) in between. This is done as follows.</p><p><span style="font-family:monospace">--infer-write-query</span> <span style="font-style:italic">mockfilename</span>.  When invoked in this mode, Menhir does
not generate a parser. Instead, generates a mock <span style="font-family:monospace">.ml</span> file, named
<span style="font-style:italic">mockfilename</span>, which contains just the semantic actions. Then, it stops.</p><p>It is then up to the user (or to the build system) to invoke <code>ocamlc -i</code>
so as to type-check the mock <span style="font-family:monospace">.ml</span> file and infer its signature. The output of
this command should be redirected to some file <span style="font-style:italic">sigfilename</span>. Then, Menhir can be invoked again, as follows.</p><p><span style="font-family:monospace">--infer-read-reply</span> <span style="font-style:italic">sigfilename</span>.  When invoked in this mode, Menhir assumes that the file <span style="font-style:italic">sigfilename</span> contains the result of running
<code>ocamlc -i</code> on the file <span style="font-style:italic">mockfilename</span>. It reads and parses this file,
so as to obtain the OCaml type of every semantic action, then proceeds
normally to generate a parser.</p><p>This protocol was introduced on 2018/05/23; earlier versions of Menhir do not
support it. Its existence can be tested as follows:</p><p><span style="font-family:monospace">--infer-protocol-supported</span>.  When invoked with this switch,
Menhir immediately terminates with exit code 0. An earlier version
of Menhir, which does not support this protocol, would display a
help message and terminate with a nonzero exit code.</p>
<!--TOC subsection id="sec94" Compilation flags-->
<h3 id="sec94" class="subsection">14.2  Compilation flags</h3><!--SEC END --><p>
<a id="sec:build:flags"></a></p><p>The following switches allow querying Menhir so as to find out which
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 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 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.cma</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 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.cmxa</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="sec95" Comparison with <span style="font-family:monospace">ocamlyacc</span>-->
<h2 id="sec95" 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
invoke functions in the module <span style="font-family:monospace">Parsing</span> behave slightly incorrectly.
For instance, the functions that provide access to positions return a dummy
position when invoked by a Menhir parser. Porting a grammar specification from
ocamlyacc to Menhir requires replacing all calls to <span style="font-family:monospace">Parsing</span> with new
Menhir-specific keywords (§<a href="#sec%3Apositions">7</a>).</p><p>Here is an incomplete list of the differences between <span style="font-family:monospace">ocamlyacc</span> and Menhir.
The list is roughly sorted by decreasing order of importance.</p><ul class="itemize"><li class="li-itemize">Menhir allows the definition of a nonterminal symbol to be
parameterized (§<a href="#sec%3Atemplates">5.2</a>). A formal parameter can be instantiated
with a terminal symbol, a nonterminal symbol, or an anonymous rule
(§<a href="#sec%3Aactual">4.2.4</a>). A library of standard parameterized definitions
(§<a href="#sec%3Alibrary">5.4</a>), including options, sequences, and lists, is bundled
with Menhir. EBNF syntax is supported: the modifiers <span style="font-family:sans-serif"><span style="font-weight:bold">?</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold"><span style="font-size:small">+</span></span></span>, and
<span style="font-family:sans-serif"><span style="font-weight:bold">*</span></span> are sugar for options, nonempty lists, and arbitrary lists
(Figure <a href="#fig%3Asugar">2</a>).</li><li class="li-itemize"><span style="font-family:monospace">ocamlyacc</span> only accepts LALR(1) grammars. Menhir accepts LR(1) grammars,
thus avoiding certain artificial conflicts.</li><li class="li-itemize">Menhir’s <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> keyword (§<a href="#sec%3Ainline">5.3</a>) helps avoid or resolve some LR(1)
conflicts without artificial modification of the grammar.</li><li class="li-itemize">Menhir explains conflicts (§<a href="#sec%3Aconflicts">6</a>) in terms of the grammar,
not just in terms of the automaton. Menhir’s explanations are believed
to be understandable by mere humans.</li><li class="li-itemize">Menhir offers an incremental API (in <span style="font-family:monospace">--table</span> mode only) (§<a href="#sec%3Aincremental">9.2</a>). This
means that the state of the parser can be saved at any point (at no
cost) and that parsing can later be resumed from a saved state.</li><li class="li-itemize">Menhir offers a set of tools for building a (complete, irredundant)
set of invalid input sentences, mapping each such sentence to a (hand-written)
error message, and maintaining this set as the grammar evolves (§<a href="#sec%3Aerrors%3Anew">11</a>).</li><li class="li-itemize">In <span style="font-family:monospace">--coq</span> mode, Menhir produces a parser whose correctness and
completeness with respect to the grammar can be checked by Coq (§<a href="#sec%3Acoq">12</a>).</li><li class="li-itemize">Menhir offers an interpreter (§<a href="#sec%3Ainterpret">8</a>) that helps debug
grammars interactively.</li><li class="li-itemize">Menhir allows grammar specifications to be split over multiple files (§<a href="#sec%3Asplit">5.1</a>).
It also allows several grammars to share a single set of tokens.</li><li class="li-itemize">Menhir produces reentrant parsers.</li><li class="li-itemize">Menhir is able to produce parsers that are parameterized by OCaml modules.</li><li class="li-itemize"><span style="font-family:monospace">ocamlyacc</span> requires semantic values to be referred to via keywords: <code>$1</code>,
<code>$2</code>, and so on. Menhir allows semantic values to be explicitly named.</li><li class="li-itemize">Menhir warns about end-of-stream conflicts (§<a href="#sec%3Aeos">6.4</a>), whereas
<span style="font-family:monospace">ocamlyacc</span> does not. Menhir warns about productions that are never
reduced, whereas, at least in some cases, <span style="font-family:monospace">ocamlyacc</span> does not.</li><li class="li-itemize">Menhir offers an option to typecheck semantic actions <em>before</em>
a parser is generated: see <span style="font-family:monospace">--infer</span>.</li><li class="li-itemize"><span style="font-family:monospace">ocamlyacc</span> produces tables that are interpreted by a piece of C code,
requiring semantic actions to be encapsulated as OCaml closures and
invoked by C code. Menhir offers a choice between producing tables
and producing code. In either case, no C code is involved.</li><li class="li-itemize">Menhir makes OCaml’s standard library module <span style="font-family:monospace">Parsing</span>
entirely obsolete. Access to locations is now via keywords
(§<a href="#sec%3Apositions">7</a>). Uses of <code>raise Parse_error</code> within
semantic actions are deprecated. The function <code>parse_error</code> is
deprecated. They are replaced with keywords (§<a href="#sec%3Aerrors">10</a>).</li><li class="li-itemize">Menhir’s error handling mechanism (§<a href="#sec%3Aerrors">10</a>) is inspired
by <span style="font-family:monospace">ocamlyacc</span>’s, but is not guaranteed to be fully
compatible. Error recovery, also known as re-synchronization, is not
supported by Menhir.</li><li class="li-itemize">The way in which severe conflicts (§<a href="#sec%3Aconflicts">6</a>) are resolved
is not guaranteed to be fully compatible with <span style="font-family:monospace">ocamlyacc</span>.</li><li class="li-itemize">Menhir warns about unused <span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%nonassoc</span></span>, <span style="font-family:sans-serif"><span style="font-weight:bold">%left</span></span>, and <span style="font-family:sans-serif"><span style="font-weight:bold">%right</span></span> declarations. It also warns about <span style="font-family:sans-serif"><span style="font-weight:bold">%prec</span></span> annotations that do not
help resolve a conflict.</li><li class="li-itemize">Menhir accepts OCaml-style comments.</li><li class="li-itemize">Menhir allows <span style="font-family:sans-serif"><span style="font-weight:bold">%start</span></span> and <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declarations to be condensed.</li><li class="li-itemize">Menhir allows two (or more) productions to share a single semantic action.</li><li class="li-itemize">Menhir produces better error messages when a semantic action
contains ill-balanced parentheses.</li><li class="li-itemize"><span style="font-family:monospace">ocamlyacc</span> ignores semicolons and commas everywhere. Menhir regards
semicolons and commas as significant, and allows them, or requires them,
in certain well-defined places.</li><li class="li-itemize"><span style="font-family:monospace">ocamlyacc</span> allows <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declarations to refer to terminal or non-terminal
symbols, whereas Menhir requires them to refer to non-terminal symbols.
Types can be assigned to terminal symbols with a <span style="font-family:sans-serif"><span style="font-weight:bold">%token</span></span> declaration.</li></ul>
<!--TOC section id="sec96" Questions and Answers-->
<h2 id="sec96" class="section">16  Questions and Answers</h2><!--SEC END --><p>
<a id="sec:qa"></a></p><p><br>
⋄ <span style="font-weight:bold">Is Menhir faster than </span><span style="font-weight:bold"><span style="font-family:monospace">ocamlyacc</span></span><span style="font-weight:bold">? What is the speed difference
between </span><span style="font-weight:bold"><span style="font-family:monospace">menhir</span></span><span style="font-weight:bold"> and </span><span style="font-weight:bold"><span style="font-family:monospace">menhir --table</span></span><span style="font-weight:bold">?</span> A (not quite
scientific) benchmark suggests that the parsers produced by <span style="font-family:monospace">ocamlyacc</span> and
<span style="font-family:monospace">menhir --table</span> have comparable speed, whereas those produced by
<span style="font-family:monospace">menhir</span> are between 2 and 5 times faster. This benchmark excludes the
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 be 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 <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>.
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,
pass <code>-menhir "menhir --table"</code> to <span style="font-family:monospace">ocamlbuild</span>,
and either
pass <code>-package menhirLib</code> to <span style="font-family:monospace">ocamlbuild</span> or add the tag <code>package(menhirLib)</code> in the <code>_tags</code> file.
To combine multiple <span style="font-family:monospace">.mly</span> files,
say <code>a.mly</code> and <code>b.mly</code>,
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 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><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)
  (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>.)
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://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>),
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">My </span><span style="font-weight:bold"><span style="font-family:monospace">.mly</span></span><span style="font-weight:bold"> file begins with a module alias declaration </span><span style="font-weight:bold"><span style="font-family:monospace">module F
= Foo</span></span><span style="font-weight:bold">. Because of this, the </span><span style="font-weight:bold"><span style="font-family:monospace">.mli</span></span><span style="font-weight:bold"> file generated by Menhir contains
references to </span><span style="font-weight:bold"><span style="font-family:monospace">F</span></span><span style="font-weight:bold"> instead of </span><span style="font-weight:bold"><span style="font-family:monospace">Foo</span></span><span style="font-weight:bold">. This does not make sense!</span>
Beginning with Menhir 20200525, Menhir prefers to use the types inferred by
the OCaml compiler over the types provided by the user in <span style="font-family:sans-serif"><span style="font-weight:bold">%type</span></span> declarations. (This may sound strange, but these types can differ in some
situations that involve polymorphic variants. Using the inferred type is
required for type soundness.)
In the presence of a module alias declaration such as <span style="font-family:monospace">module F =
Foo</span>, OCaml can infer types that begin with <span style="font-family:monospace">F.</span> instead of
<span style="font-family:monospace">Foo.</span>, and Menhir currently does not detect that <span style="font-family:monospace">F</span> is a local
name.
The suggested fix is to avoid placing module alias declarations in <span style="font-family:monospace">.mly</span> files.
</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
when the grammar is not LALR(1). If these two states happen to
contain a shift/reduce conflict, then Menhir reports two conflicts,
while <span style="font-family:monospace">ocamlyacc</span> only reports one. Of course, the two conflicts are
very similar, so fixing one will usually fix the other as well.</p><p><br>
⋄ <span style="font-weight:bold">I do not use </span><span style="font-weight:bold"><span style="font-family:monospace">ocamllex</span></span><span style="font-weight:bold">. Is there an API that does not involve lexing
buffers?</span> Like <span style="font-family:monospace">ocamlyacc</span>, Menhir produces parsers whose monolithic API
(§<a href="#sec%3Amonolithic">9.1</a>) is intended for use with <span style="font-family:monospace">ocamllex</span>. However, it is
possible to convert them, after the fact, to a simpler, revised API. In the
revised API, there are no lexing buffers, and a lexer is just a function from
unit to tokens. Converters are provided by the library module
<a href="https://gitlab.inria.fr/fpottier/menhir/blob/master/lib/Convert.mli"><span style="font-family:monospace">MenhirLib.Convert</span></a>. This can be useful, for instance, for users of
<span style="font-family:monospace">sedlex</span>, the Unicode-friendly lexer generator. Also, please note that Menhir’s
incremental API (§<a href="#sec%3Aincremental">9.2</a>) does not mention the type
<code>Lexing.lexbuf</code>. In this API, the parser expects to be supplied with
triples of a token and start/end positions of type <code>Lexing.position</code>.</p><p><br>
⋄ <span style="font-weight:bold">I need both </span><span style="font-weight:bold"><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span></span><span style="font-weight:bold"> and non-</span><span style="font-weight:bold"><span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span></span><span style="font-weight:bold"> versions of a non-terminal
symbol. Is this possible?</span> Define an <span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> version first, then use it to
define a non-<span style="font-family:sans-serif"><span style="font-weight:bold">%inline</span></span> version, like this:
</p><pre class="verbatim">%inline ioption(X):  (* nothing *) { None } | x = X { Some x }
         option(X): o = ioption(X) { o }
</pre><p>
This can work even in the presence of recursion, as illustrated by the
following definition of (reversed, left-recursive, possibly empty) lists:
</p><pre class="verbatim">%inline irevlist(X):    (* nothing *) { [] } | xs = revlist(X) x = X { x :: xs }
         revlist(X): xs = irevlist(X) { xs }
</pre><p>
The definition of <code>irevlist</code> is expanded into the definition of <code>revlist</code>,
so in the end, <code>revlist</code> receives its normal, recursive definition. One can
then view <code>irevlist</code> as a variant of <code>revlist</code> that is inlined one level
deep.
</p><p><br>
⋄ <span style="font-weight:bold">Can I ship a generated parser while avoiding a dependency on </span><span style="font-weight:bold"><span style="font-family:monospace">MenhirLib</span></span><span style="font-weight:bold">?</span>
Yes. One option is to use the code-based back-end (that is, to not
use <span style="font-family:monospace">--table</span>). In this case, the generated parser is self-contained. Another
option is to use the table-based back-end (that is, use <span style="font-family:monospace">--table</span>) and include a
copy of the files <code>menhirLib.{ml,mli}</code> together with the generated
parser. The command <span style="font-family:monospace">menhir </span><span style="font-family:monospace">--suggest-menhirLib</span> will tell you where to
find these source files.</p><p><br>
⋄ <span style="font-weight:bold">Why is </span><span style="font-weight:bold"><span style="font-family:monospace">$startpos</span></span><span style="font-weight:bold"> off towards the left? It seems to include some leading whitespace.</span>
Indeed, as of 2015/11/04, the computation of positions has changed so as to match <span style="font-family:monospace">ocamlyacc</span>’s
behavior. As a result, <span style="font-family:monospace">$startpos</span> can now appear to be too far off to the left. This is explained
in §<a href="#sec%3Apositions">7</a>. In short, the solution is to use <code>$symbolstartpos</code> instead.</p><p><br>
⋄ <span style="font-weight:bold">Can I pretty-print a grammar in ASCII, HTML, or L<sup>A</sup>T<sub>E</sub>X format?</span>
Yes. Have a look at <span style="font-family:monospace">obelisk</span> [<a href="#obelisk">4</a>].</p><p><br>
⋄ <span style="font-weight:bold">Does Menhir support mid-rule actions?</span> Yes.
See <span style="font-style:italic">midrule</span> and its explanation in §<a href="#sec%3Alibrary">5.4</a>.</p>
<!--TOC section id="sec97" Technical background-->
<h2 id="sec97" class="section">17  Technical background</h2><!--SEC END --><p>After experimenting with Knuth’s canonical LR(1) technique [<a href="#knuth-lr-65">15</a>],
we found that it <em>really</em> is not practical, even on today’s computers.
For this reason, Menhir implements a slightly modified version of Pager’s
algorithm [<a href="#pager-77">19</a>], which merges states on the fly if it can be proved
that no reduce/reduce conflicts will arise as a consequence of this decision.
This is how Menhir avoids the so-called <em>mysterious</em> conflicts created
by LALR(1) parser generators [<a href="#bison">7,  section 5.7</a>].</p><p>Menhir’s algorithm for explaining conflicts is inspired by DeRemer and
Pennello’s [<a href="#deremer-pennello-82">6</a>] and adapted for use with Pager’s
construction technique.</p><p>By default, Menhir produces code, as opposed to tables. This approach has
been explored before [<a href="#bhamidipaty-proebsting-98">3</a>,<a href="#horspool-faster-90">9</a>].
Menhir performs some static analysis of the automaton in order to produce
more compact code.</p><p>When asked to produce tables, Menhir performs compression via first-fit
row displacement, as described by Tarjan and Yao [<a href="#tarjan-yao-79">23</a>].
Double displacement is not used. The action table is made sparse by
factoring out an error matrix, as suggested by Dencker, Dürre, and
Heuft [<a href="#dencker-84">5</a>].</p><p>The type-theoretic tricks that triggered our interest in LR
parsers [<a href="#pottier-regis-gianas-typed-lr">21</a>] are not implemented in Menhir.
In the beginning, we did not implement them because the OCaml compiler did
not at the time offer generalized algebraic data types (GADTs). Today, OCaml has GADTs, but, as the saying goes, “if it ain’t broken, don’t fix it”.</p><p>The main ideas behind the Coq back-end are described in a paper by Jourdan,
Pottier and Leroy [<a href="#jourdan-leroy-pottier-12">13</a>]. The C11 parser in the
CompCert compiler [<a href="#compcert">17</a>] is constructed by Menhir and verified by
Coq, following this technique. How to construct a correct C11 parser using
Menhir is described by Jourdan and Pottier [<a href="#jourdan-pottier-17">12</a>].</p><p>The approach to error reports presented in §<a href="#sec%3Aerrors%3Anew">11</a> was
proposed by Jeffery [<a href="#jeffery-03">10</a>] and further explored by
Pottier [<a href="#pottier-reachability-cc-2016">20</a>].</p>
<!--TOC section id="sec98" Acknowledgements-->
<h2 id="sec98" class="section">18  Acknowledgements</h2><!--SEC END --><p>Menhir’s interpreter (<span style="font-family:monospace">--interpret</span>) and table-based back-end (<span style="font-family:monospace">--table</span>) were
implemented by Guillaume Bau, Raja Boujbel, and François Pottier. The project
was generously funded by Jane Street Capital, LLC through the “OCaml Summer
Project” initiative.</p><p>Frédéric Bour provided motivation and an initial implementation for the
incremental API, for the inspection API, for attributes, and for <span style="font-family:monospace">MenhirSdk</span>.
<a href="https://github.com/ocaml/merlin">Merlin</a>, an emacs mode for OCaml,
contains an impressive incremental, syntax-error-tolerant OCaml parser,
which is based on Menhir and has been a driving force for Menhir’s APIs.</p><p>Jacques-Henri Jourdan designed and implemented the Coq back-end and did the
Coq proofs for it.</p><p>Gabriel Scherer provided motivation for investigating Jeffery’s technique.</p><!--TOC section id="sec99" References-->
<h2 id="sec99" class="section">References</h2><!--SEC END --><dl class="thebibliography"><dt class="dt-thebibliography">
<a id="aho-86"><span style="color:purple">[1]</span></a></dt><dd class="dd-thebibliography">
Alfred V. Aho, Ravi Sethi, and Jeffrey D. Ullman.
<em>Compilers: Principles, Techniques, and Tools</em>.
Addison-Wesley, 1986.</dd><dt class="dt-thebibliography"><a id="appel-tiger-98"><span style="color:purple">[2]</span></a></dt><dd class="dd-thebibliography">
Andrew Appel.
<a href="http://www.cs.princeton.edu/~appel/modern/ml/"><em>Modern
Compiler Implementation in </em><em>ML</em></a>.
Cambridge University Press, 1998.</dd><dt class="dt-thebibliography"><a id="bhamidipaty-proebsting-98"><span style="color:purple">[3]</span></a></dt><dd class="dd-thebibliography">
Achyutram Bhamidipaty and Todd A. Proebsting.
<a href="http://www.cs.arizona.edu/people/todd/papers/TR95-09.ps">Very
fast YACC-compatible parsers (for very little effort)</a>.
<em>Software: Practice and Experience</em>, 28(2):181–190, 1998.</dd><dt class="dt-thebibliography"><a id="obelisk"><span style="color:purple">[4]</span></a></dt><dd class="dd-thebibliography">
Lélio Brun.
Obelisk.
<a href="https://github.com/Lelio-Brun/Obelisk"><span style="font-family:monospace">https://github.com/Lelio-Brun/Obelisk</span></a>, 2017.</dd><dt class="dt-thebibliography"><a id="dencker-84"><span style="color:purple">[5]</span></a></dt><dd class="dd-thebibliography">
Peter Dencker, Karl Dürre, and Johannes Heuft.
<a href="http://doi.acm.org/10.1145/1780.1802">Optimization of parser
tables for portable compilers</a>.
<em>ACM Transactions on Programming Languages and Systems</em>,
6(4):546–572, 1984.</dd><dt class="dt-thebibliography"><a id="deremer-pennello-82"><span style="color:purple">[6]</span></a></dt><dd class="dd-thebibliography">
Frank DeRemer and Thomas Pennello.
<a href="http://doi.acm.org/10.1145/69622.357187">Efficient computation
of <span style="font-style:italic">LALR</span>(1) look-ahead sets</a>.
<em>ACM Transactions on Programming Languages and Systems</em>,
4(4):615–649, 1982.</dd><dt class="dt-thebibliography"><a id="bison"><span style="color:purple">[7]</span></a></dt><dd class="dd-thebibliography">
Charles Donnelly and Richard Stallman.
<a href="http://www.gnu.org/software/bison/manual/"><em>Bison</em></a>, 2015.</dd><dt class="dt-thebibliography"><a id="hopcroft-motwani-ullman-00"><span style="color:purple">[8]</span></a></dt><dd class="dd-thebibliography">
John E. Hopcroft, Rajeev Motwani, and Jeffrey D. Ullman.
<a href="http://www-db.stanford.edu/~ullman/ialc.html"><em>Introduction
to Automata Theory, Languages, and Computation</em></a>.
Addison-Wesley, 2000.</dd><dt class="dt-thebibliography"><a id="horspool-faster-90"><span style="color:purple">[9]</span></a></dt><dd class="dd-thebibliography">
R. Nigel Horspool and Michael Whitney.
<a href="http://www.cs.uvic.ca/~nigelh/Publications/fastparse.pdf">Even
faster LR parsing</a>.
<em>Software: Practice and Experience</em>, 20(6):515–535, 1990.</dd><dt class="dt-thebibliography"><a id="jeffery-03"><span style="color:purple">[10]</span></a></dt><dd class="dd-thebibliography">
Clinton L. Jeffery.
<a href="http://doi.acm.org/10.1145/937563.937566">Generating LR
syntax error messages from examples</a>.
<em>ACM Transactions on Programming Languages and Systems</em>,
25(5):631–640, 2003.</dd><dt class="dt-thebibliography"><a id="johnson-yacc-79"><span style="color:purple">[11]</span></a></dt><dd class="dd-thebibliography">
Steven C. Johnson.
<a href="http://dinosaur.compilertools.net/">Yacc: Yet another
compiler compiler</a>.
In <em>UNIX</em><em> Programmer’s Manual</em>, volume 2, pages 353–387. Holt,
Rinehart, and Winston, 1979.</dd><dt class="dt-thebibliography"><a id="jourdan-pottier-17"><span style="color:purple">[12]</span></a></dt><dd class="dd-thebibliography">
Jacques-Henri Jourdan and François Pottier.
<a href="http://gallium.inria.fr/~fpottier/publis/jourdan-fpottier-2016.pdf">A
simple, possibly correct LR parser for C11</a>.
<em>ACM Transactions on Programming Languages and Systems</em>,
39(4):14:1–14:36, August 2017.</dd><dt class="dt-thebibliography"><a id="jourdan-leroy-pottier-12"><span style="color:purple">[13]</span></a></dt><dd class="dd-thebibliography">
Jacques-Henri Jourdan, François Pottier, and Xavier Leroy.
<a href="http://gallium.inria.fr/~fpottier/publis/jourdan-leroy-pottier-validating-parsers.pdf">Validating
<span style="font-style:italic">LR</span>(1) parsers</a>.
volume 7211, pages 397–416, 2012.</dd><dt class="dt-thebibliography"><a id="klint-laemmel-verhoef-05"><span style="color:purple">[14]</span></a></dt><dd class="dd-thebibliography">
Paul Klint, Ralf Lämmel, and Chris Verhoef.
<a href="http://www.few.vu.nl/~x/gw/gw.pdf">Toward an engineering
discipline for grammarware</a>.
14(3):331–380, 2005.</dd><dt class="dt-thebibliography"><a id="knuth-lr-65"><span style="color:purple">[15]</span></a></dt><dd class="dd-thebibliography">
Donald E. Knuth.
<a href="http://www.sciencedirect.com/science/article/pii/S0019995865904262">On
the translation of languages from left to right</a>.
<em>Information &amp; Control</em>, 8(6):607–639, 1965.</dd><dt class="dt-thebibliography"><a id="compcert-github"><span style="color:purple">[16]</span></a></dt><dd class="dd-thebibliography">
Xavier Leroy.
The CompCert C verified compiler.
<a href="https://github.com/AbsInt/CompCert"><span style="font-family:monospace">https://github.com/AbsInt/CompCert</span></a>, 2014.</dd><dt class="dt-thebibliography"><a id="compcert"><span style="color:purple">[17]</span></a></dt><dd class="dd-thebibliography">
Xavier Leroy.
The CompCert C compiler.
<a href="http://compcert.inria.fr/"><span style="font-family:monospace">http://compcert.inria.fr/</span></a>, 2015.</dd><dt class="dt-thebibliography"><a id="ocaml"><span style="color:purple">[18]</span></a></dt><dd class="dd-thebibliography">
Xavier Leroy, Damien Doligez, Alain Frisch, Jacques Garrigue, Didier Rémy, and
Jérôme Vouillon.
<a href="http://caml.inria.fr/">The OCaml system: documentation and
user’s manual</a>, 2016.</dd><dt class="dt-thebibliography"><a id="pager-77"><span style="color:purple">[19]</span></a></dt><dd class="dd-thebibliography">
David Pager.
<a href="http://dx.doi.org/10.1007/BF00290336">A practical general
method for constructing <span style="font-style:italic">LR</span>(<span style="font-style:italic">k</span>) parsers</a>.
<em>Acta Informatica</em>, 7:249–268, 1977.</dd><dt class="dt-thebibliography"><a id="pottier-reachability-cc-2016"><span style="color:purple">[20]</span></a></dt><dd class="dd-thebibliography">
François Pottier.
<a href="http://gallium.inria.fr/~fpottier/publis/fpottier-reachability-cc2016.pdf">Reachability
and error diagnosis in LR(1) parsers</a>.
In <em>Compiler Construction (CC)</em>, pages 88–98, 2016.</dd><dt class="dt-thebibliography"><a id="pottier-regis-gianas-typed-lr"><span style="color:purple">[21]</span></a></dt><dd class="dd-thebibliography">
François Pottier and Yann Régis-Gianas.
<a href="http://gallium.inria.fr/~fpottier/publis/fpottier-regis-gianas-typed-lr.pdf">Towards
efficient, typed LR parsers</a>.
<em>Electronic Notes in Theoretical Computer Science</em>,
148(2):155–180, 2006.</dd><dt class="dt-thebibliography"><a id="tarditi-appel-00"><span style="color:purple">[22]</span></a></dt><dd class="dd-thebibliography">
David R. Tarditi and Andrew W. Appel.
<a href="http://www.smlnj.org/doc/ML-Yacc/"><em>ML-Yacc</em><em> User’s
Manual</em></a>, 2000.</dd><dt class="dt-thebibliography"><a id="tarjan-yao-79"><span style="color:purple">[23]</span></a></dt><dd class="dd-thebibliography">
Robert Endre Tarjan and Andrew Chi-Chih Yao.
<a href="http://doi.acm.org/10.1145/359168.359175">Storing a sparse
table</a>.
<em>Communications of the </em><em>ACM</em>, 22(11):606–611, 1979.</dd></dl><!--BEGIN NOTES document-->
<hr class="footnoterule"><dl class="thefootnotes"><dt class="dt-thefootnotes">
<a id="note1" href="#text1">1</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">The computation of <span style="font-family:monospace">$symbolstartpos</span> is optimized by Menhir under two assumptions about the lexer. First,
Menhir assumes that the lexer never produces a token whose start and end
positions are equal. Second, Menhir assumes that two positions produced
by the lexer are equal if and only if they are physically equal. If the
lexer violates either of these assumptions, the computation of
<span style="font-family:monospace">$symbolstartpos</span> could produce a result that differs from
<span style="font-family:monospace">Parsing.symbol_start_pos()</span>.
</div></dd><dt class="dt-thefootnotes"><a id="note2" href="#text2">2</a></dt><dd class="dd-thefootnotes"><div class="footnotetext">This assumes that you have installed <span style="font-family:monospace">opam</span>, the OCaml package manager,
and that you have run the command <span style="font-family:monospace">opam repo add coq-released
https://coq.inria.fr/opam/released</span>.</div></dd></dl>
<!--END NOTES-->
<!--CUT END -->
<!--HTMLFOOT-->
<!--ENDHTML-->
<!--FOOTER-->
<hr style="height:2"><blockquote class="quote"><em>This document was translated from L<sup>A</sup>T<sub>E</sub>X by
</em><a href="http://hevea.inria.fr/index.html"><em>H</em><em><span style="font-size:small"><sup>E</sup></span></em><em>V</em><em><span style="font-size:small"><sup>E</sup></span></em><em>A</em></a><em>.</em></blockquote></body>
</html>