Menhir

https://gallium.inria.fr/~fpottier/menhir/
Admin
Menhir is a parser generator that transforms high-level grammar specifications into parsers using...
Tokens:31,976
Snippets:456
Trust Score:9.9
Update:6 months ago
Show doc for...
Tokens:
Raw
### Accessing start position in a production

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Example of using the $startpos keyword within a semantic action to retrieve the start position of a production.

```menhir
  declaration: modifier? variable { $startpos }
```

--------------------------------

### Menhir Incremental API Start Function

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

This OCaml code declares the 'Incremental.main' function, which starts the incremental parser. It returns a checkpoint, serving as a starting point for parsing operations.

```ocaml
  module Incremental : sig
    val main: position -> thing MenhirInterpreter.checkpoint
  end

```

--------------------------------

### Anonymous Rule Expansion Example

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Demonstrates how an anonymous rule passed as an argument to a list is expanded into a fresh nonterminal symbol.

```menhir
list ( e = expression; SEMICOLON { e } )
```

```menhir
list ( expression_SEMICOLON )
```

```menhir
%inline expression_SEMICOLON:   
---  
| e = expression; SEMICOLON { e }
```

--------------------------------

### Menhir Interpreter Command and Output Example

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Demonstrates invoking Menhir in interpreter mode with concrete syntax tree output enabled. It shows sample input sentences and Menhir's corresponding outcomes (ACCEPT, OVERSHOOT, REJECT) and generated concrete syntax trees.

```bash
$ 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

```

--------------------------------

### Define arithmetic expressions with shift/reduce conflicts

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

A grammar example demonstrating shift/reduce conflicts due to undefined precedence in a nonterminal operator.

```Menhir
%token < int > INT  
---
%token PLUS TIMES  
%left PLUS  
%left TIMES  
%%  
expression:   
| i = INT { i }  
| e = expression; o = op; f = expression { o e f }  
op:   
| PLUS { ( + ) }  
| TIMES { ( * ) }
```

--------------------------------

### Get lookahead positions

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Returns the start and end positions of the current lookahead token.

```OCaml
  val positions: 'a env -> position * position
```

--------------------------------

### Syntactic Sugar for Multiple Attributes

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The %attribute declaration provides syntactic sugar to attach multiple attributes to multiple symbols simultaneously. This example attaches 'cost' and 'precious' attributes to 'INT' and 'id'.

```ocaml
%attribute INT id [@cost 0] [@precious false]

```

--------------------------------

### Define .messages file entries

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Example of a .messages file entry mapping grammar input sentences to a diagnostic message.

```text
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 <Syntax.expression> expression
  %type <int> date time
```

--------------------------------

### Example Sentences for Arithmetic Expressions Grammar

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

These are valid sentences for the arithmetic expressions grammar. Sentences consist of terminal symbols separated by whitespace, optionally preceded by a start symbol and terminated by a newline. The start symbol can be omitted if the grammar has only one.

```plaintext
main: INT PLUS INT EOL
INT PLUS INT
INT PLUS PLUS INT EOL
INT PLUS PLUS

```

--------------------------------

### Define .messages file entries with state information

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Example of .messages file entries including auto-generated comments detailing the automaton state and stack suffix.

```text
grammar: TYPE UID
##
## Ends in an error in state: 1.
##
## declaration -> 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 -> 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.
```

--------------------------------

### Menhir Error State Example

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

An example of a Menhir grammar snippet demonstrating an error state. The auto-generated comments indicate the state and the LR(1) items.

```menhir
program: ID COLON ID LPAREN
##
## Ends in an error in state: 8.
##
## typ1 -> typ0 . [ SEMICOLON RPAREN ]
## typ1 -> typ0 . ARROW typ1 [ SEMICOLON RPAREN ]
##
## The known suffix of the stack is as follows:
## typ0
##

```

--------------------------------

### Interpreting a Grammar with Menhir

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Use the --interpret and --interpret-show-cst flags with menhir to debug grammar associativity. This example checks left-associativity for addition.

```bash
$ ./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
]

```

--------------------------------

### Settle function for start nonterminals

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The Settle function transforms a DCST to a CST for a given start nonterminal.

```OCaml
  val main: DCST.main -> CST.main option
```

--------------------------------

### Attribute Attachment to Production

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Attributes can be attached to a production, appearing after the semantic action and any %prec annotation. This example shows attributes attached to two productions within 'option(X)'.

```ocaml
option(X):
      { None   } [@name none]
  | x = X
      { Some x } [@name some]

```

--------------------------------

### Using endrule for inlined anonymous rules

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Demonstrates how `endrule` with an `%inline` declaration effectively moves OCaml code to the end of the rule, executing after all recognized producers. This example shows a simplified case where `endrule` might be redundant.

```Menhir
cat endrule(dog { OCaml code1 }) cow { OCaml code2 }
```

```Menhir
cat dog cow { OCaml code1; OCaml code2 }
```

--------------------------------

### Generated OCaml Monolithic Parsing Function

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

This OCaml code declares the 'main' parsing function, named after the grammar's start symbol. It takes a lexer and a lexing buffer, returning a semantic value or throwing an Error.

```ocaml
  val main: (Lexing.lexbuf -> token) -> Lexing.lexbuf -> thing

```

--------------------------------

### Create Checkpoint from Environment

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Use `input_needed` to obtain a checkpoint from a parser environment. This checkpoint can then be used with `offer` to resume normal parsing. Exercise caution as this can lead to arbitrary parser states and lookahead symbols, potentially causing unexpected behavior or errors if not managed carefully.

```ocaml
val input_needed: 'a env -> 'a checkpoint
```

--------------------------------

### Menhir Command-Line Options

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Detailed explanation of available command-line switches for Menhir.

```APIDOC
## Menhir Command-Line Options

### Description
This section details the various command-line switches available for controlling Menhir's behavior.

### Method
Command Line Tool Options

### Endpoint
 menhir [option …option] [filename …filename]

### Parameters
#### Query Parameters
- **--base basename** (string) - Specifies the base name for the output .ml and .mli files. If only one filename is provided, the default basename is derived from it. Must be used when multiple filenames are provided.
- **--cmly** - Generates a .cmly file containing a binary representation of the grammar and automaton.
- **--comment** - Inserts comments into the generated OCaml code.
- **--compare-errors filename1 filename2** (string, string) - Compares error messages between two .messages files to ensure consistency. Requires two filenames.
- **--compile-errors filename** (string) - Compiles a .messages file into an OCaml function that maps state numbers to messages. Checks for correctness and irredundancy of the input sentences.
- **--rocq** - Generates Rocq code. Grammar files must end with .vy.
- **--rocq-lib-no-path** - Prevents qualification of references to the Rocq library MenhirLib. For compatibility with older versions.
- **--rocq-lib-path path** (string) - Specifies the name or path under which the Rocq support library MenhirLib is known to Rocq.
- **--rocq-no-actions** - Ignores semantic actions in the .vy file, replacing them with `tt`.
- **--rocq-no-complete** - Disables the generation of the proof of completeness for the parser. Useful for grammars with conflicts or for performance.
- **--rocq-no-version-check** - Prevents the generation of a version check between Menhir and MenhirLib.
- **--depend** - See §15 for details.
- **--dump** - Writes a description of the automaton to basename.automaton after benign conflicts are resolved but before severe conflicts and extra reductions.
- **--dump-menhirLib directory** (string) - Writes the source code of the MenhirLib runtime library to the specified directory and exits. The directory must exist.
- **--dump-resolved** - Writes a description of the automaton to basename.automaton.resolved after all conflicts are resolved and extra reductions are introduced.

### Request Example
```bash
menhir --base myparser --cmly --comment mygrammar.mly
menhir --rocq --rocq-lib-path MyRocqLib mygrammar.vy
```

### Response
Output files and behavior depend on the options specified. Common outputs include .ml, .mli, .cmly, and .automaton files.
```

--------------------------------

### Instantiate a parameterized nonterminal

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Demonstrates using the 'option' symbol within a 'declarations' rule by passing 'COMMA' as the actual parameter.

```Menhir
declarations:   
---
| { [] }  
| ds = declarations; option(COMMA); d = declaration { d :: ds }
```

--------------------------------

### Compare parser environments

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Checks if two parser configurations are physically identical in state and stack.

```OCaml
  val equal: 'a env -> 'a env -> bool
```

--------------------------------

### Define Grammar Production

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Example of a grammar production rule with a named attribute for the unparsing API.

```Menhir
  expr:
    LPAREN; e = expr; RPAREN { e } [@name paren]
```

--------------------------------

### Define production type

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The production type represents a grammar production, excluding internally constructed start productions.

```ocaml
  type production
```

--------------------------------

### Production visitor method

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Generated visitor method for a specific production, reducing children and concatenating results.

```OCaml
  expr:
    LPAREN; e = expr; RPAREN { e } [@name paren]
```

```OCaml
  method case_paren : expr -> 'r
```

--------------------------------

### Get current state number

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Returns the integer number of the current automaton state, even if the stack is empty.

```OCaml
  val current_state_number: 'a env -> int
```

--------------------------------

### Define offer function

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The offer function resumes the parser when it is in an InputNeeded state by providing a new token.

```ocaml
  val offer:
    'a checkpoint ->
    token * position * position ->
    'a checkpoint
```

--------------------------------

### Expand parameterized nonterminal instantiation

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Shows the equivalent grammar rules after the 'option' symbol is expanded with 'COMMA'.

```Menhir
optional_comma:   
---
| { None }  
| x = COMMA { Some x }  
declarations:   
| { [] }  
| ds = declarations; optional_comma; d = declaration { d :: ds }
```

--------------------------------

### Attribute Attachment to Terminal Symbol

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Attributes can be attached to terminal symbols, following their declaration. This example shows attributes for the INT terminal.

```ocaml
%token<int> INT [@cost 0] [@printer print_int]

```

--------------------------------

### Define a parser loop

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Parses tokens from a supplier until acceptance or rejection.

```OCaml
  val loop:
    ?strategy:[ `Legacy | `Simplified ] ->
    supplier -> 'a checkpoint -> 'a
```

--------------------------------

### Menhir Grammar Definition

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

A Menhir grammar definition specifying tokens, start symbol, and production rules. Used for parsing and error analysis.

```menhir
%token ID ARROW LPAREN RPAREN COLON SEMICOLON
%start<unit> program
%%
typ0: ID | LPAREN typ1 RPAREN {}
typ1: typ0 | typ0 ARROW typ1  {}
declaration: ID COLON typ1    {}
program:
| LPAREN declaration RPAREN
| declaration SEMICOLON       {}

```

--------------------------------

### CST reduce visitor class

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Virtual visitor class for traversing and reducing a CST into a printable form.

```OCaml
  class virtual ['r] reduce : object
    method virtual zero : 'r
    method virtual cat : 'r -> 'r -> 'r
    method virtual text : string -> 'r
    (* one method per terminal symbol *)
    (* one method per nonterminal symbol *)
    (* one method per production *)
  end
```

--------------------------------

### Menhir Compilation and Linking Flags CLI

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

CLI switches for retrieving necessary OCaml compilation and linking flags for Menhir-generated parsers.

```APIDOC
## CLI Switches for Compilation and Linking

### Description
These switches allow querying Menhir to determine the appropriate flags for the OCaml compiler and linker. They are particularly relevant when the --table switch is used.

### Switches
- **--suggest-comp-flags**: Prints suggested flags for ocamlc or ocamlopt. If --table is set, it suggests a -I flag for MenhirLib.
- **--suggest-link-flags-byte**: Prints suggested link flags for ocamlc. If --table is set, it suggests menhirLib.cma.
- **--suggest-link-flags-opt**: Prints suggested link flags for ocamlopt. If --table is set, it suggests menhirLib.cmxa.
- **--suggest-menhirLib**: Prints the absolute path of the directory where MenhirLib is installed.
- **--suggest-ocamlfind**: Deprecated switch that always returns false.
```

--------------------------------

### Attribute Attachment to Parameterized Nonterminal Symbol

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Attributes can be attached to parameterized nonterminal symbols. This example shows an attribute for the 'option' parameterized symbol.

```ocaml
option [@default None] (X):
          { None }
  | x = X { Some x }

```

--------------------------------

### input_needed

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Converts a parser environment into a checkpoint to resume normal parsing.

```APIDOC
## input_needed

### Description
Constructs a checkpoint from a parser environment, allowing the parser to resume in normal mode via the offer function.

### Parameters
- **env** ('a env) - Required - The parser environment to convert.

### Response
- **'a checkpoint** - A checkpoint that can be used with offer.
```

--------------------------------

### Define recursive lists with inlining

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Demonstrates defining reversed, left-recursive, possibly empty lists using the %inline keyword to manage recursion.

```menhir
%inline irevlist(X):    (* nothing *) { [] } | xs = revlist(X) x = X { x :: xs }
         revlist(X): xs = irevlist(X) { xs }
```

--------------------------------

### Attribute Attachment to Nonterminal Symbol

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Attributes can be attached to nonterminal symbols within their definition, immediately after the symbol's name. This example shows an attribute for the 'expr' nonterminal.

```ocaml
expr [@default EConst 0]:
  i = INT                  { EConst i }
| e1 = expr PLUS e2 = expr { EAdd (e1, e2) }

```

--------------------------------

### Define Executable with MenhirLib

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Include menhirLib in the libraries list when using the --table flag.

```dune
(executable
   (name myexecutable)
   (libraries menhirLib)
)
```

--------------------------------

### Manage production indices

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Converts between production objects and their integer indices.

```OCaml
  val production_index: production -> int
  val find_production: int -> production
```

--------------------------------

### Attribute Attachment to Producer

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Attributes can be attached to a producer (an occurrence of a terminal or nonterminal symbol) in the right-hand side of a production, appearing immediately after the producer. This example attaches an attribute to the 'expr*' producer.

```ocaml
exprs:
  LPAREN es = expr* [@list true] RPAREN { es }

```

--------------------------------

### Grammar with Error Reductions to Avoid Problematic States

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

This grammar uses error-based reductions to avoid problematic states, but can lead to under-approximation and spurious reductions, as shown in the error example.

```Menhir Grammar
program: ID COLON ID LPAREN

```

--------------------------------

### Use %inline keyword for automatic inlining

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Using the %inline keyword to automatically resolve conflicts without manual grammar transformation.

```Menhir
expression:   
---
| i = INT { i }  
| e = expression; o = op; f = expression { o e f }  
%inline op:   
| PLUS { ( + ) }  
| TIMES { ( * ) }
```

--------------------------------

### Define resume function

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The resume function continues parsing from non-input-needed states like Shifting or AboutToReduce.

```ocaml
  val resume:
    ?strategy:[ `Legacy | `Simplified ] ->
    'a checkpoint ->
    'a checkpoint
```

--------------------------------

### Force Reduction in Parser Environment

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Use `force_reduction` to reduce a production if the current state allows it. This executes the semantic action and performs a goto transition. An `Invalid_argument` exception is raised if the condition is not met.

```ocaml
val force_reduction: production -> 'a env -> 'a env
```

--------------------------------

### Parameterized Option Rule with Pun and Point-Free Action (New Syntax)

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Defines the 'option' nonterminal using a pun and a point-free semantic action for conciseness.

```Menhir
let option(x) :=
| = x ; { None }
| = x ; < Some >
```

--------------------------------

### Monolithic API

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The monolithic API provides a single parsing function that handles tokenization, parsing, and semantic value generation. It defines the `token` type, the `Error` exception, and a parsing function named after the grammar's start symbol.

```APIDOC
## Monolithic API Details

### Description
This API exposes a `token` type representing terminal symbols, an `Error` exception for syntax errors, and a primary parsing function.

### Type: token
Represents a terminal symbol and its associated semantic value.

Example:
```
type token =
  | A
  | B of int
```

### Exception: Error
Raised when a syntax error is detected during parsing.

```
exception Error
```

### Function: main
Parses input using a provided lexer and lexing buffer.

#### Parameters
- **lexer** (Lexing.lexbuf -> token) - The lexer function.
- **lexbuf** (Lexing.lexbuf) - The lexing buffer to parse.

#### Return Value
- **thing** - The semantic value of the parsed input.

#### Example Signature
```
val main: (Lexing.lexbuf -> token) -> Lexing.lexbuf -> thing
```
```

--------------------------------

### Attribute Declaration with %

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Attributes can be attached to the grammar itself using a '%' prefix in the declarations section.

```ocaml
%[@trace true]

```

--------------------------------

### Position Keywords in Semantic Actions

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Keywords available within Menhir's semantic actions to access and manipulate token positions. These keywords are used to retrieve start and end positions of symbols, and can be used to define custom position logic.

```APIDOC
## Position Keywords

Menhir provides a set of keywords that can be used within semantic actions to access and manipulate token positions. These keywords are crucial for tasks such as error reporting, code generation, and source code analysis.

### Keyword Reference

| Keyword | Description |
|---|---|
| `$startpos` | Start position of the first symbol in the production's right-hand side, or the end position of the most recently parsed symbol if the right-hand side is empty. |
| `$endpos` | End position of the last symbol in the production's right-hand side, or the end position of the most recently parsed symbol if the right-hand side is empty. |
| `$startpos(id)` | Start position of the symbol named `id`. |
| `$endpos(id)` | End position of the symbol named `id`. |
| `$symbolstartpos` | Start position of the leftmost symbol `id` such that `$startpos(id)` is not equal to `$endpos(id)`. If no such symbol exists, it defaults to `$endpos`. |
| `$startofs` | Integer offset representing the start position. |
| `$endofs` | Integer offset representing the end position. |
| `$startofs(id)` | Integer offset representing the start position of the symbol named `id`. |
| `$endofs(id)` | Integer offset representing the end position of the symbol named `id`. |
| `$loc` | Represents the pair `($startpos, $endpos)`. |
| `$loc(id)` | Represents the pair `($startpos(id), $endpos(id))`. |
| `$sloc` | Represents the pair `($symbolstartpos, $endpos)`. |

### Usage Notes

- These keywords are only available within semantic actions and cannot be used in OCaml headers.
- The `Lexing.lexbuf` type in OCaml provides `lex_start_p` and `lex_curr_p` fields, which are updated by the lexical analyzer. Menhir reads these fields.
- For productions with an empty right-hand side, `$startpos` and `$endpos` are conventionally set to the end position of the most recently parsed symbol.
- If a production has a non-empty right-hand side, `$startpos` is equivalent to `$startpos($1)` and `$endpos` is equivalent to `$endpos($n)`, where `n` is the length of the right-hand side.
- `$symbolstartpos` is useful when `$startpos` might point to an optional or absent symbol, providing the start position of the first meaningful symbol.
- There is no `$symbolendpos` keyword as the asymmetry in position definitions primarily affects the start position.

### Example

Consider the following production rule:

```ocaml
declaration: modifier? variable { $startpos }
```

If the `modifier?` is absent, `$startpos` would refer to the end position of the previously parsed symbol. Using `$symbolstartpos` in this case would yield the start position of the `variable` symbol, assuming it has distinct start and end positions.
```

--------------------------------

### Grammar Preprocessing and Analysis

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Switches for transforming grammar specifications and analyzing dependencies.

```APIDOC
## --only-preprocess

### Description
Transforms grammar specifications up to the point where automaton construction begins, including expanding parameterized nonterminals and inline symbols.

## --reference-graph

### Description
Writes a description of the grammar's dependency graph to basename.dot for use with the graphviz toolkit.
```

--------------------------------

### Define a parser loop with custom error handling

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Executes a success or failure continuation based on the parsing result.

```OCaml
  val loop_handle:
    ('a -> 'answer) ->
    ('a checkpoint -> 'answer) ->
    supplier -> 'a checkpoint -> 'answer
```

--------------------------------

### Token and Code Generation

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Switches for managing token definitions and selecting the parser back-end.

```APIDOC
## --only-tokens

### Description
Translates %token declarations into a token type definition written to basename.ml and basename.mli.

## --table

### Description
Instructs Menhir to use the table back-end, producing compact tables that require MenhirLib at runtime.
```

--------------------------------

### Define a parser loop with undo capability

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Provides access to the last InputNeeded checkpoint before an error for recovery or explanation.

```OCaml
  val loop_handle_undo:
    ('a -> 'answer) ->
    ('a checkpoint -> 'a checkpoint -> 'answer) ->
    supplier -> 'a checkpoint -> 'answer
```

--------------------------------

### Access production sides

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Retrieves the left-hand side and right-hand side of a production.

```ocaml
  val lhs: production -> xsymbol
  val rhs: production -> xsymbol list
```

--------------------------------

### Compare inspection types

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Provides total ordering functions for various inspection API types.

```ocaml
  val compare_terminals: _ terminal -> _ terminal -> int
  val compare_nonterminals: _ nonterminal -> _ nonterminal -> int
  val compare_symbols: xsymbol -> xsymbol -> int
  val compare_productions: production -> production -> int
  val compare_items: item -> item -> int
```

--------------------------------

### Grammar Specification Syntax

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Overview of the structure and syntax rules for Menhir grammar files.

```APIDOC
## Grammar Specification Syntax

### Description
Grammar specifications consist of a sequence of declarations followed by a mandatory %% keyword and a sequence of rules.

### Structure
- **Declarations**: Defined before the %% keyword (e.g., %token, %left, %right, %type, %start).
- **Rules**: Define nonterminal symbols using either 'old syntax' or 'new syntax'.
- **Lexical Conventions**:
  - Identifiers: Same as OCaml, excluding the quote (') character.
  - Quoted identifiers: Used as token aliases.
  - Comments: C-style (/* */), C++-style (//), or OCaml-style ((* *)).
  - OCaml types: Enclosed in < and >.
```

--------------------------------

### Construct DCST Nodes

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Constructor functions for creating DCST nodes, including production-specific constructors and choice nodes for disjunctions.

```OCaml
  val paren: expr -> expr
```

```OCaml
  val expr_choice: expr -> expr -> expr
```

--------------------------------

### Nonterminal symbol visitor method

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Generated visitor method for a nonterminal symbol that performs case analysis on the root node.

```OCaml
  method visit_expr : expr -> 'r
```

--------------------------------

### Incremental API

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

The incremental API, enabled by the `--table` flag, allows for more control over the parsing process. The parser yields its state, allowing the user to provide tokens and resume parsing, enabling features like live parsing.

```APIDOC
## Incremental API

### Description
This API allows for fine-grained control over the parsing process, where the parser yields control to the user at intermediate states.

### Starting the Parser: Incremental.main
Initializes the incremental parser.

#### Parameters
- **position** (position) - The initial position in the input stream (e.g., `lexbuf.lex_curr_p`).

#### Return Value
- **MenhirInterpreter.checkpoint** - A checkpoint representing the initial state of the parser.

#### Example Signature
```
module Incremental : sig
  val main: position -> thing MenhirInterpreter.checkpoint
end
```

### Usage Notes
- The `Incremental.main` function itself does not perform parsing; it sets up the initial state.
- The `offer` and `resume` functions (not detailed here) are used to drive the parser by providing tokens and resuming execution.
- This API is suitable for applications requiring "live parsing" or dynamic updates to parsed content.
```

--------------------------------

### Retrieve stack element by index

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Accesses the i-th element of the stack, where 0 is the top.

```OCaml
  val get: int -> 'a env -> element option
```

--------------------------------

### DCST Construction API

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Functions for constructing Disjunctive Concrete Syntax Trees (DCST) to support the unparsing process.

```APIDOC
## DCST Construction

### Description
Provides constructor functions within the DCST sub-module to build well-formed DCSTs based on grammar productions.

### Parameters
- **production_constructor** (function) - Required - A function generated for each production, taking parameters matching the right-hand side of the production.
- **expr_choice** (expr -> expr -> expr) - Required - Constructs a disjunction node for a nonterminal symbol, representing a choice between two subtree descriptions.
```

--------------------------------

### Terminal symbol visitor methods

Source: https://gallium.inria.fr/~fpottier/menhir/manual.html

Visitor methods for terminal symbols, which may be virtual or have default implementations based on token aliases.

```OCaml
  method virtual visit_INT : int -> 'r
```

```OCaml
  method visit_LPAREN : 'r
```
Tokens:
Raw