cairn 1.0 · OCaml Package

This module main use is to create a parser that can log its execution and is able to signal several errors (with the right option) from a parser generated with menhir.

The functor Make produces this parser provided it is given the modules generated by menhir, along the one obtained from reading the .cmly file generated by menhir.

A typical instantiation of this module should look like :

module ParserSign :
  StepParsing.Parsing.parser_decorated with type value_parsed = Program.program =
struct
  type value_parsed = Program.program

  let error_strategy = StepParsing.Parsing.PopFirst

  module Lexer = Lexer
  module Parser = Parser
  module ParserMessages = ParserMessages
end

module Grammar = MenhirSdk.Cmly_read.Read (struct let filename = "Parser.cmly" end)

module P = StepParsing.Parsing.Make (ParserSign) (Grammar)

assuming Lexer, Parser and ParserMessages are the modules produced by menhir (with the right options), and that "Parser.cmly" is the name (with path) to the cmly file produced by menhir. Namely, type value_parsed should be rendered visible for the result of the parser to be usable.

For the cmly file, it might not straightforward to use its direct name (especially if the executable is destined to be installed or executed from somewhere else than its own directory).

In that case, it might be worth to bundle it in the executable with, for example, ocaml-crunch (see examples provided to see how). It is then needed to use the Lift functor of MenhirSdk.Cmly_read rather than the Read one as follows:

module Grammar = MenhirSdk.Cmly_read.Lift (struct
  let file_content = Option.get (<Module_generated_by_ocaml_crunch>.read "<name_of_cmly_file>")
  let prefix = "CMLY" ^ MenhirSdk.Version.version
  let grammar = Marshal.from_string file_content (String.length prefix)
end)

This is adapted from the Read functor of MenhirSdk.Cmly_read.

author Vincent Penelle <vincent.penelle@u-bordeaux.fr>.

type error_strategy =

| Stop
(*
The parser will stop after the first error encountered.
*)
| PopFirst
(*
After an error, the parser will pop the stack until either the top element is a terminal or non-terminal with backup attribute set (in the grammar) or the stack is empty, and then ignore tokens until the first that can be shifted.
*)

type for error-recovery strategy

module type parser_decorated = sig ... end

Signature to provide to the Make functor. The module Parser and Lexer should be those generated by menhir, with options --table --inspection --cmly.

module type parser_messages = sig ... end

Signature matching the module generated by menhir with option --compile-errors. Used for error displaying. Will work if provided with a dummy message function instead (but less informative).

module type parser_logger = sig ... end

Signature of the modules produced by this library. Common to Make and MakeWithDefaultMessage. Contains functions to get a log of the execution of the parser, as long with a graphical explorer of this log.

module Make
  (Parser : parser_decorated)
  (ParserMessages : parser_messages)
  (Grammar : MenhirSdk.Cmly_api.GRAMMAR) : 
  parser_logger with module Parser = Parser

Main functor of this module. It generates a module that can parse a text with the parser provided as an argument, and generates a log of the partial derivations produced along the run of the parser, a log of errors encountered (several errors supported if generated with PopFirst strategy), and can display a tui explorer of the sequence of partial derivations produced by the parser.

module MakeWithDefaultMessage
  (Parser : parser_decorated)
  (Grammar : MenhirSdk.Cmly_api.GRAMMAR) : 
  parser_logger with module Parser = Parser

Same as Make, but provides defaults error messages of the form "Error on state x" where x is the state where the parser encountered the message. Useful if you do not want to generate messages with menhir (yet).

package cairn