\documentclass[twoside]{report}
\marginparwidth 0pt \oddsidemargin 0pt \evensidemargin 0pt \marginparsep 0pt
\topmargin 0pt \textwidth 6.5in \textheight 8.5 in
\usepackage{longtable}
\usepackage{fancyhdr}
\fancyhead{}
\fancyhead[LE,RO]{\leftmark}

\newcommand{\clearemptydoublepage}{%
\newpage{\pagestyle{empty}\cleardoublepage}}

\begin{document}

\def\cslversion{6.13}

\pagestyle{empty}
\begin{center}
~\vfill
\Huge           Camlp5 - Reference Manual \\
\Large          version \cslversion \\[1cm]
\large          Daniel de Rauglaudre \\
                \today \\[1cm]
\vfill
\normalsize	Copyright \copyright\ 2007-2014 Institut National de
                Recherche en Informatique et Automatique

This document was generated by a shell script from the html documentation
pages.
\end{center}
\clearemptydoublepage
\setcounter{page}{1}
\pagestyle{plain}
\tableofcontents
\clearemptydoublepage

\pagestyle{fancy}\chapter{Introduction}

\noindent Camlp5 is a preprocessor and pretty-printer for OCaml programs. It
  also provides parsing and printing tools.

\

\noindent As a preprocessor, it allows to:

\begin{itemize}
\item extend the syntax of OCaml,
\item redefine the whole syntax of the language.
\end{itemize}

\noindent As a pretty printer, it allows to:

\begin{itemize}
\item display OCaml programs in an elegant way,
\item convert from one syntax to another,
\item check the results of syntax extensions.
\end{itemize}

\noindent Camlp5 also provides some parsing and pretty printing tools:

\begin{itemize}
\item extensible grammars
\item extensible printers
\item stream parsers and lexers
\item pretty print module
\end{itemize}

\noindent It works as a shell command and can also be used in the OCaml
  toplevel.


\section{Shell usage}

\noindent The main shell commands are:

\begin{itemize}
\item \texttt{camlp5o} : to treat files written in normal OCaml
  syntax,
\item \texttt{camlp5r} : to treat files written in an original syntax
    named the \emph{revised syntax}.
\end{itemize}

\noindent These commands can be given as parameters of the
option \texttt{-pp} of the OCaml compiler. Examples:

\begin{verbatim}
  ocamlc -pp camlp5o foo.ml
  ocamlc -pp camlp5r bar.ml
\end{verbatim}

\noindent This way, the parsing is done by Camlp5. In case of syntax errors,
the parsing fails with an error message and the compilation is
aborted. Otherwise, the OCaml compiler continues with the syntax tree
provided by Camlp5.

\

\noindent In the toplevel, it is possible to preprocess the input phrases by
loading one of the files "\texttt{camlp5o.cma}" or
"\texttt{camlp5r.cma}".  The common usage is:

\begin{verbatim}
  ocaml -I +camlp5 camlp5o.cma
  ocaml -I +camlp5 camlp5r.cma
\end{verbatim}

\noindent It is possible that, in your installation, the Camlp5 library is
  not in the OCaml directory. In this case, the commands must be:

\begin{verbatim}
  ocaml -I `camlp5 -where` camlp5o.cma
  ocaml -I `camlp5 -where` camlp5r.cma
\end{verbatim}

\noindent In general, in this documentation, when a command requires:

\begin{verbatim}
  -I +camlp5
\end{verbatim}

\noindent it can be replaced by:

\begin{verbatim}
  -I `camlp5 -where`
\end{verbatim}

\noindent or, by:

\begin{verbatim}
  -I <directory>
\end{verbatim}

\noindent where "directory" is the directory path where the Camlp5 library
  files are installed.

\section{Parsing and Printing kits}

\noindent Parsing and printing extensions are OCaml object files, i.e. files
  with the extension "\texttt{.cmo}" or "\texttt{.cma}". They are the
  result of the compilation of OCaml source files containing what is
  necessary to do the parsing or printing. These object files are
  named parsing and printing \emph{kits}.

\

\noindent These files cannot be linked to produce executables because they
  generally call functions and use variables defined only in Camlp5
  core, typically belonging to the module "\texttt{Pcaml}". The kits
  are designed to be loaded by the Camlp5 commands, either through
  their command arguments or through directives in the source
  files.

\

\noindent It is therefore important to compile the \emph{kits} with the
  option "\texttt{-c}" of the OCaml compiler (i.e. just compilation,
  not producing an executable) and with the option "\texttt{-I
  +camlp5}" (or "\texttt{-I `camlp5 -where`}") to inform the
  compiler to find module interfaces in installed Camlp5 library.

\

\noindent In the OCaml toplevel, it is possible to use a kit by simply
  loading it with the directive "\texttt{\#load}".

\section{Extending syntax}

\noindent A syntax extension is a Camlp5 parsing kit. There are two ways to
  use a syntax extension:

\begin{itemize}
\item Either by giving this object file as parameter to the Camlp5
    command. For example:

\begin{verbatim}
  ocamlc -pp "camlp5o ./myext.cmo" foo.ml
\end{verbatim}


\item Or by adding the directive "\texttt{\#load}" in the source file:

\begin{verbatim}
  #load "./myext.cmo";;
\end{verbatim}

and then compile it simply like this:

\begin{verbatim}
  ocamlc -pp camlp5o foo.ml
\end{verbatim}


\end{itemize}

\noindent Several syntax extensions can be used for a single file. The way to
  create one's own syntax extensions is explained in this document.

\section{Pretty printing}

\noindent As for syntax extensions, the pretty printing is defined or
  extended through Camlp5 printing kits. Some pretty printing kits are
  provided by Camlp5, the main ones being:

\begin{itemize}
\item \texttt{pr\_o.cmo}: to pretty print in normal syntax,
\item \texttt{pr\_r.cmo}: to pretty print in revised syntax.
\end{itemize}

\noindent Examples: if we have a file, \texttt{foo.ml}, written in normal
  syntax and and another one, \texttt{bar.ml}, written in revised
  syntax, here are the commands to pretty print them in their own
  syntax:

\begin{verbatim}
  camlp5o pr_o.cmo foo.ml
  camlp5r pr_r.cmo bar.ml
\end{verbatim}

\noindent And how to convert them into the other syntax:

\begin{verbatim}
  camlp5o pr_r.cmo foo.ml
  camlp5r pr_o.cmo foo.ml
\end{verbatim}

\noindent The way to create one's own pretty printing extensions is
  explained in this document.

\section{Note: the revised syntax}

\noindent The \emph{revised syntax} is a specific syntax whose aim is to
  resolve some problems and inconsistencies of the normal OCaml
  syntax. A chapter will explain the differences between the normal
  and the revised syntax.

\

\noindent All examples of this documentation are written in that revised
  syntax. Even if you don't know it, it is not difficult to
  understand. The same examples can be written in normal syntax. In
  case of problems, refer to the chapter describing it.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Transitional and Strict modes}

\noindent Since version 5.00, Camlp5 has been able to be installed in two
  modes: the \emph{transitional} mode and the \emph{strict}
  mode. When Camlp5 is installed, it works with one only of these
  modes (the two modes contain indeed different definitions of some
  interfaces and are incompatible with one another). The user must
  choose in which mode he wants to use Camlp5.

\

\noindent This notion has been introduced to ensure backward compatibility of
  the Camlp5 syntax tree, together with the usage of a new quotation
  kit "\texttt{q\_ast.cmo}", which allows to use Camlp5 syntax tree
  quotations in user syntax (with all its possible extensions).

\begin{description}
\item[A short example of these syntax tree quotations:]

\


\noindent If the syntax of the extensible
        grammars has been added, it is possible to write things
      like:

\begin{verbatim}
  <:expr< EXTEND a: [ [ c = d -> $e$ ] ]; END >>;
\end{verbatim}
\noindent representing the syntax tree of this statement: this is not
      possible with the classical quotation kit "\texttt{q\_MLast.cmo}"
      because all quotations must be there only
      in revised syntax and without syntax
      extensions.


\end{description}

\noindent Here are the differences between the two modes:

\begin{description}
\item[Transitional]

\


\begin{description}
\item[Compatibility]

\

The syntax tree is fully compatible with the previous
        versions of Camlp5, no changes has to be done in the users'
        programs.
\item[Quotation kit "\texttt{q\_ast.cmo}"]

\

The antiquotations are not available: when used, a syntax
        error message is displayed.
    \end{description}
  
\item[Strict]

\


\begin{description}
\item[Compatibility]

\

The syntax tree is different, users' programs may have to be
        modified, but not necessarily.
\item[Quotation kit "\texttt{q\_ast.cmo}"]

\

All antiquotations are available.
    \end{description}
  
\end{description}

\noindent In strict mode, the programs have more chances to be compatible
  with the previous versions if they use syntax tree quotations rather
  than syntax tree nodes. A solution is therefore to change the
  expressions and patterns using nodes into expressions and patterns
  using quotations (which is backward compatible).

\section{Which mode is installed ?}

\noindent To determine the mode of an installed version of Camlp5, type:

\begin{verbatim}
  camlp5 -pmode
\end{verbatim}

\section{Selecting mode when compiling Camlp5}

\noindent When compiling Camlp5 from source, the mode must first be selected
  at configuration time. The \emph{configure} script must be run
  with one of these options:

\begin{verbatim}
  ./configure -strict
  ./configure -transitional
\end{verbatim}

\noindent The default is "transitional", i.e. without option, the sources are
  compiled in transitional mode.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Parsing and Printing tools}

\noindent Camlp5 provides two parsing tools:

\begin{itemize}
\item stream parsers
\item extensible grammars
\end{itemize}

\noindent The first parsing tool, the stream parsers, is the elementary
  system. It is pure syntactic sugar, i.e. the code is directly
  converted into basic OCaml statements: essentially functions,
  pattern matchings, try. A stream parser is just a function. But the
  system does not manage associativity, nor parsing level. Left
  recursion results on infinite loops, just like functions whose first
  action would be a call to itself.

\

\noindent The second parsing tool, the extensible grammars, are more
  sophisticated. A grammar written with them is more readable, and
  look like grammars written with tools like "yacc". They take care of
  associativity, left recursion, and level of parsing. They are
  dynamically extensible, what allows the syntax extensions what
  Camlp5 provides for OCaml syntax.

\

\noindent In both cases, the input data are streams.

\

\noindent Camlp5 also provides:

\begin{itemize}
\item a pretty printing module
\item extensible printers
\end{itemize}

\noindent The next sections give an overview of the parsing and printing
  tools.


\section{Stream parsers}

\noindent The stream parsers is a system of recursive descendant
  parsing. Streams are actually lazy lists. At each step, the head of
  the list is compared against a \emph{stream pattern}. There are
  three kinds of streams parsers:

\begin{itemize}
\item The imperative streams parsers, where
    the elements are removed from the stream as long as they are
    parsed.  Parsers return either:
\begin{itemize}
\item A value, in case of success,
\item The exception "\texttt{Stream.Failure}" when the parser does
        not apply and no elements have been removed from the stream,
        indicating that, possibly, other parsers may apply,
\item The exception "\texttt{Stream.Error}" when the parser does
        not apply, but one or several elements have been removed from
        the stream, indicating that nothing can to be done to make up
        the error.
\end{itemize}

\item The functional stream parsers
    where the elements are not removed from the stream during the
    parsing. These parsers return a value of type "option", i.e
    either:
\begin{itemize}
\item "Some" a value and the remaining stream, in case of
        success,
\item "None", in case of failure.
\end{itemize}

\item The backtracking stream parsers
    which are like the functional stream parsers but with a backtracking
    algorithm, testing all possibilities. These parsers also return a
    value of type "option" different from the functional stream parsers,
    i.e either:
\begin{itemize}
\item "Some" a value, the remaining stream and a continuation, in
        case of success,
\item "None", in case of failure.
\end{itemize}

\end{itemize}

\noindent The differences are about:

\begin{itemize}
\item Syntax errors: in the imperative version,
    the location of the error is clear, it is at the current position
    of the stream, and the system provides a specific error message
    (typically, that some "element" was "expected"). On the other
    hand, in the functional and backtracking version, the position is
    not clear since it returns nothing and the initial stream is
    unaffected. The only solution to know where the error happened is
    to analyze that stream to see how many elements have be
    unfrozen. No clear error message is available, just "syntax error"
    (but this could be improved in a future version).
\item Power: in the imperative version, when a
    rule raises the exception "\texttt{Stream.Error}", the parsing
    cannot continue.  In the functional version, the parsing can
    continue by analyzing the next rule with the initial unaffected
    stream: this is \emph{limited backtrack}. In the backtracking
    version, more powerful, the parsing continues by analyzing the
    next case of the previous symbol of the rule; moreover it is
    possible to get the list of all possible solutions.
\item Neatness: functional streams are neater,
    just like functional programming is neater than imperative
    programming.
\end{itemize}

\noindent The imperative parsers implement what is called "predictive
  parsing", i.e. recursive descendant parsing without backtrack.

\

\noindent In the imperative version, there also exist
  lexers, a shorter syntax when the stream
  elements are of the specific type '\texttt{char}'.

\section{Extensible grammars}

\noindent Extensible grammars manipulate \emph{grammar entries}. Grammar
  entries are abstract values internally containing mutable stream
  parsers. When a grammar entry is created, its internal parser is
  empty, i.e. it always fails when used. A specific syntactic
  construction, with the keyword "\texttt{EXTEND}" allows one to
  extend grammar entries with new grammar rules.

\

\noindent In opposition to stream parsers, grammar entries manage
  associativity, left factorization, and levels. Moreover, these
  grammars allow optional calls, lists and lists with separators. They
  are not however functions and hence cannot have parameters.

\

\noindent Since the internal system is stream parsers, extensible grammars
  use recursive descendant parsing.

\

\noindent The parsers of the OCaml language in Camlp5 are written with
  extensible grammars.

\section{Pretty module}

\noindent The "\texttt{Pretty}" module is an original tool allowing control
  over the displaying of lines. The user must specify two functions
  where:

\begin{itemize}
\item the data is printed on a single line
\item the data is printed on several lines
\end{itemize}

\noindent The system first tries to print on a single line. At any time, if
  the line overflows, i.e. if its size is greater than some "line
  length" specified in the module interface, or if it contains
  newlines, the function is aborted and control is given to the second
  function, to print on several lines.

\

\noindent This is a basic, but powerful, system. It supposes that the programmer
  takes care of the current indentation, and the beginning and the end of
  its lines.

\

\noindent The module will be extended in the future to hide the management of
  indendations and line continuations, and by the supply of functions
  combinating the two cases above, in which the programmer can specify
  the possible places where newlines can be inserted.

\section{Extensible printers}

\noindent The extensible printers are symmetric to the extensible grammars.
  The extensible grammars take syntax rules and return syntax trees.
  The extensible printers are actually extensible functions taking
  syntax trees as parameters and returning the pretty printed
  statements in strings.

\

\noindent The extensible printers can have printing levels, just like
  grammars have parsing levels, and it is possible to take the
  associativity into account by provided functions to call either the
  current level or the next level.

\

\noindent The printers of the OCaml language are written with extensible
  printers.

\clearemptydoublepage
\part{Parsing tools}
\clearemptydoublepage

\pagestyle{fancy}\chapter{Stream parsers}

\noindent We describe here the syntax and the semantics of the parsers of
  streams of Camlp5. Streams are kinds of lazy lists. The parsers of
  these streams use recursive descendent method without backtracking,
  which is the most natural one in functional languages. In
  particular, parsers are normal functions.

\

\noindent Notice that the parsers have existed in OCaml since many years (the
  beginning of the 90ies), but some new features have been added in
  2007 (lookahead, "no error" optimization, let..in statement and left
  factorization) in Camlp5 distribution. This chapter describes them
  also.


\section{Introduction}

\noindent Parsers apply to values of type "Stream.t" defined in the module
  "Stream" of the standard library of OCaml. Like the type "list", the
  type "Stream.t" has a type parameter, indicating the type of its
  elements. They differ from the lists that they are lazy (the
  elements are evaluated as long as the parser need them for its
  actions), and imperative (parsers deletes their first elements when
  they take their parsing decisions): notice that purely functional
  parsers exist in Camlp5, where the corresponding streams are lazy
  and functional, the analyzed elements remaining in the initial
  stream and the semantic action returning the resulting stream
  together with the normal result, which allow natural limited
  backtrack but have the drawback that it is not easy to find the
  position of parsing errors when they happen.

\

\noindent Parsers of lazy+imperative streams, which are described here, use a
  method named "recursive descendent": they look at the first element,
  they decide what to do in function of its value, and continue the
  parsing with the remaining elements. Parsers can call other parsers,
  and can be recursive, like normal functions.

\

\noindent Actually, parsers are just pure syntactic sugar. When writing a
  parser in the syntax of the parser, Camlp5 transforms them into
  normal call to functions, use of patterns matchings and try..with
  statements.  The pretty printer of Camlp5, by default, displays this
  expanded result, without syntax of parsers. A pretty printing kit,
  when added, can rebuild the parsers in their initial syntax and
  display it.

\section{Syntax}

\noindent The syntax of the parsers, when loading "pa\_rp.cmo" (or already
  included in the command "camlp5r"), is the following:

\begin{verbatim}
            expression ::= parser
                         | match-with-parser
                parser ::= "parser" pos-opt "[" parser-cases "]"
                         | "parser" pos-opt parser-case
     match-with-parser ::= "match" expression "with" parser
          parser-cases ::= parser-cases parser-case
                         | <nothing>
           parser-case ::= "[:" stream-pattern ":]" pos-opt "->" expression
        stream-pattern ::= stream-patt-comp
                         | stream-patt-comp ";" stream-patt-cont
                         | "let" LIDENT "=" expression "in" stream-pattern
                         | <nothing>
      stream-patt-cont ::= stream-patt-comp-err
                         | stream-patt-comp-err ";" stream-patt-cont
                         | "let" LIDENT "=" expression "in" stream-patt-cont
  stream-patt-comp-err ::= stream-patt-comp
                         | stream-patt-comp "?" expression
                         | stream-patt-comp "!"
      stream-patt-comp ::= "`" pattern
                         | "`" pattern "when" expression
                         | "?=" lookaheads
                         | pattern "=" expression
                         | pattern
            lookaheads ::= lookaheads "|" lookahead
                         | lookahead
             lookahead ::= "[" patterns "]"
              patterns ::= patterns pattern
                         | pattern
               pos-opt ::= pattern
                         | <nothing>
\end{verbatim}

\section{Streams}

\noindent The parsers are functions taking streams as parameter. Streams are
  are values of type "\texttt{Stream.t a}" for some type
  "\texttt{a}". It is possible to build streams using the
  functions defined in the module "\texttt{Stream}":

\subsection{Stream.from}

\noindent "\texttt{Stream.from f}" returns a stream built from the
  function "\texttt{f}". To create a new stream element, the
  function "\texttt{f}" is called with the current stream count,
  starting with zero. The user function "\texttt{f}" must return
  either "\texttt{Some <value>}" for a value or
  "\texttt{None}" to specify the end of the stream.

\subsection{Stream.of\_list}

\noindent Return a stream built from the list in the same order.

\subsection{Stream.of\_string}

\noindent Return a stream of the characters of the string parameter.

\subsection{Stream.of\_channel}

\noindent Return a stream of the characters read from the input channel
  parameter.

\section{Semantics of parsers}

\subsection{Parser}

\noindent A parser, defined with the syntax "parser" above, is of type
  "\texttt{Stream.t a -> b}" where "a" is the type of the elements
  of the streams and "b" the type of the result. The parser cases are
  tested in the order they are defined until one of them applies. The
  result is the semantic action of the parser case which applies. If
  no parser case applies, the exception "\texttt{Stream.Failure}"
  is raised.

\

\noindent When testing a parser case, if the first stream pattern component
  matches, all remaining stream pattern components of the stream
  pattern must match also. If one does not match, the parser raises
  the exception "\texttt{Stream.Error}" which has a parameter of
  type string: by default, this string is the empty string, but if the
  stream pattern component which does not match is followed by a
  question mark and an expression, this expression is evaluated and
  given as parameter to "\texttt{Stream.Error}".

\

\noindent In short, a parser can return with three ways:

\begin{itemize}
\item A normal result, of type "\texttt{b}" for a parser of type
    "\texttt{Stream.t a -> b}".
\item Raising the exception "\texttt{Stream.Failure}".
\item Raising the exception "\texttt{Stream.Error}".
\end{itemize}

\noindent Fundamentally, the exception "\texttt{Stream.Failure}" means
  "this parser does not apply and no element have been removed from
  the initial stream". This is a normal case when parsing: the parser
  locally fails, but the parsing can continue.

\

\noindent Conversely, the exception "\texttt{Stream.Error}" means that
  "this parser encountered a syntax error and elements have probably
  been removed from the stream". In this case, there is no way to
  recover the parsing, and it definitively fails.

\subsection{Left factorization}

\noindent In parsers, \emph{consecutive} rules starting with the same
  components are left factorized. It means that they are transformed
  into one only rule starting with the common path, and continuing
  with a call to a parser separating the two cases. The order is
  kept, except that the possible empty rule is inserted at the
  end.

\

\noindent For example, the parser:

\begin{verbatim}
  parser
  [ [: `If; e1 = expr; `Then; e2 = expr; `Else; e3 = expr :] -> f e1 e2 e3
  | [: `If; e1 = expr; `Then; e2 = expr :] -> g e1 e2 ]
\end{verbatim}

\noindent is transformed into:

\begin{verbatim}
  parser
    [: `If; e1 = expr; `Then; e2 = expr;
       a =
         parser
         [ [: `Else; e3 = expr :] -> f e1 e2 e3
         | [: :] -> g e1 e2 ] :] -> a
\end{verbatim}

\noindent The version where rules are inverted:

\begin{verbatim}
  parser
  [ [: `If; e1 = expr; `Then; e2 = expr :] -> g e1 e2
  | [: `If; e1 = expr; `Then; e2 = expr; `Else; e3 = expr :] -> f e1 e2 e3 ]
\end{verbatim}

\noindent is transformed into the same parser.

\

\noindent Notice that:

\begin{itemize}
\item Only \emph{consecutive} rules are left factorized. In the
    following parser:
\begin{verbatim}
  parser
  [ [: `If; e1 = expr; `Then; e2 = expr; `Else; e3 = expr :] -> ...
  | [: a = b :] -> a
  | [: `If; e1 = expr; `Then; e2 = expr :] -> ... ]
\end{verbatim}
    the two rules starting with "\texttt{If}" are not left factorized,
    and the second "\texttt{If}" rule will never work.

\item The components which are not \emph{identical} are not
    factorized. In the following parser:
\begin{verbatim}
  parser
  [ [: `If; e1 = expr; `Then; e2 = expr; `Else; e3 = expr :] -> ...
  | [: `If; e4 = expr; `Then; e2 = expr :] -> ... ]
\end{verbatim}
    only the first component, "\texttt{If}" is factorized, the second
    one being different because of different patterns ("\texttt{e1}" and
      "\texttt{e4}").

\end{itemize}

\subsection{Match with parser}

\noindent The syntax "match expression with parser" allows to match a stream
  against a parser. It is, for "parser", the equivalent of "match
  expression with" for "fun". The same way we could say:

\begin{verbatim}
  match expression with ...
\end{verbatim}

\noindent could be considered as an equivalent to:

\begin{verbatim}
  (fun ...) expression
\end{verbatim}

\noindent we could consider that:

\begin{verbatim}
  match expression with parser ...
\end{verbatim}

\noindent is an equivalent to:

\begin{verbatim}
  (parser ...) expression
\end{verbatim}

\subsection{Error messages}

\noindent A "\texttt{Stream.Error}" exception is raised when a stream
  pattern component does not match and that it is not the first one of
  the parser case. This exception has a parameter of type string,
  useful to specify the error message. By default, this is the empty
  string. To specify an error message, add a question mark and an
  expression after the stream pattern component. A typical error
  message is "that stream pattern component expected". Example with
  the parser of "if..then..else.." above:

\begin{verbatim}
  parser
    [: `If; e1 = expr ? "expression expected after 'if'";
       `Then ? "'then' expected";
       e2 = expr ? "expression expected after 'then'";
       a =
         parser
         [ [: `Else; e3 = expr ? "expression expected" :] -> f e1 e2 e3
         | [: :] -> g e1 e2 ] :] -> a
\end{verbatim}

\noindent Notice that the expression after the question mark is evaluated
  only in case of syntax error. Therefore, it can be a complicated
  call to a complicated function without slowing down the normal
  parsing.

\subsection{Stream pattern component}

\noindent In a stream pattern (starting with "\texttt{[:}" and ending
  with "\texttt{:]}"), the stream pattern components are separated
  with the semicolon character. There are three cases of stream
  pattern components with some sub-cases for some of them, and an
  extra syntax can be used with a "let..in" construction. The three
  cases are:

\begin{itemize}
\item A direct test of one or several stream elements
    (called \textbf{terminal} symbol), in three ways:
\begin{enumerate}
\item The character "backquote" followed by a pattern, meaning: if
        the stream starts with an element which is matched by this
        pattern, the stream pattern component matches, and the stream
        element is removed from the stream.
\item The character "backquote" followed by a pattern, the keyword
        "when" and an expression of type "\texttt{bool}", meaning:
        if the stream starts with an element which is matched by this
        pattern and if the evaluation of the expression is
        "\texttt{True}", the stream pattern component matches, and
        the first element of the stream is removed.
\item The character "question mark" followed by the character
        "equal" and a lookahead expression (see further), meaning: if
        the lookahead applies, the stream pattern component
        matches. The lookahead may unfreeze one or several elements on
        the stream, but does not remove them.
\end{enumerate}

\item A pattern followed by the "equal" sign and an expression of type
    "\texttt{Stream.t x -> y}" for some types "\texttt{x}" and
    "\texttt{y}". This expression is called a \textbf{non terminal}
    symbol. It means: call the expression (which is a parser) with the
    current stream. If this sub-parser:

\begin{enumerate}
\item Returns an element, the pattern is bound to this result and
        the next stream pattern component is tested.
\item Raises the exception "\texttt{Stream.Failure}", there
        are two cases:

\begin{itemize}
\item if the stream pattern component is the first one of the
            stream case, the current parser also fails with the
            exception "\texttt{Stream.Failure}".
\item if the stream pattern component is not the first one of
            the stream case, the current parser fails with the
            exception "\texttt{Stream.Error}".
\end{itemize}

        In this second case:

\begin{itemize}
\item If the stream pattern component is followed by a
            "question mark" and an expression (which must be of type
            "\texttt{string}"), the expression is evaluated and
            given as parameter of the exception
            "\texttt{Stream.Error}".
\item If the expression is followed by an "exclamation mark",
            the test and conversion from "\texttt{Stream.Failure}"
            to "\texttt{Stream.Error}" is not done, and the parser
            just raises "\texttt{Stream.Failure}" again. This is
            an optimization which must be assumed by the programmer,
            in general when he knows that the sub-parser called never
            raises "\texttt{Stream.Failure}" (for example if the
            called parser ends with a parser case containing an empty
            stream pattern). See "no error optionization" below.
\item Otherwise the exception parameter is the empty string.
\end{itemize}

\end{enumerate}

\item A pattern, which is bound to the current stream.
\end{itemize}

\noindent Notice that patterns are bound immediately and can be used in the
  next stream pattern component.

\subsection{Let statement}

\noindent Between stream pattern components, it is possible to use the
  "let..in" construction. This is not considered as a real stream
  pattern component, in the fact that is is not tested against the
  exception "\texttt{Stream.Failure}" it may raise. It can be
  useful for intermediate computation. In particular, it is used
  internally by the lexers (see chapter
  about lexers as character stream
  parsers).

\

\noindent Example of use, when an expression have to be used several times
  (in the example, "\texttt{d a}", which is bound to the variable
  "\texttt{c}"):

\begin{verbatim}
  parser
    [: a = b;
       let c = d a in
       e =
         parser
         [ [: f = g :] -> h c
         | [: :] -> c ] :] -> e
\end{verbatim}

\subsection{Lookahead}

\noindent The lookahead feature allows to look at several terminals in the
  stream without removing them, in order to take decisions when more
  than one terminal is necessary.

\

\noindent For example, when parsing the normal syntax of the OCaml language,
  there is a problem, in recursing descendent parsing, for the cases
  where to treat and differentiate the following inputs:

\begin{verbatim}
  (-x+1)
  (-)
\end{verbatim}

\noindent The first case is treated in a rule, telling: "a left parenthesis,
  followed by an expression, and a right parenthesis". The second one
  is "a left parenthesis, an operator, a right
  parenthesis". Programming it like this (left factorizing the first
  parenthesis):

\begin{verbatim}
  parser
    [: `Lparen;
       e =
         parser
         [ [: e = expr; `Rparen :] -> e
         | [: `Minus; `Rparen :] -> minus_op ] :] -> e
\end{verbatim}

\noindent does not work if the input is "\texttt{(-)}" because the rule
  "\texttt{e = expr}" accepts the minus sign as expression start,
  removing it from the input stream and fails as parsing error, while
  encountering the right parenthesis.

\

\noindent Conversely, writing it this way:

\begin{verbatim}
  parser
    [: `Lparen;
       e =
         parser
         [ [: `Minus; `Rparen :] -> minus_op
         | [: e = expr; `Rparen :] -> e ] :] -> e
\end{verbatim}

\noindent does not help, because if the input is "\texttt{(-x+1)}" the
  rule above starting with "\texttt{`Minus}" is accepted and the
  exception "\texttt{Stream.Error}" is raised while encountering
  the variable "\texttt{x}" since a right parenthesis is
  expected.

\

\noindent In general, this kind of situation is best resolved by a left
  factorization of the parser cases (see the section "Semantics"
  above), but that is not possible in this case. The solution is to
  test whether the character after the minus sign is a right
  parenthesis:

\begin{verbatim}
  parser
    [: `Lparen;
       e =
         parser
         [ [: ?= [ _ Rparen ]; `Minus; `Rparen :] -> minus_op
         | [: e = expr; `Rparen :] -> e ] :] -> e
\end{verbatim}

\noindent It is possible to put several lists of patterns separated by a
  vertical bar in the lookahead construction, but with a limitation
  (due to the implementation): all lists of patterns must have the
  same number of elements.

\subsection{No error optimization}

\noindent The "no error optimization" is the fact to end a stream pattern
  component of kind "non-terminal" ("pattern" "equal" "expression") by
  the character "exclamation mark". Like said above, this inhibits the
  transformation of the exception "\texttt{Stream.Failure}",
  possibly raised by the called parser, into the exception
  "\texttt{Stream.Error}".

\

\noindent The code:

\begin{verbatim}
  parser [: a = b; c = d ! :] -> e
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  parser [: a = b; s :] -> let c = d s in e
\end{verbatim}

\noindent One interest of the first syntax is that it shows to readers that
  "\texttt{d}" is indeed a syntactic sub-parser. In the second
  syntax, it is called in the semantic action, which makes the parser
  case not so clear, as far as readability is concerned.

\

\noindent If the stream pattern component is at end of the stream pattern,
  this allow possible tail recursion by the OCaml compiler, in the
  following case:

\begin{verbatim}
  parser [: a = b; c = d ! :] -> c
\end{verbatim}

\noindent since it is equivalent (with the fact that "\texttt{c}" is at
  the same time the pattern of the last case and the expression of the
  parser case semantic action) to:

\begin{verbatim}
  parser [: a = b; s :] -> d s
\end{verbatim}

\noindent The call to "\texttt{d s}" can be a tail recursive
  call. Without the use of the "exclamation mark" in the rule, the
  equivalent code is:

\begin{verbatim}
  parser [: a = b; s :] ->
    try d s with [ Stream.Failure -> raise (Stream.Error "") ]
\end{verbatim}

\noindent which is not tail recursive (due to the "try..with" construction
  pushes a context), preventing the compiler to optimize its
  code. This can be important when many recursive calls happen, since
  it can overflow the OCaml stack.

\subsection{Position}

\noindent The optional "pattern" before and after a stream pattern is bound
  to the current stream count. Indeed, streams internally contain a
  count of their elements. At the beginning the count is zero. When an
  element is removed, the count is incremented. The example:

\begin{verbatim}
  parser [: a = b :] ep -> c
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  parser [: a = b; s :] -> let ep = Stream.count s in c
\end{verbatim}

\noindent There is no direct syntax equivalent to the optional pattern at
  beginning of the stream pattern:

\begin{verbatim}
  parser bp [: a = b :] -> c
\end{verbatim}

\noindent These optional patterns allow disposal of the stream count at the
  beginning and at the end of the parser case, allowing to compute
  locations of the rule in the source. In particular, if the stream is
  a stream of characters, these counts are the source location in
  number of characters.

\subsection{Semantic action}

\noindent In a parser case, after the stream pattern, there is an "arrow" and
  an expression, called the "semantic action". If the parser case is
  matched the parser returns with the evaluated expression whose
  environment contains all values bound in the stream pattern.

\section{Remarks}

\subsection{Simplicity vs Associativity}

\noindent This parsing technology has the advantage of simplicity of use and
  understanding, but it does not treat the associativity of
  operators. For example, if you write a parser like this (to compute
  arithmetic expressions):

\begin{verbatim}
  value rec expr =
    parser
    [ [: e1 = expr; `'+'; e2 = expr :] -> e1 + e2
    | [: `('0'..'9' as c) :] -> Char.code c - Char.code '0' ]
\end{verbatim}

\noindent this would loop endlessly, exactly as if you wrote code starting
  with:

\begin{verbatim}
  value rec expr e =
    let e1 = expr e in
    ...
\end{verbatim}

\noindent One solution is to treat the associativity "by hand": by reading a
  sub-expression, then looping with a parser which parses the operator
  and another sub-expression, and so on.

\

\noindent An alternative solution is to write parsing "combinators". Indeed,
  parsers being normal functions, it is possible to make a function
  which takes a parser as parameter and returning a parser using
  it. For example, left and right associativity parsing
  combinators:

\begin{verbatim}
  value rec left_assoc op elem =
    let rec op_elem x =
      parser
      [ [: t = op; y = elem; r = op_elem (t x y) :] -> r
      | [: :] -> x ]
    in
    parser [: x = elem; r = op_elem x :] -> r
  ;

  value rec right_assoc op elem =
    let rec op_elem x =
      parser
      [ [: t = op; y = elem; r = op_elem y :] -> t x r
      | [: :] -> x ]
    in
    parser [: x = elem; r = op_elem x :] -> r
  ;
\end{verbatim}

\noindent which can be used, e.g. like this:

\begin{verbatim}
  value expr =
    List.fold_right (fun op elem -> op elem)
      [left_assoc (parser [: `'+' :] -> fun x y -> x +. y);
       left_assoc (parser [: `'*' :] -> fun x y -> x *. y);
       right_assoc (parser [: `'^' :] -> fun x y -> x ** y)]
      (parser [: `('0'..'9' as c) :] -> float (Char.code c - Char.code '0'))
  ;
\end{verbatim}

\noindent and tested, e.g. in the toplevel, like that:

\begin{verbatim}
  expr (Stream.of_string "2^3^2+1");
\end{verbatim}

\noindent The same way, it is possible to parse non-context free grammars, by
  programming parsers returning other parsers.

\

\noindent A third solution, to resolve the problem of associativity, is to
  use the grammars of Camlp5, which have the other advantage that they
  are extensible.

\subsection{Lexing vs Parsing}

\noindent In general, while analyzing a language, there are two levels:

\begin{itemize}
\item The level where the input, considered as a stream of characters,
    is read to make a stream of tokens (for example "words", if it is
    a human language, or punctuation). This level is generally called
    "lexing".
\item The level where the input is a stream of tokens where grammar
    rules are parsed. This level is generally called "parsing".
\end{itemize}

\noindent The "parser" construction described here can be used for both,
  thanks to the polymorphism of OCaml:

\begin{itemize}
\item The lexing level is a "parser" of streams of characters
    returning tokens.
\item The parsing level is a "parser" of streams of tokens returning
    syntax trees.
\end{itemize}

\noindent By comparison, the programs "lex" and "yacc" use two different
  technologies. With "parser"s, it is possible to use the same one for
  both.

\subsection{Lexer syntax vs Parser syntax}

\noindent For "lexers", i.e. for the specific case of parsers when the input
  is a stream of characters, it is possible to use a shorter
  syntax. See the chapter on lexers. They
  have another syntax, shorter and adapted for the specific type
  "\texttt{char}". But they still are internally parsers of
  streams with the same semantics.

\subsection{Purely functional parsers}

\noindent This system of parsers is imperative: while parsing, the stream
  advances and the already parsed terminals disappear from the stream
  structure. This is useful because it is not necessary to return the
  remaining stream together with the normal result. This is the reason
  there is this "\texttt{Stream.Error}" exception: when it is raised,
  it means that some terminals have been consummed from the stream,
  which are definitively lost, and therefore that are no more possible
  parser cases to try.

\

\noindent An alternative is to use functional
  parsers which use a new stream type, lazy but not
  destructive. Their advantage is that they use a limited backtrack:
  the case of "if..then..else.." and the shorter "if..then.." work
  without having to left factorize the parser cases, and there is no
  need to lookahead. They have no equivalent to the exception
  "\texttt{Stream.Error}": when all cases are tested, and have
  failed, the parsers return the value "\texttt{None}". The
  drawback is that, when a parsing error happens, it is not easily
  possible to know the location of the error in the input, as the
  initial stream has not been modified: the system would indicate a
  failure at the first character of the first line: this is a general
  drawback of backtracking parsers. See the solutions found to this
  problem in the chapter about purely
  functional parsers.

\

\noindent A second alternative is to use the
  backtracking parsers. They use the same
  stream type as the functional parsers, but they test more cases than
  them. They have the same advantages and drawbacks than the functional
  parsers.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Stream lexers}

\noindent The file "\texttt{pa\_lexer.cmo}" is a Camlp5 syntax extension kit
  for parsers of streams of the type 'char'. This syntax is shorter
  and more readable than its equivalent version written
  with classical stream parsers. Like
  classical parsers, they use recursive descendant parsing. They are
  also pure syntax sugar, and each lexer written with this syntax can
  be written using normal parsers syntax.


\noindent (An old version, named "\texttt{pa\_lex.cmo}" was provided before
  with a different syntax. It is no longer distributed, its proposed
  syntax being confusing.)

\section{Introduction}

\noindent Classical parsers in OCaml apply to streams of any type of
  values. For the specific type "char", it has been possible to
  shorten the encoding in several ways, in particular by using strings
  to group several characters together, and by hidding the management
  of a "lexing buffer", a data structure recording the matched
  characters.

\

\noindent Let us take an example. The following function parses a left
  bracket followed by a less, a colon or nothing, and record the
  result in a buffer. In classical parsers syntax, this could be
  written like this:

\begin{verbatim}
  fun buf ->
    parser
    [ [: `'['; `'<' :] ->
        Plexing.Lexbuf.add '<' (Plexing.Lexbuf.add '[' buf)
    | [: `'['; `':' :] ->
        Plexing.Lexbuf.add ':' (Plexing.Lexbuf.add '[' buf)
    | [: `'[' :] ->
        Plexing.Lexbuf '[' buf ]
\end{verbatim}

\noindent With the new syntax, it is possible to write it as:

\begin{verbatim}
  lexer [ "[<" | "[:" | "[" ]
\end{verbatim}

\noindent The two codes are strictly equivalent, but the lexer version is
  easier to write and understand, and is much shorter.

\section{Syntax}

\noindent When loading the syntax extension \texttt{pa\_lexer.cmo}, the OCaml
  syntax is extended as follows:

\begin{verbatim}
          expression ::= lexer
               lexer ::= "lexer" "[" rules "]"
               rules ::= rules rule
                       | <nothing>
                rule ::= symbols [ "->" action ]
             symbols ::= symbols symbol err
                       | <nothing>
              symbol ::= "_" no-record-opt
                       | CHAR no-record-opt
                       | CHAR "-" CHAR no-record-opt
                       | STRING no-record-opt
                       | simple-expression
                       | "?=" "[" lookaheads "]"
                       | "[" rules "]"
       no-record-opt ::= "/"
                       | <nothing>
   simple-expression ::= LIDENT
                       | "(" <expression> ")"
          lookaheads ::= lookaheads "|" lookahead-sequence
                       | lookahead-sequence
  lookahead-sequence ::= lookahead-symbols
                       | STRING
   lookahead-symbols ::= lookahead-symbols lookahead-symbol
                       | lookahead-symbol
    lookahead-symbol ::= CHAR
                       | CHAR "-" CHAR
                       | "_"
                 err ::= "?" simple-expression
                       | "!"
                       | <nothing>
              action ::= expression
\end{verbatim}

\noindent The identifiers "\texttt{STRING}", "\texttt{CHAR}" and
  "\texttt{LIDENT}" above represent the OCaml tokens corresponding to
  string, character and lowercase identifier (identifier starting with
  a lowercase character).

\

\noindent Moreover, together with that syntax extension, another extension is
  added the entry \texttt{expression}, typically for the semantics
  actions of the "\texttt{lexer}" statement above, but not only. It
  is:

\begin{verbatim}
  expression ::= "$" "add" STRING
               | "$" "buf"
               | "$" "empty"
               | "$" "pos"
\end{verbatim}

\noindent Remark: the identifiers "add", "buf", "empty" and "pos" are not
  keywords (they are not reserved words) but just identifiers. On the
  contrary, the identifier "\texttt{lexer}", which introduces the
  syntax, is a new keyword and cannot be used as variable identifier
  any more.

\section{Semantics}

\noindent A lexer defined in the syntax above is a shortcut version of a
  parser applied to the specific case of streams of characters. It
  could be written with a normal parser. The proposed syntax is much
  shorter, easier to use and to understand, and silently takes care of
  the lexing buffer for the programmer. The lexing buffers are data
  structures, which are passed as parameters to called lexers and
  returned by them.

\

\noindent Our lexers are of the type:

\begin{verbatim}
  Plexing.Lexbuf.t -> Stream.t char -> u
\end{verbatim}

\noindent where "\texttt{u}" is a type which depends on what the lexer
  returns. If there is no semantic action (since it it optional), this
  type is automatically "\texttt{Plexing.Lexbuf.t}" also.

\

\noindent A lexer is, actually, a function with two implicit parameters: the
  first one is the lexing buffer itself, and the second one the
  stream. When called, it tries to match the stream against its first
  rule. If it fails, it tries its second rule, and so on, up to its
  last rule. If the last rule fails, the lexer fails by raising the
  exception "\texttt{Stream.Failure}". All of this is
  the usual behaviour of stream
  parsers.

\

\noindent In a rule, when a character is matched, it is inserted into the
  lexing buffer, except if the "no record" feature is used (see
  further).

\

\noindent Rules which have no semantic action return the lexing buffer
  itself.

\subsection{Symbols}

\noindent The different kinds or symbols in a rule are:

\begin{itemize}
\item The token "underscore", which represents any character. Fails
    only if the stream is empty.
\item A character which represents a matching of this character.
\item A character followed by the minus sign and by another character
    which represent all characters in the range between the two
    characters in question.
\item A string with represents a matching of all its characters, one
    after the other.
\item An expression corresponding to a call to another lexer, which
    takes the buffer as first parameter and returns another lexing
    buffer with all characters found in the stream added to the
    initial lexing buffer.
\item The sequence "\texttt{?=}" introducing lookahead
    characters.
\item A rule, recursively, between brackets, inlining a lexer.
\end{itemize}

\noindent In the cases matching characters (namely underscore, character,
  characters range and string), the symbol can be optionally followed
  by the "no record" character "slash" specifying that the found
  character(s) are not added into the lexing buffer. By default, they
  are. This feature is useful, for example, writing a lexer which
  parses strings, when the initial double quote and final double quote
  should not be part of the string itself.

\

\noindent Moreover, a symbol can be followed by an optional error indicator,
  which can be:

\begin{itemize}
\item The character \texttt{?} (question mark) followed by a
    string expression, telling that, if there is a syntax error at
    this point (i.e. the symbol is not matched although the beginning
    of the rule was), the exception \texttt{Stream.Error} is
    raised with that string as parameter. Without this indicator, it
    is raised with the empty string. This is the same behaviour than
    with classical stream parsers.
\item The character \texttt{!} (exclamation mark), which is just an
    indicator to let the syntax expander optimize the code. If the
    programmer is sure that the symbol never fails (i.e. never
    raises \texttt{Stream.Failure}), in particular if this symbol
    recognizes the empty rule, he can add this exclamation mark. If it
    is used correctly (the compiler cannot check it), the behaviour is
    identical as without the \texttt{!}, except that the code is
    shorter and faster, and can sometimes be tail recursive. If the
    indication is not correct, the behaviour of the lexer is
    undefined.
\end{itemize}

\subsection{Specific expressions}

\noindent When loading this syntax extension, the
  entry \texttt{<expression>}, at level labelled "simple" of the
  OCaml language is extended with the following rules:

\begin{itemize}
\item \texttt{\$add} followed by a string, specifing that the
    programmer wants to add all characters of the string in the lexing
    buffer. It returns the new lexing buffer. It corresponds to an
    iteration of calls to \texttt{Plexing.Lexbuf.add} with all
    characters of the string with the current lexing buffer as initial
    parameter.
\item \texttt{\$buf} which returns the lexing buffer converted into
    string.
\item \texttt{\$empty} which returns an empty lexing buffer.
\item \texttt{\$pos} which returns the current position of the
    stream in number of characters (starting at zero).
\end{itemize}

\subsection{Lookahead}

\noindent Lookahead is useful in some cases, when factorization of rules is
  impossible. To understand how it is useful, a first remark must be
  done, about the usual behaviour of Camlp5 stream parsers.

\

\noindent Stream parsers (including these lexers) use a limited parsing
  algorithm, in a way that when the first symbol of a rule is matched,
  all the following symbols of the same rule must apply, otherwise it
  is a syntax error. There is no backtrack. In most of the cases, left
  factorization of rules resolve conflicting problems. For example, in
  parsers of tokens (which is not our case here, since we parse only
  characters), when one writes a parser to recognize both typical
  grammar rules "if..then..else" and the shorter "if..then..", the
  system transforms them into a single rule starting with "if..then.."
  followed by a call to a parser recognizing
  "else.." or nothing.

\

\noindent Sometimes, however, this left factorization is not possible. A
  lookahead of the stream to check the presence of some elements
  (these elements being characters, if we are using this "lexer"
  syntax) might be necessary to decide if is a good idea to start the
  rule. This lookahead feature may unfreeze several characters from
  the input stream but without removing them.

\

\noindent Syntactically, a lookahead starts with \texttt{?=} and is
  followed by one or several lookahead sequences separated by the
  vertical bar \texttt{|}, the whole list being enclosed by
  braces.

\

\noindent If there are several lookaheads, they must all be of the same size
  (contain the same number of characters).

\

\noindent If the lookahead sequence is just a string, it corresponds to all
  characters of this string in the order (which is different for
  strings outside lookahead sequences, representing a choice of all
  characters).

\

\noindent Examples of lookaheads:

\begin{verbatim}
  ?= [ _ ''' | '\\' _ ]
  ?= [ "<<" | "<:" ]
\end{verbatim}

\noindent The first line above matches a stream whose second character is a
  quote or a stream whose first character is a backslash (real example
  in the lexer of OCaml, in the library of Camlp5, named
  "plexer.ml"). The second line matches a stream starting with the two
  characters \texttt{<} and \texttt{<} or starting with
  the two characters \texttt{<} and \texttt{:} (this is
  another example in the same file).

\subsection{Semantic actions of rules}

\noindent By default, the result of a "lexer" is the current lexing buffer,
  which is of type "\texttt{Plexing.Lexbuf.t}". But it is possible to
  return other values, by adding "\texttt{->}" at end of rules
  followed by the expression you want to return, as in usual pattern
  matching in OCaml.

\

\noindent An interesting result, for example, could be the string
  corresponding to the characters of the lexing buffer. This can be
  obtained by returning the value "\texttt{\$buf}".

\subsection{A complete example}

\noindent A complete example can be seen in the sources of Camlp5, file
"lib/plexer.ml". This is the lexer of OCaml, either "normal" or
"revised" syntax.

\subsection{Compiling}

\noindent To compile a file containing lexers, just
  load \texttt{pa\_lexer.cmo} using one of the following methods:

\begin{itemize}
\item Either by adding \texttt{pa\_lexer.cmo} among the Camlp5
    options. See the Camlp5 manual page or documentation.
\item Or by adding \texttt{\#load "pa\_lexer.cmo";} anywhere in the
    file, before the usages of this "lexer" syntax.
\end{itemize}

\subsection{How to display the generated code}

\noindent You can see the generated code, for a file "bar.ml" containing
  lexers, by typing in a command line:

\begin{verbatim}
  camlp5r pa_lexer.cmo pr_r.cmo bar.ml
\end{verbatim}

\noindent To see the equivalent code with stream parsers, use:

\begin{verbatim}
  camlp5r pa_lexer.cmo pr_r.cmo pr_rp.cmo bar.ml
\end{verbatim}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Functional parsers}

\noindent Purely functional parsers are an alternative
  of stream parsers where the used stream
  type is a lazy non-destructive type. These streams are lazy values,
  as in classical stream parsers, but the values are not removed as
  long as the parsing advances.

\

\noindent To make them work, the parsers of purely functional streams return,
  not the simple values, but a value of type option :
  "\texttt{None}" meaning "no match" (the equivalent of the
  exception "\texttt{Parse.Failure}" of normal streams) and
  "\texttt{Some (r, s)}" meaning "the result is r and the
  remaining stream is s".


\section{Syntax}

\noindent The syntax of purely functional parsers, when loading
  "pa\_fstream.cmo", is the following:

\begin{verbatim}
          expression ::= fparser
                       | match-with-fparser
             fparser ::= "fparser" pos-opt "[" parser-cases "]"
                       | "fparser" pos-opt parser-case
  match-with-fparser ::= "match" expression "with" fparser
        parser-cases ::= parser-cases parser-case
                       | <nothing>
         parser-case ::= "[:" stream-pattern ":]" pos-opt "->" expression
                       | "[:" ":]" pos-opt "->" expression
      stream-pattern ::= stream-patt-comp
                       | stream-patt-comp ";" stream-pattern
    stream-patt-comp ::= "`" pattern
                       | "`" pattern "when" expression
                       | pattern "=" expression
                       | pattern
                       | "when" expression
             pos-opt ::= pattern
                       | <nothing>
\end{verbatim}

\noindent Notice that, unlike classical parsers, there is no difference, in a
  stream pattern, between the first stream pattern component and the
  other ones. In particular, there is no "question mark" syntax and
  expression optionnally ending those components. Moreover, the
  "lookahead" case is not necessary, we see further why. The syntaxes
  "pattern when" and "let..in" inside stream patterns we see in
  classical parsers are not implemented. 

\section{Streams}

\noindent The functional parsers are functions taking as parameters
  functional streams, which are values of type "\texttt{Fstream.t
  a}" for some type "\texttt{a}". It is possible to build
  functional streams using the functions defined in the module
  "\texttt{Fstream}":

\subsection{Fstream.from}

\noindent "\texttt{Fstream.from f}" returns a stream built from the
function "\texttt{f}". To create a new stream element, the
function "\texttt{f}" is called with the current stream count,
starting with zero. The user function "\texttt{f}" must return
either "\texttt{Some <value>}" for a value or
"\texttt{None}" to specify the end of the stream.

\subsection{Fstream.of\_list}

\noindent Return a stream built from the list in the same order.

\subsection{Fstream.of\_string}

\noindent Return a stream of the characters of the string parameter.

\subsection{Fstream.of\_channel}

\noindent Return a stream of the characters read from the input channel
parameter.

\section{Semantics of parsers}

\subsection{Fparser}

\noindent The purely functional parsers act like classical parsers, with a
recursive descent algorithm, except that:

\begin{itemize}
\item If the first stream pattern component matches the beginning of
    the stream, there is no error if the following stream patterns
    components do not match: the control simply passes to the next
    parser case with the initial stream.
\item If the semantic actions are of type "\texttt{t}", the result
    of the parser is of type "\texttt{option (t * Fstream.t)}",
    not just "\texttt{t}" like in classical parsers. If a stream
    pattern matches, the semantic action is evaluated, giving some
    result "\texttt{e}" and the result of the parser is
    "\texttt{Some (e, strm)}" where "\texttt{strm}" is the
    remaining stream.
\item If no parser case matches, the result of the parser is
    "\texttt{None}".
\end{itemize}

\subsection{Error position}

\noindent A difficulty, with purely functional parsers, is how to find the
  position of the syntax error, when the input is wrong. Since the
  system tries all parsers cases before returning "\texttt{None}",
  and that the initial stream is not affected, it is not possible to
  directly find where the error happened. This is a problem for
  parsing using backtracking (here, it is limited backtracking, but
  the problem is the same).

\

\noindent The solution is to use the function
  "\texttt{Fstream.count\_unfrozen}" applied to the initial
  stream. Like its name says, it returns the number of unfrozen
  elements of the stream, which is exactly the longest match found. If
  the input is a stream of characters, the return of this function is
  exactly the position in number of characters from the beginning of
  the stream.

\

\noindent However, it is not possible to know directly which rule failed and
  therefore it is not possible, as in classical parsers, to specify
  and get clear error messages. Future versions of purely functional
  parsers may propose solutions to resolve this problem.

\

\noindent Notice that, if using the "\texttt{count\_unfrozen}" method, it is
  not possible to reuse that same stream to call another parser, and
  hope to get the right position of the error, if another error
  happens, since it may test less terminals than the first parser. Use
  a fresh stream in this case, if possible.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Backtracking parsers}

\noindent Backtracking parsers are a second alternative
  of stream parsers
  and functional parsers.

\

\noindent Backtracking parsers are close to functional parsers: they use the
  same stream type, "\texttt{Fstream.t}", and their syntax is almost
  identical, its introducing keyword being "\texttt{bparser}" instead
  of "\texttt{fparser}".

\

\noindent The difference is that they are implemented with \emph{full
    backtracking} and that they return values of the type
    "\texttt{option}" of the triplet: 1/ value, 2/ remaining stream
    and 3/ continuation.


\section{Syntax}

\noindent The syntax of backtracking parsers is added together with the
  syntax of functional parsers, when the kit "pa\_fstream.cmo" is
  loaded. It is:

\begin{verbatim}
          expression ::= bparser
                       | match-with-bparser
             bparser ::= "bparser" pos-opt "[" parser-cases "]"
                       | "bparser" pos-opt parser-case
  match-with-bparser ::= "match" expression "with" bparser
        parser-cases ::= parser-cases parser-case
                       | <nothing>
         parser-case ::= "[:" stream-pattern ":]" pos-opt "->" expression
                       | "[:" ":]" pos-opt "->" expression
      stream-pattern ::= stream-patt-comp
                       | stream-patt-comp ";" stream-pattern
    stream-patt-comp ::= "`" pattern
                       | "`" pattern "when" expression
                       | pattern "=" expression
                       | pattern
                       | "when" expression
             pos-opt ::= pattern
                       | <nothing>
\end{verbatim}

\section{Semantics}

\subsection{Algorithm}

\noindent The backtracking parsers, like classical parsers and functional
  parsers, use a recursive descent algorithm. But:

\begin{itemize}
\item If a stream pattern component does not match the current
    position of the input stream, the control is given to the next
    case of the stream pattern component before it. If it is the first
    stream pattern component, the rule (the stream pattern) is left
    and the next rule is tested.
\end{itemize}

\noindent For example, the following grammar:

\begin{verbatim}
   E -> X Y
   X -> a b | a
   Y -> b
\end{verbatim}

\noindent works, with the backtracking algorithm, for the input "\texttt{a
  b}".

\

\noindent Parsing with the non-terminal "\texttt{E}", the non-terminal
  "\texttt{X}" first accepts the input "\texttt{a b}" with its first
  rule. Then when "\texttt{Y}" is called, the parsing fails since
  nothing remains in the input stream.

\

\noindent In the rule "\texttt{X Y}" of the non-terminal "\texttt{E}", the
  non-terminal "\texttt{Y}" having failed, the control is given the
  the continuation of the non-terminal "\texttt{X}". This continuation
  is its second rule containing only "\texttt{a}". Then "\texttt{Y}"
  is called and accepted.

\

\noindent This case does not work with functional parsers since when the rule
  "\texttt{a b}" of the non-terminal "\texttt{X}" is accepted, it is
  definitive. If the input starts with "\texttt{a b}", there is no way
  to apply its second rule.

\

\noindent Backtracking parsers are strictly more powerful than functional
  parsers.

\subsection{Type}

\noindent A backtracking parser whose stream elements are of type
  "\texttt{t1}", and whose semantic actions are of some type
  "\texttt{t2}", is of type:

\begin{verbatim}
   Fstream.t t1 -> option (t * Fstream.t t1 * Fstream.kont t1 t2)
\end{verbatim}

\noindent If the backtracking parsers fails, its returning value is
  "\texttt{None}".

\

\noindent If it succeeds, its returning value is "\texttt{Some (x, strm, k)}"
  where "\texttt{x}" is its result, "\texttt{strm}" the remaining
  stream, and "\texttt{k}" the continuation.

\

\noindent The continuation is internally used in the backtracking algorithm,
  but is can also be used in the main call to compute the next
  solution, using the function "\texttt{Fstream.bcontinue}".

\

\noindent It is also possible to directly get the list of all solutions by
  calling the function "\texttt{Fstream.bparse\_all}".

\subsection{Syntax errors}

\noindent Like for functional parsers, in case of
  syntax error, the error position can be found by using the function
  "\texttt{Fstream.count\_unfrozen}", the token in error being the
  last unfrozen element of the stream.

\

\noindent A syntax error is not really an error: for the backtracking
  parsers, like for functional parsers, it is viewed as a
  "non-working" case and another solution is searched.<p>

\noindent In the backtracking algorithm, depending on the grammar and the
  input, the search of the next solution can be very long. A solution
  is proposed for that in the extensible
  grammars system when the parsing algorithm is set to
  "backtracking".

\section{Example}

\noindent Here is an example which just shows the backtracking algorithm but
  without parsing, an empty stream being given as parameter and never
  referred.<p>

\noindent It creates a list of three strings, each of them being choosen
  between \texttt{"A"}, \texttt{"B"} and \texttt{"C"}.

\

\noindent The code is:

\begin{verbatim}
  #load "pa_fstream.cmo";
  value choice = bparser [ [: :] -> "A" | [: :] -> "B" | [: :] -> "C" ];
  value combine = bparser [: x = choice; y = choice; z = choice :] -> [x; y; z];
\end{verbatim}

\noindent The function "combine" returns the first solution:

\begin{verbatim}
  # combine (fstream [: :]);
  - : option (list string * Fstream.t '_a * Fstream.kont '_a (list string)) =
  Some (["A"; "A"; "A"], <abstr>, Fstream.K <fun>)
\end{verbatim}

\noindent The function "Fstream.bparse\_all" returns the list of all solutions,
  showing the interest of the backtracking:

\begin{verbatim}
  # Fstream.bparse_all combine (fstream [: :]);
  - : list (list string) =
  [["A"; "A"; "A"]; ["A"; "A"; "B"]; ["A"; "A"; "C"]; ["A"; "B"; "A"];
   ["A"; "B"; "B"]; ["A"; "B"; "C"]; ["A"; "C"; "A"]; ["A"; "C"; "B"];
   ["A"; "C"; "C"]; ["B"; "A"; "A"]; ["B"; "A"; "B"]; ["B"; "A"; "C"];
   ["B"; "B"; "A"]; ["B"; "B"; "B"]; ["B"; "B"; "C"]; ["B"; "C"; "A"];
   ["B"; "C"; "B"]; ["B"; "C"; "C"]; ["C"; "A"; "A"]; ["C"; "A"; "B"];
   ["C"; "A"; "C"]; ["C"; "B"; "A"]; ["C"; "B"; "B"]; ["C"; "B"; "C"];
   ["C"; "C"; "A"]; ["C"; "C"; "B"]; ["C"; "C"; "C"]]
\end{verbatim}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Extensible grammars}

\noindent This chapter describes the syntax and semantics of the extensible
  grammars of Camlp5.

\

\noindent The extensible grammars are the most advanced parsing tool of
  Camlp5. They apply to streams of characters using a lexer which has
  to be previously defined by the programmer. In Camlp5, the syntax of
  the OCaml language is defined with extensible grammars, which makes
  Camlp5 a bootstrapped system (it compiles its own features by
  itself).


\section{Getting started}

\noindent The extensible grammars are a system to build \emph{grammar
    entries} which can be extended dynamically. A grammar entry is
  an abstract value internally containing a stream parser. The type
  of a grammar entry is \texttt{"Grammar.Entry.e t"}
  where \texttt{"t"} is the type of the values returned by the
  grammar entry.

\

\noindent To start with extensible grammars, it is necessary to build
  a \emph{grammar}, a value of type "\texttt{Grammar.g}", using the
  function "\texttt{Grammar.gcreate}":

\begin{verbatim}
  value g = Grammar.gcreate lexer;
\end{verbatim}

\noindent where "\texttt{lexer}" is a lexer previously defined. See the
  section explaining the interface with lexers. In a first time, it is
  possible to use a lexer of the module "\texttt{Plexer}" provided by
  Camlp5:

\begin{verbatim}
  value g = Grammar.gcreate (Plexer.gmake ());
\end{verbatim}

\noindent Each grammar entry is associated with a grammar. Only grammar
entries of the same grammar can call each other. To create a grammar
entry, one has to use the function "\texttt{Grammar.Entry.create}" with
takes the grammar as first parameter and a name as second parameter. This
name is used in case of syntax errors. For example:

\begin{verbatim}
  value exp = Grammar.Entry.create g "expression";
\end{verbatim}

\noindent To apply a grammar entry, the function
  "\texttt{Grammar.Entry.parse}" can be used. Its first parameter is the
  grammar entry, the second one a stream of characters:

\begin{verbatim}
  Grammar.Entry.parse exp (Stream.of_string "hello");
\end{verbatim}

\noindent But if you experiment this, since the entry was just created
  without any rules, you receive an error message:

\begin{verbatim}
  Stream.Error "entry [expression] is empty"
\end{verbatim}

\noindent To add grammar rules to the grammar entry, it is necessary
to \emph{extend} it, using a specific syntactic statement:
"\texttt{EXTEND}".

\section{Syntax of the EXTEND statement}

\noindent The "\texttt{EXTEND}" statement is added in the expressions of the
  OCaml language when the syntax extension kit "\texttt{pa\_extend.cmo}"
  is loaded. Its syntax is:

\begin{verbatim}
    expression ::= extend
        extend ::= "EXTEND" extend-body "END"
   extend-body ::= global-opt entries
    global-opt ::= "GLOBAL" ":" entry-names ";"
                 | <nothing>
   entry-names ::= entry-name entry-names
                 | entry-name
         entry ::= entry-name ":" position-opt "[" levels "]"
  position-opt ::= "FIRST"
                 | "LAST"
                 | "BEFORE" label
                 | "AFTER" label
                 | "LIKE" string
                 | "LEVEL" label
                 | <nothing>
        levels ::= level "|" levels
                 | level
         level ::= label-opt assoc-opt "[" rules "]"
     label-opt ::= label
                 | <nothing>
     assoc-opt ::= "LEFTA"
                 | "RIGHTA"
                 | "NONA"
                 | <nothing>
         rules ::= rule "|" rules
                 | rule
          rule ::= psymbols-opt "->" expression
                 | psymbols-opt
  psymbols-opt ::= psymbols
                 | <nothing>
      psymbols ::= psymbol ";" psymbols
                 | psymbol
       psymbol ::= symbol
                 | pattern "=" symbol
        symbol ::= keyword
                 | token
                 | token string
                 | entry-name
                 | entry-name "LEVEL" label
                 | "SELF"
                 | "NEXT"
                 | "LIST0" symbol
                 | "LIST0" symbol "SEP" symbol opt-opt-sep
                 | "LIST1" symbol
                 | "LIST1" symbol "SEP" symbol opt-opt-sep
                 | "OPT" symbol
                 | "FLAG" symbol
                 | "V" symbol opt-strings
                 | "[" rules "]"
                 | "(" symbol ")"
   opt-opt-sep ::= "OPT_SEP"
                 | <nothing>
   opt-strings ::= string opt-strings
                 | <nothing>
       keyword ::= string
         token ::= uident
         label ::= string
    entry-name ::= qualid
        qualid ::= qualid "." qualid
                 | uident
                 | lident
        uident ::= 'A'-'Z' ident
        lident ::= ('a'-'z' | '_' | misc-letter) ident
         ident ::= ident-char*
    ident-char ::= ('a'-'a' | 'A'-'Z' | '0'-'9' | '_' | ''' | misc-letter)
   misc-letter ::= '\128'-'\255'
\end{verbatim}

\noindent Other statements, "\texttt{GEXTEND}", "\texttt{DELETE\_RULE}",
  "\texttt{GDELETE\_RULE}" are also defined by the same syntax extension
  kit. See further.

\

\noindent In the description above, only "\texttt{EXTEND}" and "\texttt{END}"
  are new keywords (reserved words which cannot be used in variables,
  constructors or module names). The other strings
  (e.g. "\texttt{GLOBAL}", "\texttt{LEVEL}", "\texttt{LIST0}",
  "\texttt{LEFTA}", etc.) are not reserved.

\section{Semantics of the EXTEND statement}

\noindent The EXTEND statement starts with the "\texttt{EXTEND}" keyword and ends
  with the "\texttt{END}" keyword.

\subsection{GLOBAL indicator}

\noindent After the first keyword, it is possible to see the identifier
"\texttt{GLOBAL}" followed by a colon, a list of entries names and a
semicolon. It says that these entries correspond to visible
(previously defined) entry variables, in the context of the EXTEND
statement, the other ones being locally and silently defined
inside.

\begin{itemize}
\item If an entry, which is extended in the EXTEND statement, is in the
    GLOBAL list, but is not defined in the context of the EXTEND
    statement, the OCaml compiler will fail with the error "unbound
    value".
\item If there is no GLOBAL indicator, and an entry, which is extended
    in the EXTEND statement, is not defined in the contex of the EXTEND
    statement, the OCaml compiler will also fail with the error "unbound
    value".
\end{itemize}

\noindent Example:

\begin{verbatim}
  value exp = Grammar.Entry.create g "exp";
  EXTEND
    GLOBAL: exp;
    exp: [ [ x = foo; y = bar ] ];
    foo: [ [ "foo" ] ];
    bar: [ [ "bar" ] ];
  END;
\end{verbatim}

\noindent The entry "exp" is an existing variable (defined by value exp =
...). On the other hand, the entries "foo" and "bar" have not been
defined. Because of the GLOBAL indicator, the system define them
locally.

\

\noindent Without the GLOBAL indicator, the three entries would have been
considered as global variables, therefore the OCaml compiler would
say "unbound variable" under the first undefined entry, "foo".

\subsection{Entries list}

\noindent Then the list of entries extensions follow. An entry extension
starts with the entry name followed by a colon. An entry may have
several levels corresponding to several stream parsers which call the
ones the others (see further).

\subsubsection{Optional position}

\noindent After the colon, it is possible to specify a where to insert the
defined levels:

\begin{itemize}
\item The identifier "\texttt{FIRST}" (resp. "\texttt{LAST}")
    indicates that the level must be inserted before (resp. after) all
    possibly existing levels of the entry. They become their first
    (resp. last) levels.
\item The identifier "\texttt{BEFORE}" (resp. "\texttt{AFTER}")
    followed by a level label (a string) indicates that the levels
    must be inserted before (resp. after) that level, if it exists. If
    it does not exist, the extend statement fails at run time.
\item The identifier "\texttt{LIKE}" followed by a string indicates
    that the first level defined in the extend statement must be
    inserted in the first already existing level with a rule
    containing this string as keyword or token name. For example,
    "\texttt{LIKE "match"}" is the first level having "\texttt{match}"
    as keyword. If there is no level with this string, the extend
    statement fails at run time.
\item The identifier "\texttt{LEVEL}" followed by a level label
    indicates that the first level defined in the extend statement
    must be inserted at the given level, extending and modifying
    it. The other levels defined in the statement are inserted after
    this level, and before the possible levels following this
    level. If there is no level with this label, the extend statement
    fails at run time.
\item By default, if the entry has no level, the levels defined in the
    statement are inserted in the entry. Otherwise the first defined
    level is inserted at the first level of the entry, extending or
    modifying it. The other levels are inserted afterwards (before the
    possible second level which may previously exist in the entry).
\end{itemize}

\subsubsection{Levels}

\noindent After the optional "position", the \emph{level} list follow. The
  levels are separated by vertical bars, the whole list being between
  brackets.

\

\noindent A level starts with an optional label, which corresponds to its
  name. This label is useful to specify this level in case of future
  extensions, using the \emph{position} (see previous section) or
  for possible direct calls to this specific level.

\

\noindent The level continues with an optional associativity indicator, which
  can be:

\begin{itemize}
\item LEFTA for left associativity (default),
\item RIGHTA for right associativity,
\item NONA for no associativity.
\end{itemize}

\subsubsection{Rules}

\noindent At last, the grammar \emph{rule} list appear. The rules are
separated by vertical bars, the whole list being brackets.

\

\noindent A rule looks like a match case in the "\texttt{match}" statement or
a parser case in the "\texttt{parser}" statement: a list of psymbols
(see next paragraph) separated by semicolons, followed by a right
arrow and an expression, the semantic action. Actually, the right
arrow and expression are optional: in this case, it is equivalent to
an expression which would be the unit "\texttt{()}" constructor.

\

\noindent A psymbol is either a pattern, followed with the equal sign and a
symbol, or by a symbol alone. It corresponds to a test of this symbol,
whose value is bound to the pattern if any.

\subsection{Symbols}

\noindent A symbol is an item in a grammar rule. It is either:

\begin{itemize}
\item a keyword (a string): the input must match this keyword,
\item a token name (an identifier starting with an uppercase
    character), optionally followed by a string: the input must match
    this token (any value if no string, or that string if a string
    follows the token name), the list of the available tokens
    depending on the associated lexer (the list of tokens available
    with "Plexer.gmake ()" is: LIDENT, UIDENT, TILDEIDENT,
    TILDEIDENTCOLON, QUESTIONIDENT, INT, INT\_l, INT\_L, INT\_n, FLOAT,
    CHAR, STRING, QUOTATION, ANTIQUOT and EOI; other lexers may
    propose other lists of tokens),

\item an entry name, which correspond to a call to this entry,
\item an entry name followed by the identifier "\texttt{LEVEL}" and a
    level label, which correspond to the call to this entry at that
    level,
\item the identifier "\texttt{SELF}" which is a recursive call to the
    present entry, according to the associativity (i.e. it may be a
    call at the current level, to the next level, or to the top level
    of the entry): "\texttt{SELF}" is equivalent to the name of the
    entry itself,
\item the identifier "\texttt{NEXT}", which is a call to the next level
    of the current entry,
\item a left brace, followed by a list of rules separated by vertical
    bars, and a right brace: equivalent to a call to an entry, with
    these rules, inlined,
\item a meta symbol (see further),
\item a symbol between parentheses.
\end{itemize}

\noindent The syntactic analysis follow the list of symbols. If it fails,
depending on the first items of the rule (see the section about the
kind of grammars recognized):

\begin{itemize}
\item the parsing may fail by raising the exception
    "\texttt{Stream.Error}"
\item the parsing may continue with the next rule.
\end{itemize}

\subsubsection{Meta symbols}

\noindent Extra symbols exist, allowing to manipulate lists or optional
symbols. They are:

\begin{itemize}
\item LIST0 followed by a symbol: this is a list of this symbol,
    possibly empty,
\item LIST0 followed by a symbol, SEP and another symbol, and optional
    OPT\_SEP: this is a list, possibly empty, of the first symbol
    separated by the second one, possibly ended with the separator if
    OPT\_SEP is present,
\item LIST1 followed by a symbol: this is a list of this symbol,
    with at least one element,
\item LIST1 followed by a symbol, SEP and another symbol, and optional
    OPT\_SEP: this is a list, with at least one element, of the first
    symbol separated by the second one, possibly ended with the
    separator if OPT\_SEP is present,
\item OPT followed by a symbol: equivalent to "this symbol or
    nothing" returning a value of type "\texttt{option}".
\item FLAG followed by a symbol: equivalent to "this symbol or
    nothing", returning a boolean.
\end{itemize}

\subsubsection{The V meta symbol}

\noindent The V meta symbol is destinated to allow antiquotations while using
  the syntax tree quotation
  kit \texttt{q\_ast.cmo}. It works only in
  strict mode. In transitional mode, it is just equivalent to its
  symbol parameter.

\textbf{Antiquotation kind}

\noindent The antiquotation kind is the optional identifier between the
  starting "\texttt{\$}" (dollar) and the "\texttt{:}" (colon) in a
  quotation of syntax tree (see the
  chapter syntax tree).

\

\noindent The optional list of strings following the "V" meta symbol and its
  symbol parameter gives the allowed antiquotations kinds.

\

\noindent By default, this string list, i.e. the available antiquotation
  kinds, is:

\begin{itemize}
\item \texttt{["flag"]} for FLAG
\item \texttt{["list"]} for LIST0 and LIST1
\item \texttt{["opt"]} for OPT
\end{itemize}

\noindent For example, the symbol:

\begin{verbatim}
  V (FLAG "rec")
\end{verbatim}

\noindent is like "FLAG" while normally parsing, allowing to parse the keyword
  "\texttt{rec}". While using it in quotations, also allows the parse
  the keyword "\texttt{rec}" but, moreover, the antiquotation
  "\texttt{\$flag:..\$}" where "\texttt{..}" is an expression or a pattern
  depending on the position of the quotation.

\

\noindent There are also default antiquotations kinds for the tokens used in
  the OCaml language predefined parsers "\texttt{pa\_r.cmo}" (revised
  syntax) and "\texttt{pa\_o.cmo}" (normal syntax), actually all
  parsers using the provided lexer "\texttt{Plexer}" (see the
  chapter Library). They are:

\begin{itemize}
\item \texttt{["chr"]} for CHAR
\item \texttt{["flo"]} for FLOAT
\item \texttt{["int"]} for INT
\item \texttt{["int32"]} for INT\_l
\item \texttt{["int64"]} for INT\_L
\item \texttt{["nativeint"]} for INT\_n
\item \texttt{["lid"]} for LIDENT
\item \texttt{["str"]} for STRING
\item \texttt{["uid"]} for UIDENT
\end{itemize}

\noindent It is also possible to use the "V" meta symbol over non-terminals
  (grammars entries), but there is no default antiquotation kind. For
  example, while parsing a quotation, the symbol:

\begin{verbatim}
  V foo "bar" "oops"
\end{verbatim}

\noindent corresponds to either a call to the grammar entry "\texttt{foo}",
  or to the antiquotations "\texttt{\$bar:...\$}" or
  "\texttt{\$oops:...\$}".

\textbf{Type}

\noindent The type of the value returned by a V meta symbol is:

\begin{itemize}
\item in transitional mode, the type of its symbol parameter,
\item in strict mode, "\texttt{Ploc.vala t}", where "\texttt{t}" is
    its symbol parameter.
\end{itemize}

\noindent In strict mode, if the symbol parameter is found, whose value is,
  say, "\texttt{x}", the result is "\texttt{Ploc.VaVal x}". If an
  antiquotation is found the result is "\texttt{Ploc.VaAnt s}" where
  "\texttt{s}" is some string containing the antiquotation text and
  some other internal information.

\subsection{Rules insertion}

\noindent Remember that "\texttt{EXTEND}" is a statement, not a declaration:
the rules are added in the entries at run time. Each rule is
internally inserted in a tree, allowing the left factorization of the
rule. For example, with this list of rules (borrowed from the Camlp5
sources):

\begin{verbatim}
  "method"; "private"; "virtual"; l = label; ":"; t = poly_type
  "method"; "virtual"; "private"; l = label; ":"; t = poly_type
  "method"; "virtual"; l = label; ":"; t = poly_type
  "method"; "private"; l = label; ":"; t = poly_type; "="; e = expr
  "method"; "private"; l = label; sb = fun_binding
  "method"; l = label; ":"; t = poly_type; "="; e = expr
  "method"; l = label; sb = fun_binding
\end{verbatim}

\noindent the rules are inserted in a tree and the result looks like:

\begin{verbatim}
  "method"
     |-- "private"
     |       |-- "virtual"
     |       |       |-- label
     |       |             |-- ":"
     |       |                  |-- poly_type
     |       |-- label
     |             |-- ":"
     |             |    |-- poly_type
     |             |            |-- ":="
     |             |                 |-- expr
     |             |-- fun_binding
     |-- "virtual"
     |       |-- "private"
     |       |       |-- label
     |       |             |-- ":"
     |       |                  |-- poly_type
     |       |-- label
     |             |-- ":"
     |                  |-- poly_type
     |-- label
           |-- ":"
           |    |-- poly_type
           |            |-- "="
           |                 |-- expr
           |-- fun_binding
\end{verbatim}

\noindent This tree is built as long as rules are inserted. When used, by
  applying the function "\texttt{Grammar.Entry.parse}" to the current
  entry, the input is matched with that tree, starting from the tree
  root, descending on it as long as the parsing advances.

\

\noindent There is a different tree by entry level.

\subsection{Semantic action}

\noindent The semantic action, i.e. the expression following the right arrow
  in rules, contains in its environment:

\begin{itemize}
\item the variables bound by the patterns of the symbols found in the
    rules,
\item the specific variable "\texttt{loc}" which contain the location
    of the whole rule in the source.
\end{itemize}

\noindent The location is an abstract type defined in the module
  "\texttt{Ploc}" of Camlp5.

\

\noindent It is possible to change the name of this variable by using the option
"\texttt{-loc}" of Camlp5. For example, compiling a file like this:

\begin{verbatim}
  camlp5r -loc foobar file.ml
\end{verbatim}

\noindent the variable name, for the location will be "\texttt{foobar}"
instead of "\texttt{loc}".

\section{The DELETE\_RULE statement}

\noindent The "\texttt{DELETE\_RULE}" statement is also added in the
  expressions of the OCaml language when the syntax extension kit
  "\texttt{pa\_extend.cmo}" is loaded. Its syntax is:

\begin{verbatim}
        expression ::= delete-rule
       delete-rule ::= "DELETE_RULE" delete-rule-body "END"
  delete-rule-body ::= entry-name ":" symbols
           symbols ::= symbol symbols
                     | symbol
\end{verbatim}

\noindent See the syntax of the EXTEND statement for the meaning of the syntax
  entries not defined above.

\

\noindent The entry is scanned for a rule matching the giving symbol
  list. When found, the rule is removed. If no rule is found, the
  exception "\texttt{Not\_found}" is raised.

\section{Extensions FOLD0 and FOLD1}

\noindent When loading "\texttt{pa\_extfold.cmo}" after
  "\texttt{pa\_extend.cmo}", the entry "\texttt{symbol}" of the EXTEND
  statement is extended with what is named the \emph{fold
  iterators}, like this:

\begin{verbatim}
       symbol ::= "FOLD0" simple_expr simple_expr symbol
                | "FOLD1" simple_expr simple_expr symbol
                | "FOLD0" simple_expr simple_expr symbol "SEP" symbol
                | "FOLD1" simple_expr simple_expr symbol "SEP" symbol
  simple_expr ::= expr (level "simple")
\end{verbatim}

\noindent Like their equivalent with the lists iterators: "\texttt{LIST0}",
  "\texttt{LIST1}", "\texttt{LIST0SEP}", "\texttt{LIST1SEP}", they
  read a sequence of symbols, possibly with the separators, but
  instead of building the list of these symbols, apply a fold function
  to each symbol, starting at the second "expr" (which must be a
  expression node) and continuing with the first "expr" (which must be
  a function taking two expressions and returing a new
  expression).

\

\noindent The list iterators can be seen almost as a specific case of these
  fold iterators where the initial "expr" would be:

\begin{verbatim}
  <:expr< [] >>
\end{verbatim}

\noindent and the fold function would be:

\begin{verbatim}
  fun e1 e2 -> <:expr< [$e1$ :: $e2$ ] >>
\end{verbatim}

\noindent except that, implemented like that, they would return the list in
  reverse order.

\

\noindent Actually, a program using them can be written with the lists
  iterators with the semantic action applying the function
  "\texttt{List.fold\_left}" to the returned list, except that with the
  fold iterators, this operation is done as long as the symbols
  are read on the input, no intermediate list being built.

\

\noindent Example, file "sum.ml":

\begin{verbatim}
  #load "pa_extend.cmo";
  #load "pa_extfold.cmo";
  #load "q_MLast.cmo";
  let loc = Ploc.dummy in
  EXTEND
    Pcaml.expr:
      [ [ "sum";
          e =
            FOLD0 (fun e1 e2 -> <:expr< $e2$ + $e1$ >>) <:expr< 0 >>
              Pcaml.expr SEP ";";
          "end" -> e ] ]
    ;
  END;
\end{verbatim}

\noindent which can be compiled like this:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 -c sum.ml
\end{verbatim}

\noindent and tested:

\begin{verbatim}
  ocaml -I +camlp5 camlp5r.cma sum.cmo
          Objective Caml version ...

          Camlp5 Parsing version ...

  # sum 3;4;5 end;
- : int = 12
\end{verbatim}

\section{Grammar machinery}

\noindent We explain here the detail of the mechanism of the parsing of an
  entry.

\subsection{Start and Continue}

\noindent At each entry level, the rules are separated into two trees:

\begin{itemize}
\item The tree of the rules \emph{not} starting with the current entry
    name nor by "\texttt{SELF}".
\item The tree of the rules starting with the current entry name or by
    the identifier "\texttt{SELF}", this symbol not being included in
    the tree.
\end{itemize}

\noindent They determine two functions:

\begin{itemize}
\item The function named "start", analyzing the first tree.
\item The function named "continue", taking, as parameter, a value
    previously parsed, and analyzing the second tree.
\end{itemize}

\noindent A call to an entry, using "\texttt{Grammar.Entry.parse}" correspond
  to a call to the "start" function of the first level of the
  entry.

\

\noindent The "start" function tries its associated tree. If it works, it
  calls the "continue" function of the same level, giving the result
  of "start" as parameter. If this "continue" function fails, this
  parameter is simply returned. If the "start" function fails, the
  "start" function of the next level is tested. If there is no more
  levels, the parsing fails.

\

\noindent The "continue" function first tries the "continue" function of the
  next level. If it fails, or if it is the last level, it tries its
  associated tree, then calls itself again, giving the result as
  parameter. If its associated tree fails, it returns its extra
  parameter.

\subsection{Associativity}

\noindent While testing the tree, there is a special case for rules ending
  with SELF or with the current entry name. For this last symbol,
  there is a call to the "start" function: of the current level if the
  level is right associative, or of the next level otherwise.

\

\noindent There is no behaviour difference between left and non associative,
  because, in case of syntax error, the system attempts to recover the
  error by applying the "continue" function of the previous symbol (if
  this symbol is a call to an entry).

\

\noindent When a SELF or the current entry name is encountered in the middle
  of the rule (i.e. if it is not the last symbol), there is a call to
  the "start" function of the first level of the current entry.

\

\noindent Example. Let us consider the following grammar:

\begin{verbatim}
  EXTEND
    expr:
      [ "minus" LEFTA
        [ x = SELF; "-"; y = SELF -> x -. y ]
      | "power" RIGHTA
        [ x = SELF; "**"; y = SELF -> x ** y ]
      | "simple"
        [ "("; x = SELF; ")" -> x
        | x = INT -> float_of_int x ] ]
    ;
  END
\end{verbatim}

\noindent The left "SELF"s of the two levels "minus" and "power" correspond
  to a call to the next level. In the level "minus", the right "SELF"
  also, and the left associativity is treated by the fact that the
  "continue" function is called (starting with the keyword "-" since
  the left "SELF" is not part of the tree). On the other hand, for the
  level "power", the right "SELF" corresponds to a call to the current
  level, i.e. the level "power" again. At end, the "SELF" between
  parentheses of the level "simple" correspond to a call to the first
  level, namely "minus" in this grammar.

\subsection{Parsing algorithm}

\noindent By default, the kind of grammar is predictive parsing grammar,
  i.e. recursive descent parsing without backtrack. But with some
  nuances, due to the improvements (error recovery and token starting
  rules) indicated in the next sections.

\

\noindent However, it is possible to change the parsing algorithm, by calling
  the function "\texttt{Grammar.set\_algorithm}". The possible values
  are:

\begin{description}
\item[\texttt{Grammar.Predictive}]

\

internally using normal parsers, with
    a predictive (recursive descent without backtracking)
    algorithm.
\item[\texttt{Grammar.Backtracking}]

\

internally using backtracking
    parsers, with a full backtracking algorithm,
\item[\texttt{Grammar.DefaultAlgorithm}]

\

the parsing algorithm is determined by the environment variable
    "CAMLP5PARAM". If this environment variable exists and contains
    "b", the parsing algorithm is "backtracking". Otherwise it is
    "predictive".
\end{description}

\noindent An interesting function, when using then backtracking algorithm, is
  "\texttt{Grammar.Entry.parse\_all}" which returns all solutions of a
  given input.

\

\noindent See details in the chapter Library,
  section "Grammar module".

\subsection{Errors and recovery}

\noindent In extensible grammars, the exceptions are encapsulated with the
  exception "Ploc.Exc" giving the location of the error together with
  the exception itself.

\

\noindent If the parsing algorithm is "\texttt{Grammar.Predictive}", the
  system internally uses stream
  parsers. Two exceptions may happen: "Stream.Failure" or
  "Stream.Error". "Stream.Failure" indicates that the parsing just
  could not start. "Stream.Error" indicates that the parsing started
  but failed further.

\

\noindent With this algorithm, when the first symbol of a rule has been
  accepted, all the symbols of the same rule must be accepted,
  otherwise the exception "Stream.Error" is raised.

\

\noindent If the parsing algorithm is "\texttt{Grammar.Backtracking}", the
  system internally uses backtracking
  parsers. If no solution is found, the exception
  "\texttt{Stream.Error}" is raised and the location of the error is
  the location of the last unfrozen token, i.e. where the stream
  advanced the farthest.

\

\noindent In extensible grammars, unlike stream parsers, before the
  "Stream.Error" exception, the system attempts to recover the error
  by the following trick: if the previous symbol of the rule was a
  call to another entry, the system calls the "continue" function of
  that entry, which may resolve the problem.

\subsection{Tokens starting rules}

\noindent Another improvement (other than error recovery) is that when a rule
  starts with several tokens and/or keywords, all these tokens and
  keywords are tested in one time, and the possible "Stream.Error" may
  happen, only from the symbol following them on, if any.

\section{The Grammar module}

\noindent See its section in the
  chapter "Library".

\section{Interface with the lexer}

\noindent To create a grammar, the function "\texttt{Grammar.gcreate}" must
  be called, with a lexer as parameter.

\

\noindent A simple solution, as possible lexer, is the predefined lexer built
  by "\texttt{Plexer.gmake ()}", lexer used for the OCaml grammar of
  Camlp5. In this case, you can just put it as parameter of
  "\texttt{Grammar.gcreate}" and it is not necessary to read this
  section.

\

\noindent The section first introduces the notion of "token patterns" which
  are the way the tokens and keywords symbols in the EXTEND statement
  are represented. Then follow the description of the type of the
  parameter of "\texttt{Grammar.gcreate}".

\subsection{Token patterns}

\noindent A token pattern is a value of the type defined like this:

\begin{verbatim}
  type pattern = (string * string);
\end{verbatim}

\noindent This type represents values of the token and keywords symbols in
  the grammar rules.

\

\noindent For a token symbol in the grammar rules, the first string is the
  token constructor name (starting with an uppercase character), the
  second string indicates whether the match is "any" (the empty
  string) or some specific value of the token (an non-empty
  string).

\

\noindent For a keyword symbol, the first string is empty and the second
  string is the keyword itself.

\

\noindent For example, given this grammar rule:

\begin{verbatim}
  "for"; i = LIDENT; "="; e1 = SELF; "to"; e2 = SELF
\end{verbatim}

\noindent the different symbols and keywords are represented by the following
  couples of strings:

\begin{itemize}
\item the keyword "for" is represented by \texttt{("", "for")},
\item the keyword "=" by \texttt{("", "=")},
\item the keyword "to" by \texttt{("", "to")}),
\item and the token symbol \texttt{LIDENT} by \texttt{("LIDENT", "")}.
\end{itemize}

\noindent The symbol \texttt{UIDENT "Foo"} in a rule would be represented
  by the token pattern:

\begin{verbatim}
  ("UIDENT", "Foo")
\end{verbatim}

\noindent Notice that the symbol "\texttt{SELF}" is a specific symbol of the
  EXTEND syntax: it does not correspond to a token pattern and is
  represented differently. A token constructor name must not belong to
  the specific symbols: SELF, NEXT, LIST0, LIST1, OPT and FLAG.

\subsection{The lexer record}

\noindent The type of the parameter of the function
  "\texttt{Grammar.gcreate}" is "\texttt{lexer}", defined in the
  module "\texttt{Plexing}". It is a record type with the following
  fields:

\subsubsection{\texttt{tok\_func}}

\noindent It is the lexer itself. Its type is:

\begin{verbatim}
  Stream.t char -> (Stream.t (string * string) * location_function);
\end{verbatim}

\noindent The lexer takes a character stream as parameter and return a couple
  of containing: a token stream (the tokens being represented by a
  couple of strings), and a location function.

\

\noindent The location function is a function taking, as parameter, a integer
  corresponding to a token number in the stream (starting from zero),
  and returning the location of this token in the source. This is
  important to get good locations in the semantic actions of the
  grammar rules.

\

\noindent Notice that, despite the lexer taking a character stream as
  parameter, it is not mandatory to use the stream parsers technology
  to write the lexer. What is important is that it does the job.

\subsubsection{\texttt{tok\_using}}

\noindent Is a function of type:

\begin{verbatim}
  pattern -> unit
\end{verbatim}

\noindent The parameter of this function is the representation of a token
  symbol or a keyword symbol in grammar rules. See the section about
  token patterns.

\

\noindent This function is called for each token symbol and each keyword
  encountered in the grammar rules of the EXTEND statement. Its goal
  is to allow the lexer to check that the tokens and keywords do
  respect the lexer rules. It checks that the tokens exist and are not
  mispelled. It can be also used to enter the keywords in the lexer
  keyword tables.

\

\noindent Setting it as the function that does nothing is possible, but the
  check of correctness of tokens is not done.

\

\noindent In case or error, the function must raise the exception
  "\texttt{Plexing.Error}" with an error message as parameter.

\subsubsection{\texttt{tok\_removing}}

\noindent Is a function of type:

\begin{verbatim}
  pattern -> unit
\end{verbatim}

\noindent It is possibly called by the DELETE\_RULE statement for tokens and
  keywords no longer used in the grammar. The grammar system maintains
  a number of usages of all tokens and keywords and calls this
  function only when this number reaches zero. This can be interesting
  for keywords: the lexer can remove them from its tables.

\subsubsection{\texttt{tok\_match}}

\noindent Is a function of type:

\begin{verbatim}
  pattern -> ((string * string) -> unit)
\end{verbatim}

\noindent The function tells how a token of the input stream is matched
  against a token pattern. Both are represented by a couple of
  strings.

\

\noindent This function takes a token pattern as parameter and return a
  function matching a token, returning the matched string or raising
  the exception "\texttt{Stream.Failure}" if the token does not
  match.

\

\noindent Notice that, for efficiency, it is necessary to write this function
  as a match of token patterns returning, for each case, the function
  which matches the token, \emph{not} a function matching the token
  pattern and the token together and returning a string for each
  case.

\

\noindent An acceptable function is provided in the module "\texttt{Plexing}"
  and is named "default\_match". Its code looks like this:

\begin{verbatim}
  value default_match =
    fun
    [ (p_con, "") ->
        fun (con, prm) -> if con = p_con then prm else raise Stream.Failure
    | (p_con, p_prm) ->
        fun (con, prm) ->
          if con = p_con \&\& prm = p_prm then prm else raise Stream.Failure ]
  ;
\end{verbatim}

\subsubsection{\texttt{tok\_text}}

\noindent Is a function of type:

\begin{verbatim}
  pattern -> string
\end{verbatim}

\noindent Designed for error messages, it takes a token pattern as parameter
  and returns the string giving its name.

\

\noindent It is possible to use the predefined function "\texttt{lexer\_text}"
  of the Plexing module. This function just returns the name of the
  token pattern constructor and its parameter if any.

\

\noindent For example, with this default function, the token symbol IDENT
  would be written as IDENT in error message (e.g. "IDENT expected").
  The "text" function may decide to print it differently, e.g., as
  "identifier".

\subsubsection{\texttt{tok\_comm}}

\noindent Is a mutable field of type:

\begin{verbatim}
  option (list location)
\end{verbatim}

\noindent It asks the lexer (the lexer function should do it) to record the
  locations of the comments in the program. Setting this field to
  "None" indicates that the lexer must not record them. Setting it to
  "Some []" indicated that the lexer must put the comments location
  list in the field, which is mutable.

\subsection{Minimalist version}

\noindent If a lexer have been written, named "\texttt{lexer}", here is the
  minimalist version of the value suitable as parameter to
  "\texttt{Grammar.gcreate}":

\begin{verbatim}
  {Plexing.tok_func = lexer;
   Plexing.tok_using _ = (); Plexing.tok_removing _ = ();
   Plexing.tok_match = Plexing.default_match;
   Plexing.tok_text = Plexing.lexer_text;
   Plexing.tok_comm = None}
\end{verbatim}

\section{Functorial interface}

\noindent The normal interface for grammars described in the previous sections
  has two drawbacks:

\begin{itemize}
\item First, the type of tokens of the lexers must be "\texttt{(string *
      string)}"
\item Second, since the entry type has no parameter to specify the
    grammar it is bound to, there is no static check that entries are
    compatible, i.e.  belong to the same grammar. The check is done at
    run time.
\end{itemize}

\noindent The functorial interface resolve these two problems. The functor
  takes a module as parameter where the token type has to be defined,
  together with the lexer returning streams of tokens of this
  type. The resulting module define entries compatible the ones to the
  other, and this is controlled by the OCaml type checker.

\

\noindent The syntax extension must be done with the statement GEXTEND, instead
  of EXTEND, and deletion by GDELETE\_RULE instead of DELETE\_RULE.

\subsection{The lexer type}

\noindent In the section about the interface with the lexer, we presented the
  "\texttt{Plexing.lexer}" type as a record without type
  parameter. Actually, this type is defined as:

\begin{verbatim}
  type lexer 'te =
    { tok_func : lexer_func 'te;
      tok_using : pattern -> unit;
      tok_removing : pattern -> unit;
      tok_match : pattern -> 'te -> string;
      tok_text : pattern -> string;
      tok_comm : mutable option (list location) }
  ;
\end{verbatim}

\noindent where the type parameter is the type of the token, which can be any
  type, different from "\texttt{(string * string)}", providing the
  lexer function (\texttt{tok\_func}) returns a stream of this token
  type and the match function (\texttt{tok\_match}) indicates how to
  match values of this token type against the token patterns (which
  remain defined as "\texttt{(string * string)}").

\

\noindent Here is an example of an user token type and the associated match
  function:

\begin{verbatim}
  type mytoken =
    [ Ident of string
    | Int of int
    | Comma | Equal
    | Keyw of string  ]
  ;

  value mymatch =
    fun
    [ ("IDENT", "") ->
        fun [ Ident s -> s | _ -> raise Stream.Failure ]
    | ("INT", "") ->
        fun [ Int i -> string_of_int i | _ -> raise Stream.Failure ]
    | ("", ",") ->
        fun [ Comma -> "" | _ -> raise Stream.Failure ]
    | ("", "=") ->
        fun [ Equal -> "" | _ -> raise Stream.Failure ]
    | ("", s) ->
        fun
        [ Keyw k -> if k = s then "" else raise Stream.Failure
        | _ -> raise Stream.Failure ]
    | _ -> raise (Plexing.Error "bad token in match function") ]
  ;
\end{verbatim}

\subsection{The functor parameter}

\noindent The type of the functor parameter is defined as:

\begin{verbatim}
  module type GLexerType =
    sig
      type te = 'x;
      value lexer : Plexing.lexer te;
    end;
\end{verbatim}

\noindent The token type must be specified (type "\texttt{te}") and the lexer
  also, with the interface for lexers, of the lexer type defined
  above, the record fields being described in the section "interface
  with the lexer", but with a general token type.

\subsection{The resulting grammar module}

\noindent Once a module of type "\texttt{GLexerType}" has been built
  (previous section), it is possible to create a grammar module by
  applying the functor "\texttt{Grammar.GMake}". For example:

\begin{verbatim}
  module MyGram = Grammar.GMake MyLexer;
\end{verbatim}

\noindent Notice that the function "\texttt{Entry.parse}" of this resulting
  module does not take a character stream as parameter, but a value of
  type "\texttt{parsable}". This function is equivalent to the
  function "\texttt{parse\_parsable}" of the non functorial
  interface. In short, the parsing of some character stream
  "\texttt{cs}" by some entry "\texttt{e}" of the example grammar
  above, must be done by:

\begin{verbatim}
  MyGram.Entry.parse e (MyGram.parsable cs)
\end{verbatim}

\noindent instead of:

\begin{verbatim}
  MyGram.Entry.parse e cs
\end{verbatim}

\subsection{GEXTEND and GDELETE\_RULE}

\noindent The "\texttt{GEXTEND}" and "\texttt{GDELETE\_RULE}" statements are
  also added in the expressions of the OCaml language when the syntax
  extension kit "\texttt{pa\_extend.cmo}" is loaded. They must be used
  for grammars defined with the functorial interface. Their syntax
  is:

\begin{verbatim}
           expression ::= gextend
                        | gdelete-rule
         gdelete-rule ::= "GDELETE_RULE" gdelete-rule-body "END"
              gextend ::= "GEXTEND" gextend-body "END"
         gextend-body ::= grammar-module-name extend-body
    gdelete-rule-body ::= grammar-module-name delete-rule-body
  grammar-module-name ::= qualid
\end{verbatim}

\noindent See the syntax of the EXTEND statement for the meaning of the syntax
  entries not defined above.

\section{An example: arithmetic calculator}

\noindent Here is a small calculator of expressions. They are given as
  parameters of the command.

\

\noindent File "calc.ml":

\begin{verbatim}
  #load "pa_extend.cmo";

  value g = Grammar.gcreate (Plexer.gmake ());
  value e = Grammar.Entry.create g "expression";

  EXTEND
    e:
      [ [ x = e; "+"; y = e -> x + y
        | x = e; "-"; y = e -> x - y ]
      | [ x = e; "*"; y = e -> x * y
        | x = e; "/"; y = e -> x / y ]
      | [ x = INT -> int_of_string x
        | "("; x = e; ")" -> x ] ]
    ;
  END;

  open Printf;

  for i = 1 to Array.length Sys.argv - 1 do {
    let r = Grammar.Entry.parse e (Stream.of_string Sys.argv.(i)) in
    printf "\%s = \%d\n" Sys.argv.(i) r;
    flush stdout;
  };
\end{verbatim}

\noindent The link needs the library "gramlib.cma" provided with Camlp5:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 gramlib.cma test/calc.ml -o calc
\end{verbatim}

\noindent Examples:

\begin{verbatim}
  $ ./calc '239*4649'
  239*4649 = 1111111
  $ ./calc '(47+2)/3'
  (47+2)/3 = 16
\end{verbatim}

\clearemptydoublepage
\part{Printing tools}
\clearemptydoublepage

\pagestyle{fancy}\chapter{Extensible printers}

\noindent This chapter describes the syntax and semantics of the extensible
  printers of Camlp5.

\

\noindent Similar to the extensible grammars, the
  extensible printers allow to define and extend printers of data or
  programs. A specific statement "\texttt{EXTEND\_PRINTER}" allow to
  define these extensions.


\section{Getting started}

\noindent A printer is a value of type "\texttt{Eprinter.t a}" where
  "\texttt{a}" is the type of the item to be printed. When applied, a
  printer returns a string, representing the printed item.

\

\noindent To create a printer, one must use the function
  "\texttt{Eprinter.make}" with, as parameter, the name of the
  printer, (used in error messages). A printer is created empty,
  i.e. it fails if it is applied.

\

\noindent As with grammar entries, printers may have several levels. When the
  function "\texttt{Eprinter.apply}" is applied to a printer, the
  first level is called.  The function "\texttt{Eprinter.apply\_level}"
  allows to call a printer at some specific level possibly different
  from the first one. When a level does not match any value of the
  printed item, the next level is tested. If there is no more levels,
  the printer fails.

\

\noindent In semantic actions of printers, functions are provided to
  recursively call the current level and the next level. Moreover,
  a \emph{printing context} variable is also given, giving the
  current indentation, what should be printed before in the same line
  and what should be printed after in the same line (it is not
  mandatory to use them).

\

\noindent The extension of printers can be done with the
  "\texttt{EXTEND\_PRINTER}" statement added by the \emph{parsing
  kit} "\texttt{pa\_extprint.cmo}".

\section{Syntax of the EXTEND\_PRINTER statement}

\begin{verbatim}
        expression ::= extend-statement
  extend-statement ::= "EXTEND_PRINTER" extend-body "END"
       extend-body ::= extend-printers
   extend-printers ::= extend-printer extend-printers
                     | <nothing>
    extend-printer ::= printer-name ":" position-opt "[" levels "]"
      position-opt ::= "FIRST"
                     | "LAST"
                     | "BEFORE" label
                     | "AFTER" label
                     | "LEVEL" label
                     | <nothing>
            levels ::= level "|" levels
                     | level
             level ::= label-opt "[" rules "]"
         label-opt ::= label
                     | <nothing>
             rules ::= rule "|" rules
                     | rule
              rule ::= pattern "->" expression
                     | pattern "when" expression "->" expression
      printer-name ::= qualid
            qualid ::= qualid "." qualid
                     | uident
                     | lident
            uident ::= 'A'-'Z' ident
            lident ::= ('a'-'z' | '_' | misc-byte) ident
             ident ::= ident-char*
        ident-char ::= ('a'-'a' | 'A'-'Z' | '0'-'9' | '_' | ''' | misc-byte)
         misc-byte ::= '\128'-'\255'
\end{verbatim}

\section{Semantics of EXTEND\_PRINTER}

\subsection{Printers definition list}

\noindent All printers are extended according to their corresponding
  definitions which start with an optional "position" and follow with
  the "levels" definition.

\subsubsection{Optional position}

\noindent After the colon, it is possible to specify where to insert the
  defined levels:

\begin{itemize}
\item The identifier "\texttt{FIRST}" (resp. "\texttt{LAST}")
    indicates that the level must be inserted before (resp. after) all
    possibly existing levels of the entry. They become their first
    (resp. last) levels.
\item The identifier "\texttt{BEFORE}" (resp. "\texttt{AFTER}")
    followed by a level label (a string) indicates that the levels
    must be inserted before (resp. after) that level, if it exists. If
    it does not exist, the extend statement fails at run time.
\item The identifier "\texttt{LEVEL}" followed by a label indicates
    that the first level defined in the extend statement must be
    inserted at the given level, extending and modifying it. The other
    levels defined in the statement are inserted after this level, and
    before the possible levels following this level. If there is no
    level with this label, the extend statement fails at run
    time.
\item By default, if the entry has no level, the levels defined in the
    statement are inserted in the entry. Otherwise the first defined
    level is inserted at the first level of the entry, extending or
    modifying it. The other levels are inserted afterwards (before the
    possible second level which may previously exist in the entry).
\end{itemize}

\subsubsection{Levels}

\noindent After the optional "position", the \emph{level} list follow. The
  levels are separated by vertical bars, the whole list being between
  brackets.

\

\noindent A level starts with an optional label, which corresponds to its
  name. This label is useful to specify this level in case of future
  extensions, using the \emph{position} (see previous section) or
  for possible direct calls to this specific level.

\subsubsection{Rules}

\noindent A level is a list of \emph{rules} separated by vertical bars, the
  whole list being between brackets.

\

\noindent A rule is an usual pattern association (in a function or in the
  "match" statement), i.e. a pattern, an arrow and an expression. The
  expression is the semantic action which must be of type
  "\texttt{string}".

\subsection{Rules insertion}

\noindent The rules are sorted by their patterns, according to the rules of
  the extensible functions.

\subsection{Semantic action}

\noindent The semantic action, i.e. the expression following the right arrow
  in rules, contains in its environment the variables bound by the
  pattern and three more variables:

\begin{itemize}
\item The variable "\texttt{curr}" which is a function which can be
    called to recursively invoke the printer at the current
    level,
\item The variable "\texttt{next}" which is a function which can be
    called to invoke the printer at the next level,
\item The variable "\texttt{pc}" which contains the printing context
    of type "\texttt{Pprintf.pr\_context}" (see
    chapter Pprintf).
\end{itemize}

\noindent The variables "\texttt{curr}" and "\texttt{next}" are of type:

\begin{verbatim}
  pr_context -> t -> string
\end{verbatim}

\noindent where "\texttt{t}" is the type of the printer (i.e. the type of its
  patterns).

\

\noindent The variable "\texttt{curr}", "\texttt{next}" and "\texttt{pc}"
  have predefined names and can hide the possible identifiers having
  the same names in the pattern or in the environment of the
  "\texttt{EXTEND\_PRINTER}" statement.

\section{The Eprinter module}

\noindent See its section in the
  chapter "Library".

\section{Examples}

\subsection{Parser and Printer of expressions}

\noindent This example illustrates the symmetry between parsers and
  printers. A simple type of expressions is defined. A parser converts
  a string to a value of this type, and a printer converts a value of
  this type to a string.

\

\noindent In the printer, there is no use of the "\texttt{pc}" parameter and
  no use of the "\texttt{Pretty}" module. The strings are printed on
  a single line.

\

\noindent Here is the source (file "\texttt{foo.ml}"):

\begin{verbatim}
  #load "pa_extend.cmo";
  #load "pa_extprint.cmo";

  open Printf;

  type expr =
    [ Op of string and expr and expr
    | Int of int
    | Var of string ]
  ;

  value g = Grammar.gcreate (Plexer.gmake ());
  value pa_e = Grammar.Entry.create g "expr";
  value pr_e = Eprinter.make "expr";

  EXTEND
    pa_e:
      [ [ x = SELF; "+"; y = SELF -> Op "+" x y
        | x = SELF; "-"; y = SELF -> Op "-" x y ]
      | [ x = SELF; "*"; y = SELF -> Op "*" x y
        | x = SELF; "/"; y = SELF -> Op "/" x y ]
      | [ x = INT -> Int (int_of_string x)
        | x = LIDENT -> Var x
        | "("; x = SELF; ")" -> x ] ]
    ;
  END;

  EXTEND_PRINTER
    pr_e:
      [ [ Op "+" x y -> sprintf "\%s + \%s" (curr pc x) (next pc y)
        | Op "-" x y -> sprintf "\%s - \%s" (curr pc x) (next pc y) ]
      | [ Op "*" x y -> sprintf "\%s * \%s" (curr pc x) (next pc y)
        | Op "/" x y -> sprintf "\%s / \%s" (curr pc x) (next pc y) ]
      | [ Int x -> string_of_int x
        | Var x -> x
        | x -> sprintf "(\%s)" (Eprinter.apply pr_e pc x) ] ]
    ;
  END;

  value parse s = Grammar.Entry.parse pa_e (Stream.of_string s);
  value print e = Eprinter.apply pr_e Pprintf.empty_pc e;

  if Sys.interactive.val then ()
  else print_endline (print (parse Sys.argv.(1)));
\end{verbatim}

\noindent Remark on the use of "curr" and "next" while printing operators:
  due to left associativity, the first operand uses "curr" and the
  second operand uses "next". For right associativity operators, they
  should be inverted. For no associativity, both should use
  "next".

\

\noindent The last line of the file allows use in either the OCaml toplevel
  or as standalone program, taking the string to be printed as
  parameter. It can be compiled this way:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 gramlib.cma foo.ml
\end{verbatim}

\noindent Examples of use (notice the redundant parentheses automatically
  removed by the printing algorithm):

\begin{verbatim}
  $ ./a.out "(3 * x) + (2 / y)"
  3 * x + 2 / y
  $ ./a.out "(x+y)*(x-y)"
  (x + y) * (x - y)
  $ ./a.out "x + y - z"
  x + y - z
  $ ./a.out "(x + y) - z"
  x + y - z
  $ ./a.out "x + (y - z)"
  x + (y - z)
\end{verbatim}

\subsection{Printing OCaml programs}

\noindent Complete examples of usage of extensible printers are the printers
  in syntaxes and extended syntaxes provided by Camlp5 in the pretty
  printing \emph{kits}:

\begin{itemize}
\item \texttt{pr\_r.cmo}: pretty print in revised syntax
\item \texttt{pr\_o.cmo}: pretty print in normal syntax
\item \texttt{pr\_rp.cmo}: also pretty print the parsers in revised
    syntax
\item \texttt{pr\_op.cmo}: also pretty print the parsers in normal
    syntax
\end{itemize}

\noindent See the chapter entitled "Printing
  programs".

\clearemptydoublepage

\pagestyle{fancy}\chapter{Pprintf}

\noindent This chapter describes "pprintf", a statement to pretty print data.
  It looks like the "sprintf" function of the OCaml library, and
  borrows some ideas of the Format OCaml library. Another statement,
  "lprintf", is a slightly different version of "pprintf" handling
  with locations.


\section{Syntax of the pprintf statement}

\noindent The "pprintf" statement is added by the \emph{parsing kit}
"\texttt{pa\_pprintf.cmo}".</pp>

\noindent Notice that, in opposition to "printf", "fprintf", "sprintf", and
  all its variants, which are functions, this "pprintf" is a
  \emph{statement}, not a function: "pprintf" is a keyword and the
  expander analyzes its string format parameter to generate specific
  statements. In particular, it cannot be used alone and has no type
  by itself.

\begin{verbatim}
        expression ::= pprintf-statement
 pprintf-statement ::= "pprintf" qualid format expressions
            qualid ::= qualid "." qualid
                     | uident
                     | lident
            format ::= string
       expressions ::= expression expressions
                     | <nothing>
\end{verbatim}

\section{Semantics of pprintf}

\noindent The "pprintf" statement converts the format string into a string
  like the "sprintf" of the OCaml library "Printf" does (see the OCaml
  manual for details). The string format can accept new conversion
  specifications, "\%p" and "\%q", and some pretty printing annotations,
  starting with "@" like in the OCaml library "Format".

\

\noindent The "pprintf" statement takes as first parameter, a value of type
  "pr\_context" defined below. Its second parameter is the extended
  format string. It can take other parameters, depending on the
  format, like "sprintf".

\

\noindent The result of "pprintf" is always a string. There is no versions
  applying to files or buffers.

\

\noindent The strings built by "pprintf" are concatened by the function
  "Pretty.sprintf" (see the chapter entitled
  "Pretty Print") which controls the line
  length and prevents overflowing.

\subsection{Printing context}

\noindent The "pprintf" statement takes, as first parameter, a \emph{printing
  context}. It is a value of the following type:

\begin{verbatim}
  type pr_context =
    { ind : int;
      bef : string;
      aft : string;
      dang : string };
\end{verbatim}

\noindent The fields are:

\begin{itemize}
\item "\texttt{ind}" : the current indendation
\item "\texttt{bef}" : what should be printed before, in the same line
\item "\texttt{aft}" : what should be printed after, in the same line
\item "\texttt{dang}" : the dangling token to know whether parentheses
    are necessary
\end{itemize}

\noindent Basically, the "pprintf" statement concats the "bef" string, the
  formatted string and the "aft" string. The example:

\begin{verbatim}
  pprintf pc "hello world"
\end{verbatim}

\noindent is equivalent to (and indeed generates):

\begin{verbatim}
  Pretty.sprintf "\%shello world\%s" pc.bef pc.aft
\end{verbatim}

\noindent But if the format string contains conversion specifications "\%p" or
  "\%q", the "bef" and "aft" strings are actually transmitted to the
  corresponding functions:

\begin{verbatim}
  pprintf pc "hello \%p world" f x
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  f {(pc) with
     bef = Pretty.sprintf "\%shello " pc.bef;
     aft = Pretty.sprintf " world\%s" pc.aft}
    x
\end{verbatim}

\noindent Thus, the decision of including the "bef" and the "aft" strings are
  delayed to the called function, allowing this function to possibly
  concatenate "bef" and "aft" to its own strings.

\

\noindent A typical case is, while printing programs, when an expression
  needs to be printed between parentheses. The code which does that
  looks like:

\begin{verbatim}
  pprintf pc "(\%p)" expr e
\end{verbatim}

\noindent The right parenthesis of this string format is included in the
  "aft" string transmitted to the function "expr". In a situation when
  several right parentheses are concatened this way, the fact that all
  these parentheses are grouped together allows the function which
  eventually print them to decide to break the line or not, these
  parentheses being taken into account in the line length.

\

\noindent For example, if the code contains a print of an program containing
  an application whose source is:

\begin{verbatim}
  myfunction myarg
\end{verbatim}

\noindent and if the "aft" contains "))))))", the decision of printing in one
  line as:

\begin{verbatim}
  myfunction myarg))))))
\end{verbatim}

\noindent or in two lines as:

\begin{verbatim}
  myfunction
    myarg))))))
\end{verbatim}

\noindent is exact, the right parentheses being added to "myarg" to determine
  whether the line overflows or not.

\subsection{Extended format}

\noindent The extended format used by "pprintf" may contain any strings and
  conversion specifications allowed by the "sprintf" function (see
  module "Printf" of the OCaml library), plus:

\begin{itemize}
\item the conversion specifications: "\texttt{\%p}" and
    "\texttt{q}",
\item the pretty printing annotations introduced by, "\texttt{@}"
    and followed by:
\begin{itemize}
\item the character "\texttt{;}" (semicolon), optionally followed
        by "\texttt{<}", two numbers and "\texttt{>}",
\item the character "\texttt{\ }" (space),
\item the character "\texttt{[}", optionally followed by the character
        "\texttt{<}" and either:
\begin{itemize}
\item the character "\texttt{a}"
\item the character "\texttt{b}"
\item a number
\end{itemize}
        and the character "\texttt{>}", then followed by format
        string, and ended with "\texttt{@]}"
\end{itemize}

\end{itemize}

\noindent The format string is applied like in the "sprintf"
  function. Specific actions are done for the extended features. The
  result is a string like for the "sprintf" function. The "string
  before" and "string after" defined by the fields "bef" and "aft" of
  the printing context are taken into account and it is not necessary
  to add them in the format.

\

\noindent Example:

\begin{verbatim}
  pprintf pc "hello, world"
\end{verbatim}

\noindent generates:

\begin{verbatim}
  Pretty.sprintf "\%shello, world\%s" pc.bef pc.aft;
\end{verbatim}

\noindent An empty format:

\begin{verbatim}
  pprintf pc "";
\end{verbatim}

\noindent just prints the "before" and "after" strings:

\begin{verbatim}
  Pretty.sprintf "\%s\%s" pc.bef pc.aft;
\end{verbatim}

\subsection{Line length}

\noindent The function "pprintf" uses the Camlp5 "Pretty" module. The line
  length can be set by changing the value of the reference
  "Pretty.line\_length".

\subsection{The conversion specifications "p" and "q"}

\noindent The "\%p" conversion specification works like the "\%a" of the printf
  statement. It takes two arguments and applies the first one to the
  printing context and to the second argument. The first argument must
  therefore have type "\texttt{pr\_context -> t -> unit}" (for some
  type "\texttt{t}") and the second one "t".

\

\noindent Notice that this function can be called twice: one to test whether
  the resulting string holds in the line, and another one to possibly
  recall this function to print it in several lines. In the two cases,
  the printing context given as parameter is different.

\

\noindent It uses the functions defined in the
  "Pretty" module.

\noindent Example: the following statement:

\begin{verbatim}
  pprintf pc "hello, \%p, world" f x
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  f {(pc) with
     bef = Pretty.sprintf "\%shello, " pc.bef;
     aft = Pretty.sprintf ", world\%s" pc.aft}
    x
\end{verbatim}

\noindent The "\%q" conversion specification is like "\%p" except that it takes
  a third argument which is the value of the "dang" field, useful when
  the syntax has "dangling" problems requiring parentheses. See
  chapter Extensions of printing for more
  explanations about dangling problems.

\

\noindent The same example with "\%q":

\begin{verbatim}
  pprintf pc "hello, \%q, world" f x "abc"
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  f {(pc) with
     bef = Pretty.sprintf "\%shello, " pc.bef;
     aft = Pretty.sprintf ", world\%s" pc.aft;
     dang = "abc"}
    x
\end{verbatim}

\subsection{The pretty printing annotations}

\subsubsection{Breaks}

\noindent The pretty printing annotations allow to indicate places where
  lines can be broken. They all start with the "at" sign "@". The main
  ones are called \emph{breaks} and are:<p>

\begin{itemize}
\item "\texttt{@;}" specifying: \emph{write a space or 'a newline and an
      indentation incremented by 2 spaces'}
\item "\texttt{@\ }" specifying: \emph{write a space or 'a newline
      and the indentation'}
\end{itemize}

\noindent Example - where "pc" is a variable of type "pr\_context" (for
  example "Pprintf.empty\_pc"):

\begin{verbatim}
  pprintf pc "hello,@;world"
\end{verbatim}

\noindent builds the string, if it holds in the line:

\begin{verbatim}
  hello, world
\end{verbatim}

\noindent and if it does not:

\begin{verbatim}
  hello,
    world
\end{verbatim}

\noindent The second form:

\begin{verbatim}
  pprintf pc "hello,@ world"
\end{verbatim}

\noindent is printed the same way, if it holds in the line, and if it does
  not, as:

\begin{verbatim}
  hello,
  world
\end{verbatim}

\noindent The general form is:

\begin{itemize}
\item "\texttt{@;<s o>}", which is a break with "\texttt{s}" spaces
    if the string holds in the line, or an indentation offset
    (incrementation of the indentation) of "\texttt{o}" spaces if the
    string does not hold in the line.
\end{itemize}

\noindent The break "\texttt{@;}" is therefore equivalent to "\texttt{@;<1
  2>}" and "\texttt{@\ }" is equivalent to "\texttt{@;<1
  0>}".

\subsubsection{Parentheses}

\noindent A second form of the pretty printing annotations is the
  parenthesization of format strings possibly containing other pretty
  printing annotations. They start with "\texttt{@[}" and end with
  "\texttt{@]}".

\

\noindent It allows to change the associativity of the breaks. For example:

\begin{verbatim}
  pprintf pc "@[the quick brown fox@;jumps@]@;over the lazy dog"
\end{verbatim}

\noindent If the whole string holds on the line, it is printed:

\begin{verbatim}
  the quick brown fox jumps over the lazy dog
\end{verbatim}

\noindent If the whole string does not hold on the line, but "the quick brow
  fox jumps" does, it is printed:

\begin{verbatim}
  the quick brown fox jumps
    over the lazy dog
\end{verbatim}

\noindent If the string "the quick brown fox jumps" does not hold on the line,
  the whole string is printed:

\begin{verbatim}
  the quick brown fox
    jumps
    over the lazy dog
\end{verbatim}

\noindent Conversely, if the code is right associated:

\begin{verbatim}
  pprintf pc "the quick brown fox@;@[jumps@;over the lazy dog@]"
\end{verbatim}

\noindent It can be printed:

\begin{verbatim}
  the quick brown fox jumps over the lazy dog
\end{verbatim}

\noindent or:

\begin{verbatim}
  the quick brown fox
    jumps over the lazy dog
\end{verbatim}

\noindent or:

\begin{verbatim}
  the quick brown fox
    jumps
      over the lazy dog
\end{verbatim}

\noindent The default is left associativity: without parentheses, it is
  printed like in the first example.

\subsubsection{Incrementation of indentation}

\noindent The open parenthesis of the parenthesized form, "\texttt{@[}" can
  be followed by "\texttt{<n>}" where "\texttt{n}" is a number. It
  increments the current indentation (for possible newlines in the
  parenthesized text) with this number.

\

\noindent Example:

\begin{verbatim}
  pprintf pc "@[<4>Incrementation@;actually of six characters@]"
\end{verbatim}

\noindent makes the string (if not holding in the line):

\begin{verbatim}
  Incrementation
        actually of six characters
\end{verbatim}

\subsubsection{Break all or nothing}

\noindent The open parenthesis of the parenthesized form, "\texttt{@[}" can
  be followed by "\texttt{<a>}". It specifies that if the string
  does not hold in the line, all breaks between the parentheses (at
  one only level) are printed in two lines, even if sub-strings could
  hold on the line. For example:

\begin{verbatim}
  pprintf pc "@[<a>the quick brown fox@;jumps@;over the lazy dog@]"
\end{verbatim}

\noindent can be printed only as:

\begin{verbatim}
  the quick brown fox jumps over the lazy dog
\end{verbatim}

\noindent or as:

\begin{verbatim}
  the quick brown fox
    jumps
    over the lazy dog
\end{verbatim}

\subsubsection{Break all}

\noindent The open parenthesis of the parenthesized form, "\texttt{@[}" can
  be followed by "\texttt{<b>}". It specifies that all breaks are
  always printed in two lines. For example:

\begin{verbatim}
  pprintf pc "@[<b>the quick brown fox@;jumps@;over the lazy dog@]"
\end{verbatim}

\noindent is printed in all circumstances:

\begin{verbatim}
  the quick brown fox
    jumps
    over the lazy dog
\end{verbatim}

\subsubsection{Break all if}

\noindent The open parenthesis of the parenthesized form, "\texttt{@[}" can
  be followed by "\texttt{<i>}". Depending on the value of the
  boolean variable of the argument list, the breaks are all printed
  in two lines like with the "break all" option above, or not.
  For example:

\begin{verbatim}
  pprintf pc "\%s@;@[<i>\%s,@;\%s@]" "good" True "morning" "everybody";
  pprintf pc "\%s@;@[<i>\%s,@;\%s@]" "good" False "morning" "everybody";
\end{verbatim}

\noindent are printed:

\begin{verbatim}
  good
    morning,
      everybody
  good morning, everybody
\end{verbatim}

\subsubsection{Parentheses not neighbours of breaks}

\noindent In the examples above, we can remark that the left parentheses are
  always the begin of the string or are preceeded by a break, and that
  the right parentheses are always the end of the string or followed
  by a break.

\

\noindent When the parentheses "\texttt{@[}" and "\texttt{@]}" are not
  preceeded or followed by the string begin nor end, nor preceeded or
  followed by breaks, they are considered as the "bef" or "aft" part
  of the neighbour string. For example, the following forms:

\begin{verbatim}
  pprintf pc "the quick brown fox@[ jumps over@]"
\end{verbatim}

\noindent and:

\begin{verbatim}
  pprintf pc "@[the quick brown fox @]jumps over"
\end{verbatim}

\noindent are respectively equivalent to:

\begin{verbatim}
  let pc = {(pc) with aft = sprintf " jumps over\%s" pc.aft} in
  Pretty.sprintf "\%sthe quick brown fox\%s" pc.bef pc.aft
\end{verbatim}

\noindent and:

\begin{verbatim}
  let pc = {(pc) with bef = sprintf "\%sthe quick brown fox" pc.bef} in
  Pretty.sprintf "\%sjumps over\%s" pc.bef pc.aft
\end{verbatim}

\noindent In these examples, the results are identical, but it can be
  important if the non-parenthesized part contain one or several
  "\%p". In this case, the corresponding function receives the "bef" or
  "aft" part in its pr\_context variable and can take it into account
  when printing its data.

\subsection{Lprintf}

\noindent "Lprintf" is like "pprintf" with the same parameters. It is equivalent
  to an call to the function "expand\_lprintf":

\begin{verbatim}
   lprintf pc "..."
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
   expand_lprintf pc loc (fun pc -< pprintf pc "...")
\end{verbatim}

\noindent The function "expand\_lprintf" and the variable "loc" must be
  defined by the user in the environment where "lprintf" is used.

\

\noindent "Lprintf" is used in predefined printers "pr\_r.ml" and "pr\_o.ml" to
  allow optional insertions of location comments in the output.

\section{Comparison with the OCaml modules Printf and Format}

\subsection{Pprintf and Printf}

\noindent The statement "pprintf" acts like the function
  "Printf.sprintf". But since it requires this extra parameter of type
  "pr\_context" and needs the "\%p" and "\%q" conversions specifications
  (which do not exist in "Printf"), it was not possible to use the
  "Printf" machinery directly and a new statement had to be added.

\

\noindent The principle of "pprintf" and "sprintf" are the same. However,
  "pprintf" is a syntax extension and has no type by itself. It cannot
  be used alone or without all its required parameters.

\subsection{Pprintf and Format}

\noindent The pretty printing annotations look like the ones of the OCaml
  module Format. Actually, they have different semantics. They do not
  use \emph{boxes} like "Format" does. In "pprintf" statement, the
  machinery acts only on indentations.

\

\noindent Notice that, with "pprintf", it is always possible to know the
  current indentation (it is the field "ind" of the "pr\_context"
  variable) and it is therefore possible to take decisions before
  printing.

\

\noindent For example, it is possible, in a printer of OCaml statements, to
  decide to print all match cases symmetrically, i.e. all with one
  line for each case or all with newlines after the patterns.

\

\noindent It is what is done in the option "\texttt{-flag E}" added by the
  pretty printing kits "pr\_r.cmo" (pretty print in revised syntax) and
  "pr\_o.cmo" (pretty print in normal syntax). See
  chapter Commands and Files or type
  "\texttt{camlp5 pr\_r.cmo -help}" or "\texttt{camlp5 pr\_o.cmo
  -help}".

\

\noindent Another difference is that the internal behaviour of this printing
  system is accessible, and it is always possible to use the basic
  functions of the "Pretty" module ("horiz\_vertic" and "sprintf") if
  the behaviour of "pprintf" is not what is desired by the
  programmer.

\section{Relation with the Camlp5 extensible printers}

\noindent The extensible printers of Camlp5 (see its
  corresponding chapter) use the type
  "\texttt{pr\_context}" of "pprintf". It is therefore possible to use
  "pprintf" in the semantic actions of the extensible printers.  But
  it is not mandatory. An extensible printer can just use the "Pretty"
  module or even neither "pprintf" nor "Pretty".

\

\noindent The printing kits "\texttt{pr\_r.ml}" and "\texttt{pr\_o.ml}"
  (respectively pretty print in revised and in normal syntax) and some
  other related to them, are examples of usage of the "pprintf"
  statement.

\section{The Pprintf module}

\noindent See its section in the
  chapter "Library".

\clearemptydoublepage

\pagestyle{fancy}\chapter{Pretty print}

\noindent A pretty print system is provided in the library module Pretty. It
  allows one to pretty print data or programs. The Pretty module
  contains:

\begin{itemize}
\item The function "horiz\_vertic" to specify how data must be printed.
\item The function "sprintf" to format strings.
\item The variable "line\_length" which is a reference specifying the
    maximum lines lengths.
\end{itemize}


\section{Module description}

\subsection{horiz\_vertic}

\noindent The function "horiz\_vertic" takes two functions as parameters. When
  invoked, it calls its first function. If that function fails with
  some specific internal error (that the function "\texttt{sprintf}"
  below may raise), the second function is called.

\

\noindent The type of "horiz\_vertic" is:

\begin{verbatim}
  (unit -> 'a) -> (unit -> 'a) -> 'a
\end{verbatim}

\subsubsection{the horizontal function}

\noindent The first function is said to be the "horizontal" function. It
  tries to pretty print the data on a single line. In the context of
  this function, if the strings built by the function "sprintf" (see
  below) contain newlines or have lengths greater than "line\_length",
  the function fails (with a internal exception local to the
  module).

\subsubsection{the vertical function}

\noindent In case of failure of the "horizontal function", the second
  function of "horiz\_vertic", the "vertical" function, is called. In
  the context of that function, the "sprintf" function behaves like
  the normal "sprintf" function of the OCaml library module
  "Printf".

\subsection{sprintf}

\noindent The function "sprintf" works like its equivalent in the module
  "Printf" of the OCaml library, and takes the same parameters. Its
  difference is that if it is called in the context of the first
  function (the "horizontal" function) of the function "horiz\_vertic"
  (above), all strings built by "sprintf" are checked for newlines or
  length greater than the maximum line length. If either occurs, the
  "sprintf" function fails and the horizontal function fails.

\

\noindent If "sprintf" is not in the context of the horizontal function, it
  behaves like the usual "sprintf" function.

\subsection{line\_length}

\noindent The variable "line\_length" is a reference holding the maximum line
  length of lines printed horizontally. Its default is 78. This can be
  changed by the user before using "horiz\_vertic".

\subsection{horizontally}

\noindent The call "\texttt{horizontally ()}" returns a boolean telling whether
  the context is horizontal.

\section{Example}

\noindent Suppose you want to pretty print the XML code
  \texttt{"<li>something</li>"}. If the "something" is
  short, you want to see:

\begin{verbatim}
  <li>something</li>
\end{verbatim}

\noindent If the "something" has several lines, you want to see that:

\begin{verbatim}
  <li>
    something
  </li>
\end{verbatim}

\noindent A possible implementation is:

\begin{verbatim}
  open Pretty;
  horiz_vertic
    (fun () -> sprintf "<li>something</li>")
    (fun () -> sprintf "<li>\n  something\n</li>");
\end{verbatim}

\noindent Notice that the "\texttt{sprintf}" above is the one of the
  library Pretty.

\

\noindent Notice also that, in a program displaying XML code, this
  "something" may contain other XML tags, and is therefore generally
  the result of other pretty printing functions, and the program
  should rather look like:

\begin{verbatim}
  horiz_vertic
    (fun () -> sprintf "<li>\%s</li>" (print something))
    (fun () -> sprintf "<li>\n  \%s\n</li>" (print something))
\end{verbatim}

\noindent Parts of this "something" can be printed horizontally and other
  vertically using other calls to "horiz\_vertic" in the user function
  "print" above. But it is important to remark that if they are called
  in the context of the first function parameter of "horiz\_vertic"
  above, only horizontal functions are accepted: the first failing
  "horizontal" function triggers the failure of the horizontal pretty
  printing.

\section{Programming with Pretty}

\subsection{Hints}

\noindent Just start with a call to "horiz\_vertic".

\

\noindent As its first function, use "sprintf" just to concat the strings
  without putting any newlines or indentations, e.g. just using spaces
  to separate pieces of data.

\

\noindent As its second function, consider how you want your data to be cut.
  At the cutting point or points, add newlines. Notice that you
  probably need to give the current indentation string as parameter of
  the called functions because they need to be taken into account in
  the called "horizontal" functions.

\

\noindent In the example below, don't put the indentation in the sprintf
  function but give it as parameter of your "print" function:

\begin{verbatim}
  horiz_vertic
    (fun () -> sprintf "<li>\%s</li>" (print "" something))
    (fun () -> sprintf "<li>\n\%s\n</li>" (print "  " something))
\end{verbatim}

\noindent Now, the "print" function could look like, supposing you print
  other things with "other" of the current indentation and "things"
  with a new shifted one:

\begin{verbatim}
  value print ind something =
    horiz_vertic
      (fun () -> sprintf "\%sother things..." ind)
      (fun () -> sprintf "\%sother\n\%s  things..." ind ind);
\end{verbatim}

\noindent Supposing than "other" and "things" are the result of two other
  functions "print\_other" and "print\_things", your program could look
  like:

\begin{verbatim}
  value print ind (x, y) =
    horiz_vertic
      (fun () -> sprintf "\%s\%s \%s" ind (print_other 0 x) (print_things 0 y))
      (fun () -> sprintf "\%s\n\%s" (print_other ind x) (print_things (ind ^ "  ") y));
\end{verbatim}

\subsection{How to cancel a horizontal print}

\noindent If you want to prevent a pretty printing function from being called
  in a horizontal context, constraining the pretty print to be on
  several lines in the calling function, just do:

\begin{verbatim}
  horiz_vertic
    (fun () -> sprintf "\n")
    (fun () -> ... (* your normal pretty print *))
\end{verbatim}

\noindent In this case, the horizontal print always fails, due to the newline
  character in the sprintf format.

\section{Remarks}

\subsection{Kernel}

\noindent The module "Pretty" is intended to be basic, a "kernel" module to
  pretty print data. It presumes that the user takes care of the
  indentation. Programs using "Pretty" are not as short as the ones
  using "Format" of the OCaml library, but are more flexible. To
  pretty print with a shorter syntax like in the OCaml module "Format"
  (with the "@" convention), see statement
  "pprintf" (which internally uses the
  module "Pretty").

\subsection{Strings vs Channels}

\noindent In "Pretty", the pretty printing is done only on strings, not on
  files. To pretty print files, just build the strings and print them
  afterwards with the usual output functions. Notice that OCaml
  allocates and frees strings quickly, and if pretty printed values
  are not huge, which is generally the case, it is not a real problem,
  memory sizes these days being more than enough for this job.

\subsection{Strings or other types}

\noindent The "horiz\_vertic" function can return values of types other than
  "string". For example, if you are interested only in the result of
  horizontal context and not on the vertical one, it is perfectly
  correct to write:

\begin{verbatim}
  horiz_vertic
    (fun () -> Some (sprintf "I hold on a single line")
    (fun () -> None)
\end{verbatim}

\subsection{Why raising exceptions ?}

\noindent One could ask why this pretty print system raises internal
  exceptions. Why not simply write the pretty printing program like
  this:

\begin{enumerate}
\item first build the data horizontally (without newlines)
\item if the string length is lower than the maximum line length,
    return it
\item if not, build the string by adding newlines in the specific
    places
\end{enumerate}

\noindent This method works but is generally very slow (exponential in time)
  because while printing horizontally, many useless strings are
  built. If, for example, the final printed data holds on 50 lines,
  tens of lines may be built uselessly again and again before the
  overflowing is corrected.

\clearemptydoublepage
\part{Language extensions}
\clearemptydoublepage

\pagestyle{fancy}\chapter{Locations}

\noindent The location is a concept often used in Camlp5, bound to where
  errors occur in the source. The basic type is "\texttt{Ploc.t}"
  which is an abstract type.


\section{Definitions}

\noindent Internally a location is a pair of source \emph{positions}: the
  beginning and the end of an element in the source (file or
  interactive).  A located element can be a character (the end is just
  the beginning plus one), a token, or a longer sequence generally
  corresponding to a grammar rule.

\

\noindent A \emph{position} is a count of characters since the beginning of
  the file, starting at zero. When a couple of positions define a
  location, the first position is the position of the first character
  of the element, and the last position is the first
  character \emph{not} part of the element. The location length is
  the difference between those two numbers. Notice that the position
  corresponds exactly to the character count in the streams of
  characters.

\

\noindent In the extensible grammars, a variable
  with the specific name "\texttt{loc}" is predefined in all semantic
  actions: it is the location of the associated rule. Since
  the syntax tree quotations generate nodes
  with "\texttt{loc}" as location part, this allow to generate
  grammars without having to consider source locations.

\

\noindent It is possible to change the name "\texttt{loc}" to another name,
  through the parameter "\texttt{-loc}" of the Camlp5 commands.

\

\noindent Remark: the reason why the type "\texttt{location}" is abstract is
  that in future versions, it may contain other informations, such as
  the associated comments, the type (for expressions nodes), things
  like that, without having to change the already written
  programs.

\section{Building locations}

\noindent Tools are provided in the module "\texttt{Ploc}" to manage
  locations.

\

\noindent First, "\texttt{Ploc.dummy}" is a dummy location used when the
  element does not correspond to any source, or if the programmer does
  not want to worry about locations.

\

\noindent The function "\texttt{Ploc.make}" builds a location from three
  parameters:

\begin{itemize}
\item the line number, starting at 1
\item the position of the first column of the line
\item a couple of positions of the location: the first one belonging
    to the given line, the second one being able to belong to another
    line, further.
\end{itemize}

\noindent If the line number is not known, it is possible to use the function
  "\texttt{Ploc.make\_unlined}" taking only the couple of positions of
  the location. In this case, error messages may indicate the first
  line and a big count of characters from this line (actually from the
  beginning of the file). With a good text editor, it is possible, to
  find the good location, anyway.

\

\noindent If the location is built with "\texttt{Ploc.make\_unlined}", and if
  your program displays a source location itself, it is possible to
  use the function "\texttt{Ploc.from\_file}" which takes the file
  name and the location as parameters and return, by reading that
  file, the line number, and the character positions of the
  location.

\section{Raising with a location}

\noindent The function "\texttt{Ploc.raise}" allows one to raise an exception
  together with a location. All exceptions raised in
  the extensible grammars use
  "\texttt{Ploc.raise}". The raised exception is "\texttt{Ploc.Exc}"
  with two parameters: the location and the exception itself.

\

\noindent Notice that "\texttt{Ploc.raise}" just reraises the exception
  if it is already the exception "\texttt{Ploc.Exc}", ignoring then
  the new given location.

\

\noindent A paradigm to print exceptions possibly enclosed by
  "\texttt{Ploc.Exc}" is to write the "\texttt{try..with}" statement
  like this:

\begin{verbatim}
  try ... with exn ->
    let exn =
      match exn with
      [ Ploc.Exc loc exn -> do { ... print the location ...; exn }
      | _ -> exn ]
    in
    match exn with
    ...print the exception which is *not* located...
\end{verbatim}

\section{Other functions}

\noindent Some other functions are provided:

\begin{description}
\item[\texttt{Ploc.first\_pos}]

\

returns the first position (an integer) of the location.
\item[\texttt{Ploc.last\_pos}]

\

returns the last position (an integer) of the location (position
    of the first character not belonging to the element.
\item[\texttt{Ploc.line\_nb}]

\

returns the line number of the location or \texttt{-1} if the
    location does not contain a line number (i.e. built by
    "\texttt{Ploc.make\_unlined}").
\item[\texttt{Ploc.bol\_pos}]

\

returns the position of the beginning of the line of the
    location. It is zero if the location does not contain a line
    number (i.e. built by "\texttt{Ploc.make\_unlined}").
\end{description}

\noindent And still other ones used in Camlp5 sources:

\begin{description}
\item[\texttt{Ploc.encl}]

\

"\texttt{Ploc.encl loc1 loc2}" returns the location starting at
    the smallest begin of "\texttt{loc1}" and "\texttt{loc2}" and
    ending at their greatest end.. In simple words, it is the location
    enclosing "\texttt{loc1}" and "\texttt{loc2}" and all what is
    between them.
\item[\texttt{Ploc.shift}]

\

"\texttt{Ploc.shift sh loc}" returns the location "\texttt{loc}"
    shifted with "\texttt{sh}" characters. The line number is not
    recomputed.
\item[\texttt{Ploc.sub}]

\

"\texttt{Ploc.sub loc sh len}" is the location "\texttt{loc}"
    shifted with "\texttt{sh}" characters and with length
    "\texttt{len}". The previous ending position of the location is
    lost.
\item["\texttt{Ploc.after}"]

\

"\texttt{Ploc.after loc sh len}" is the location just after
    "\texttt{loc}" (i.e. starting at the end position of
    "\texttt{loc}"), shifted with "\texttt{sh}" characters, and of
    length "\texttt{len}".
\end{description}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Syntax tree}

\noindent In Camlp5, one often uses syntax trees. For example, in grammars of
  the language (semantic actions), in pretty printing (as patterns),
  in optimizing syntax code (typically stream parsers). Syntax trees
  are mainly defined by sum types, one for each kind of tree:
  "\texttt{expr}" for expressions, "\texttt{patt}" for patterns,
  "\texttt{ctyp}" for types, "\texttt{str\_item}" for structure items,
  and so on. Each node corresponds to a possible value of this
  type.


\section{Transitional and Strict modes}

\noindent Since version 5.00 of Camlp5, the definition of the syntax tree has
  been different according to the mode Camlp5 has been installed:

\begin{itemize}
\item In \emph{transitional} mode,
    this definition is the same than in the previous Camlp5
    versions.
\item In \emph{strict} mode, many
    constructor parameters have a type enclosed by the predefined type
    "\texttt{Ploc.vala}".
\end{itemize}

\noindent The advantage of the transitional mode is that the abstract syntax
  tree is fully compatible with previous versions of Camlp5. Its
  drawback is that when using the syntax tree
  quotations in user syntax, it is not possible to use
  antiquotations, a significatant limitation.

\

\noindent In strict mode, the abstract syntax is not compatible with versions
  of Camlp5 previous to 5.00. Most of the parameters of the
  constructor are enclosed with the type "\texttt{Ploc.vala}" whose
  aim is to allow nodes to be either of the type argument, or an
  antiquotation. In this mode, the syntax tree quotations in user
  syntax can be used, with the same power of the previous syntax tree
  quotations provided by Camlp5.

\section{Compatibility}

\noindent As there is a problem of compatibility in strict mode, a good
  solution, for the programmer, is to always use syntax trees using
  quotations, which is backward compatible. See the chapter
  about syntax tree in strict mode.

\

\noindent For example, if the program made a value of the syntax tree of the
  "let" statement, like this:

\begin{verbatim}
  ExLet loc rf pel e
\end{verbatim}

\noindent In strict mode, to be equivalent, this expression should be
  rewritten like this:

\begin{verbatim}
  ExLet loc (Ploc.VaVal rf) (Ploc.VaVal pel) e
\end{verbatim}

\noindent where "\texttt{Ploc.VaVal}" is a value of the type "\texttt{vala}"
  defined in the module Ploc (see its
  section "pervasives").

\

\noindent This necessary conversion is a drawback if the programmer wants
  that his programs remain compilable with previous versions of
  Camlp5.

\

\noindent The recommended solution is to always write this code with
  quotations, namely, in this example, like this:

\begin{verbatim}
  <:expr< let $flag:rf$ $list:pel$ in $e$ >>
\end{verbatim}

\noindent The quotation expanders ensure that, in strict mode, the variable
  "rf" is still of type "\texttt{bool}", and that the variable "pel"
  of type "\texttt{list (patt * expr)}", by enclosing them around
  "\texttt{Ploc.VaVal}".

\

\noindent In transitional mode, it is equivalent to the first form above.  In
  strict mode, it is equivalent to the second form. And the previous
  versions of Camlp5 also recognizes this form.

\section{Two quotations expanders}

\noindent Camlp5 provides two quotations expanders of syntax trees:
  "\texttt{q\_MLast.cmo}" and "\texttt{q\_ast.cmo}".

\

\noindent Both allow writing syntax trees in concrete syntax as explained in
  the previous section.

\

\noindent The first one, "\texttt{q\_MLast.cmo}" requires that the contents of
  the quotation be in revised syntax
  without any syntax extension (even the stream
  parsers). It works in transitional and in strict modes.

\

\noindent The second one, "\texttt{q\_ast.cmo}" requires that the contents of
  the quotation be in the current user syntax (normal, revised, lisp,
  scheme, or other) and can accept all the syntax extensions he added
  to compile his program. It fully works only in strict mode. In
  transitional mode, the antiquotations are not available.

\section{Syntax tree and Quotations in the two modes}

\noindent For the detail of the syntax tree and the quotations forms, see the
  chapters about the syntax tree in
  transitional mode and the syntax tree
  in strict mode.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Syntax tree - transitional mode}

\noindent This chapter presents the Camlp5 syntax tree when Camlp5 is installed
  in \emph{transitional} mode.


\section{Introduction}

\noindent This syntax tree is defined in the module "\texttt{MLast}" provided
  by Camlp5. Each node corresponds to a syntactic entity of the
  corresponding type.

\

\noindent For example, the syntax tree of the statement "\texttt{if}" can
  be written:

\begin{verbatim}
  MLast.ExIfe loc e1 e2 e3
\end{verbatim}

\noindent where "\texttt{loc}" is the location in the source, and
  "\texttt{e1}", "\texttt{e2}" and "\texttt{e3}" are
  respectively the expression after the "\texttt{if}", the one after
  the "\texttt{then}" and the one after the "\texttt{else}".

\

\noindent If a program needs to manipulate syntax trees, it can use the nodes
  defined in the module "\texttt{MLast}". The programmer must know how
  the concrete syntax is transformed into this abstract syntax.

\

\noindent A simpler solution is to use one of the quotation kit
  "\texttt{q\_MLast.cmo}". It
  proposes quotations which represent the
  abstract syntax (the nodes of the module "\texttt{MLast}") into
  concrete syntax with antiquotations to bind variables inside. The
  example above can be written:

\begin{verbatim}
  <:expr< if $e1$ then $e2$ else $e3$ >>
\end{verbatim}

\noindent This representation is very interesting when one wants to
  manipulate complicated syntax trees. Here is an example taken from
  the Camlp5 sources themselves:

\begin{verbatim}
  <:expr<
    match try Some $f$ with [ Stream.Failure -> None ] with
    [ Some $p$ -> $e$
    | _ -> raise (Stream.Error $e2$) ]
  >>
\end{verbatim}

\noindent This example was in a position of a pattern. In abstract syntax, it
  should have been written:

\begin{verbatim}
  MLast.ExMat _
    (MLast.ExTry _ (MLast.ExApp _ (MLast.ExUid _ "Some") f)
       [(MLast.PaAcc _ (MLast.PaUid _ "Stream") (MLast.PaUid _ "Failure"),
         None, MLast.ExUid _ "None")])
    [(MLast.PaApp _ (MLast.PaUid _ "Some") p, None, e);
     (MLast.PaAny _, None,
      MLast.ExApp _ (MLast.ExLid _ "raise")
        (MLast.ExApp _
           (MLast.ExAcc _ (MLast.ExUid _ "Stream") (MLast.ExUid _ "Error"))
           e2))]
\end{verbatim}

\noindent Which is less readable and much more complicated to build and
  update.

\

\noindent Instead of thinking of "a syntax tree", the programmer can think of
  "a piece of program".

\section{Location}

\noindent In all syntax tree nodes, the first parameter is the source
  location of the node.

\subsection{In expressions}

\noindent When a quotation is in the context of an expression, the location
  parameter is "\texttt{loc}" in the node and in all its possible
  sub-nodes. Example: if we consider the quotation:

\begin{verbatim}
  <:sig_item< value foo : int -> bool >>
\end{verbatim}

\noindent This quotation, in a context of an expression, is equivalent
  to:

\begin{verbatim}
  MLast.SgVal loc "foo"
    (MLast.TyArr loc (MLast.TyLid loc "int") (MLast.TyLid loc "bool"));
\end{verbatim}

\noindent The name "\texttt{loc}" is predefined. However, it is possible to
  change it, using the argument "\texttt{-loc}" of the Camlp5 shell
  commands.

\

\noindent Consequently, if there is no variable "\texttt{loc}" defined in the
  context of the quotation, or if it is not of the correct type, a
  semantic error occur in the OCaml compiler ("Unbound value
  loc").

\

\noindent Note that in the extensible grammars,
  the variable "\texttt{loc}" is bound, in all semantic actions, to
  the location of the rule.

\

\noindent If the created node has no location, the programmer can define a
  variable named "\texttt{loc}" equal to "\texttt{Ploc.dummy}".

\subsection{In patterns}

\noindent When a quotation is in the context of a pattern, the location
  parameter of all nodes and possible sub-nodes is set to the wildcard
  ("\texttt{\_}"). The same example above:

\begin{verbatim}
  <:sig_item< value foo : int -> bool >>
\end{verbatim}

\noindent is equivalent, in a pattern, to:

\begin{verbatim}
  MLast.SgVal _ "foo"
    (MLast.TyArr _ (MLast.TyLid _ "int") (MLast.TyLid _ "bool"))
\end{verbatim}

\noindent However, it is possible to generate a binding of the variable
  "\texttt{loc}" on the top node by writing a "colon" before the
  "less" in the quotation. The same example:

\begin{verbatim}
  <:sig_item:< value foo : int -> bool >>
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  MLast.SgVal loc "foo"
    (MLast.TyArr _ (MLast.TyLid _ "int") (MLast.TyLid _ "bool"))
\end{verbatim}

\section{Antiquotations}

\noindent The expressions or patterns between dollar (\$) characters are
  called \emph{antiquotations}. In opposition to quotations which
  has its own syntax rules, the antiquotation is an area in the syntax
  of the enclosing context (expression or pattern). See the chapter
  about quotations.

\

\noindent If a quotation is in the context of an expression, the
  antiquotation must be an expression. It can be any expression,
  including function calls. Examples:

\begin{verbatim}
  value f e el = <:expr< [$e$ :: $loop False el$] >>;
  value patt_list p pl = <:patt< ( $list:[p::pl]$) >>;
\end{verbatim}

\noindent If a quotation is in the context of an pattern, the antiquotation
  is a pattern. Any pattern is possible, including the wildcard
  character ("\texttt{\_}"). Examples:

\begin{verbatim}
   fun [ <:expr< $lid:op$ $_$ $_$ >> -> op ]
   match p with [ <:patt< $_$ | $_$ >> -> Some p ]
\end{verbatim}

\section{Nodes and Quotations}

\noindent This section describes all nodes defined in the module "MLast" of
  Camlp5 and how to write them with quotations. Notice that, inside
  quotations, one is not restricted to these elementary cases, but
  any complex value can be used, resulting on possibly complex combined
  nodes.

\

\noindent Variables names give information of their types:

\begin{itemize}
\item \texttt{e}, \texttt{e1}, \texttt{e2}, \texttt{e3}: expr
\item \texttt{p}, \texttt{p1}, \texttt{p2}, \texttt{p3}: patt
\item \texttt{t}, \texttt{t1}, \texttt{t2}, \texttt{e3}: ctyp
\item \texttt{s}: string
\item \texttt{b}: bool
\item \texttt{me}, \texttt{me1}, \texttt{me2}: module\_expr
\item \texttt{mt}, \texttt{mt1}, \texttt{mt2}: module\_type
\item \texttt{le}: list expr
\item \texttt{lp}: list patt
\item \texttt{lt}: list ctyp
\item \texttt{ls}: list string
\item \texttt{lse}: list (string * expr)
\item \texttt{lpe}: list (patt * expr)
\item \texttt{lpp}: list (patt * patt)
\item \texttt{lpee}: list (patt * option expr * expr)
\item \texttt{op}: option patt
\item \texttt{lcsi}: list class\_str\_item
\item \texttt{lcsi}: list class\_sig\_item
\end{itemize}

\subsection{expr}

\noindent Expressions of the language.

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:expr< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{ExAcc loc e1 e2}} & {\texttt{\$e1\$ . \$e2\$}} & {access} \\
{\texttt{ExAnt loc e}} & {\texttt{\$anti:e\$}} & {antiquotation (1)} \\
{\texttt{ExApp loc e1 e2}} & {\texttt{\$e1\$ \$e2\$}} & {application} \\
{\texttt{ExAre loc e1 e2}} & {\texttt{\$e1\$ .( \$e2\$ )}} & {array element} \\
{\texttt{ExArr loc le}} & {\texttt{[| \$list:le\$ |]}} & {array} \\
{\texttt{ExAsr loc e}} & {\texttt{assert \$e\$}} & {assert} \\
{\texttt{ExAss loc e1 e2}} & {\texttt{\$e1\$ := \$e2\$}} & {assignment} \\
{\texttt{ExBae loc e le}} & {\texttt{\$e\$ .\{ \$list:le\$ \}}} & {big array element} \\
{\texttt{ExChr loc s}} & {\texttt{\$chr:s\$}} & {character constant} \\
{\texttt{ExCoe loc e None t2}} & {\texttt{(\$e\$ :> \$t2\$)}} & {coercion} \\
{\texttt{ExCoe loc e (Some t1) t2}} & {\texttt{(\$e\$ : \$t1\$ :> \$t2\$)}} & {coercion} \\
{\texttt{ExFlo loc s}} & {\texttt{\$flo:s\$}} & {float constant} \\
{\texttt{ExFor loc s e1 e2 True le}} & {\texttt{for \$lid:s\$ = \$e1\$ to \$e2\$ do \{ \$list:le\$ \}}} & {for (increasing)} \\
{\texttt{ExFor loc s e1 e2 False le}} & {\texttt{for \$lid:s\$ = \$e1\$ downto \$e2\$ do \{ \$list:le\$ \}}} & {for (decreasing)} \\
{\texttt{ExFor loc s e1 e2 b le}} & {\texttt{for \$lid:s\$ = \$e1\$ \$to:b\$ \$e2\$ do \{ \$list:le\$ \}}} & {for} \\
{\texttt{ExFun loc lpee}} & {\texttt{fun [ \$list:lpee\$ ]}} & {function (2)} \\
{\texttt{ExIfe loc e1 e2 e3}} & {\texttt{if \$e1\$ then \$e2\$ else \$e3\$}} & {if} \\
{\texttt{ExInt loc s1 ""}} & {\texttt{\$int:s1\$}} & {integer constant} \\
{\texttt{ExInt loc s1 "l"}} & {\texttt{\$int32:s1\$}} & {integer 32 bits} \\
{\texttt{ExInt loc s1 "L"}} & {\texttt{\$int64:s1\$}} & {integer 64 bits} \\
{\texttt{ExInt loc s1 "n"}} & {\texttt{\$nativeint:s1\$}} & {native integer} \\
{\texttt{ExLab loc p None}} & {\texttt{\~{}\{\$p\$\}}} & {label} \\
{\texttt{ExLab loc p (Some e)}} & {\texttt{\~{}\{\$p\$ = \$e\$\}}} & {label} \\
{\texttt{ExLab loc p oe}} & {\texttt{\~{}\{\$p\$ \$opt:oe\$\}}} & {label} \\
{\texttt{ExLaz loc e}} & {\texttt{lazy \$e\$}} & {lazy} \\
{\texttt{ExLet loc True lpe e}} & {\texttt{let rec \$list:lpe\$ in \$e\$}} & {let rec} \\
{\texttt{ExLet loc False lpe e}} & {\texttt{let \$list:lpe\$ in \$e\$}} & {let not rec} \\
{\texttt{ExLet loc b lpe e}} & {\texttt{let \$flag:b\$ \$list:lpe\$ in \$e\$}} & {let} \\
{\texttt{ExLid loc s}} & {\texttt{\$lid:s\$}} & {lowercase identifier} \\
{\texttt{ExLmd loc s me e}} & {\texttt{let module \$uid:s\$ = \$me\$ in \$e\$}} & {let module} \\
{\texttt{ExMat loc e lpee}} & {\texttt{match \$e\$ with [ \$list:lpee\$ ]}} & {match (2)} \\
{\texttt{ExNew loc ls}} & {\texttt{new \$list:ls\$}} & {new} \\
{\texttt{ExObj loc None lcsi}} & {\texttt{object \$list:lcsi\$ end}} & {object expression} \\
{\texttt{ExObj loc (Some p) lcsi}} & {\texttt{object (\$p\$) \$list:lcsi\$ end}} & {object expression} \\
{\texttt{ExObj loc op lcsi}} & {\texttt{object \$opt:op\$ \$list:lcsi\$ end}} & {object expression} \\
{\texttt{ExOlb loc p None}} & {\texttt{?\{\$p\$\}}} & {option label} \\
{\texttt{ExOlb loc p (Some e)}} & {\texttt{?\{\$p\$ = \$e\$\}}} & {option label} \\
{\texttt{ExOlb loc p oe}} & {\texttt{?\{\$p\$ \$opt:oe\$\}}} & {option label} \\
{\texttt{ExOvr loc lse}} & {\texttt{\{< \$list:lse\$ >\}}} & {override} \\
{\texttt{ExPck loc me None}} & {\texttt{(module \$me\$)}} & {module packing} \\
{\texttt{ExPck loc me (Some mt)}} & {\texttt{(module \$me\$ : \$mt\$)}} & {module packing} \\
{\texttt{ExRec loc lpe None}} & {\texttt{\{\$list:lpe\$\}}} & {record} \\
{\texttt{ExRec loc lpe (Some e)}} & {\texttt{\{(\$e\$) with \$list:lpe\$\}}} & {record} \\
{\texttt{ExSeq loc le}} & {\texttt{do \{ \$list:le\$ \}}} & {sequence} \\
{\texttt{ExSnd loc e s}} & {\texttt{\$e\$ \# \$s\$}} & {method call} \\
{\texttt{ExSte loc e1 e2}} & {\texttt{\$e1\$ .[ \$e2\$ ]}} & {string element} \\
{\texttt{ExStr loc s}} & {\texttt{\$str:s\$}} & {string} \\
{\texttt{ExTry loc e lpee}} & {\texttt{try \$e\$ with [ \$list:lpee\$ ]}} & {try (2)} \\
{\texttt{ExTup loc le}} & {\texttt{(\$list:le\$)}} & {t-uple} \\
{\texttt{ExTyc loc e t}} & {\texttt{(\$e\$ : \$t\$)}} & {type constraint} \\
{\texttt{ExUid loc s}} & {\texttt{\$uid:s\$}} & {uppercase identifier} \\
{\texttt{ExVrn loc s}} & {\texttt{` \$s\$}} & {variant} \\
{\texttt{ExWhi loc e le}} & {\texttt{while \$e\$ do \{ \$list:le\$ \}}} & {while} \\
\hline
\end{longtable}
\end{center}\normalsize

\noindent (1)
\noindent Node used in the quotation expanders to tells at conversion to
    OCaml compiler syntax tree time, that all locations of the
    sub-tree is correcty located in the quotation. By default, in
    quotations, the locations of all generated nodes are the location
    of the whole quotation. This node allows to make an exception to
    this rule, since we know that the antiquotation belongs to the
    universe of the enclosing program. See the chapter
    about quotations and, in particular, its
    section about antiquotations.



\noindent (2)
\noindent The variable "lpee" found in "function", "match" and "try"
    statements correspond to a list of "\texttt{(patt * option expr *
      expr)}" where the "\texttt{option expr}" is the "when"
    optionally following the pattern:

\begin{verbatim}
  p -> e
\end{verbatim}

\noindent is represented by:

\begin{verbatim}
  (p, None, e)
\end{verbatim}

\noindent and

\begin{verbatim}
  p when e1 -> e
\end{verbatim}

\noindent is represented by:

\begin{verbatim}
  (p, Some e1, e)
\end{verbatim}


\subsection{patt}

\noindent Patterns of the language.

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:patt< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{PaAcc loc p1 p2}} & {\texttt{\$p1\$ . \$p2\$}} & {access} \\
{\texttt{PaAli loc p1 p2}} & {\texttt{(\$p1\$ as \$p2\$)}} & {alias} \\
{\texttt{PaAnt loc p}} & {\texttt{\$anti:p\$}} & {antiquotation (1)} \\
{\texttt{PaAny loc}} & {\texttt{\_}} & {wildcard} \\
{\texttt{PaApp loc p1 p2}} & {\texttt{\$p1\$ \$p2\$}} & {application} \\
{\texttt{PaArr loc lp}} & {\texttt{[| \$list:lp\$ |]}} & {array} \\
{\texttt{PaChr loc s}} & {\texttt{\$chr:s\$}} & {character} \\
{\texttt{PaFlo loc s}} & {\texttt{\$flo:s\$}} & {float} \\
{\texttt{PaInt loc s1 ""}} & {\texttt{\$int:s1\$}} & {integer constant} \\
{\texttt{PaInt loc s1 "l"}} & {\texttt{\$int32:s1\$}} & {integer 32 bits} \\
{\texttt{PaInt loc s1 "L"}} & {\texttt{\$int64:s1\$}} & {integer 64 bits} \\
{\texttt{PaInt loc s1 "n"}} & {\texttt{\$nativeint:s1\$}} & {native integer} \\
{\texttt{PaLab loc p1 None}} & {\texttt{\~{}\{\$p1\$\}}} & {label} \\
{\texttt{PaLab loc p1 (Some p2)}} & {\texttt{\~{}\{\$p1\$ = \$p2\$\}}} & {label} \\
{\texttt{PaLab loc p1 op2}} & {\texttt{\~{}\{\$p1\$ \$opt:op2\$\}}} & {label} \\
{\texttt{PaLaz loc p}} & {\texttt{lazy \$p\$}} & {lazy} \\
{\texttt{PaLid loc s}} & {\texttt{\$lid:s\$}} & {lowercase identifier} \\
{\texttt{PaNty loc s}} & {\texttt{(type \$lid:s\$)}} & {new type} \\
{\texttt{PaOlb loc p None}} & {\texttt{?\{\$p\$\}}} & {option label} \\
{\texttt{PaOlb loc p (Some e)}} & {\texttt{?\{\$p\$ = \$e\$\}}} & {option label} \\
{\texttt{PaOlb loc p oe}} & {\texttt{?\{\$p\$ \$opt:oe\$\}}} & {option label} \\
{\texttt{PaOrp loc p1 p2}} & {\texttt{\$p1\$ | \$p2\$}} & {or} \\
{\texttt{PaRec loc lpp}} & {\texttt{\{ \$list:lpp\$ \}}} & {record} \\
{\texttt{PaRng loc p1 p2}} & {\texttt{\$p1\$ .. \$p2\$}} & {range} \\
{\texttt{PaStr loc s}} & {\texttt{\$str:s\$}} & {string} \\
{\texttt{PaTup loc lp}} & {\texttt{(\$list:lp\$)}} & {t-uple} \\
{\texttt{PaTyc loc p t}} & {\texttt{(\$p\$ : \$t\$)}} & {type constraint} \\
{\texttt{PaTyp loc ls}} & {\texttt{\# \$list:ls\$}} & {type pattern} \\
{\texttt{PaUid loc s}} & {\texttt{\$uid:s\$}} & {uppercase identifier} \\
{\texttt{PaUnp loc s None}} & {\texttt{(module \$uid:s\$)}} & {module unpacking} \\
{\texttt{PaUnp loc s (Some mt)}} & {\texttt{(module \$uid:s\$ : \$mt\$)}} & {module unpacking} \\
{\texttt{PaVrn loc s}} & {\texttt{` \$s\$}} & {variant} \\
\hline
\end{longtable}
\end{center}\normalsize

\noindent (1)
  Node used to specify an antiquotation area, like for the
  equivalent node in expressions. See above.


\subsection{ctyp}

\noindent Type expressions of the language.

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:ctyp< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{TyAcc loc t1 t2}} & {\texttt{\$t1\$ . \$t2\$}} & {access} \\
{\texttt{TyAli loc t1 t2}} & {\texttt{\$t1\$ as \$t2\$}} & {alias} \\
{\texttt{TyAny loc}} & {\texttt{\_}} & {wildcard} \\
{\texttt{TyApp loc t1 t2}} & {\texttt{\$t1\$ \$t2\$}} & {application} \\
{\texttt{TyArr loc t1 t2}} & {\texttt{\$t1\$ -> \$t2\$}} & {arrow} \\
{\texttt{TyCls loc ls}} & {\texttt{\# \$list:ls\$}} & {class} \\
{\texttt{TyLab loc s t}} & {\texttt{\~{}\$s\$: \$t\$}} & {label} \\
{\texttt{TyLid loc s}} & {\texttt{\$lid:s\$}} & {lowercase identifier} \\
{\texttt{TyMan loc t1 True t2}} & {\texttt{\$t1\$ == private \$t2\$}} & {manifest} \\
{\texttt{TyMan loc t1 False t2}} & {\texttt{\$t1\$ == \$t2\$}} & {manifest} \\
{\texttt{TyMan loc t1 b t2}} & {\texttt{\$t1\$ == \$priv:b\$ \$t2\$}} & {manifest} \\
{\texttt{TyObj loc lst True}} & {\texttt{< \$list:lst\$ .. >}} & {object} \\
{\texttt{TyObj loc lst False}} & {\texttt{< \$list:lst\$ >}} & {object} \\
{\texttt{TyObj loc lst b}} & {\texttt{< \$list:lst\$ \$flag:b\$ >}} & {object} \\
{\texttt{TyOlb loc s t}} & {\texttt{?\$s\$: \$t\$}} & {option label} \\
{\texttt{TyPck loc mt}} & {\texttt{(module \$mt\$)}} & {package} \\
{\texttt{TyPol loc ls t}} & {\texttt{! \$list:ls\$ . \$t\$}} & {polymorph} \\
{\texttt{TyQuo loc s}} & {\texttt{'\$s\$}} & {variable} \\
{\texttt{TyRec loc llsbt}} & {\texttt{\{ \$list:llsbt\$ \}}} & {record} \\
{\texttt{TySum loc llslt}} & {\texttt{[ \$list:llslt\$ ]}} & {sum} \\
{\texttt{TyTup loc lt}} & {\texttt{( \$list:lt\$ )}} & {t-uple} \\
{\texttt{TyUid loc s}} & {\texttt{\$uid:s\$}} & {uppercase identifier} \\
{\texttt{TyVrn loc lpv None}} & {\texttt{[ = \$list:lpv\$ ]}} & {variant} \\
{\texttt{TyVrn loc lpv (Some None)}} & {\texttt{[ > \$list:lpv\$ ]}} & {variant} \\
{\texttt{TyVrn loc lpv (Some (Some []))}} & {\texttt{[ < \$list:lpv\$ ]}} & {variant} \\
{\texttt{TyVrn loc lpv (Some (Some ls))}} & {\texttt{[ < \$list:lpv\$ > \$list:ls\$ ]}} & {variant} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsection{modules...}

\subsubsection{str\_item}

\noindent Structure items, i.e. phrases in a ".ml" file or "struct"
  elements.

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:str\_item< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{StCls loc lcice}} & {\texttt{class \$list:lcice\$}} & {class declaration} \\
{\texttt{StClt loc lcict}} & {\texttt{class type \$list:lcict\$}} & {class type declaration} \\
{\texttt{StDcl loc lsi}} & {\texttt{declare \$list:lsi\$ end}} & {declare} \\
{\texttt{StDir loc s None}} & {\texttt{\# \$lid:s\$}} & {directive} \\
{\texttt{StDir loc s (Some e)}} & {\texttt{\# \$lid:s\$ \$e\$}} & {directive} \\
{\texttt{StDir loc s oe}} & {\texttt{\# \$lid:s\$ \$opt:oe\$}} & {directive} \\
{\texttt{StExc loc s [] []}} & {\texttt{exception \$uid:s\$}} & {exception} \\
{\texttt{StExc loc s lt []}} & {\texttt{exception \$uid:s\$ of \$list:lt\$}} & {exception} \\
{\texttt{StExc loc s [] ls}} & {\texttt{exception \$uid:s\$ = \$list:ls\$}} & {exception} \\
{\texttt{StExc loc s lt ls}} & {\texttt{exception \$uid:s\$ of \$list:lt\$ = \$list:ls\$}} & {exception} \\
{\texttt{StExp loc e}} & {\texttt{\$exp:e\$}} & {expression} \\
{\texttt{StExt loc s t ls}} & {\texttt{external \$s\$ : \$t\$ = \$list:ls\$}} & {external} \\
{\texttt{StInc loc me}} & {\texttt{include \$me\$}} & {include} \\
{\texttt{StMod loc True lsme}} & {\texttt{module rec \$list:lsme\$}} & {module rec} \\
{\texttt{StMod loc False lsme}} & {\texttt{module \$list:lsme\$}} & {module non rec} \\
{\texttt{StMod loc b lsme}} & {\texttt{module \$flag:b\$ \$list:lsme\$}} & {module} \\
{\texttt{StMty loc s mt}} & {\texttt{module type \$s\$ = \$mt\$}} & {module type} \\
{\texttt{StOpn loc ls}} & {\texttt{open \$list:ls\$}} & {open} \\
{\texttt{StTyp loc ltd}} & {\texttt{type \$list:ltd\$}} & {type declaration} \\
{\texttt{StUse loc s lsil}} & {\texttt{\# \$str:s\$ \$list:lsil\$}} & {... internal use ... (1)} \\
{\texttt{StVal loc True lpe}} & {\texttt{value rec \$list:lpe\$}} & {value rec} \\
{\texttt{StVal loc False lpe}} & {\texttt{value \$list:lpe\$}} & {value non rec} \\
{\texttt{StVal loc b lpe}} & {\texttt{value \$flag:b\$ \$list:lpe\$}} & {value} \\
\hline
\end{longtable}
\end{center}\normalsize

\noindent (1)
\noindent Node internally used to specify a different file name applying to
    the whole subtree. This is generated by the directive "use" and
    used when converting to the OCaml syntax tree which needs the file
    name in its location type.



\subsubsection{sig\_item}

\noindent Signature items, i.e. phrases in a ".mli" file or elements
  inside "sig ... end".

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:sig\_item< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{SgCls loc lcict}} & {\texttt{class \$list:lcict\$}} & {class} \\
{\texttt{SgClt loc lcict}} & {\texttt{class type \$list:lcict\$}} & {class type} \\
{\texttt{SgDcl loc lsi}} & {\texttt{declare \$list:lsi\$ end}} & {declare} \\
{\texttt{SgDir loc s None}} & {\texttt{\# \$lid:s\$}} & {directive} \\
{\texttt{SgDir loc s (Some e)}} & {\texttt{\# \$lid:s\$ \$e\$}} & {directive} \\
{\texttt{SgDir loc s oe}} & {\texttt{\# \$lid:s\$ \$opt:oe\$}} & {directive} \\
{\texttt{SgExc loc s []}} & {\texttt{exception \$s\$}} & {exception} \\
{\texttt{SgExc loc s lt}} & {\texttt{exception \$s\$ of \$list:lt\$}} & {exception} \\
{\texttt{SgExt loc s t ls}} & {\texttt{external \$s\$ : \$t\$ = \$list:ls\$}} & {external} \\
{\texttt{SgInc loc mt}} & {\texttt{include \$mt\$}} & {include} \\
{\texttt{SgMod loc True lsmt}} & {\texttt{module rec \$list:lsmt\$}} & {module rec} \\
{\texttt{SgMod loc False lsmt}} & {\texttt{module \$list:lsmt\$}} & {module non rec} \\
{\texttt{SgMod loc b lsmt}} & {\texttt{module \$flag:b\$ \$list:lsmt\$}} & {module} \\
{\texttt{SgMty loc s mt}} & {\texttt{module type \$s\$ = \$mt\$}} & {module type} \\
{\texttt{SgOpn loc ls}} & {\texttt{open \$list:ls\$}} & {open} \\
{\texttt{SgTyp loc ltd}} & {\texttt{type \$list:ltd\$}} & {type declaration} \\
{\texttt{SgUse loc s lsil}} & {\texttt{\# \$str:s\$ \$list:lsil\$}} & {... internal use ... (1)} \\
{\texttt{SgVal loc s t}} & {\texttt{value \$s\$ : \$t\$}} & {value} \\
\hline
\end{longtable}
\end{center}\normalsize

\noindent (1)
\noindent Same remark as for "\texttt{str\_item}" above.



\subsubsection{module\_expr}

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:module\_expr< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{MeAcc loc me1 me2}} & {\texttt{\$me1\$ . \$me2\$}} & {access} \\
{\texttt{MeApp loc me1 me2}} & {\texttt{\$me1\$ \$me2\$}} & {application} \\
{\texttt{MeFun loc s mt me}} & {\texttt{functor (\$s\$ : \$mt\$) -> \$me\$}} & {functor} \\
{\texttt{MeStr loc lsi}} & {\texttt{struct \$list:lsi\$ end}} & {struct} \\
{\texttt{MeTyc loc me mt}} & {\texttt{(\$me\$ : \$mt\$)}} & {module type constraint} \\
{\texttt{MeUid loc s}} & {\texttt{\$uid:s\$}} & {uppercase identifier} \\
{\texttt{MeUnp loc e None}} & {\texttt{(value \$e\$)}} & {module unpacking} \\
{\texttt{MeUnp loc e (Some mt)}} & {\texttt{(value \$e\$ : \$mt\$)}} & {module unpacking} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsubsection{module\_type}

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:module\_type< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{MtAcc loc mt1 mt2}} & {\texttt{\$mt1\$ . \$mt2\$}} & {access} \\
{\texttt{MtApp loc mt1 mt2}} & {\texttt{\$mt1\$ \$mt2\$}} & {application} \\
{\texttt{MtFun loc s mt1 mt2}} & {\texttt{functor (\$s\$ : \$mt1\$) -> \$mt2\$}} & {functor} \\
{\texttt{MtLid loc s}} & {\texttt{\$lid:s\$}} & {lowercase identifier} \\
{\texttt{MtQuo loc s}} & {\texttt{' \$s\$}} & {abstract} \\
{\texttt{MtSig loc lsi}} & {\texttt{sig \$list:lsi\$ end}} & {signature} \\
{\texttt{MtTyo loc me}} & {\texttt{module type of \$me\$}} & {of module expression} \\
{\texttt{MtUid loc s}} & {\texttt{\$uid:s\$}} & {uppercase identifier} \\
{\texttt{MtWit loc mt lwc}} & {\texttt{\$mt\$ with \$list:lwc\$}} & {with construction} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsection{classes...}

\subsubsection{class\_expr}

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:class\_expr< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{CeApp loc ce e}} & {\texttt{\$ce\$ \$e\$}} & {application} \\
{\texttt{CeCon loc ls lt}} & {\texttt{[ \$list:lt\$ ] \$list:ls\$}} & {constructor} \\
{\texttt{CeFun loc p ce}} & {\texttt{fun \$p\$ -> \$ce\$}} & {function} \\
{\texttt{CeLet loc True lpe ce}} & {\texttt{let rec \$list:lpe\$ in \$ce\$}} & {let rec} \\
{\texttt{CeLet loc False lpe ce}} & {\texttt{let \$list:lpe\$ in \$ce\$}} & {let non rec} \\
{\texttt{CeLet loc b lpe ce}} & {\texttt{let \$flag:b\$ \$list:lpe\$ in \$ce\$}} & {let} \\
{\texttt{CeStr loc None lcsi}} & {\texttt{object \$list:lcsi\$ end}} & {object} \\
{\texttt{CeStr loc (Some p) lcsi}} & {\texttt{object (\$p\$) \$list:lcsi\$ end}} & {object} \\
{\texttt{CeStr loc op lcsi}} & {\texttt{object \$opt:op\$ \$list:lcsi\$ end}} & {object} \\
{\texttt{CeTyc loc ce ct}} & {\texttt{(\$ce\$ : \$ct\$)}} & {class type constraint} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsubsection{class\_type}

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:class\_type< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{CtAcc loc ct1 ct2}} & {\texttt{\$ct1\$ . \$ct2\$}} & {access} \\
{\texttt{CtApp loc ct1 ct2}} & {\texttt{\$ct1\$ \$ct2\$}} & {application} \\
{\texttt{CtCon loc ct lt}} & {\texttt{\$ct\$ [ \$list:lt\$ ]}} & {constructor} \\
{\texttt{CtFun loc t ct}} & {\texttt{[ \$t\$ ] -> \$ct\$}} & {arrow} \\
{\texttt{CtIde loc s}} & {\texttt{\$id:s\$}} & {identifier} \\
{\texttt{CtSig loc None lcsi}} & {\texttt{object \$list:lcsi\$ end}} & {object} \\
{\texttt{CtSig loc (Some t) lcsi}} & {\texttt{object (\$t\$) \$list:lcsi\$ end}} & {object} \\
{\texttt{CtSig loc ot lcsi}} & {\texttt{object \$opt:ot\$ \$list:lcsi\$ end}} & {object} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsubsection{class\_str\_item}

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:class\_str\_item< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{CrCtr loc t1 t2}} & {\texttt{type \$t1\$ = \$t2\$}} & {type constraint} \\
{\texttt{CrDcl loc lcsi}} & {\texttt{declare \$list:lcsi\$ end}} & {declaration list} \\
{\texttt{CrInh loc ce None}} & {\texttt{inherit \$ce\$}} & {inheritance} \\
{\texttt{CrInh loc ce (Some s)}} & {\texttt{inherit \$ce\$ \$opt:Some s\$}} & {inheritance} \\
{\texttt{CrInh loc ce os}} & {\texttt{inherit \$ce\$ \$opt:os\$}} & {inheritance} \\
{\texttt{CrIni loc e}} & {\texttt{initializer \$e\$}} & {initialization} \\
{\texttt{CrMth loc True True s None e}} & {\texttt{method! private \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True True s (Some t) e}} & {\texttt{method! private \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True True s ot e}} & {\texttt{method! private \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True False s None e}} & {\texttt{method! \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True False s (Some t) e}} & {\texttt{method! \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True False s ot e}} & {\texttt{method! \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True b2 s None e}} & {\texttt{method! \$priv:b2\$ \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True b2 s (Some t) e}} & {\texttt{method! \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc True b2 s ot e}} & {\texttt{method! \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False True s None e}} & {\texttt{method private \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False True s (Some t) e}} & {\texttt{method private \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False True s ot e}} & {\texttt{method private \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False False s None e}} & {\texttt{method \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False False s (Some t) e}} & {\texttt{method \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False False s ot e}} & {\texttt{method \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False b2 s None e}} & {\texttt{method \$priv:b2\$ \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False b2 s (Some t) e}} & {\texttt{method \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc False b2 s ot e}} & {\texttt{method \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 True s None e}} & {\texttt{method \$!:b1\$ private \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 True s (Some t) e}} & {\texttt{method \$!:b1\$ private \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 True s ot e}} & {\texttt{method \$!:b1\$ private \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 False s None e}} & {\texttt{method \$!:b1\$ \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 False s (Some t) e}} & {\texttt{method \$!:b1\$ \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 False s ot e}} & {\texttt{method \$!:b1\$ \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 b2 s None e}} & {\texttt{method \$!:b1\$ \$priv:b2\$ \$lid:s\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 b2 s (Some t) e}} & {\texttt{method \$!:b1\$ \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$}} & {method} \\
{\texttt{CrMth loc b1 b2 s ot e}} & {\texttt{method \$!:b1\$ \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$}} & {method} \\
{\texttt{CrVal loc True True s e}} & {\texttt{value! mutable \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc True False s e}} & {\texttt{value! \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc True b2 s e}} & {\texttt{value! \$flag:b2\$ \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc False True s e}} & {\texttt{value mutable \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc False False s e}} & {\texttt{value \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc False b2 s e}} & {\texttt{value \$flag:b2\$ \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc b1 True s e}} & {\texttt{value \$!:b1\$ mutable \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc b1 False s e}} & {\texttt{value \$!:b1\$ \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVal loc b1 b2 s e}} & {\texttt{value \$!:b1\$ \$flag:b2\$ \$lid:s\$ = \$e\$}} & {value} \\
{\texttt{CrVav loc True s t}} & {\texttt{value virtual mutable \$lid:s\$ : \$t\$}} & {virtual value} \\
{\texttt{CrVav loc False s t}} & {\texttt{value virtual \$lid:s\$ : \$t\$}} & {virtual value} \\
{\texttt{CrVav loc b s t}} & {\texttt{value virtual \$flag:b\$ \$lid:s\$ : \$t\$}} & {virtual value} \\
{\texttt{CrVir loc True s t}} & {\texttt{method virtual private \$lid:s\$ : \$t\$}} & {virtual method} \\
{\texttt{CrVir loc False s t}} & {\texttt{method virtual \$lid:s\$ : \$t\$}} & {virtual method} \\
{\texttt{CrVir loc b s t}} & {\texttt{method virtual \$flag:b\$ \$lid:s\$ : \$t\$}} & {virtual method} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsubsection{class\_sig\_item}

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:class\_sig\_item< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{CgCtr loc t1 t2}} & {\texttt{type \$t1\$ = \$t2\$}} & {type constraint} \\
{\texttt{CgDcl loc lcsi}} & {\texttt{declare \$list:lcsi\$ end}} & {declare} \\
{\texttt{CgInh loc ct}} & {\texttt{inherit \$ct\$}} & {inheritance} \\
{\texttt{CgMth loc True s t}} & {\texttt{method private \$lid:s\$ : \$t\$}} & {method} \\
{\texttt{CgMth loc False s t}} & {\texttt{method \$lid:s\$ : \$t\$}} & {method} \\
{\texttt{CgMth loc b s t}} & {\texttt{method \$flag:b\$ \$lid:s\$ : \$t\$}} & {method} \\
{\texttt{CgVal loc True s t}} & {\texttt{value mutable \$lid:s\$ : \$t\$}} & {value} \\
{\texttt{CgVal loc False s t}} & {\texttt{value \$lid:s\$ : \$t\$}} & {value} \\
{\texttt{CgVal loc b s t}} & {\texttt{value \$flag:b\$ \$lid:s\$ : \$t\$}} & {value} \\
{\texttt{CgVir loc True s t}} & {\texttt{method virtual private \$lid:s\$ : \$t\$}} & {virtual method} \\
{\texttt{CgVir loc False s t}} & {\texttt{method virtual \$lid:s\$ : \$t\$}} & {virtual method} \\
{\texttt{CgVir loc b s t}} & {\texttt{method virtual \$flag:b\$ \$lid:s\$ : \$t\$}} & {virtual method} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsection{other}

\subsubsection{type\_decl}

\noindent What is after 'type' or 'and' in a type declaration.

\small
\begin{center}
\begin{longtable}{|l|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:type\_decl< ... >>}} \\
\hline
{\texttt{\{tdNam=ls;tdPrm=ltv;tdPrv=True;tdDef=t;tdCon=ltt\}}} & {\texttt{\$tp:ls\$ \$list:ltv\$ = private \$t\$ \$list:ltt\$}} \\
{\texttt{\{tdNam=ls;tdPrm=ltv;tdPrv=False;tdDef=t;tdCon=ltt\}}} & {\texttt{\$tp:ls\$ \$list:ltv\$ = \$t\$ \$list:ltt\$}} \\
{\texttt{\{tdNam=ls;tdPrm=ltv;tdPrv=b;tdDef=t;tdCon=ltt\}}} & {\texttt{\$tp:ls\$ \$list:ltv\$ = \$priv:b\$ \$t\$ \$list:ltt\$}} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsubsection{with\_constr}

\noindent "With" possibly following a module type.

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:with\_constr< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{WcMod loc ls me}} & {\texttt{module \$list:ls\$ = \$me\$}} & {with module} \\
{\texttt{WcMos loc ls me}} & {\texttt{module \$list:ls\$ := \$me\$}} & {with module substitution} \\
{\texttt{WcTyp loc ls ltv True t}} & {\texttt{type \$list:ls\$ \$list:ltv\$ = private \$t\$}} & {with type} \\
{\texttt{WcTyp loc ls ltv False t}} & {\texttt{type \$list:ls\$ \$list:ltv\$ = \$t\$}} & {with type} \\
{\texttt{WcTyp loc ls ltv b t}} & {\texttt{type \$list:ls\$ \$list:ltv\$ = \$flag:b\$ \$t\$}} & {with type} \\
{\texttt{WcTys loc ls ltv t}} & {\texttt{type \$list:ls\$ \$list:ltv\$ := \$t\$}} & {with type substitution} \\
\hline
\end{longtable}
\end{center}\normalsize

\subsubsection{poly\_variant}

\noindent Polymorphic variants.

\small
\begin{center}
\begin{longtable}{|l|c|l|}
\hline
\makebox[3cm][l]{Node} & \makebox[3cm][l]{\texttt{<:poly\_variant< ... >>}} & \makebox[3cm][l]{Comment} \\
\hline
{\texttt{PvTag loc s True []}} & {\texttt{`\$s\$}} & {constructor} \\
{\texttt{PvTag loc s True lt}} & {\texttt{`\$s\$ of \& \$list:lt\$}} & {constructor} \\
{\texttt{PvTag loc s False lt}} & {\texttt{`\$s\$ of \$list:lt\$}} & {constructor} \\
{\texttt{PvTag loc s b lt}} & {\texttt{`\$s\$ of \$flag:b\$ \$list:lt\$}} & {constructor} \\
{\texttt{PvInh loc t}} & {\texttt{\$t\$}} & {type} \\
\hline
\end{longtable}
\end{center}\normalsize

\clearemptydoublepage

\pagestyle{fancy}\chapter{Syntax tree - strict mode}

\noindent This chapter presents the Camlp5 syntax tree when Camlp5 is installed
  in \emph{strict} mode.


\section{Introduction}

\noindent This syntax tree is defined in the module "\texttt{MLast}" provided
  by Camlp5. Each node corresponds to a syntactic entity of the
  corresponding type.

\

\noindent For example, the syntax tree of the statement "\texttt{if}" can
  be written:

\begin{verbatim}
  MLast.ExIfe loc e1 e2 e3
\end{verbatim}

\noindent where "\texttt{loc}" is the location in the source, and
  "\texttt{e1}", "\texttt{e2}" and "\texttt{e3}" are
  respectively the expression after the "\texttt{if}", the one after
  the "\texttt{then}" and the one after the "\texttt{else}".

\

\noindent If a program needs to manipulate syntax trees, it can use the nodes
  defined in the module "\texttt{MLast}". The programmer must know how
  the concrete syntax is transformed into this abstract syntax.

\

\noindent A simpler solution is to use one of the quotation kits
  "\texttt{q\_MLast.cmo}" or "\texttt{q\_ast.cmo}". Both propose
  quotations which represent the abstract
  syntax (the nodes of the module "\texttt{MLast}") into concrete
  syntax with antiquotations to bind variables inside. The example
  above can be written:

\begin{verbatim}
  <:expr< if $e1$ then $e2$ else $e3$ >>
\end{verbatim}

\noindent This representation is very interesting when one wants to
  manipulate complicated syntax trees. Here is an example taken from
  the Camlp5 sources themselves:

\begin{verbatim}
  <:expr<
    match try Some $f$ with [ Stream.Failure -> None ] with
    [ Some $p$ -> $e$
    | _ -> raise (Stream.Error $e2$) ]
  >>
\end{verbatim}

\noindent This example was in a position of a pattern. In abstract syntax, it
  should have been written:

\begin{verbatim}
  MLast.ExMat _
    (MLast.ExTry _ (MLast.ExApp _ (MLast.ExUid _ (Ploc.VaVal "Some")) f)
       (Ploc.VaVal
          [(MLast.PaAcc _ (MLast.PaUid _ (Ploc.VaVal "Stream"))
             (MLast.PaUid _ (Ploc.VaVal "Failure")),
            Ploc.VaVal None, MLast.ExUid _ (Ploc.VaVal "None"))]))
    (Ploc.VaVal
       [(MLast.PaApp _ (MLast.PaUid _ (Ploc.VaVal "Some")) p,
         Ploc.VaVal None, e);
        (MLast.PaAny _, Ploc.VaVal None,
         MLast.ExApp _ (MLast.ExLid _ (Ploc.VaVal "raise"))
           (MLast.ExApp _
              (MLast.ExAcc _ (MLast.ExUid _ (Ploc.VaVal "Stream"))
                 (MLast.ExUid _ (Ploc.VaVal "Error")))
              e2))])
\end{verbatim}

\noindent Which is less readable and much more complicated to build and
  update.

\

\noindent Instead of thinking of "a syntax tree", the programmer can think of
  "a piece of program".

\section{Location}

\noindent In all syntax tree nodes, the first parameter is the source
  location of the node.

\subsection{In expressions}

\noindent When a quotation is in the context of an expression, the location
  parameter is "\texttt{loc}" in the node and in all its possible
  sub-nodes. Example: if we consider the quotation:

\begin{verbatim}
  <:sig_item< value foo : int -> bool >>
\end{verbatim}

\noindent This quotation, in a context of an expression, is equivalent
  to:

\begin{verbatim}
  MLast.SgVal loc (Ploc.VaVal "foo")
    (MLast.TyArr loc (MLast.TyLid loc (Ploc.VaVal "int"))
       (MLast.TyLid loc (Ploc.VaVal "bool")));
\end{verbatim}

\noindent The name "\texttt{loc}" is predefined. However, it is possible to
  change it, using the argument "\texttt{-loc}" of the Camlp5 shell
  commands.

\

\noindent Consequently, if there is no variable "\texttt{loc}" defined in the
  context of the quotation, or if it is not of the good type, a
  semantic error occur in the OCaml compiler ("Unbound value
  loc").

\

\noindent Note that in the extensible grammars,
  the variable "\texttt{loc}" is bound, in all semantic actions, to
  the location of the rule.

\

\noindent If the created node has no location, the programmer can define a
  variable named "\texttt{loc}" equal to "\texttt{Ploc.dummy}".

\subsection{In patterns}

\noindent When a quotation is in the context of a pattern, the location
  parameter of all nodes and possible sub-nodes is set to the wildcard
  ("\texttt{\_}"). The same example above:

\begin{verbatim}
  <:sig_item< value foo : int -> bool >>
\end{verbatim}

\noindent is equivalent, in a pattern, to:

\begin{verbatim}
  MLast.SgVal _ (Ploc.VaVal "foo")
    (MLast.TyArr _ (MLast.TyLid _ (Ploc.VaVal "int"))
       (MLast.TyLid _ (Ploc.VaVal "bool")))
\end{verbatim}

\noindent However, it is possible to generate a binding of the variable
  "\texttt{loc}" on the top node by writing a "colon" before the
  "less" in the quotation. The same example:

\begin{verbatim}
  <:sig_item:< value foo : int -> bool >>
\end{verbatim}

\noindent is equivalent to:

\begin{verbatim}
  MLast.SgVal loc (Ploc.VaVal "foo")
    (MLast.TyArr _ (MLast.TyLid _ (Ploc.VaVal "int"))
       (MLast.TyLid _ (Ploc.VaVal "bool")))
\end{verbatim}

\section{Antiquotations}

\noindent The expressions or patterns between dollar (\$) characters are
  called \emph{antiquotations}. In opposition to quotations which
  has its own syntax rules, the antiquotation is an area in the syntax
  of the enclosing context (expression or pattern). See the chapter
  about quotations.

\

\noindent If a quotation is in the context of an expression, the
  antiquotation must be an expression. It could be any expression,
  including function calls. Examples:

\begin{verbatim}
  value f e el = <:expr< [$e$ :: $loop False el$] >>;
  value patt_list p pl = <:patt< ( $list:[p::pl]$) >>;
\end{verbatim}

\noindent If a quotation is in the context of an pattern, the antiquotation
  is a pattern. Any pattern is possible, including the wildcard
  character ("\texttt{\_}"). Examples:

\begin{verbatim}
   fun [ <:expr< $lid:op$ $_$ $_$ >> -> op ]
   match p with [ <:patt< $_$ | $_$ >> -> Some p ]
\end{verbatim}

\section{Two kinds of antiquotations}

\subsection{Preliminary remark}

\noindent In strict mode, we remark that most constructors defined of the
  module "\texttt{MLast}" are of type "\texttt{Ploc.vala}". This type
  is defined like this:

\begin{verbatim}
  type vala 'a =
    [ VaAnt of string
    | VaVal of 'a ]
  ;
\end{verbatim}

\noindent The type argument is the real type of the node. For example, a
  value of type "\texttt{bool}" in transitional mode is frequently
  represented by a value of type "\texttt{Ploc.vala bool}".

\

\noindent The first case of the type "\texttt{vala}" corresponds to an
  antiquotation in the concrete syntax. The second case to a normal
  syntax situation, without antiquotation.

\

\noindent Example: in the "let" statement, the fact that it is "rec" or not
  is represented by a boolean. This boolean is, in the syntax tree,
  encapsulated with the type "\texttt{Ploc.vala}". The syntax tree of
  the two following lines:

\begin{verbatim}
  let x = y in z
  let rec x = y in z
\end{verbatim}

\noindent start with, respectively:

\begin{verbatim}
  MLast.ExLet loc (Ploc.VaVal False)
    ... (* and so on *)
\end{verbatim}

\noindent and:

\begin{verbatim}
  MLast.ExLet loc (Ploc.VaVal True)
    ... (* and so on *)
\end{verbatim}

\noindent The case "\texttt{Ploc.VaAnt s}" is internally used by the parsers
  and by the quotation kit "\texttt{q\_ast.cmo}" to record
  antiquotation strings representing the expression or the patterns
  having this value. For example, in this "let" statement:

\begin{verbatim}
  MLast.ExLet loc (Ploc.VaAnt s)
    ... (* and so on *)
\end{verbatim}

\noindent The contents of this "\texttt{s}" is internally handled. For
  information, it contains the antiquotation string (kind included)
  together with representation of the location of the antiquotation
  in the quotation. See the next section.

\subsection{Antiquoting}

\noindent To antiquotate the fact that the "let" is with or without rec (a flag
  of type boolean), there are two ways.

\subsubsection{direct antiquoting}

\noindent The first way, hidding the type "\texttt{Ploc.val}", can be
  written with the antiquotation kind "flag":

\begin{verbatim}
  <:expr< let $flag:rf$ x = y in z >>
\end{verbatim}

\noindent This corresponds to the syntax tree:

\begin{verbatim}
  MLast.ExLet loc (Ploc.VaVal rf)
     ... (* and so on *)
\end{verbatim}

\noindent And, therefore, the type of the variable "\texttt{rf}" is simply
  "\texttt{bool}".

\subsubsection{general antiquoting}

\noindent The second way, introducing variables of type "\texttt{Ploc.vala}"
  can be written a kind prefixed by "\texttt{\_}", namely here
  "\texttt{\_flag}":

\begin{verbatim}
  <:expr< let $_flag:rf$ x = y in z >>
\end{verbatim}

\noindent In that case, it corresponds to the syntax tree:

\begin{verbatim}
  MLast.ExLet loc rf
     ... (* and so on *)
\end{verbatim}

\noindent And, therefore, the type of the variable "\texttt{rf}" is now
  "\texttt{Ploc.vala bool}".

\subsection{Remarks}

\noindent The first form of antiquotation ensures the compatibility with
  previous versions of Camlp5. The syntax tree is \emph{not} the
  same, but the bound variables keep the same type.

\

\noindent All antiquotations kinds have these two forms: one with some name
  (e.g. "flag") and one with the same name prefixed by "a"
  (e.g. "aflag").

\section{Nodes and Quotations}

\noindent This section describes all nodes defined in the module "MLast" of
  Camlp5 and how to write them with quotations. Notice that, inside
  quotations, one is not restricted to these elementary cases, but
  any complex value can be used, resulting on possibly complex combined
  nodes.

\

\noindent The quotation forms are described here
    in revised syntax (like the rest of
    this document). In reality, it depends on which quotation kit is
    loaded:

\begin{itemize}
\item If "\texttt{q\_MLast.cmo}" is used, the revised syntax is
    mandatory: the quotations must be in that syntax without any
    extension.
\item If "\texttt{q\_ast.cmo}" is used, the quotation
    syntax \emph{must} be in the current user syntax with
    all extensions added to compile the file.
\end{itemize}

\noindent Last remark: in the following tables, the variables names give
  information of their types. The details can be found in the
  distributed source file "\texttt{mLast.mli}".

\begin{itemize}
\item \texttt{e}, \texttt{e1}, \texttt{e2}, \texttt{e3}: expr
\item \texttt{p}, \texttt{p1}, \texttt{p2}, \texttt{p3}: patt
\item \texttt{t}, \texttt{t1}, \texttt{t2}, \texttt{e3}: ctyp
\item \texttt{s}: string
\item \texttt{b}: bool
\item \texttt{me}, \texttt{me1}, \texttt{me2}: module\_expr
\item \texttt{mt}, \texttt{mt1}, \texttt{mt2}: module\_type
\item \texttt{le}: list expr
\item \texttt{lp}: list patt
\item \texttt{lt}: list ctyp
\item \texttt{ls}: list string
\item \texttt{lse}: list (string * expr)
\item \texttt{lpe}: list (patt * expr)
\item \texttt{lpp}: list (patt * patt)
\item \texttt{lpoee}: list (patt * option expr * expr)
\item \texttt{op}: option patt
\item \texttt{lcstri}: list class\_str\_item
\item \texttt{lcsigi}: list class\_sig\_item
\end{itemize}

\subsection{expr}

\noindent Expressions of the language.

\begin{description}
\item[- access]

\


    \texttt{<:expr< \$e1\$ . \$e2\$ >>}\\
    \texttt{MLast.ExAcc loc e1 e2}
  
\end{description}
\begin{description}
\item[- antiquotation (1)]

\


    \texttt{<:expr< \$anti:e\$ >>}\\
    \texttt{MLast.ExAnt loc e}
  
\end{description}
\begin{description}
\item[- application]

\


    \texttt{<:expr< \$e1\$ \$e2\$ >>}\\
    \texttt{MLast.ExApp loc e1 e2}
  
\end{description}
\begin{description}
\item[- array element]

\


    \texttt{<:expr< \$e1\$ .( \$e2\$ ) >>}\\
    \texttt{MLast.ExAre loc e1 e2}
  
\end{description}
\begin{description}
\item[- array]

\


    \texttt{<:expr< [| \$list:le\$ |] >>}\\
    \texttt{MLast.ExArr loc (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< [| \$\_list:le\$ |] >>}\\
    \texttt{MLast.ExArr loc le}
  
\end{description}
\begin{description}
\item[- assert]

\


    \texttt{<:expr< assert \$e\$ >>}\\
    \texttt{MLast.ExAsr loc e}
  
\end{description}
\begin{description}
\item[- assignment]

\


    \texttt{<:expr< \$e1\$ := \$e2\$ >>}\\
    \texttt{MLast.ExAss loc e1 e2}
  
\end{description}
\begin{description}
\item[- big array element]

\


    \texttt{<:expr< \$e\$ .\{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExBae loc e (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< \$e\$ .\{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExBae loc e le}
  
\end{description}
\begin{description}
\item[- character constant]

\


    \texttt{<:expr< \$chr:s\$ >>}\\
    \texttt{MLast.ExChr loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< \$\_chr:s\$ >>}\\
    \texttt{MLast.ExChr loc s}
  
\end{description}
\begin{description}
\item[- coercion]

\


    \texttt{<:expr< (\$e\$ :> \$t2\$) >>}\\
    \texttt{MLast.ExCoe loc e None t2}
    \\\\
    \texttt{<:expr< (\$e\$ : \$t1\$ :> \$t2\$) >>}\\
    \texttt{MLast.ExCoe loc e (Some t1) t2}
  
\end{description}
\begin{description}
\item[- float constant]

\


    \texttt{<:expr< \$flo:s\$ >>}\\
    \texttt{MLast.ExFlo loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< \$\_flo:s\$ >>}\\
    \texttt{MLast.ExFlo loc s}
  
\end{description}
\begin{description}
\item[- for (increasing)]

\


    \texttt{<:expr< for \$lid:s\$ = \$e1\$ to \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 (Ploc.VaVal True) (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$lid:s\$ = \$e1\$ to \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 (Ploc.VaVal True) le}
  
\end{description}
\begin{description}
\item[- for (decreasing)]

\


    \texttt{<:expr< for \$lid:s\$ = \$e1\$ downto \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 (Ploc.VaVal False) (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$lid:s\$ = \$e1\$ downto \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 (Ploc.VaVal False) le}
  
\end{description}
\begin{description}
\item[- for]

\


    \texttt{<:expr< for \$lid:s\$ = \$e1\$ \$to:b\$ \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 (Ploc.VaVal b) (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$lid:s\$ = \$e1\$ \$to:b\$ \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 (Ploc.VaVal b) le}
    \\\\
    \texttt{<:expr< for \$lid:s\$ = \$e1\$ \$\_to:b\$ \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 b (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$lid:s\$ = \$e1\$ \$\_to:b\$ \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc (Ploc.VaVal s) e1 e2 b le}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ to \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 (Ploc.VaVal True) (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ to \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 (Ploc.VaVal True) le}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ downto \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 (Ploc.VaVal False) (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ downto \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 (Ploc.VaVal False) le}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ \$to:b\$ \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 (Ploc.VaVal b) (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ \$to:b\$ \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 (Ploc.VaVal b) le}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ \$\_to:b\$ \$e2\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 b (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< for \$\_lid:s\$ = \$e1\$ \$\_to:b\$ \$e2\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExFor loc s e1 e2 b le}
  
\end{description}
\begin{description}
\item[- function]

\


    \texttt{<:expr< fun [ \$list:lpee\$ ] >>}\\
    \texttt{MLast.ExFun loc (Ploc.VaVal lpee)}
    \\\\
    \texttt{<:expr< fun [ \$\_list:lpee\$ ] >>}\\
    \texttt{MLast.ExFun loc lpee}
  
\end{description}
\begin{description}
\item[- if]

\


    \texttt{<:expr< if \$e1\$ then \$e2\$ else \$e3\$ >>}\\
    \texttt{MLast.ExIfe loc e1 e2 e3}
  
\end{description}
\begin{description}
\item[- integer constant]

\


    \texttt{<:expr< \$int:s1\$ >>}\\
    \texttt{MLast.ExInt loc (Ploc.VaVal s1) ""}
    \\\\
    \texttt{<:expr< \$\_int:s1\$ >>}\\
    \texttt{MLast.ExInt loc s1 ""}
  
\end{description}
\begin{description}
\item[- integer 32 bits]

\


    \texttt{<:expr< \$int32:s1\$ >>}\\
    \texttt{MLast.ExInt loc (Ploc.VaVal s1) "l"}
    \\\\
    \texttt{<:expr< \$\_int32:s1\$ >>}\\
    \texttt{MLast.ExInt loc s1 "l"}
  
\end{description}
\begin{description}
\item[- integer 64 bits]

\


    \texttt{<:expr< \$int64:s1\$ >>}\\
    \texttt{MLast.ExInt loc (Ploc.VaVal s1) "L"}
    \\\\
    \texttt{<:expr< \$\_int64:s1\$ >>}\\
    \texttt{MLast.ExInt loc s1 "L"}
  
\end{description}
\begin{description}
\item[- native integer]

\


    \texttt{<:expr< \$nativeint:s1\$ >>}\\
    \texttt{MLast.ExInt loc (Ploc.VaVal s1) "n"}
    \\\\
    \texttt{<:expr< \$\_nativeint:s1\$ >>}\\
    \texttt{MLast.ExInt loc s1 "n"}
  
\end{description}
\begin{description}
\item[- label]

\


    \texttt{<:expr< \~{}\{\$p\$\} >>}\\
    \texttt{MLast.ExLab loc p (Ploc.VaVal None)}
    \\\\
    \texttt{<:expr< \~{}\{\$p\$ = \$e\$\} >>}\\
    \texttt{MLast.ExLab loc p (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:expr< \~{}\{\$p\$ \$opt:oe\$\} >>}\\
    \texttt{MLast.ExLab loc p (Ploc.VaVal oe)}
    \\\\
    \texttt{<:expr< \~{}\{\$p\$ \$\_opt:oe\$\} >>}\\
    \texttt{MLast.ExLab loc p oe}
  
\end{description}
\begin{description}
\item[- lazy]

\


    \texttt{<:expr< lazy \$e\$ >>}\\
    \texttt{MLast.ExLaz loc e}
  
\end{description}
\begin{description}
\item[- let rec]

\


    \texttt{<:expr< let rec \$list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc (Ploc.VaVal True) (Ploc.VaVal lpe) e}
    \\\\
    \texttt{<:expr< let rec \$\_list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc (Ploc.VaVal True) lpe e}
  
\end{description}
\begin{description}
\item[- let not rec]

\


    \texttt{<:expr< let \$list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc (Ploc.VaVal False) (Ploc.VaVal lpe) e}
    \\\\
    \texttt{<:expr< let \$\_list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc (Ploc.VaVal False) lpe e}
  
\end{description}
\begin{description}
\item[- let]

\


    \texttt{<:expr< let \$flag:b\$ \$list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc (Ploc.VaVal b) (Ploc.VaVal lpe) e}
    \\\\
    \texttt{<:expr< let \$flag:b\$ \$\_list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc (Ploc.VaVal b) lpe e}
    \\\\
    \texttt{<:expr< let \$\_flag:b\$ \$list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc b (Ploc.VaVal lpe) e}
    \\\\
    \texttt{<:expr< let \$\_flag:b\$ \$\_list:lpe\$ in \$e\$ >>}\\
    \texttt{MLast.ExLet loc b lpe e}
  
\end{description}
\begin{description}
\item[- lowercase identifier]

\


    \texttt{<:expr< \$lid:s\$ >>}\\
    \texttt{MLast.ExLid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< \$\_lid:s\$ >>}\\
    \texttt{MLast.ExLid loc s}
  
\end{description}
\begin{description}
\item[- let module]

\


    \texttt{<:expr< let module \$uid:s\$ = \$me\$ in \$e\$ >>}\\
    \texttt{MLast.ExLmd loc (Ploc.VaVal s) me e}
    \\\\
    \texttt{<:expr< let module \$\_uid:s\$ = \$me\$ in \$e\$ >>}\\
    \texttt{MLast.ExLmd loc s me e}
  
\end{description}
\begin{description}
\item[- match]

\


    \texttt{<:expr< match \$e\$ with [ \$list:lpee\$ ] >>}\\
    \texttt{MLast.ExMat loc e (Ploc.VaVal lpee)}
    \\\\
    \texttt{<:expr< match \$e\$ with [ \$\_list:lpee\$ ] >>}\\
    \texttt{MLast.ExMat loc e lpee}
  
\end{description}
\begin{description}
\item[- new]

\


    \texttt{<:expr< new \$list:ls\$ >>}\\
    \texttt{MLast.ExNew loc (Ploc.VaVal ls)}
    \\\\
    \texttt{<:expr< new \$\_list:ls\$ >>}\\
    \texttt{MLast.ExNew loc ls}
  
\end{description}
\begin{description}
\item[- object expression]

\


    \texttt{<:expr< object \$list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc (Ploc.VaVal None) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:expr< object \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc (Ploc.VaVal None) lcsi}
    \\\\
    \texttt{<:expr< object (\$p\$) \$list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc (Ploc.VaVal (Some p)) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:expr< object (\$p\$) \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc (Ploc.VaVal (Some p)) lcsi}
    \\\\
    \texttt{<:expr< object \$opt:op\$ \$list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc (Ploc.VaVal op) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:expr< object \$opt:op\$ \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc (Ploc.VaVal op) lcsi}
    \\\\
    \texttt{<:expr< object \$\_opt:op\$ \$list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc op (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:expr< object \$\_opt:op\$ \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.ExObj loc op lcsi}
  
\end{description}
\begin{description}
\item[- option label]

\


    \texttt{<:expr< ?\{\$p\$\} >>}\\
    \texttt{MLast.ExOlb loc p (Ploc.VaVal None)}
    \\\\
    \texttt{<:expr< ?\{\$p\$ = \$e\$\} >>}\\
    \texttt{MLast.ExOlb loc p (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:expr< ?\{\$p\$ \$opt:oe\$\} >>}\\
    \texttt{MLast.ExOlb loc p (Ploc.VaVal oe)}
    \\\\
    \texttt{<:expr< ?\{\$p\$ \$\_opt:oe\$\} >>}\\
    \texttt{MLast.ExOlb loc p oe}
  
\end{description}
\begin{description}
\item[- override]

\


    \texttt{<:expr< \{< \$list:lse\$ >\} >>}\\
    \texttt{MLast.ExOvr loc (Ploc.VaVal lse)}
    \\\\
    \texttt{<:expr< \{< \$\_list:lse\$ >\} >>}\\
    \texttt{MLast.ExOvr loc lse}
  
\end{description}
\begin{description}
\item[- module packing]

\


    \texttt{<:expr< (module \$me\$) >>}\\
    \texttt{MLast.ExPck loc me None}
    \\\\
    \texttt{<:expr< (module \$me\$ : \$mt\$) >>}\\
    \texttt{MLast.ExPck loc me (Some mt)}
  
\end{description}
\begin{description}
\item[- record]

\


    \texttt{<:expr< \{\$list:lpe\$\} >>}\\
    \texttt{MLast.ExRec loc (Ploc.VaVal lpe) None}
    \\\\
    \texttt{<:expr< \{(\$e\$) with \$list:lpe\$\} >>}\\
    \texttt{MLast.ExRec loc (Ploc.VaVal lpe) (Some e)}
    \\\\
    \texttt{<:expr< \{\$\_list:lpe\$\} >>}\\
    \texttt{MLast.ExRec loc lpe None}
    \\\\
    \texttt{<:expr< \{(\$e\$) with \$\_list:lpe\$\} >>}\\
    \texttt{MLast.ExRec loc lpe (Some e)}
  
\end{description}
\begin{description}
\item[- sequence]

\


    \texttt{<:expr< do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExSeq loc (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExSeq loc le}
  
\end{description}
\begin{description}
\item[- method call]

\


    \texttt{<:expr< \$e\$ \# \$s\$ >>}\\
    \texttt{MLast.ExSnd loc e (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< \$e\$ \# \$\_:s\$ >>}\\
    \texttt{MLast.ExSnd loc e s}
  
\end{description}
\begin{description}
\item[- string element]

\


    \texttt{<:expr< \$e1\$ .[ \$e2\$ ] >>}\\
    \texttt{MLast.ExSte loc e1 e2}
  
\end{description}
\begin{description}
\item[- string]

\


    \texttt{<:expr< \$str:s\$ >>}\\
    \texttt{MLast.ExStr loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< \$\_str:s\$ >>}\\
    \texttt{MLast.ExStr loc s}
  
\end{description}
\begin{description}
\item[- try]

\


    \texttt{<:expr< try \$e\$ with [ \$list:lpee\$ ] >>}\\
    \texttt{MLast.ExTry loc e (Ploc.VaVal lpee)}
    \\\\
    \texttt{<:expr< try \$e\$ with [ \$\_list:lpee\$ ] >>}\\
    \texttt{MLast.ExTry loc e lpee}
  
\end{description}
\begin{description}
\item[- t-uple]

\


    \texttt{<:expr< (\$list:le\$) >>}\\
    \texttt{MLast.ExTup loc (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< (\$\_list:le\$) >>}\\
    \texttt{MLast.ExTup loc le}
  
\end{description}
\begin{description}
\item[- type constraint]

\


    \texttt{<:expr< (\$e\$ : \$t\$) >>}\\
    \texttt{MLast.ExTyc loc e t}
  
\end{description}
\begin{description}
\item[- uppercase identifier]

\


    \texttt{<:expr< \$uid:s\$ >>}\\
    \texttt{MLast.ExUid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< \$\_uid:s\$ >>}\\
    \texttt{MLast.ExUid loc s}
  
\end{description}
\begin{description}
\item[- variant]

\


    \texttt{<:expr< ` \$s\$ >>}\\
    \texttt{MLast.ExVrn loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:expr< ` \$\_:s\$ >>}\\
    \texttt{MLast.ExVrn loc s}
  
\end{description}
\begin{description}
\item[- while]

\


    \texttt{<:expr< while \$e\$ do \{ \$list:le\$ \} >>}\\
    \texttt{MLast.ExWhi loc e (Ploc.VaVal le)}
    \\\\
    \texttt{<:expr< while \$e\$ do \{ \$\_list:le\$ \} >>}\\
    \texttt{MLast.ExWhi loc e le}
  
\end{description}
\begin{description}
\item[- extra node (2)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.ExXtr loc s oe}
  
\end{description}

\noindent (1)
\noindent Node used in the quotation expanders to tells at conversion to
    OCaml compiler syntax tree time, that all locations of the
    sub-tree is correcty located in the quotation. By default, in
    quotations, the locations of all generated nodes are the location
    of the whole quotation. This node allows to make an exception to
    this rule, since we know that the antiquotation belongs to the
    universe of the enclosing program. See the chapter
    about quotations and, in particular, its
    section about antiquotations.



\noindent (2)
\noindent Extra node internally used by the quotation kit
    "\texttt{q\_ast.cmo}" to build antiquotations of expressions.



\subsection{patt}

\noindent Patterns of the language.

\begin{description}
\item[- access]

\


    \texttt{<:patt< \$p1\$ . \$p2\$ >>}\\
    \texttt{MLast.PaAcc loc p1 p2}
  
\end{description}
\begin{description}
\item[- alias]

\


    \texttt{<:patt< (\$p1\$ as \$p2\$) >>}\\
    \texttt{MLast.PaAli loc p1 p2}
  
\end{description}
\begin{description}
\item[- antiquotation (1)]

\


    \texttt{<:patt< \$anti:p\$ >>}\\
    \texttt{MLast.PaAnt loc p}
  
\end{description}
\begin{description}
\item[- wildcard]

\


    \texttt{<:patt< \_ >>}\\
    \texttt{MLast.PaAny loc}
  
\end{description}
\begin{description}
\item[- application]

\


    \texttt{<:patt< \$p1\$ \$p2\$ >>}\\
    \texttt{MLast.PaApp loc p1 p2}
  
\end{description}
\begin{description}
\item[- array]

\


    \texttt{<:patt< [| \$list:lp\$ |] >>}\\
    \texttt{MLast.PaArr loc (Ploc.VaVal lp)}
    \\\\
    \texttt{<:patt< [| \$\_list:lp\$ |] >>}\\
    \texttt{MLast.PaArr loc lp}
  
\end{description}
\begin{description}
\item[- character]

\


    \texttt{<:patt< \$chr:s\$ >>}\\
    \texttt{MLast.PaChr loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< \$\_chr:s\$ >>}\\
    \texttt{MLast.PaChr loc s}
  
\end{description}
\begin{description}
\item[- float]

\


    \texttt{<:patt< \$flo:s\$ >>}\\
    \texttt{MLast.PaFlo loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< \$\_flo:s\$ >>}\\
    \texttt{MLast.PaFlo loc s}
  
\end{description}
\begin{description}
\item[- integer constant]

\


    \texttt{<:patt< \$int:s1\$ >>}\\
    \texttt{MLast.PaInt loc (Ploc.VaVal s1) ""}
    \\\\
    \texttt{<:patt< \$\_int:s1\$ >>}\\
    \texttt{MLast.PaInt loc s1 ""}
  
\end{description}
\begin{description}
\item[- integer 32 bits]

\


    \texttt{<:patt< \$int32:s1\$ >>}\\
    \texttt{MLast.PaInt loc (Ploc.VaVal s1) "l"}
    \\\\
    \texttt{<:patt< \$\_int32:s1\$ >>}\\
    \texttt{MLast.PaInt loc s1 "l"}
  
\end{description}
\begin{description}
\item[- integer 64 bits]

\


    \texttt{<:patt< \$int64:s1\$ >>}\\
    \texttt{MLast.PaInt loc (Ploc.VaVal s1) "L"}
    \\\\
    \texttt{<:patt< \$\_int64:s1\$ >>}\\
    \texttt{MLast.PaInt loc s1 "L"}
  
\end{description}
\begin{description}
\item[- native integer]

\


    \texttt{<:patt< \$nativeint:s1\$ >>}\\
    \texttt{MLast.PaInt loc (Ploc.VaVal s1) "n"}
    \\\\
    \texttt{<:patt< \$\_nativeint:s1\$ >>}\\
    \texttt{MLast.PaInt loc s1 "n"}
  
\end{description}
\begin{description}
\item[- label]

\


    \texttt{<:patt< \~{}\{\$p1\$\} >>}\\
    \texttt{MLast.PaLab loc p1 (Ploc.VaVal None)}
    \\\\
    \texttt{<:patt< \~{}\{\$p1\$ = \$p2\$\} >>}\\
    \texttt{MLast.PaLab loc p1 (Ploc.VaVal (Some p2))}
    \\\\
    \texttt{<:patt< \~{}\{\$p1\$ \$opt:op2\$\} >>}\\
    \texttt{MLast.PaLab loc p1 (Ploc.VaVal op2)}
    \\\\
    \texttt{<:patt< \~{}\{\$p1\$ \$\_opt:op2\$\} >>}\\
    \texttt{MLast.PaLab loc p1 op2}
  
\end{description}
\begin{description}
\item[- lazy]

\


    \texttt{<:patt< lazy \$p\$ >>}\\
    \texttt{MLast.PaLaz loc p}
  
\end{description}
\begin{description}
\item[- lowercase identifier]

\


    \texttt{<:patt< \$lid:s\$ >>}\\
    \texttt{MLast.PaLid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< \$\_lid:s\$ >>}\\
    \texttt{MLast.PaLid loc s}
  
\end{description}
\begin{description}
\item[- new type]

\


    \texttt{<:patt< (type \$lid:s\$) >>}\\
    \texttt{MLast.PaNty loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< (type \$\_lid:s\$) >>}\\
    \texttt{MLast.PaNty loc s}
  
\end{description}
\begin{description}
\item[- option label]

\


    \texttt{<:patt< ?\{\$p\$\} >>}\\
    \texttt{MLast.PaOlb loc p (Ploc.VaVal None)}
    \\\\
    \texttt{<:patt< ?\{\$p\$ = \$e\$\} >>}\\
    \texttt{MLast.PaOlb loc p (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:patt< ?\{\$p\$ \$opt:oe\$\} >>}\\
    \texttt{MLast.PaOlb loc p (Ploc.VaVal oe)}
    \\\\
    \texttt{<:patt< ?\{\$p\$ \$\_opt:oe\$\} >>}\\
    \texttt{MLast.PaOlb loc p oe}
  
\end{description}
\begin{description}
\item[- or]

\


    \texttt{<:patt< \$p1\$ | \$p2\$ >>}\\
    \texttt{MLast.PaOrp loc p1 p2}
  
\end{description}
\begin{description}
\item[- record]

\


    \texttt{<:patt< \{ \$list:lpp\$ \} >>}\\
    \texttt{MLast.PaRec loc (Ploc.VaVal lpp)}
    \\\\
    \texttt{<:patt< \{ \$\_list:lpp\$ \} >>}\\
    \texttt{MLast.PaRec loc lpp}
  
\end{description}
\begin{description}
\item[- range]

\


    \texttt{<:patt< \$p1\$ .. \$p2\$ >>}\\
    \texttt{MLast.PaRng loc p1 p2}
  
\end{description}
\begin{description}
\item[- string]

\


    \texttt{<:patt< \$str:s\$ >>}\\
    \texttt{MLast.PaStr loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< \$\_str:s\$ >>}\\
    \texttt{MLast.PaStr loc s}
  
\end{description}
\begin{description}
\item[- t-uple]

\


    \texttt{<:patt< (\$list:lp\$) >>}\\
    \texttt{MLast.PaTup loc (Ploc.VaVal lp)}
    \\\\
    \texttt{<:patt< (\$\_list:lp\$) >>}\\
    \texttt{MLast.PaTup loc lp}
  
\end{description}
\begin{description}
\item[- type constraint]

\


    \texttt{<:patt< (\$p\$ : \$t\$) >>}\\
    \texttt{MLast.PaTyc loc p t}
  
\end{description}
\begin{description}
\item[- type pattern]

\


    \texttt{<:patt< \# \$list:ls\$ >>}\\
    \texttt{MLast.PaTyp loc (Ploc.VaVal ls)}
    \\\\
    \texttt{<:patt< \# \$\_list:ls\$ >>}\\
    \texttt{MLast.PaTyp loc ls}
  
\end{description}
\begin{description}
\item[- uppercase identifier]

\


    \texttt{<:patt< \$uid:s\$ >>}\\
    \texttt{MLast.PaUid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< \$\_uid:s\$ >>}\\
    \texttt{MLast.PaUid loc s}
  
\end{description}
\begin{description}
\item[- module unpacking]

\


    \texttt{<:patt< (module \$uid:s\$) >>}\\
    \texttt{MLast.PaUnp loc (Ploc.VaVal s) None}
    \\\\
    \texttt{<:patt< (module \$uid:s\$ : \$mt\$) >>}\\
    \texttt{MLast.PaUnp loc (Ploc.VaVal s) (Some mt)}
    \\\\
    \texttt{<:patt< (module \$\_uid:s\$) >>}\\
    \texttt{MLast.PaUnp loc s None}
    \\\\
    \texttt{<:patt< (module \$\_uid:s\$ : \$mt\$) >>}\\
    \texttt{MLast.PaUnp loc s (Some mt)}
  
\end{description}
\begin{description}
\item[- variant]

\


    \texttt{<:patt< ` \$s\$ >>}\\
    \texttt{MLast.PaVrn loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:patt< ` \$\_:s\$ >>}\\
    \texttt{MLast.PaVrn loc s}
  
\end{description}
\begin{description}
\item[- extra node (2)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.PaXtr loc s op}
  
\end{description}

\noindent (1)
  Node used to specify an antiquotation area, like for the
  equivalent node in expressions. See above.


\noindent (2)
  Extra node internally used by the quotation kit "\texttt{q\_ast.cmo}"
    to build antiquotations of patterns.


\subsection{ctyp}

\noindent Type expressions of the language.

\begin{description}
\item[- access]

\


    \texttt{<:ctyp< \$t1\$ . \$t2\$ >>}\\
    \texttt{MLast.TyAcc loc t1 t2}
  
\end{description}
\begin{description}
\item[- alias]

\


    \texttt{<:ctyp< \$t1\$ as \$t2\$ >>}\\
    \texttt{MLast.TyAli loc t1 t2}
  
\end{description}
\begin{description}
\item[- wildcard]

\


    \texttt{<:ctyp< \_ >>}\\
    \texttt{MLast.TyAny loc}
  
\end{description}
\begin{description}
\item[- application]

\


    \texttt{<:ctyp< \$t1\$ \$t2\$ >>}\\
    \texttt{MLast.TyApp loc t1 t2}
  
\end{description}
\begin{description}
\item[- arrow]

\


    \texttt{<:ctyp< \$t1\$ -> \$t2\$ >>}\\
    \texttt{MLast.TyArr loc t1 t2}
  
\end{description}
\begin{description}
\item[- class]

\


    \texttt{<:ctyp< \# \$list:ls\$ >>}\\
    \texttt{MLast.TyCls loc (Ploc.VaVal ls)}
    \\\\
    \texttt{<:ctyp< \# \$\_list:ls\$ >>}\\
    \texttt{MLast.TyCls loc ls}
  
\end{description}
\begin{description}
\item[- label]

\


    \texttt{<:ctyp< \~{}\$s\$: \$t\$ >>}\\
    \texttt{MLast.TyLab loc (Ploc.VaVal s) t}
    \\\\
    \texttt{<:ctyp< \~{}\$\_:s\$: \$t\$ >>}\\
    \texttt{MLast.TyLab loc s t}
  
\end{description}
\begin{description}
\item[- lowercase identifier]

\


    \texttt{<:ctyp< \$lid:s\$ >>}\\
    \texttt{MLast.TyLid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:ctyp< \$\_lid:s\$ >>}\\
    \texttt{MLast.TyLid loc s}
  
\end{description}
\begin{description}
\item[- manifest]

\


    \texttt{<:ctyp< \$t1\$ == private \$t2\$ >>}\\
    \texttt{MLast.TyMan loc t1 (Ploc.VaVal True) t2}
    \\\\
    \texttt{<:ctyp< \$t1\$ == \$t2\$ >>}\\
    \texttt{MLast.TyMan loc t1 (Ploc.VaVal False) t2}
    \\\\
    \texttt{<:ctyp< \$t1\$ == \$priv:b\$ \$t2\$ >>}\\
    \texttt{MLast.TyMan loc t1 (Ploc.VaVal b) t2}
    \\\\
    \texttt{<:ctyp< \$t1\$ == \$\_priv:b\$ \$t2\$ >>}\\
    \texttt{MLast.TyMan loc t1 b t2}
  
\end{description}
\begin{description}
\item[- object]

\


    \texttt{<:ctyp< < \$list:lst\$ .. > >>}\\
    \texttt{MLast.TyObj loc (Ploc.VaVal lst) (Ploc.VaVal True)}
    \\\\
    \texttt{<:ctyp< < \$list:lst\$ > >>}\\
    \texttt{MLast.TyObj loc (Ploc.VaVal lst) (Ploc.VaVal False)}
    \\\\
    \texttt{<:ctyp< < \$list:lst\$ \$flag:b\$ > >>}\\
    \texttt{MLast.TyObj loc (Ploc.VaVal lst) (Ploc.VaVal b)}
    \\\\
    \texttt{<:ctyp< < \$list:lst\$ \$\_flag:b\$ > >>}\\
    \texttt{MLast.TyObj loc (Ploc.VaVal lst) b}
    \\\\
    \texttt{<:ctyp< < \$\_list:lst\$ .. > >>}\\
    \texttt{MLast.TyObj loc lst (Ploc.VaVal True)}
    \\\\
    \texttt{<:ctyp< < \$\_list:lst\$ > >>}\\
    \texttt{MLast.TyObj loc lst (Ploc.VaVal False)}
    \\\\
    \texttt{<:ctyp< < \$\_list:lst\$ \$flag:b\$ > >>}\\
    \texttt{MLast.TyObj loc lst (Ploc.VaVal b)}
    \\\\
    \texttt{<:ctyp< < \$\_list:lst\$ \$\_flag:b\$ > >>}\\
    \texttt{MLast.TyObj loc lst b}
  
\end{description}
\begin{description}
\item[- option label]

\


    \texttt{<:ctyp< ?\$s\$: \$t\$ >>}\\
    \texttt{MLast.TyOlb loc (Ploc.VaVal s) t}
    \\\\
    \texttt{<:ctyp< ?\$\_:s\$: \$t\$ >>}\\
    \texttt{MLast.TyOlb loc s t}
  
\end{description}
\begin{description}
\item[- package]

\


    \texttt{<:ctyp< (module \$mt\$) >>}\\
    \texttt{MLast.TyPck loc mt}
  
\end{description}
\begin{description}
\item[- polymorph]

\


    \texttt{<:ctyp< ! \$list:ls\$ . \$t\$ >>}\\
    \texttt{MLast.TyPol loc (Ploc.VaVal ls) t}
    \\\\
    \texttt{<:ctyp< ! \$\_list:ls\$ . \$t\$ >>}\\
    \texttt{MLast.TyPol loc ls t}
  
\end{description}
\begin{description}
\item[- variable]

\


    \texttt{<:ctyp< '\$s\$ >>}\\
    \texttt{MLast.TyQuo loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:ctyp< '\$\_:s\$ >>}\\
    \texttt{MLast.TyQuo loc s}
  
\end{description}
\begin{description}
\item[- record]

\


    \texttt{<:ctyp< \{ \$list:llsbt\$ \} >>}\\
    \texttt{MLast.TyRec loc (Ploc.VaVal llsbt)}
    \\\\
    \texttt{<:ctyp< \{ \$\_list:llsbt\$ \} >>}\\
    \texttt{MLast.TyRec loc llsbt}
  
\end{description}
\begin{description}
\item[- sum]

\


    \texttt{<:ctyp< [ \$list:llslt\$ ] >>}\\
    \texttt{MLast.TySum loc (Ploc.VaVal llslt)}
    \\\\
    \texttt{<:ctyp< [ \$\_list:llslt\$ ] >>}\\
    \texttt{MLast.TySum loc llslt}
  
\end{description}
\begin{description}
\item[- t-uple]

\


    \texttt{<:ctyp< ( \$list:lt\$ ) >>}\\
    \texttt{MLast.TyTup loc (Ploc.VaVal lt)}
    \\\\
    \texttt{<:ctyp< ( \$\_list:lt\$ ) >>}\\
    \texttt{MLast.TyTup loc lt}
  
\end{description}
\begin{description}
\item[- uppercase identifier]

\


    \texttt{<:ctyp< \$uid:s\$ >>}\\
    \texttt{MLast.TyUid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:ctyp< \$\_uid:s\$ >>}\\
    \texttt{MLast.TyUid loc s}
  
\end{description}
\begin{description}
\item[- variant]

\


    \texttt{<:ctyp< [ = \$list:lpv\$ ] >>}\\
    \texttt{MLast.TyVrn loc (Ploc.VaVal lpv) None}
    \\\\
    \texttt{<:ctyp< [ > \$list:lpv\$ ] >>}\\
    \texttt{MLast.TyVrn loc (Ploc.VaVal lpv) (Some None)}
    \\\\
    \texttt{<:ctyp< [ < \$list:lpv\$ ] >>}\\
    \texttt{MLast.TyVrn loc (Ploc.VaVal lpv) (Some (Some (Ploc.VaVal [])))}
    \\\\
    \texttt{<:ctyp< [ < \$list:lpv\$ > \$list:ls\$ ] >>}\\
    \texttt{MLast.TyVrn loc (Ploc.VaVal lpv) (Some (Some (Ploc.VaVal ls)))}
    \\\\
    \texttt{<:ctyp< [ < \$list:lpv\$ > \$\_list:ls\$ ] >>}\\
    \texttt{MLast.TyVrn loc (Ploc.VaVal lpv) (Some (Some ls))}
    \\\\
    \texttt{<:ctyp< [ = \$\_list:lpv\$ ] >>}\\
    \texttt{MLast.TyVrn loc lpv None}
    \\\\
    \texttt{<:ctyp< [ > \$\_list:lpv\$ ] >>}\\
    \texttt{MLast.TyVrn loc lpv (Some None)}
    \\\\
    \texttt{<:ctyp< [ < \$\_list:lpv\$ ] >>}\\
    \texttt{MLast.TyVrn loc lpv (Some (Some (Ploc.VaVal [])))}
    \\\\
    \texttt{<:ctyp< [ < \$\_list:lpv\$ > \$list:ls\$ ] >>}\\
    \texttt{MLast.TyVrn loc lpv (Some (Some (Ploc.VaVal ls)))}
    \\\\
    \texttt{<:ctyp< [ < \$\_list:lpv\$ > \$\_list:ls\$ ] >>}\\
    \texttt{MLast.TyVrn loc lpv (Some (Some ls))}
  
\end{description}
\begin{description}
\item[- extra node (1)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.TyXtr loc s ot}
  
\end{description}

\noindent (1)
  Extra node internally used by the quotation kit "\texttt{q\_ast.cmo}"
    to build antiquotations of types.


\subsection{modules...}

\subsubsection{str\_item}

\noindent Structure items, i.e. phrases in a ".ml" file or "struct"
  elements.

\begin{description}
\item[- class declaration]

\


    \texttt{<:str\_item< class \$list:lcice\$ >>}\\
    \texttt{MLast.StCls loc (Ploc.VaVal lcice)}
    \\\\
    \texttt{<:str\_item< class \$\_list:lcice\$ >>}\\
    \texttt{MLast.StCls loc lcice}
  
\end{description}
\begin{description}
\item[- class type declaration]

\


    \texttt{<:str\_item< class type \$list:lcict\$ >>}\\
    \texttt{MLast.StClt loc (Ploc.VaVal lcict)}
    \\\\
    \texttt{<:str\_item< class type \$\_list:lcict\$ >>}\\
    \texttt{MLast.StClt loc lcict}
  
\end{description}
\begin{description}
\item[- declare]

\


    \texttt{<:str\_item< declare \$list:lsi\$ end >>}\\
    \texttt{MLast.StDcl loc (Ploc.VaVal lsi)}
    \\\\
    \texttt{<:str\_item< declare \$\_list:lsi\$ end >>}\\
    \texttt{MLast.StDcl loc lsi}
  
\end{description}
\begin{description}
\item[- directive]

\


    \texttt{<:str\_item< \# \$lid:s\$ >>}\\
    \texttt{MLast.StDir loc (Ploc.VaVal s) (Ploc.VaVal None)}
    \\\\
    \texttt{<:str\_item< \# \$lid:s\$ \$e\$ >>}\\
    \texttt{MLast.StDir loc (Ploc.VaVal s) (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:str\_item< \# \$lid:s\$ \$opt:oe\$ >>}\\
    \texttt{MLast.StDir loc (Ploc.VaVal s) (Ploc.VaVal oe)}
    \\\\
    \texttt{<:str\_item< \# \$lid:s\$ \$\_opt:oe\$ >>}\\
    \texttt{MLast.StDir loc (Ploc.VaVal s) oe}
    \\\\
    \texttt{<:str\_item< \# \$\_lid:s\$ >>}\\
    \texttt{MLast.StDir loc s (Ploc.VaVal None)}
    \\\\
    \texttt{<:str\_item< \# \$\_lid:s\$ \$e\$ >>}\\
    \texttt{MLast.StDir loc s (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:str\_item< \# \$\_lid:s\$ \$opt:oe\$ >>}\\
    \texttt{MLast.StDir loc s (Ploc.VaVal oe)}
    \\\\
    \texttt{<:str\_item< \# \$\_lid:s\$ \$\_opt:oe\$ >>}\\
    \texttt{MLast.StDir loc s oe}
  
\end{description}
\begin{description}
\item[- exception]

\


    \texttt{<:str\_item< exception \$uid:s\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) (Ploc.VaVal []) (Ploc.VaVal [])}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ of \$list:lt\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) (Ploc.VaVal lt) (Ploc.VaVal [])}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) (Ploc.VaVal []) (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ of \$list:lt\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) (Ploc.VaVal lt) (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) (Ploc.VaVal []) ls}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ of \$list:lt\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) (Ploc.VaVal lt) ls}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ of \$\_list:lt\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) lt (Ploc.VaVal [])}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ of \$\_list:lt\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) lt (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< exception \$uid:s\$ of \$\_list:lt\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExc loc (Ploc.VaVal s) lt ls}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ >>}\\
    \texttt{MLast.StExc loc s (Ploc.VaVal []) (Ploc.VaVal [])}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ of \$list:lt\$ >>}\\
    \texttt{MLast.StExc loc s (Ploc.VaVal lt) (Ploc.VaVal [])}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExc loc s (Ploc.VaVal []) (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ of \$list:lt\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExc loc s (Ploc.VaVal lt) (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExc loc s (Ploc.VaVal []) ls}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ of \$list:lt\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExc loc s (Ploc.VaVal lt) ls}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ of \$\_list:lt\$ >>}\\
    \texttt{MLast.StExc loc s lt (Ploc.VaVal [])}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ of \$\_list:lt\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExc loc s lt (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< exception \$\_uid:s\$ of \$\_list:lt\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExc loc s lt ls}
  
\end{description}
\begin{description}
\item[- expression]

\


    \texttt{<:str\_item< \$exp:e\$ >>}\\
    \texttt{MLast.StExp loc e}
  
\end{description}
\begin{description}
\item[- external]

\


    \texttt{<:str\_item< external \$s\$ : \$t\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExt loc (Ploc.VaVal s) t (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< external \$s\$ : \$t\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExt loc (Ploc.VaVal s) t ls}
    \\\\
    \texttt{<:str\_item< external \$\_:s\$ : \$t\$ = \$list:ls\$ >>}\\
    \texttt{MLast.StExt loc s t (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< external \$\_:s\$ : \$t\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.StExt loc s t ls}
  
\end{description}
\begin{description}
\item[- include]

\


    \texttt{<:str\_item< include \$me\$ >>}\\
    \texttt{MLast.StInc loc me}
  
\end{description}
\begin{description}
\item[- module rec]

\


    \texttt{<:str\_item< module rec \$list:lsme\$ >>}\\
    \texttt{MLast.StMod loc (Ploc.VaVal True) (Ploc.VaVal lsme)}
    \\\\
    \texttt{<:str\_item< module rec \$\_list:lsme\$ >>}\\
    \texttt{MLast.StMod loc (Ploc.VaVal True) lsme}
  
\end{description}
\begin{description}
\item[- module non rec]

\


    \texttt{<:str\_item< module \$list:lsme\$ >>}\\
    \texttt{MLast.StMod loc (Ploc.VaVal False) (Ploc.VaVal lsme)}
    \\\\
    \texttt{<:str\_item< module \$\_list:lsme\$ >>}\\
    \texttt{MLast.StMod loc (Ploc.VaVal False) lsme}
  
\end{description}
\begin{description}
\item[- module]

\


    \texttt{<:str\_item< module \$flag:b\$ \$list:lsme\$ >>}\\
    \texttt{MLast.StMod loc (Ploc.VaVal b) (Ploc.VaVal lsme)}
    \\\\
    \texttt{<:str\_item< module \$flag:b\$ \$\_list:lsme\$ >>}\\
    \texttt{MLast.StMod loc (Ploc.VaVal b) lsme}
    \\\\
    \texttt{<:str\_item< module \$\_flag:b\$ \$list:lsme\$ >>}\\
    \texttt{MLast.StMod loc b (Ploc.VaVal lsme)}
    \\\\
    \texttt{<:str\_item< module \$\_flag:b\$ \$\_list:lsme\$ >>}\\
    \texttt{MLast.StMod loc b lsme}
  
\end{description}
\begin{description}
\item[- module type]

\


    \texttt{<:str\_item< module type \$s\$ = \$mt\$ >>}\\
    \texttt{MLast.StMty loc (Ploc.VaVal s) mt}
    \\\\
    \texttt{<:str\_item< module type \$\_:s\$ = \$mt\$ >>}\\
    \texttt{MLast.StMty loc s mt}
  
\end{description}
\begin{description}
\item[- open]

\


    \texttt{<:str\_item< open \$list:ls\$ >>}\\
    \texttt{MLast.StOpn loc (Ploc.VaVal ls)}
    \\\\
    \texttt{<:str\_item< open \$\_list:ls\$ >>}\\
    \texttt{MLast.StOpn loc ls}
  
\end{description}
\begin{description}
\item[- type declaration]

\


    \texttt{<:str\_item< type \$list:ltd\$ >>}\\
    \texttt{MLast.StTyp loc (Ploc.VaVal ltd)}
    \\\\
    \texttt{<:str\_item< type \$\_list:ltd\$ >>}\\
    \texttt{MLast.StTyp loc ltd}
  
\end{description}
\begin{description}
\item[- ... internal use ... (1)]

\


    \texttt{<:str\_item< \# \$str:s\$ \$list:lsil\$ >>}\\
    \texttt{MLast.StUse loc (Ploc.VaVal s) (Ploc.VaVal lsil)}
    \\\\
    \texttt{<:str\_item< \# \$str:s\$ \$\_list:lsil\$ >>}\\
    \texttt{MLast.StUse loc (Ploc.VaVal s) lsil}
    \\\\
    \texttt{<:str\_item< \# \$\_str:s\$ \$list:lsil\$ >>}\\
    \texttt{MLast.StUse loc s (Ploc.VaVal lsil)}
    \\\\
    \texttt{<:str\_item< \# \$\_str:s\$ \$\_list:lsil\$ >>}\\
    \texttt{MLast.StUse loc s lsil}
  
\end{description}
\begin{description}
\item[- value rec]

\


    \texttt{<:str\_item< value rec \$list:lpe\$ >>}\\
    \texttt{MLast.StVal loc (Ploc.VaVal True) (Ploc.VaVal lpe)}
    \\\\
    \texttt{<:str\_item< value rec \$\_list:lpe\$ >>}\\
    \texttt{MLast.StVal loc (Ploc.VaVal True) lpe}
  
\end{description}
\begin{description}
\item[- value non rec]

\


    \texttt{<:str\_item< value \$list:lpe\$ >>}\\
    \texttt{MLast.StVal loc (Ploc.VaVal False) (Ploc.VaVal lpe)}
    \\\\
    \texttt{<:str\_item< value \$\_list:lpe\$ >>}\\
    \texttt{MLast.StVal loc (Ploc.VaVal False) lpe}
  
\end{description}
\begin{description}
\item[- value]

\


    \texttt{<:str\_item< value \$flag:b\$ \$list:lpe\$ >>}\\
    \texttt{MLast.StVal loc (Ploc.VaVal b) (Ploc.VaVal lpe)}
    \\\\
    \texttt{<:str\_item< value \$flag:b\$ \$\_list:lpe\$ >>}\\
    \texttt{MLast.StVal loc (Ploc.VaVal b) lpe}
    \\\\
    \texttt{<:str\_item< value \$\_flag:b\$ \$list:lpe\$ >>}\\
    \texttt{MLast.StVal loc b (Ploc.VaVal lpe)}
    \\\\
    \texttt{<:str\_item< value \$\_flag:b\$ \$\_list:lpe\$ >>}\\
    \texttt{MLast.StVal loc b lpe}
  
\end{description}
\begin{description}
\item[- extra node (2)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.StXtr loc s ot}
  
\end{description}

\noindent (1)
\noindent Node internally used to specify a different file name applying to
    the whole subtree. This is generated by the directive "use" and
    used when converting to the OCaml syntax tree which needs the file
    name in its location type.



\noindent (2)
\noindent Extra node internally used by the quotation kit
    "\texttt{q\_ast.cmo}" to build antiquotations of structure
    items.



\subsubsection{sig\_item}

\noindent Signature items, i.e. phrases in a ".mli" file or elements
  inside "sig ... end".

\begin{description}
\item[- class]

\


    \texttt{<:sig\_item< class \$list:lcict\$ >>}\\
    \texttt{MLast.SgCls loc (Ploc.VaVal lcict)}
    \\\\
    \texttt{<:sig\_item< class \$\_list:lcict\$ >>}\\
    \texttt{MLast.SgCls loc lcict}
  
\end{description}
\begin{description}
\item[- class type]

\


    \texttt{<:sig\_item< class type \$list:lcict\$ >>}\\
    \texttt{MLast.SgClt loc (Ploc.VaVal lcict)}
    \\\\
    \texttt{<:sig\_item< class type \$\_list:lcict\$ >>}\\
    \texttt{MLast.SgClt loc lcict}
  
\end{description}
\begin{description}
\item[- declare]

\


    \texttt{<:sig\_item< declare \$list:lsi\$ end >>}\\
    \texttt{MLast.SgDcl loc (Ploc.VaVal lsi)}
    \\\\
    \texttt{<:sig\_item< declare \$\_list:lsi\$ end >>}\\
    \texttt{MLast.SgDcl loc lsi}
  
\end{description}
\begin{description}
\item[- directive]

\


    \texttt{<:sig\_item< \# \$lid:s\$ >>}\\
    \texttt{MLast.SgDir loc (Ploc.VaVal s) (Ploc.VaVal None)}
    \\\\
    \texttt{<:sig\_item< \# \$lid:s\$ \$e\$ >>}\\
    \texttt{MLast.SgDir loc (Ploc.VaVal s) (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:sig\_item< \# \$lid:s\$ \$opt:oe\$ >>}\\
    \texttt{MLast.SgDir loc (Ploc.VaVal s) (Ploc.VaVal oe)}
    \\\\
    \texttt{<:sig\_item< \# \$lid:s\$ \$\_opt:oe\$ >>}\\
    \texttt{MLast.SgDir loc (Ploc.VaVal s) oe}
    \\\\
    \texttt{<:sig\_item< \# \$\_lid:s\$ >>}\\
    \texttt{MLast.SgDir loc s (Ploc.VaVal None)}
    \\\\
    \texttt{<:sig\_item< \# \$\_lid:s\$ \$e\$ >>}\\
    \texttt{MLast.SgDir loc s (Ploc.VaVal (Some e))}
    \\\\
    \texttt{<:sig\_item< \# \$\_lid:s\$ \$opt:oe\$ >>}\\
    \texttt{MLast.SgDir loc s (Ploc.VaVal oe)}
    \\\\
    \texttt{<:sig\_item< \# \$\_lid:s\$ \$\_opt:oe\$ >>}\\
    \texttt{MLast.SgDir loc s oe}
  
\end{description}
\begin{description}
\item[- exception]

\


    \texttt{<:sig\_item< exception \$s\$ >>}\\
    \texttt{MLast.SgExc loc (Ploc.VaVal s) (Ploc.VaVal [])}
    \\\\
    \texttt{<:sig\_item< exception \$s\$ of \$list:lt\$ >>}\\
    \texttt{MLast.SgExc loc (Ploc.VaVal s) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:sig\_item< exception \$s\$ of \$\_list:lt\$ >>}\\
    \texttt{MLast.SgExc loc (Ploc.VaVal s) lt}
    \\\\
    \texttt{<:sig\_item< exception \$\_:s\$ >>}\\
    \texttt{MLast.SgExc loc s (Ploc.VaVal [])}
    \\\\
    \texttt{<:sig\_item< exception \$\_:s\$ of \$list:lt\$ >>}\\
    \texttt{MLast.SgExc loc s (Ploc.VaVal lt)}
    \\\\
    \texttt{<:sig\_item< exception \$\_:s\$ of \$\_list:lt\$ >>}\\
    \texttt{MLast.SgExc loc s lt}
  
\end{description}
\begin{description}
\item[- external]

\


    \texttt{<:sig\_item< external \$s\$ : \$t\$ = \$list:ls\$ >>}\\
    \texttt{MLast.SgExt loc (Ploc.VaVal s) t (Ploc.VaVal ls)}
    \\\\
    \texttt{<:sig\_item< external \$s\$ : \$t\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.SgExt loc (Ploc.VaVal s) t ls}
    \\\\
    \texttt{<:sig\_item< external \$\_:s\$ : \$t\$ = \$list:ls\$ >>}\\
    \texttt{MLast.SgExt loc s t (Ploc.VaVal ls)}
    \\\\
    \texttt{<:sig\_item< external \$\_:s\$ : \$t\$ = \$\_list:ls\$ >>}\\
    \texttt{MLast.SgExt loc s t ls}
  
\end{description}
\begin{description}
\item[- include]

\


    \texttt{<:sig\_item< include \$mt\$ >>}\\
    \texttt{MLast.SgInc loc mt}
  
\end{description}
\begin{description}
\item[- module rec]

\


    \texttt{<:sig\_item< module rec \$list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc (Ploc.VaVal True) (Ploc.VaVal lsmt)}
    \\\\
    \texttt{<:sig\_item< module rec \$\_list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc (Ploc.VaVal True) lsmt}
  
\end{description}
\begin{description}
\item[- module non rec]

\


    \texttt{<:sig\_item< module \$list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc (Ploc.VaVal False) (Ploc.VaVal lsmt)}
    \\\\
    \texttt{<:sig\_item< module \$\_list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc (Ploc.VaVal False) lsmt}
  
\end{description}
\begin{description}
\item[- module]

\


    \texttt{<:sig\_item< module \$flag:b\$ \$list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc (Ploc.VaVal b) (Ploc.VaVal lsmt)}
    \\\\
    \texttt{<:sig\_item< module \$flag:b\$ \$\_list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc (Ploc.VaVal b) lsmt}
    \\\\
    \texttt{<:sig\_item< module \$\_flag:b\$ \$list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc b (Ploc.VaVal lsmt)}
    \\\\
    \texttt{<:sig\_item< module \$\_flag:b\$ \$\_list:lsmt\$ >>}\\
    \texttt{MLast.SgMod loc b lsmt}
  
\end{description}
\begin{description}
\item[- module type]

\


    \texttt{<:sig\_item< module type \$s\$ = \$mt\$ >>}\\
    \texttt{MLast.SgMty loc (Ploc.VaVal s) mt}
    \\\\
    \texttt{<:sig\_item< module type \$\_:s\$ = \$mt\$ >>}\\
    \texttt{MLast.SgMty loc s mt}
  
\end{description}
\begin{description}
\item[- open]

\


    \texttt{<:sig\_item< open \$list:ls\$ >>}\\
    \texttt{MLast.SgOpn loc (Ploc.VaVal ls)}
    \\\\
    \texttt{<:sig\_item< open \$\_list:ls\$ >>}\\
    \texttt{MLast.SgOpn loc ls}
  
\end{description}
\begin{description}
\item[- type declaration]

\


    \texttt{<:sig\_item< type \$list:ltd\$ >>}\\
    \texttt{MLast.SgTyp loc (Ploc.VaVal ltd)}
    \\\\
    \texttt{<:sig\_item< type \$\_list:ltd\$ >>}\\
    \texttt{MLast.SgTyp loc ltd}
  
\end{description}
\begin{description}
\item[- ... internal use ... (1)]

\


    \texttt{<:sig\_item< \# \$str:s\$ \$list:lsil\$ >>}\\
    \texttt{MLast.SgUse loc (Ploc.VaVal s) (Ploc.VaVal lsil)}
    \\\\
    \texttt{<:sig\_item< \# \$str:s\$ \$\_list:lsil\$ >>}\\
    \texttt{MLast.SgUse loc (Ploc.VaVal s) lsil}
    \\\\
    \texttt{<:sig\_item< \# \$\_str:s\$ \$list:lsil\$ >>}\\
    \texttt{MLast.SgUse loc s (Ploc.VaVal lsil)}
    \\\\
    \texttt{<:sig\_item< \# \$\_str:s\$ \$\_list:lsil\$ >>}\\
    \texttt{MLast.SgUse loc s lsil}
  
\end{description}
\begin{description}
\item[- value]

\


    \texttt{<:sig\_item< value \$s\$ : \$t\$ >>}\\
    \texttt{MLast.SgVal loc (Ploc.VaVal s) t}
    \\\\
    \texttt{<:sig\_item< value \$\_:s\$ : \$t\$ >>}\\
    \texttt{MLast.SgVal loc s t}
  
\end{description}
\begin{description}
\item[- extra node (2)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.SgXtr loc s ot}
  
\end{description}

\noindent (1)
  Same remark as for "\texttt{str\_item}" above.


\noindent (2)
  Extra node internally used by the quotation kit "\texttt{q\_ast.cmo}"
    to build antiquotations of signature items.


\subsubsection{module\_expr}

\begin{description}
\item[- access]

\


    \texttt{<:module\_expr< \$me1\$ . \$me2\$ >>}\\
    \texttt{MLast.MeAcc loc me1 me2}
  
\end{description}
\begin{description}
\item[- application]

\


    \texttt{<:module\_expr< \$me1\$ \$me2\$ >>}\\
    \texttt{MLast.MeApp loc me1 me2}
  
\end{description}
\begin{description}
\item[- functor]

\


    \texttt{<:module\_expr< functor (\$s\$ : \$mt\$) -> \$me\$ >>}\\
    \texttt{MLast.MeFun loc (Ploc.VaVal s) mt me}
    \\\\
    \texttt{<:module\_expr< functor (\$\_:s\$ : \$mt\$) -> \$me\$ >>}\\
    \texttt{MLast.MeFun loc s mt me}
  
\end{description}
\begin{description}
\item[- struct]

\


    \texttt{<:module\_expr< struct \$list:lsi\$ end >>}\\
    \texttt{MLast.MeStr loc (Ploc.VaVal lsi)}
    \\\\
    \texttt{<:module\_expr< struct \$\_list:lsi\$ end >>}\\
    \texttt{MLast.MeStr loc lsi}
  
\end{description}
\begin{description}
\item[- module type constraint]

\


    \texttt{<:module\_expr< (\$me\$ : \$mt\$) >>}\\
    \texttt{MLast.MeTyc loc me mt}
  
\end{description}
\begin{description}
\item[- uppercase identifier]

\


    \texttt{<:module\_expr< \$uid:s\$ >>}\\
    \texttt{MLast.MeUid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:module\_expr< \$\_uid:s\$ >>}\\
    \texttt{MLast.MeUid loc s}
  
\end{description}
\begin{description}
\item[- module unpacking]

\


    \texttt{<:module\_expr< (value \$e\$) >>}\\
    \texttt{MLast.MeUnp loc e None}
    \\\\
    \texttt{<:module\_expr< (value \$e\$ : \$mt\$) >>}\\
    \texttt{MLast.MeUnp loc e (Some mt)}
  
\end{description}
\begin{description}
\item[- extra node (1)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.MeXtr loc s ot}
  
\end{description}

\noindent (1)
  Extra node internally used by the quotation kit "\texttt{q\_ast.cmo}"
    to build antiquotations of module expressions.


\subsubsection{module\_type}

\begin{description}
\item[- access]

\


    \texttt{<:module\_type< \$mt1\$ . \$mt2\$ >>}\\
    \texttt{MLast.MtAcc loc mt1 mt2}
  
\end{description}
\begin{description}
\item[- application]

\


    \texttt{<:module\_type< \$mt1\$ \$mt2\$ >>}\\
    \texttt{MLast.MtApp loc mt1 mt2}
  
\end{description}
\begin{description}
\item[- functor]

\


    \texttt{<:module\_type< functor (\$s\$ : \$mt1\$) -> \$mt2\$ >>}\\
    \texttt{MLast.MtFun loc (Ploc.VaVal s) mt1 mt2}
    \\\\
    \texttt{<:module\_type< functor (\$\_:s\$ : \$mt1\$) -> \$mt2\$ >>}\\
    \texttt{MLast.MtFun loc s mt1 mt2}
  
\end{description}
\begin{description}
\item[- lowercase identifier]

\


    \texttt{<:module\_type< \$lid:s\$ >>}\\
    \texttt{MLast.MtLid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:module\_type< \$\_lid:s\$ >>}\\
    \texttt{MLast.MtLid loc s}
  
\end{description}
\begin{description}
\item[- abstract]

\


    \texttt{<:module\_type< ' \$s\$ >>}\\
    \texttt{MLast.MtQuo loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:module\_type< ' \$\_:s\$ >>}\\
    \texttt{MLast.MtQuo loc s}
  
\end{description}
\begin{description}
\item[- signature]

\


    \texttt{<:module\_type< sig \$list:lsi\$ end >>}\\
    \texttt{MLast.MtSig loc (Ploc.VaVal lsi)}
    \\\\
    \texttt{<:module\_type< sig \$\_list:lsi\$ end >>}\\
    \texttt{MLast.MtSig loc lsi}
  
\end{description}
\begin{description}
\item[- of module expression]

\


    \texttt{<:module\_type< module type of \$me\$ >>}\\
    \texttt{MLast.MtTyo loc me}
  
\end{description}
\begin{description}
\item[- uppercase identifier]

\


    \texttt{<:module\_type< \$uid:s\$ >>}\\
    \texttt{MLast.MtUid loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:module\_type< \$\_uid:s\$ >>}\\
    \texttt{MLast.MtUid loc s}
  
\end{description}
\begin{description}
\item[- with construction]

\


    \texttt{<:module\_type< \$mt\$ with \$list:lwc\$ >>}\\
    \texttt{MLast.MtWit loc mt (Ploc.VaVal lwc)}
    \\\\
    \texttt{<:module\_type< \$mt\$ with \$\_list:lwc\$ >>}\\
    \texttt{MLast.MtWit loc mt lwc}
  
\end{description}
\begin{description}
\item[- extra node (1)]

\


    \texttt{... no representation ...}\\
    \texttt{MLast.MtXtr loc s ot}
  
\end{description}

\noindent (1)
  Extra node internally used by the quotation kit "\texttt{q\_ast.cmo}"
    to build antiquotations of module types.


\subsection{classes...}

\subsubsection{class\_expr}

\begin{description}
\item[- application]

\


    \texttt{<:class\_expr< \$ce\$ \$e\$ >>}\\
    \texttt{MLast.CeApp loc ce e}
  
\end{description}
\begin{description}
\item[- constructor]

\


    \texttt{<:class\_expr< [ \$list:lt\$ ] \$list:ls\$ >>}\\
    \texttt{MLast.CeCon loc (Ploc.VaVal ls) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:class\_expr< [ \$\_list:lt\$ ] \$list:ls\$ >>}\\
    \texttt{MLast.CeCon loc (Ploc.VaVal ls) lt}
    \\\\
    \texttt{<:class\_expr< [ \$list:lt\$ ] \$\_list:ls\$ >>}\\
    \texttt{MLast.CeCon loc ls (Ploc.VaVal lt)}
    \\\\
    \texttt{<:class\_expr< [ \$\_list:lt\$ ] \$\_list:ls\$ >>}\\
    \texttt{MLast.CeCon loc ls lt}
  
\end{description}
\begin{description}
\item[- function]

\


    \texttt{<:class\_expr< fun \$p\$ -> \$ce\$ >>}\\
    \texttt{MLast.CeFun loc p ce}
  
\end{description}
\begin{description}
\item[- let rec]

\


    \texttt{<:class\_expr< let rec \$list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc (Ploc.VaVal True) (Ploc.VaVal lpe) ce}
    \\\\
    \texttt{<:class\_expr< let rec \$\_list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc (Ploc.VaVal True) lpe ce}
  
\end{description}
\begin{description}
\item[- let non rec]

\


    \texttt{<:class\_expr< let \$list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc (Ploc.VaVal False) (Ploc.VaVal lpe) ce}
    \\\\
    \texttt{<:class\_expr< let \$\_list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc (Ploc.VaVal False) lpe ce}
  
\end{description}
\begin{description}
\item[- let]

\


    \texttt{<:class\_expr< let \$flag:b\$ \$list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc (Ploc.VaVal b) (Ploc.VaVal lpe) ce}
    \\\\
    \texttt{<:class\_expr< let \$flag:b\$ \$\_list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc (Ploc.VaVal b) lpe ce}
    \\\\
    \texttt{<:class\_expr< let \$\_flag:b\$ \$list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc b (Ploc.VaVal lpe) ce}
    \\\\
    \texttt{<:class\_expr< let \$\_flag:b\$ \$\_list:lpe\$ in \$ce\$ >>}\\
    \texttt{MLast.CeLet loc b lpe ce}
  
\end{description}
\begin{description}
\item[- object]

\


    \texttt{<:class\_expr< object \$list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc (Ploc.VaVal None) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_expr< object \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc (Ploc.VaVal None) lcsi}
    \\\\
    \texttt{<:class\_expr< object (\$p\$) \$list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc (Ploc.VaVal (Some p)) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_expr< object (\$p\$) \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc (Ploc.VaVal (Some p)) lcsi}
    \\\\
    \texttt{<:class\_expr< object \$opt:op\$ \$list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc (Ploc.VaVal op) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_expr< object \$opt:op\$ \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc (Ploc.VaVal op) lcsi}
    \\\\
    \texttt{<:class\_expr< object \$\_opt:op\$ \$list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc op (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_expr< object \$\_opt:op\$ \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CeStr loc op lcsi}
  
\end{description}
\begin{description}
\item[- class type constraint]

\


    \texttt{<:class\_expr< (\$ce\$ : \$ct\$) >>}\\
    \texttt{MLast.CeTyc loc ce ct}
  
\end{description}

\subsubsection{class\_type}

\begin{description}
\item[- access]

\


    \texttt{<:class\_type< \$ct1\$ . \$ct2\$ >>}\\
    \texttt{MLast.CtAcc loc ct1 ct2}
  
\end{description}
\begin{description}
\item[- application]

\


    \texttt{<:class\_type< \$ct1\$ \$ct2\$ >>}\\
    \texttt{MLast.CtApp loc ct1 ct2}
  
\end{description}
\begin{description}
\item[- constructor]

\


    \texttt{<:class\_type< \$ct\$ [ \$list:lt\$ ] >>}\\
    \texttt{MLast.CtCon loc ct (Ploc.VaVal lt)}
    \\\\
    \texttt{<:class\_type< \$ct\$ [ \$\_list:lt\$ ] >>}\\
    \texttt{MLast.CtCon loc ct lt}
  
\end{description}
\begin{description}
\item[- arrow]

\


    \texttt{<:class\_type< [ \$t\$ ] -> \$ct\$ >>}\\
    \texttt{MLast.CtFun loc t ct}
  
\end{description}
\begin{description}
\item[- identifier]

\


    \texttt{<:class\_type< \$id:s\$ >>}\\
    \texttt{MLast.CtIde loc (Ploc.VaVal s)}
    \\\\
    \texttt{<:class\_type< \$\_id:s\$ >>}\\
    \texttt{MLast.CtIde loc s}
  
\end{description}
\begin{description}
\item[- object]

\


    \texttt{<:class\_type< object \$list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc (Ploc.VaVal None) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_type< object \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc (Ploc.VaVal None) lcsi}
    \\\\
    \texttt{<:class\_type< object (\$t\$) \$list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc (Ploc.VaVal (Some t)) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_type< object (\$t\$) \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc (Ploc.VaVal (Some t)) lcsi}
    \\\\
    \texttt{<:class\_type< object \$opt:ot\$ \$list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc (Ploc.VaVal ot) (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_type< object \$opt:ot\$ \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc (Ploc.VaVal ot) lcsi}
    \\\\
    \texttt{<:class\_type< object \$\_opt:ot\$ \$list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc ot (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_type< object \$\_opt:ot\$ \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CtSig loc ot lcsi}
  
\end{description}

\subsubsection{class\_str\_item}

\begin{description}
\item[- type constraint]

\


    \texttt{<:class\_str\_item< type \$t1\$ = \$t2\$ >>}\\
    \texttt{MLast.CrCtr loc t1 t2}
  
\end{description}
\begin{description}
\item[- declaration list]

\


    \texttt{<:class\_str\_item< declare \$list:lcsi\$ end >>}\\
    \texttt{MLast.CrDcl loc (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_str\_item< declare \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CrDcl loc lcsi}
  
\end{description}
\begin{description}
\item[- inheritance]

\


    \texttt{<:class\_str\_item< inherit \$ce\$ >>}\\
    \texttt{MLast.CrInh loc ce (Ploc.VaVal None)}
    \\\\
    \texttt{<:class\_str\_item< inherit \$ce\$ \$opt:Some s\$ >>}\\
    \texttt{MLast.CrInh loc ce (Ploc.VaVal (Some s))}
    \\\\
    \texttt{<:class\_str\_item< inherit \$ce\$ \$opt:os\$ >>}\\
    \texttt{MLast.CrInh loc ce (Ploc.VaVal os)}
    \\\\
    \texttt{<:class\_str\_item< inherit \$ce\$ \$\_opt:os\$ >>}\\
    \texttt{MLast.CrInh loc ce os}
  
\end{description}
\begin{description}
\item[- initialization]

\


    \texttt{<:class\_str\_item< initializer \$e\$ >>}\\
    \texttt{MLast.CrIni loc e}
  
\end{description}
\begin{description}
\item[- method]

\


    \texttt{<:class\_str\_item< method! private \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! private \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal True) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method! \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal False) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) (Ploc.VaVal b2) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method! \$\_priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal True) b2 s ot e}
    \\\\
    \texttt{<:class\_str\_item< method private \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method private \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method private \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method private \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method private \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method private \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method private \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method private \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal True) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal False) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) (Ploc.VaVal b2) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal False) b2 s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ private \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal True) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal False) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) (Ploc.VaVal b2) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc (Ploc.VaVal b1) b2 s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ private \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal True) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal False) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 (Ploc.VaVal b2) s ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 (Ploc.VaVal s) (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 (Ploc.VaVal s) (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 (Ploc.VaVal s) (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 (Ploc.VaVal s) ot e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 s (Ploc.VaVal None) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ : \$t\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 s (Ploc.VaVal (Some t)) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ \$opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 s (Ploc.VaVal ot) e}
    \\\\
    \texttt{<:class\_str\_item< method \$\_!:b1\$ \$\_priv:b2\$ \$\_lid:s\$ \$\_opt:ot\$ = \$e\$ >>}\\
    \texttt{MLast.CrMth loc b1 b2 s ot e}
  
\end{description}
\begin{description}
\item[- value]

\


    \texttt{<:class\_str\_item< value! mutable \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) (Ploc.VaVal True) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value! mutable \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) (Ploc.VaVal True) s e}
    \\\\
    \texttt{<:class\_str\_item< value! \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) (Ploc.VaVal False) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value! \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) (Ploc.VaVal False) s e}
    \\\\
    \texttt{<:class\_str\_item< value! \$flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) (Ploc.VaVal b2) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value! \$flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) (Ploc.VaVal b2) s e}
    \\\\
    \texttt{<:class\_str\_item< value! \$\_flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) b2 (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value! \$\_flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal True) b2 s e}
    \\\\
    \texttt{<:class\_str\_item< value mutable \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) (Ploc.VaVal True) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value mutable \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) (Ploc.VaVal True) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) (Ploc.VaVal False) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) (Ploc.VaVal False) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) (Ploc.VaVal b2) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) (Ploc.VaVal b2) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) b2 (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal False) b2 s e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ mutable \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) (Ploc.VaVal True) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ mutable \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) (Ploc.VaVal True) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) (Ploc.VaVal False) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) (Ploc.VaVal False) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ \$flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) (Ploc.VaVal b2) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ \$flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) (Ploc.VaVal b2) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ \$\_flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) b2 (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$!:b1\$ \$\_flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc (Ploc.VaVal b1) b2 s e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ mutable \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 (Ploc.VaVal True) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ mutable \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 (Ploc.VaVal True) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 (Ploc.VaVal False) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 (Ploc.VaVal False) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ \$flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 (Ploc.VaVal b2) (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ \$flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 (Ploc.VaVal b2) s e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ \$\_flag:b2\$ \$lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 b2 (Ploc.VaVal s) e}
    \\\\
    \texttt{<:class\_str\_item< value \$\_!:b1\$ \$\_flag:b2\$ \$\_lid:s\$ = \$e\$ >>}\\
    \texttt{MLast.CrVal loc b1 b2 s e}
  
\end{description}
\begin{description}
\item[- virtual value]

\


    \texttt{<:class\_str\_item< value virtual mutable \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc (Ploc.VaVal True) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< value virtual mutable \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc (Ploc.VaVal True) s t}
    \\\\
    \texttt{<:class\_str\_item< value virtual \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc (Ploc.VaVal False) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< value virtual \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc (Ploc.VaVal False) s t}
    \\\\
    \texttt{<:class\_str\_item< value virtual \$flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc (Ploc.VaVal b) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< value virtual \$flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc (Ploc.VaVal b) s t}
    \\\\
    \texttt{<:class\_str\_item< value virtual \$\_flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc b (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< value virtual \$\_flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVav loc b s t}
  
\end{description}
\begin{description}
\item[- virtual method]

\


    \texttt{<:class\_str\_item< method virtual private \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc (Ploc.VaVal True) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< method virtual private \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc (Ploc.VaVal True) s t}
    \\\\
    \texttt{<:class\_str\_item< method virtual \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc (Ploc.VaVal False) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< method virtual \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc (Ploc.VaVal False) s t}
    \\\\
    \texttt{<:class\_str\_item< method virtual \$flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc (Ploc.VaVal b) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< method virtual \$flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc (Ploc.VaVal b) s t}
    \\\\
    \texttt{<:class\_str\_item< method virtual \$\_flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc b (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_str\_item< method virtual \$\_flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CrVir loc b s t}
  
\end{description}

\subsubsection{class\_sig\_item}

\begin{description}
\item[- type constraint]

\


    \texttt{<:class\_sig\_item< type \$t1\$ = \$t2\$ >>}\\
    \texttt{MLast.CgCtr loc t1 t2}
  
\end{description}
\begin{description}
\item[- declare]

\


    \texttt{<:class\_sig\_item< declare \$list:lcsi\$ end >>}\\
    \texttt{MLast.CgDcl loc (Ploc.VaVal lcsi)}
    \\\\
    \texttt{<:class\_sig\_item< declare \$\_list:lcsi\$ end >>}\\
    \texttt{MLast.CgDcl loc lcsi}
  
\end{description}
\begin{description}
\item[- inheritance]

\


    \texttt{<:class\_sig\_item< inherit \$ct\$ >>}\\
    \texttt{MLast.CgInh loc ct}
  
\end{description}
\begin{description}
\item[- method]

\


    \texttt{<:class\_sig\_item< method private \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc (Ploc.VaVal True) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method private \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc (Ploc.VaVal True) s t}
    \\\\
    \texttt{<:class\_sig\_item< method \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc (Ploc.VaVal False) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc (Ploc.VaVal False) s t}
    \\\\
    \texttt{<:class\_sig\_item< method \$flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc (Ploc.VaVal b) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method \$flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc (Ploc.VaVal b) s t}
    \\\\
    \texttt{<:class\_sig\_item< method \$\_flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc b (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method \$\_flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgMth loc b s t}
  
\end{description}
\begin{description}
\item[- value]

\


    \texttt{<:class\_sig\_item< value mutable \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc (Ploc.VaVal True) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< value mutable \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc (Ploc.VaVal True) s t}
    \\\\
    \texttt{<:class\_sig\_item< value \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc (Ploc.VaVal False) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< value \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc (Ploc.VaVal False) s t}
    \\\\
    \texttt{<:class\_sig\_item< value \$flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc (Ploc.VaVal b) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< value \$flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc (Ploc.VaVal b) s t}
    \\\\
    \texttt{<:class\_sig\_item< value \$\_flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc b (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< value \$\_flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVal loc b s t}
  
\end{description}
\begin{description}
\item[- virtual method]

\


    \texttt{<:class\_sig\_item< method virtual private \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc (Ploc.VaVal True) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual private \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc (Ploc.VaVal True) s t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc (Ploc.VaVal False) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc (Ploc.VaVal False) s t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual \$flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc (Ploc.VaVal b) (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual \$flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc (Ploc.VaVal b) s t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual \$\_flag:b\$ \$lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc b (Ploc.VaVal s) t}
    \\\\
    \texttt{<:class\_sig\_item< method virtual \$\_flag:b\$ \$\_lid:s\$ : \$t\$ >>}\\
    \texttt{MLast.CgVir loc b s t}
  
\end{description}

\subsection{other}

\subsubsection{type\_decl}

\noindent What is after 'type' or 'and' in a type declaration.

\

\noindent The type "\texttt{type\_decl}" is a record type corresponding to
  a type declaration. Its definition is:

\begin{verbatim}
  type type_decl =
    { tdNam : (loc * Ploc.vaval string);
      tdPrm : Ploc.vala (list type_var);
      tdPrv : Ploc.vala bool;
      tdDef : ctyp;
      tdCon : Ploc.vala (list (ctyp * ctyp)) }
  ;
\end{verbatim}

\noindent The field "\texttt{tdNam}" is the type identifier (together with its
  location in the source).

\

\noindent The field "\texttt{tdPrm}" is the list of its possible parameters.

\

\noindent The field "\texttt{tdPrv}" tells if the type is private or not.

\

\noindent The field "\texttt{tdDef}" is the definition of the type.

\

\noindent The field "\texttt{tdCon}" is the possible list of type constraints.

\begin{description}
\item[\ ]

\


    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = private \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = private \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = \$priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = \$priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = \$\_priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$list:ltv\$ = \$\_priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = private \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = private \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = \$priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = \$priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = \$\_priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$tp:ls\$ \$\_list:ltv\$ = \$\_priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = Ploc.VaVal ls; MLast.tdPrm = ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = private \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = private \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = \$priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = \$priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = \$\_priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$list:ltv\$ = \$\_priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = Ploc.VaVal ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = private \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = private \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal True; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal False; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = \$priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = \$priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = Ploc.VaVal b; MLast.tdDef = t; MLast.tdCon = ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = \$\_priv:b\$ \$t\$ \$list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = Ploc.VaVal ltt\}}
    \\\\
    \texttt{<:type\_decl< \$\_tp:ls\$ \$\_list:ltv\$ = \$\_priv:b\$ \$t\$ \$\_list:ltt\$ >>}\\
    \texttt{\{MLast.tdNam = ls; MLast.tdPrm = ltv; MLast.tdPrv = b; MLast.tdDef = t; MLast.tdCon = ltt\}}
  
\end{description}

\subsubsection{with\_constr}

\noindent "With" possibly following a module type.

\begin{description}
\item[- with module]

\


    \texttt{<:with\_constr< module \$list:ls\$ = \$me\$ >>}\\
    \texttt{MLast.WcMod loc (Ploc.VaVal ls) me}
    \\\\
    \texttt{<:with\_constr< module \$\_list:ls\$ = \$me\$ >>}\\
    \texttt{MLast.WcMod loc ls me}
  
\end{description}
\begin{description}
\item[- with module substitution]

\


    \texttt{<:with\_constr< module \$list:ls\$ := \$me\$ >>}\\
    \texttt{MLast.WcMos loc (Ploc.VaVal ls) me}
    \\\\
    \texttt{<:with\_constr< module \$\_list:ls\$ := \$me\$ >>}\\
    \texttt{MLast.WcMos loc ls me}
  
\end{description}
\begin{description}
\item[- with type]

\


    \texttt{<:with\_constr< type \$list:ls\$ \$list:ltv\$ = private \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) (Ploc.VaVal ltv) (Ploc.VaVal True) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$list:ltv\$ = \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) (Ploc.VaVal ltv) (Ploc.VaVal False) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$list:ltv\$ = \$flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) (Ploc.VaVal ltv) (Ploc.VaVal b) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$list:ltv\$ = \$\_flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) (Ploc.VaVal ltv) b t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$\_list:ltv\$ = private \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) ltv (Ploc.VaVal True) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$\_list:ltv\$ = \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) ltv (Ploc.VaVal False) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$\_list:ltv\$ = \$flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) ltv (Ploc.VaVal b) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$\_list:ltv\$ = \$\_flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc (Ploc.VaVal ls) ltv b t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$list:ltv\$ = private \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls (Ploc.VaVal ltv) (Ploc.VaVal True) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$list:ltv\$ = \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls (Ploc.VaVal ltv) (Ploc.VaVal False) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$list:ltv\$ = \$flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls (Ploc.VaVal ltv) (Ploc.VaVal b) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$list:ltv\$ = \$\_flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls (Ploc.VaVal ltv) b t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$\_list:ltv\$ = private \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls ltv (Ploc.VaVal True) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$\_list:ltv\$ = \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls ltv (Ploc.VaVal False) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$\_list:ltv\$ = \$flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls ltv (Ploc.VaVal b) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$\_list:ltv\$ = \$\_flag:b\$ \$t\$ >>}\\
    \texttt{MLast.WcTyp loc ls ltv b t}
  
\end{description}
\begin{description}
\item[- with type substitution]

\


    \texttt{<:with\_constr< type \$list:ls\$ \$list:ltv\$ := \$t\$ >>}\\
    \texttt{MLast.WcTys loc (Ploc.VaVal ls) (Ploc.VaVal ltv) t}
    \\\\
    \texttt{<:with\_constr< type \$list:ls\$ \$\_list:ltv\$ := \$t\$ >>}\\
    \texttt{MLast.WcTys loc (Ploc.VaVal ls) ltv t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$list:ltv\$ := \$t\$ >>}\\
    \texttt{MLast.WcTys loc ls (Ploc.VaVal ltv) t}
    \\\\
    \texttt{<:with\_constr< type \$\_list:ls\$ \$\_list:ltv\$ := \$t\$ >>}\\
    \texttt{MLast.WcTys loc ls ltv t}
  
\end{description}

\subsubsection{poly\_variant}

\noindent Polymorphic variants.

\begin{description}
\item[- constructor]

\


    \texttt{<:poly\_variant< `\$s\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal True) (Ploc.VaVal [])}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \& \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal True) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \& \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal True) lt}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal False) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal False) lt}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \$flag:b\$ \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal b) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \$flag:b\$ \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) (Ploc.VaVal b) lt}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \$\_flag:b\$ \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) b (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$s\$ of \$\_flag:b\$ \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc (Ploc.VaVal s) b lt}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal True) (Ploc.VaVal [])}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \& \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal True) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \& \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal True) lt}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal False) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal False) lt}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \$flag:b\$ \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal b) (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \$flag:b\$ \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s (Ploc.VaVal b) lt}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \$\_flag:b\$ \$list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s b (Ploc.VaVal lt)}
    \\\\
    \texttt{<:poly\_variant< `\$\_:s\$ of \$\_flag:b\$ \$\_list:lt\$ >>}\\
    \texttt{MLast.PvTag loc s b lt}
  
\end{description}
\begin{description}
\item[- type]

\


    \texttt{<:poly\_variant< \$t\$ >>}\\
    \texttt{MLast.PvInh loc t}
  
\end{description}

\section{Nodes without quotations}

\noindent Some types defined in the AST tree module "\texttt{MLast}" don't
  have an associated quotation. They are:

\begin{itemize}
\item \texttt{type\_var}
\item \texttt{class\_infos}
\end{itemize}

\subsection{type\_var}

\noindent The type "\texttt{type\_var}" is defined as:

\begin{verbatim}
  type type_var = (Ploc.vala string * (bool * bool));
\end{verbatim}

\noindent The first boolean is "\texttt{True}" if the type variable is
  prefixed by "\texttt{+}" ("plus" sign). The second boolean is
  "\texttt{True}" if the type variable is prefixed by "\texttt{-}"
  ("minus" sign).

\subsection{class\_infos}

\noindent The type "\texttt{class\_infos}" is a record type parametrized with
  a type variable. It is common to:

\begin{itemize}
\item the "class declaration" ("\texttt{class ...}" as structure item),
    the type variable being "\texttt{class\_expr}",
\item the "class description" ("\texttt{class ...}" as signature item),
    the type variable being "\texttt{class\_type}",
\item the "class type declaration" ("\texttt{class type ...}"), the
    type variable being "\texttt{class\_type}".
\end{itemize}

\noindent It is defined as:

\begin{verbatim}
  type class_infos 'a =
    { ciLoc : loc;
      ciVir : Ploc.vala bool;
      ciPrm : (loc * Ploc.vala (list type_var));
      ciNam : Ploc.vala string;
      ciExp : 'a }
  ;
\end{verbatim}

\noindent The field "\texttt{ciLoc}" is the location of the whole definition.

\

\noindent The field "\texttt{ciVir}" tells whether the type is virtual or not.

\

\noindent The field "\texttt{ciPrm}" is the list of its possible parameters.

\

\noindent The field "\texttt{ciNam}" is the class identifier.

\

\noindent The field "\texttt{ciExp}" is the class definition, depending of its
  kind.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Syntax tree quotations in user syntax}

\noindent The quotation kit "\texttt{q\_ast.cmo}" allows to use syntax tree
  quotations in user syntax. It fully works only in "strict" mode. In
  "transitional" mode, there is no way to use antiquotations, which
  restricts its utility.

\

\noindent If this kit is loaded, when a quotation of syntax tree is found,
  the current OCaml language parser is called. Then, the resulting
  tree is reified (except the antiquotations) to represent \emph{the
  syntax tree of the syntax tree}.

\section{Antiquotations}

\noindent The OCaml langage parser used, and its possible extensions, must
  have been built to allow the places of the antiquotations. The
  symbols enclosed by the meta-symbol "\texttt{V}" (see the chapter
  about extensible grammars, section
  "symbols"), define where antiquotations can take place.

\

\noindent There is no need to specify antiquotations for the main types
  defined in the AST tree module ("\texttt{MLast}"): "\texttt{expr}",
  "\texttt{patt}", "\texttt{expr}", "\texttt{str\_item}",
  "\texttt{sig\_item}", and so on. All syntax parts of these types are
  automatically antiquotable.

\

\noindent For example, in Camlp5 sources, the grammar rule defining the
  "let..in" statement is:

\begin{verbatim}
   "let"; r = V (FLAG "rec") "flag" "opt";
    l = V (LIST1 let_binding SEP "and"); "in"; x = expr
\end{verbatim}

\noindent All symbols of these rules, except the keywords, are antiquotable:

\begin{itemize}
\item The "rec" flag, because enclosed by the "V" meta symbol. The two
    strings which follow it gives the possible antiquotation kinds:
    "flag" (the normal antiquotation kind) and "opt" (kept by backward
    compatibility, but not recommended). It is therefore possible to
    antiquote it as: "\texttt{\$flag:...\$}" or "\texttt{\$opt:...\$}"
    where the "\texttt{...}" is an expression or a pattern depending
    on the position of the enclosing quotation
\item The binding list is also antiquotable, since it is also enclosed
    by the "V" meta symbol. Its antiquotation kind is "list" (the
    default when the meta symbol parameter is a list). It is therefore
    possible to write "\texttt{\$list:...\$}" at the place of the
    binding list.
\item The expression after the "in" is also antiquotable, because it
    belongs to the main types defined in the module "\texttt{MLast}".
\end{itemize}

\noindent In that example, the variable "\texttt{r}" is of type "\texttt{Ploc.vala
  bool}", the variable "\texttt{r}" of type "\texttt{Ploc.vala (list
  (patt * expr))}" and the variable "\texttt{x}" of type
  "\texttt{MLast.expr}".

\

\noindent ... to be completed ...

\clearemptydoublepage

\pagestyle{fancy}\chapter{The Pcaml module}

\noindent All about language parsing entries, language printing functions,
  quotation management at parsing time, extensible directives, extensible
  options, and generalities about Camlp5.


\section{Language parsing}

\subsection{Main parsing functions}

\noindent The two functions below are called when parsing an interface (.mli
  file) or an implementation (.ml file) to build the syntax tree; the
  returned list contains the phrases (signature items or structure
  items) and their locations; the boolean tells whether the parser has
  encountered a directive; in this case, since the directive may
  change the syntax, the parsing stops, the directive is evaluated,
  and this function is called again.\\These functions are
  references, because they can be changed to use another technology
  than the Camlp5 extended grammars. By default, they use the grammars
  entries [implem] and [interf] defined below.

\begin{verbatim}
value parse_interf :
  ref (Stream.t char -> (list (MLast.sig_item * MLast.loc) * bool));
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Function called when parsing an interface (".mli") file
\end{description}

\begin{verbatim}
value parse_implem :
  ref (Stream.t char -> (list (MLast.str_item * MLast.loc) * bool));
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Function called when parsing an implementation (".ml") file
\end{description}

\subsection{Grammar}

\begin{description}
\item[\texttt{value gram : Grammar.g;}]

\

Grammar variable of the language.
\end{description}

\subsection{Entries}

\noindent Grammar entries which return syntax
  trees. These are set by the parsing kit of the current syntax,
  through the statement EXTEND. They
  are usable by other possible user syntax extensions.

\begin{description}
\item[\texttt{value expr : Grammar.Entry.e MLast.expr;}]

\

Expressions.
\item[\texttt{value patt : Grammar.Entry.e MLast.patt;}]

\

Patterns.
\item[\texttt{value ctyp : Grammar.Entry.e MLast.ctyp;}]

\

Types.
\end{description}

\begin{description}
\item[\texttt{value sig\_item : Grammar.Entry.e MLast.sig\_item;}]

\

Signature items, i.e. items between "\texttt{sig}" and
    "\texttt{end}", or inside an interface (".mli") file.
\item[\texttt{value str\_item : Grammar.Entry.e MLast.str\_item;}]

\

Structure items, i.e. items between "\texttt{struct}" and
    "\texttt{end}", or inside an implementation (".ml") file.
\end{description}

\begin{description}
\item[\texttt{value module\_type : Grammar.Entry.e MLast.module\_type;}]

\

Module types, e.g. signatures, functors, identifiers.
\item[\texttt{value module\_expr : Grammar.Entry.e MLast.module\_expr;}]

\

Module expressions, e.g. structures, functors, identifiers.
\end{description}

\begin{description}
\item[\texttt{value let\_binding : Grammar.Entry.e (MLast.patt *
      MLast.expr);}]

\

Specific entry for the "let binding", i.e. the association
    "let pattern = expression".
\item[\texttt{value type\_declaration : Grammar.Entry.e
      MLast.type\_decl;}]

\

Specific entry for the "type declaration", i.e. the association
    "type name = type-expression"
\end{description}

\begin{description}
\item[\texttt{value class\_sig\_item : Grammar.Entry.e
      MLast.class\_sig\_item;}]

\

Class signature items, i.e. items of class objects types.
\item[\texttt{value class\_str\_item : Grammar.Entry.e
      MLast.class\_str\_item;}]

\

Class structure items, i.e. items of class objects.
\item[\texttt{value class\_type : Grammar.Entry.e MLast.class\_type;}]

\

Class types, e.g. object types, class types functions,
    identifiers. 
\item[\texttt{value class\_expr : Grammar.Entry.e MLast.class\_expr;}]

\

Class expressions, e.g. objects, class functions, identifiers.
\end{description}

\begin{description}
\item[\texttt{value interf : Grammar.Entry.e (list (MLast.sig\_item * MLast.loc) * bool);}]

\

Interface, i.e. files with extension ".mli". The location is the
    top of the tree. The boolean says whether the parsing stopped
    because of the presence of a directive (which potentially could
    change the syntax).
\item[\texttt{value implem : Grammar.Entry.e (list (MLast.str\_item * MLast.loc) * bool);}]

\

Implementation, i.e. files with extension ".ml". Same remark
    about the location and the boolean.
\item[\texttt{value top\_phrase : Grammar.Entry.e (option
      MLast.str\_item);}]

\

Phrases of the OCaml interactive toplevel. Return "None" in case
    of end of file.
\item[\texttt{value use\_file : Grammar.Entry.e (list MLast.str\_item *
      bool);}]

\

Phrases in files included by the directive "\texttt{\#use}". The
    boolean indicates whether the parsing stopped because of a
    directive (as for "\texttt{interf}" above).
\end{description}

\section{Language printing}

\subsection{Main printing functions}

\noindent The two function below are called when printing an interface (.mli
  file) of an implementation (.ml file) from the syntax tree; the list
  is the result of the corresponding parsing function.\\These
  functions are references, to allow using other technologies than the
  Camlp5 extended printers.

\begin{verbatim}
value print_interf :
  ref (list (MLast.sig_item * MLast.loc) -> unit);
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Function called when printing an interface (".mli") file
\end{description}

\begin{verbatim}
value print_implem :
  ref (list (MLast.str_item * MLast.loc) -> unit);
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
  Function called when printing an implementation (".ml") file
\end{description}

\noindent By default, these functions fail. The printer kit
  "\texttt{pr\_dump.cmo}" (loaded by most Camlp5 commands) sets them to
  functions dumping the syntax tree in binary (for the OCaml
  compiler). The pretty printer kits, such as "\texttt{pr\_r.cmo}" and
  "\texttt{pr\_o.cmo}" set them to functions calling the predefined
  printers (see next section).

\subsection{Printers}

\noindent Printers taking syntax trees as
  parameters and returning pretty printed strings. These are set by
  the printing kits, through the
  statement EXTEND\_PRINTER. They are
  usable by other possible user printing extensions.

\begin{description}
\item[\texttt{value pr\_expr : Eprinter.t MLast.expr;}]

\

Expressions.
\item[\texttt{value pr\_patt : Eprinter.t MLast.patt;}]

\

Patterns.
\item[\texttt{value pr\_ctyp : Eprinter.t MLast.ctyp;}]

\

Types.
\end{description}

\begin{description}
\item[\texttt{value pr\_sig\_item : Eprinter.t MLast.sig\_item;}]

\

Signature items, i.e. items between "\texttt{sig}" and
    "\texttt{end}", or inside an interface (".mli") file.
\item[\texttt{value pr\_str\_item : Eprinter.t MLast.str\_item;}]

\

Structure items, i.e. items between "\texttt{struct}" and
    "\texttt{end}", or inside an implementation (".ml") file.
\end{description}

\begin{description}
\item[\texttt{value pr\_module\_type : Eprinter.t MLast.module\_type;}]

\

Module types, e.g. signatures, functors, identifiers.
\item[\texttt{value pr\_module\_expr : Eprinter.t MLast.module\_expr;}]

\

Module expressions, e.g. structures, functors, identifiers.
\end{description}

\begin{description}
\item[\texttt{value pr\_class\_sig\_item : Eprinter.t
      MLast.class\_sig\_item;}]

\

Class signature items, i.e. items of class objects types.
\item[\texttt{value pr\_class\_str\_item : Eprinter.t
      MLast.class\_str\_item;}]

\

Class structure items, i.e. items of class objects.
\item[\texttt{value pr\_class\_type : Eprinter.t MLast.class\_type;}]

\

Class types, e.g. object types, class types functions,
    identifiers. 
\item[\texttt{value pr\_class\_expr : Eprinter.t MLast.class\_expr;}]

\

Class expressions, e.g. objects, class functions, identifiers.
\end{description}

\section{Quotation management}

\begin{description}
\item[\texttt{value handle\_expr\_quotation : MLast.loc -> (string * string)
      -> MLast.expr;}]

\

Called in the semantic actions of the rules parsing a quotation
    in position of expression.
\item[\texttt{value handle\_patt\_quotation : MLast.loc -> (string * string)
      -> MLast.patt;}]

\

Called in the semantic actions of the rules parsing a quotation
    in position of pattern.
\end{description}

\begin{description}
\item[\texttt{value quotation\_dump\_file : ref (option string);}]

\

"\texttt{Pcaml.quotation\_dump\_file}" optionally tells the
    compiler to dump the result of an expander (of kind "generating a
    string") if this result is syntactically incorrect. If
    "\texttt{None}" (default), this result is not dumped. If "\texttt{Some
      fname}", the result is dumped in the file "\texttt{fname}".
    The same effect can be done with the option "\texttt{-QD}" of
    Camlp5 commands.
\item[\texttt{value quotation\_location : unit -> Ploc.t;}]

\

While expanding a quotation, returns the location of the
    quotation text (between the quotation quotes) in the source;
    raises "\texttt{Failure}" if not in the context of a quotation
    expander.
\end{description}

\section{Extensible directives and options}

\begin{description}
\item[\texttt{type directive\_fun = option MLast.expr -> unit;}]

\

The type of functions called to treat a directive with its
    syntactic parameter. Directives act by side effect.
\item[\texttt{value add\_directive : string -> directive\_fun -> unit;}]

\

Add a new directive.
\item[\texttt{value find\_directive : string -> directive\_fun;}]

\

Find the function associated with a directive. Raises
    "\texttt{Not\_found}" if the directive does not exists.
\end{description}

\begin{description}
\item[\texttt{value add\_option : string -> Arg.spec -> string -> unit;}]

\

Add an option to the command line of the Camlp5 command.
\end{description}

\section{Equalities over syntax trees}

\noindent These equalities skip the locations.

\begin{verbatim}
value eq_expr : MLast.expr -> MLast.expr -> bool;
value eq_patt : MLast.patt -> MLast.patt -> bool;
value eq_ctyp : MLast.ctyp -> MLast.ctyp -> bool;
value eq_str_item : MLast.str_item -> MLast.str_item -> bool;
value eq_sig_item : MLast.sig_item -> MLast.sig_item -> bool;
value eq_module_expr : MLast.module_expr -> MLast.module_expr -> bool;
value eq_module_type : MLast.module_type -> MLast.module_type -> bool;
value eq_class_sig_item : MLast.class_sig_item -> MLast.class_sig_item -> bool;
value eq_class_str_item : MLast.class_str_item -> MLast.class_str_item -> bool;
value eq_class_type : MLast.class_type -> MLast.class_type -> bool;
value eq_class_expr : MLast.class_expr -> MLast.class_expr -> bool;
\end{verbatim}

\section{Generalities}

\begin{description}
\item[\texttt{value version : string;}]

\

The current version of Camlp5.
\end{description}

\begin{description}
\item[\texttt{value syntax\_name : ref string;}]

\

The name of the current syntax. Set by the loaded syntax kit.
\end{description}

\begin{description}
\item[\texttt{value input\_file : ref string;}]

\

The file currently being parsed.
\end{description}

\begin{description}
\item[\texttt{value output\_file : ref (option string);}]

\

The output file, stdout if None (default).
\end{description}

\begin{description}
\item[\texttt{value no\_constructors\_arity : ref bool;}]

\

True if the current syntax does not generate constructor arity,
    which is the case of the normal syntax, and not of the revised
    one. This has an impact when converting Camlp5 syntax tree into
    OCaml compiler syntax tree.
\end{description}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Directives}

\noindent Directives in normal or revised syntax are statements at top level,
  or, more generally, as signature items or structure items, which
  stops the preprocessor for evaluate things - which can change the
  behaviour of the preprocessor, for example to add syntax, load
  syntax extensions and so on. After the directive is evaluated,
  the parsing resumes.

\

\noindent Directives begin with '\#', followed by an identifier, and,
  optionnally by an expression. They are usable in source files the
  and generally in the ocaml toplevel too.

\

\noindent Four predefined directives exist: \#load, \#directory, \#option and
  \#use. It is also possible to add other directives. An example of
  that is the parsing kit pa\_pragma.cmo
  which adds a new directive \#pragma.


\section{Predefined directives}

\noindent The predefined directives are:

\subsection{\#load "name"}

\noindent Loads an object file (ocaml cmo or cma file) in the core,
  evaluating it.  This is typically to be used in the ocaml toplevel
  to add an syntax extension kit.

\

\noindent For example, in the toplevel, loading
  the quotation expander
  of ocaml syntax trees:

\begin{verbatim}
  # #load "q_MLast.cmo";

  # value loc = Ploc.dummy;
  value loc : Ploc.t = <abstr>

  # <:expr< fun x -> x >>;
  - : MLast.expr =
  MLast.ExFun <abstr>
    (Ploc.VaVal
       [(MLast.PaLid <abstr> (Ploc.VaVal "x"), Ploc.VaVal None,
         MLast.ExLid <abstr> (Ploc.VaVal "x"))])
\end{verbatim}

\noindent In a source file, the '\#load' directive is equivalent to put the
  object file as camlp5 parameter among the 'load options':

\begin{verbatim}
   $ cat myfile.ml

   #load "pa_extend.cmo";
   value g = Grammar.gcreate (Plexer.gmake ());
   value e = Grammar.Entry.create g "e";

   EXTEND e: [[ i = INT -> i ]]; END;

   $ ocamlc -pp camlp5r -I +camlp5 -c myfile.ml
\end{verbatim}

\noindent which is equivalent to, without using '\#load':

\begin{verbatim}
   $ cat myfile2.ml

   value g = Grammar.gcreate (Plexer.gmake ());
   value e = Grammar.Entry.create g "e";

   EXTEND e: [[ i = INT -> i ]]; END;
\end{verbatim}

\noindent and compiling it like this:

\begin{verbatim}
   $ ocamlc -pp 'camlp5r pa_extend.cmo' -I +camlp5 -c myfile2.ml
\end{verbatim}

\subsection{\#directory "name"}

\noindent Adds a new directory in the camlp5 path searching for loaded files
  (using the directive \#load above). This is equivalent to the option
  '-I' of the camlp5 command. See the camlp5 man page.

\subsection{\#use "name"}

\noindent Loads a source file name. Useful in the ocaml toplevel to test a
  source file.

\subsection{\#option "option"}

\noindent Adds an option as if it were added in camlp5 command line (to be
  used in a source file, not in the ocaml toplevel). Implemented
  only on options without an extra parameter.

\

\noindent For example, the syntax
  kit pa\_extend.cmo adds an option named
  '-split\_ext'. This can be viewed through the command:

\begin{verbatim}
  camlp5r pa_extend.cmo -help
\end{verbatim}

\noindent Thanks to the directive '\#option', the following command in the
  shell:

\begin{verbatim}
  $ camlp5r pa_extend.cmo -split_ext file.ml
\end{verbatim}

\noindent can be used only as:

\begin{verbatim}
  $ camlp5r file.ml
\end{verbatim}

\noindent providing the file starts with:

\begin{verbatim}
  #load "pa_extend.cmo";
  #option "-split_ext";
\end{verbatim}

\section{User directives}

\noindent It is possible to add any extra directive. The syntax
  kit pragma.cmo, for example, adds a
  directive named '\#pragma'.

\

\noindent A user syntax kit can add its directives using the function
  "add\_directive" of the module Pcaml.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Extensions of syntax}

\noindent Camlp5 allows one to extend the syntax of the OCaml language, and
  even change the entire syntax.

\

\noindent It uses for that one of its parsing tools:
  the extensible grammars.

\

\noindent To understand the whole syntax in the examples given in this
  chapter, it is good to understand this parsing tool (the extensible
  grammars), but we shall try to give some minimal explanations to
  allow the reader to follow them.

\

\noindent A syntax extension is an OCaml object file (ending with ".cmo" or
  ".cma") which is loaded inside Camlp5. The source of this file uses
  calls to the specific statement EXTEND applied to entries defined in
  the Camlp5 module "\texttt{Pcaml}".


\section{Entries}

\noindent The grammar of OCaml contains several entries, corresponding to the
  major notions of the language, which are modifiable this way, and
  even erasable. They are defined in this module "\texttt{Pcaml}".

\

\noindent Most important entries:

\begin{itemize}
\item \texttt{expr}: the expressions.
\item \texttt{patt}: the patterns.
\item \texttt{ctyp}: the types.
\item \texttt{str\_item}: the structure items, i.e. the items between
    "struct" and "end", and the toplevel phrases in a ".ml" file.
\item \texttt{sig\_item}: the signature items, i.e. the items between
    "sig" and "end", and the toplevel phrases in a ".mli" file.
\item \texttt{module\_expr}: the module expressions.
\item \texttt{module\_type}: the module types.
\end{itemize}

\noindent Entries of object programming:

\begin{itemize}
\item \texttt{class\_expr}: the class expressions.
\item \texttt{class\_type}: the class types.
\item \texttt{class\_str\_item}: the objects items.
\item \texttt{class\_sig\_item}: the objects types items.
\end{itemize}

\noindent Main entries of files and interactive toplevel parsing:

\begin{itemize}
\item \texttt{implem}: the phrases that can be found in a ".ml" file.
\item \texttt{interf}: the phrases that can be found in a ".mli" file.
\item \texttt{top\_phrase}: the phrases of the interactive toplevel.
\item \texttt{use\_file}: the phrases that can be found in a file
    included by the directive "use".
\end{itemize}

\noindent Extra useful entries also accessible:

\begin{itemize}
\item \texttt{let\_binding}: the bindings "expression = pattern" found in
    the "let" statement.
\item \texttt{type\_declaration}: the bindings "name = type" found in
    the "type" statement.
\end{itemize}

\section{Syntax tree quotations}

\noindent A grammar rule is a list of rule symbols followed by the semantic
  action, i.e. the result of the rule. This result is a syntax tree,
  whose type is the type of the extended entry. The description of the
  types of the syntax tree are in the Camlp5 module
  "\texttt{MLast}".

\

\noindent There is however a simpler way to make values of these syntax tree
  types: the system quotations (see chapters
  about quotations
  and syntax tree). With this system, it is
  possible to represent syntax tree in concrete syntax, between
  specific parentheses, namely "\texttt{<<}" and
  "\texttt{>>}", or between "\texttt{<:name<}" and
  "\texttt{>>}".

\

\noindent For example, the syntax node of the "if" statement is, normally:

\begin{verbatim}
  MLast.ExIfe loc e1 e2 e3
\end{verbatim}

\noindent where loc is the source location, and e1, e2, e3 are the
  expressions constituting the if statement. With quotations, it is
  possible to write it like this (which is stricly equivalent because
  this is evaluated at parse time, not execution time):

\begin{verbatim}
  <:expr< if $e1$ then $e2$ else $e3$ >>
\end{verbatim}

\noindent With quotations, it is possible to build pieces of program as
  complex as desired. See the chapter
  about syntax trees.

\section{An example : repeat..until}

\noindent A classical extension is the creation of the "repeat" statement.
  The "repeat" statement is like a "while" except that the loop is
  executed at least one time and that the test is at the end of the
  loop and is inverted. The equivalent of:

\begin{verbatim}
  repeat x; y; z until c
\end{verbatim}

\noindent is:

\begin{verbatim}
  do {
    x; y; z;
    while not c do { x; y; z }
  }
\end{verbatim}

\noindent or, with a loop:

\begin{verbatim}
  loop () where rec loop () = do {
    x; y; z;
    if c then () else loop ()
  }
\end{verbatim}

\subsection{The code}

\noindent This syntax extension could be written like this (see the detail of
  syntax in the chapter about extensible
  grammars and the syntax tree quotations in the chapter
  about them):

\begin{verbatim}
  #load "pa_extend.cmo";
  #load "q_MLast.cmo";
  open Pcaml;
  EXTEND
    expr:
      [ [ "repeat"; el = LIST1 expr SEP ";"; "until"; c = expr ->
            let el = el @ [<:expr< while not $c$ do { $list:el$ } >>] in
            <:expr< do { $list:el$ } >> ] ]
    ;
  END;
\end{verbatim}

\noindent Alternatively, with the loop version:

\begin{verbatim}
  #load "pa_extend.cmo";
  #load "q_MLast.cmo";
  open Pcaml;
  EXTEND
    expr:
      [ [ "repeat"; el = LIST1 expr SEP ";"; "until"; c = expr ->
            let el = el @ [<:expr< if $c$ then () else loop () >>] in
            <:expr< loop () where rec loop () = do { $list:el$ } >> ] ]
    ;
  END;
\end{verbatim}

\noindent The first "\texttt{\#load}" in the code (in both files) means that a
  syntax extension has been used in the file, namely the "EXTEND"
  statement. The second "\texttt{\#load}" means that abstract
  tree quotations has been used, namely the
  "\texttt{<:expr< ... >>}".

\

\noindent The quotation, found in the second version:

\begin{verbatim}
  <:expr< loop () where rec loop () = do { $list:el$ } >>
\end{verbatim}

\noindent is especially interesting. Written with abstract syntax tree, it would
  be:

\begin{verbatim}
  MLast.ExLet loc True
    [(MLast.PaLid loc "loop",
      MLast.ExFun loc [(MLast.PaUid loc "()", None, MLast.ExSeq loc el)])]
    (MLast.ExApp loc (MLast.ExLid loc "loop") (MLast.ExUid loc "()"));
\end{verbatim}

\noindent This shows the interest of writing abstract syntax tree with quotations:
  it is easier to program and to understand.

\subsection{Compilation}

\noindent If the file "foo.ml" contains one of these versions, it is possible to
  compile it like this:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 -c foo.ml
\end{verbatim}

\noindent Notice that the ocamlc option "-c" means that we are interested
  only in generating the object file "foo.cmo", not achieving the
  compilation by creating an executable. Anyway the link would not
  work because of usage of modules specific to Camlp5.

\subsection{Testing}

\subsubsection{In the OCaml toplevel}

\begin{verbatim}
  ocaml -I +camlp5 camlp5r.cma
          Objective Caml version ...

          Camlp5 Parsing version ...

  # #load "foo.cmo";
  # value x = ref 42;
  value x : ref int = {val=42}
  # repeat
      print_int x.val; print_endline ""; x.val := x.val + 3
    until x.val > 70;
  42
  45
  48
  51
  54
  57
  60
  63
  66
  69
  - : unit = ()
\end{verbatim}

\subsubsection{In a file}

\noindent The code, above, used in the toplevel, can be written in a file,
  say "bar.ml":

\begin{verbatim}
  #load "./foo.cmo";
  value x = ref 42;
  repeat
    print_int x.val;
    print_endline "";
    x.val := x.val + 3
  until x.val > 70;
\end{verbatim}

\noindent with a subtile difference: the loaded file must be "\texttt{./foo.cmo}"
  and not just "\texttt{foo.cmo}" because Camlp5 does not have, by default,
  the current directory in its path.

\

\noindent The file can be compiled like this:

\begin{verbatim}
  ocamlc -pp camlp5r bar.ml
\end{verbatim}

\noindent or in native code:

\begin{verbatim}
  ocamlopt -pp camlp5r bar.ml
\end{verbatim}

\noindent And it is possible to check the resulting program by typing:

\begin{verbatim}
  camlp5r pr_r.cmo bar.ml
\end{verbatim}

\noindent whose displayed result is:

\begin{verbatim}
  #load "./foo.cmo";
  value x = ref 42;
  do {
    print_int x.val;
    print_endline "";
    x.val := x.val + 3;
    while not (x.val > 70) do {
      print_int x.val;
      print_endline "";
      x.val := x.val + 3
    }
  };
\end{verbatim}

\noindent See also the same
  example pretty printed in its original syntax, using the
  extendable programs printing.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Extensions of printing}

\noindent Camlp5 provides extensions kits to pretty print programs in revised
  syntax and normal syntax. Some other extensions kits also allow to
  rebuild the parsers, or the EXTEND statements in their initial
  syntax. The pretty print system is itself extensible, by adding new
  rules. We present here how it works in the Camlp5 sources.

\

\noindent The pretty print system of Camlp5 uses the library modules
  Pretty, an original system to format
  output) and Extfun, another original
  system of extensible functions.

\

\noindent This chapter is designed for programmers that want to understand
  how the pretty printing of OCaml programs work in Camlp5, want to
  adapt, modify or debug it, or want to add their own pretty printing
  extensions.


\section{Introduction}

\noindent The files doing the pretty printings are located in Camlp5 sources
in the directory "etc". Peruse them if you are interested in creating
new ones. The main ones are:

\begin{itemize}
\item "etc/pr\_r.ml": pretty print in revised syntax.
\item "etc/pr\_o.ml": pretty print in normal syntax.
\item "etc/pr\_rp.ml": rebuilding parsers in their original revised
    syntax.
\item "etc/pr\_op.ml": rebuilding parsers in their original normal
    syntax.
\item "etc/pr\_extend.ml": rebuilding EXTEND in its original
    syntax.
\end{itemize}

\noindent We present here how this system works inside these files. First,
  the general principles. Second, more details of the
  implementation.

\section{Principles}

\subsection{Using module Pretty}

\noindent All functions in OCaml pretty printing take a parameter named "the
printing context" (variable \texttt{pc}). It is a record holding :

\begin{itemize}
\item The current indendation : \texttt{pc.ind}
\item What should be printed before, in the same line
  : \texttt{pc.bef}
\item What should be printed after, in the same line
    : \texttt{pc.aft}
\item The dangling token, useful in normal syntax to know whether
    parentheses are necessary : \texttt{pc.dang}
\end{itemize}

\noindent A typical pretty printing function calls the
  function \texttt{horiz\_vertic} of the library
  module Pretty. This function takes two
  functions as parameter:

\begin{itemize}
\item The way to print the data in one only line (\emph{horizontal}
    printing)
\item The way to print the data in two or more lines (\emph{vertical}
    printing)
\end{itemize}

\noindent Both functions catenate the strings by using the
  function \texttt{sprintf} of the library
  module \texttt{Pretty} which controls whether the printed data
  holds in the line or not. They generally call, recursively, other
  pretty printing functions with the same behaviour.

\

\noindent Let us see an example (fictitious) of printing an OCaml
  application. Let us suppose we have an application expression
  "\texttt{e1 e2}" to pretty print where \texttt{e1}
  and \texttt{e2} are sub-expressions. If both expressions and
  their application holds on one only line, we want to see:

\begin{verbatim}
  e1 e2
\end{verbatim}

\noindent On the other hand, if they do not hold on one only line, we want to
  see \texttt{e2} in another line with, say, an indendation of 2
  spaces:

\begin{verbatim}
  e1
    e2
\end{verbatim}

\noindent Here is a possible implementation. The function has been
named \texttt{expr\_app} and can call the function \texttt{expr} to
print the sub-expressions \texttt{e1} and \texttt{e2}:

\begin{verbatim}
  value expr_app pc e1 e2 =
    horiz_vertic
      (fun () ->
         let s1 = expr {(pc) with aft = ""} e1 in
         let s2 = expr {(pc) with bef = ""} e2 in
         sprintf "\%s \%s" s1 s2)
      (fun () ->
         let s1 = expr {(pc) with aft = ""} e1 in
         let s2 =
           expr
             {(pc) with
                ind = pc.ind + 2;
                bef = tab (pc.ind + 2)}
             e2
         in
         sprintf "\%s\n\%s" s1 s2)
  ;
\end{verbatim}

\noindent The first function is the \emph{horizontal} printing. It ends with a
  \texttt{sprintf} separating the printing of \texttt{e1}
  and \texttt{e2} by a space. The possible "before part"
  (\texttt{pc.bef}) and "after part" (\texttt{pc.aft}) are
  transmitted in the calls of the sub-functions.

\

\noindent The second function is the \emph{vertical} printing. It ends with a
  \texttt{sprintf} separating the printing of \texttt{e1}
  and \texttt{e2} by a newline. The second line starts with an
  indendation, using the "before part" (\texttt{pc.bef}) of the
  second call to \texttt{expr}.

\

\noindent The pretty printing library
  function \texttt{Pretty.horiz\_vertic} calls the first
  (\emph{horizontal}) function, and if it fails (either
  because \texttt{s1} or \texttt{s2} are too long or hold
  newlines, or because the final string produced
  by \texttt{sprintf} is too long), calls the second
  (\emph{vertical}) function.

\

\noindent Notice that the parameter \texttt{pc} contains a
  field \texttt{pc.bef} (what should be printed before in the same
  line), which in both cases is transmitted to the printing
  of \texttt{e1} (since the syntax \texttt{\{(pc) with aft =
  ""\}} is a record with \texttt{pc.bef} kept). Same for the
  field \texttt{pc.aft} transmitted to the printing
  of \texttt{e2}.

\subsection{Using EXTEND\_PRINTER statement}

\noindent This system is combined to the extensible
  printers to allow the extensibility of the pretty printing.

\

\noindent The code above actually looks like:

\begin{verbatim}
  EXTEND_PRINTER
    pr_expr:
      [ [ <:expr< $e1$ $e2$ >> ->
            horiz_vertic
              (fun () ->
                 let s1 = curr {(pc) with aft = ""} e1 in
                 let s2 = next {(pc) with bef = ""} e2 in
                 sprintf "\%s \%s" s1 s2)
              (fun () ->
                 let s1 = curr {(pc) with aft = ""} e1 in
                 let s2 =
                   next
                     {(pc) with
                        ind = pc.ind + 2;
                        bef = tab (pc.ind + 2)}
                     e2
                 in
                 sprintf "\%s\n\%s" s1 s2) ] ]
    ;
  END;
\end{verbatim}

\noindent The variable "\texttt{pc}" is implicit in the semantic actions of
  the syntax "\texttt{EXTEND\_PRINTER}", as well as two other
  variables: "\texttt{curr}" and "\texttt{next}".

\

\noindent These parameters, "\texttt{curr}" and "\texttt{next}", correspond
  to the pretty printing of, respectively, the current level and the
  next level. Since the application in OCaml is left associative, the
  first sub-expression is printed at the same (current) level and the
  second one is printed at the next level. We also see a call
  to \texttt{next} in the last (2nd) case of the function to treat
  the other cases in the next level.

\subsection{Dangling else, bar, semicolon}

\noindent In normal syntax, there are cases where it is necessary to enclose
  expressions between parentheses (or
  between begin
  and end, which is equivalent in
  that syntax). Three tokens may cause problems: the
  "\texttt{else}", the vertical bar "\texttt{|}" and the
  semicolon "\texttt{;}". Here are examples where the presence of
  these tokens constrains the previous expression to be
  parenthesized. In these three examples, removing
  the begin..end
  enclosers would change the meaning of the expression because the
  dangling token would be included in that expression:

\

\noindent Dangling else:

\begin{verbatim}
  if a then begin if b then c end else d
\end{verbatim}

\noindent Dangling bar:

\begin{verbatim}
  function
    A ->
      begin match a with
        B -> c
      | D -> e
      end
  | F -> g
\end{verbatim}

\noindent Dangling semicolon:

\begin{verbatim}
  if a then b
  else begin
    let c = d in
    e
  end;
  f
\end{verbatim}

\noindent The information is transmitted by the
  value \texttt{pc.dang}. In the first example above, while
  displaying the "\texttt{then}" part of the outer
  "\texttt{if}", the sub-expression is called with the
  value \texttt{pc.dang} set to
  \texttt{"else"} to inform the last sub-sub-expression that it is
  going to be followed by that token. When a "\texttt{if}"
  expression should be displayed without "\texttt{else}" part, and
  that its "\texttt{pc.dang}" is "else", it should be enclosed
  with spaces.

\

\noindent This problem does not exist in revised syntax. While pretty
  printing in revised syntax, the parameter \texttt{pc.dang} is
  not necessary and remains the empty string.

\subsection{By level}

\noindent As explained in the chapter about
  the extensible printers (with the
  EXTEND\_PRINTER statement), printers contain levels. The global
  printer variable of expressions is named "\texttt{pr\_expr}" and
  contain all definitions for pretty printing expressions, organized
  by levels, just like the parsing of expressions. The definition of
  "\texttt{pr\_expr}" actually looks like this:

\begin{verbatim}
  EXTEND_PRINTER
    pr_expr:
      [ "top"
        [ (* code for level "top" *) ]
      | "add"
        [ (* code for level "add" *) ]
      | "mul"
        [ (* code for level "mul" *) ]
      | "apply"
        [ (* code for level "apply" *) ]
      | "simple"
        [ (* code for level "add" *) ] ]
    ;
  END;
\end{verbatim}

\section{The Prtools module}

\noindent The Prtools module is defined inside Camlp5 for pretty printing
  kits. It provides variables and functions to process comments, and
  meta-functions to process lists (horizontally, vertically,
  paragraphly).

\subsection{Comments}

\begin{description}
\item[\texttt{value comm\_bef : int -> MLast.loc -> string;}]

\

"\texttt{comm\_bef ind loc}" get the comment from the source just
    before the given location "\texttt{loc}". This comment may be
    reindented using "\texttt{ind}". Returns the empty string if no
    comment found.
\end{description}

\begin{description}
\item[\texttt{value source : ref string;}]

\

The initial source string, which must be set by the pretty
    printing kit. Used by [comm\_bef] above.
\item[\texttt{value set\_comm\_min\_pos : int -> unit;}]

\

Set the minimum position of the source where comments can be
    found, (to prevent possible duplication of comments).
\end{description}

\subsection{Meta functions for lists}

\begin{description}
\item[\texttt{type pr\_fun 'a = pr\_context -> 'a -> string;}]

\

Type of printer functions.
\end{description}

\begin{description}
\item[\texttt{value hlist : pr\_fun 'a -> pr\_fun (list 'a);}]

\

[hlist elem pc el] returns the horizontally pretty printed
    string of a list of elements; elements are separated with
    spaces.\\The list is displayed in one only line. If this
    function is called in the context of the [horiz] function of the
    function [horiz\_vertic] of the module Printing, and if the line
    overflows or contains newlines, the function internally fails (the
    exception is catched by [horiz\_vertic] for a vertical pretty
    print).
\item[\texttt{value hlist2 : pr\_fun 'a -> pr\_fun 'a -> pr\_fun (list 'a);}]

\

horizontal list with a different function from 2nd element on.
\item[\texttt{value hlistl : pr\_fun 'a -> pr\_fun 'a -> pr\_fun (list 'a);}]

\

horizontal list with a different function for the last element.
\end{description}

\begin{description}
\item[\texttt{value vlist : pr\_fun 'a -> pr\_fun (list 'a);}]

\

[vlist elem pc el] returns the vertically pretty printed string
    of a list of elements; elements are separated with newlines and
    indentations.
\item[\texttt{value vlist2 : pr\_fun 'a -> pr\_fun 'a -> pr\_fun (list
   'a);}]

\

vertical list with different function from 2nd element on.
\item[\texttt{value vlist3 : pr\_fun ('a * bool) -> pr\_fun ('a * bool) -> pr\_fun
      (list 'a);}]

\

vertical list with different function from 2nd element on, the
    boolean value being True for the last element of the list.
\item[\texttt{value vlistl : pr\_fun 'a -> pr\_fun 'a -> pr\_fun (list
   'a);}]

\

vertical list with different function for the last element.
\end{description}

\begin{description}
\item[\texttt{value plist : pr\_fun 'a -> int -> pr\_fun (list ('a *
   string));}]

\

[plist elem sh pc el] returns the pretty printed string of a
   list of elements with separators. The elements are printed
   horizontally as far as possible. When an element does not fit on
   the line, a newline is added and the element is displayed in the
   next line with an indentation of [sh]. [elem] is the function to
   print elements, [el] a list of pairs (element * separator) (the
   last separator being ignored).
\item[\texttt{value plistb : pr\_fun 'a -> int -> pr\_fun (list ('a *
      string));}]

\

[plist elem sh pc el] returns the pretty printed string of the
   list of elements, like with [plist] but the value of [pc.bef]
   corresponds to an element already printed, as it were on the
   list. Therefore, if the first element of [el] does not fit in the
   line, a newline and a tabulation is added after [pc.bef].
\item[\texttt{value plistl : pr\_fun 'a -> pr\_fun 'a -> int -> pr\_fun (list
      ('a * string));}]

\

paragraph list with a different function for the last element.
\end{description}

\begin{description}
\item[\texttt{value hvlistl : pr\_fun 'a -> pr\_fun 'a -> pr\_fun (list
   'a);}]

\

applies "\texttt{hlistl}" if the context is horizontal; else
    applies "\texttt{vlistl}".
\end{description}

\subsection{Miscellaneous}

\begin{description}
\item[\texttt{value tab : int -> string;}]

\

[tab ind] is equivalent to [String.make ind ' ']
\end{description}

\begin{description}
\item[\texttt{value flatten\_sequence : MLast.expr -> option (list
   MLast.expr);}]

\

[flatten\_sequence e]. If [e] is an expression representing a
   sequence, return the list of expressions of the sequence. If some
   of these expressions are already sequences, they are flattened in
   the list. If that list contains expressions of the form let..in
   sequence, this sub-sequence is also flattened with the let..in
   applying only to the first expression of the sequence. If [e] is a
   let..in sequence, it works the same way. If [e] is not a sequence
   nor a let..in sequence, return None.
\end{description}

\section{Example : repeat..until}

\noindent This pretty prints the example
  repeat..until
  statement programmed in the chapter Syntax
  extensions (first version generating a "\texttt{while}"
  statement).

\subsection{The code}

\noindent The pattern generated by the "repeat" statement is recognized
  (sequence ending with a "\texttt{while}" whose contents is the same
  than the beginning of the sequence) by the function "is\_repeat" and
  the repeat statement is pretty printed in its initial form using the
  function "horiz\_vertic" of the Pretty module. File
  "\texttt{pr\_repeat.ml}":

\begin{verbatim}
  #load "pa_extprint.cmo";
  #load "q_MLast.cmo";

  open Pcaml;
  open Pretty;
  open Prtools;

  value eq_expr_list el1 el2 =
    if List.length el1 <> List.length el2 then False
    else List.for_all2 eq_expr el1 el2
  ;

  value is_repeat el =
    match List.rev el with
    [ [<:expr< while not $e$ do { $list:el2$ } >> :: rel1] ->
        eq_expr_list (List.rev rel1) el2
    | _ -> False ]
  ;

  value semi_after pr pc = pr {(pc) with aft = sprintf "\%s;" pc.aft};

  EXTEND_PRINTER
    pr_expr:
      [ [ <:expr< do { $list:el$ } >> when is_repeat el ->
            match List.rev el with
            [ [<:expr< while not $e$ do { $list:el$ } >> :: _] ->
                horiz_vertic
                  (fun () ->
                     sprintf "\%srepeat \%s until \%s\%s" pc.bef
                       (hlistl (semi_after curr) curr
                          {(pc) with bef = ""; aft = ""} el)
                       (curr {(pc) with bef = ""; aft = ""} e)
                       pc.aft)
                  (fun () ->
                     let s1 = sprintf "\%srepeat" (tab pc.ind) in
                     let s2 =
                       vlistl (semi_after curr) curr
                         {(pc) with
                          ind = pc.ind + 2;
                          bef = tab (pc.ind + 2);
                          aft = ""}
                         el
                     in
                     let s3 =
                       sprintf "\%suntil \%s" (tab pc.ind)
                         (curr {(pc) with bef = ""} e)
                     in
                     sprintf "\%s\n\%s\n\%s" s1 s2 s3)
            | _ -> assert False ] ] ]
    ;
  END;
\end{verbatim}

\subsection{Compilation}

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 -c pr_repeat.ml
\end{verbatim}

\subsection{Testing}

\noindent Getting the same files "foo.ml" and "bar.ml" of the repeat syntax
  example:

\begin{verbatim}
  $ cat bar.ml
  #load "./foo.cmo";
  value x = ref 42;
  repeat
    print_int x.val;
    print_endline "";
    x.val := x.val + 3
  until x.val > 70;

  $ camlp
\end{verbatim}

\noindent Without the pretty printing kit:

\begin{verbatim}
  $ camlp5r pr_r.cmo bar.ml
  #load "./foo.cmo";
  value x = ref 42;
  do {
    print_int x.val;
    print_endline "";
    x.val := x.val + 3;
    while not (x.val > 70) do {
      print_int x.val;
      print_endline "";
      x.val := x.val + 3
    }
  };
\end{verbatim}

\noindent With the pretty printing kit:

\begin{verbatim}
  $ camlp5r pr_r.cmo ./pr_repeat.cmo bar.ml -l 75
  #load "./foo.cmo";
  value x = ref 42;
  repeat
    print_int x.val;
    print_endline "";
    x.val := x.val + 3
  until x.val > 70;
\end{verbatim}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Redefining OCaml syntax}

\noindent Better than just syntax extensions, it is
  possible to redefine the whole syntax of the language. For example,
  to:

\begin{itemize}
\item define your own syntax, like the revised
  syntax does,
\item have a version whose keywords are translated in your native
  language,
\item restrict the OCaml language,
\item interpret XML (or other languages) as OCaml source,
\item and so on...
\end{itemize}


\section{Starting with an example}

\noindent A way to start doing this is to take, in Camlp5 sources, one of the
  files "etc/pa\_o.ml" or file "meta/pa\_r.ml". The first one defines
  the OCaml standard syntax and the second one the revised syntax.

\

\noindent Let's say you want to take the normal syntax and make some
  readjustments. You first make a copy of "etc/pa\_o.ml" naming it,
  e.g., "mysyntax.ml" (the example below works similarly if you
  take "meta/pa\_r.ml" instead):

\

\noindent To test, you can compile it with the command:

\begin{verbatim}
    ocamlc -pp camlp5r -I $(camlp5 -where) -c mysyntax.ml
\end{verbatim}

\noindent This produces the file "mysyntax.cmo". Now you can compile one of
  your files, e.g. "foo.ml", if written in this syntax, i.e. the
  normal OCaml syntax if you made no changes in "mysyntax.ml":

\begin{verbatim}
    ocamlc -pp 'camlp5 ./mysyntax.cmo pr_dump.cmo' -c foo.ml
\end{verbatim}

\noindent If there si no changes in "mysyntax.ml" from "pa\_o.ml", this is
  just a compilation with the normal OCaml syntax. To make changes,
  you can edit the file "mysyntax.ml" and recompile it. As an
  exercice, try to translate some keywords in your native language
  (or another language if it is not English).

\

\noindent Reading the way Camlp5 extensible
  grammars and syntax tree work
  (both used in "pa\_o.ml" and "pa\_r.ml"), you can make more
  complicated changes or change everything, if you want.

\section{A file for an OCaml syntax}

\noindent This is what you can find in the files "pa\_o.ml" and "pa\_r.ml".

\

\noindent An OCaml syntax files uses the Camlp5 library
  module Pcaml. All grammar entries are
  defined there. The first thing is the reinitialization of the
  grammar (which clear all tokens and define a lexer) and all grammar
  entries, to be sure that no possible previous loaded grammars
  remain.

\

\noindent If using the same lexer (provided in Camlp5 library
  module Plexer), it is
  done by:

\begin{verbatim}
    Grammar.Unsafe.gram_reinit Pcaml.gram (Plexer.gmake ())
\end{verbatim}

\noindent The cleanup of all grammar entries are done by calls to the function
  "Grammar.Unsafe.clear\_entry". The main entries are Pcaml.interf, for
  compiling an interface (a ".mli" file) and Pcaml.implem, for compiling
  an implementation (a ".ml" file). And all other grammars entries you
  want to use must be cleared:

\begin{verbatim}
    Grammar.Unsafe.clear_entry Pcaml.interf;
    Grammar.Unsafe.clear_entry Pcaml.implem;
    Grammar.Unsafe.clear_entry Pcaml.expr;
    Grammar.Unsafe.clear_entry Pcaml.patt;
    ...
\end{verbatim}

\noindent Actually, the camlp5 command can compile the input file with other
  ways than using the Camlp5 grammars. The variables "Pcaml.parse\_interf"
  and "Pcaml.parse\_implem" are references to the functions called by
  camlp5. By default, it is the Camlp5 grammar syntax, but to be sure
  it goes on using it (if a previous load changed that), the following
  statement are added:

\begin{verbatim}
    Pcaml.parse_interf.val := Pcaml.Grammar.Entry.parse interf;
    Pcaml.parse_implem.val := Pcaml.Grammar.Entry.parse implem;
\end{verbatim}

\noindent In the files "pa\_o.ml" and "pa\_r.ml", some local functions follow,
  which are themselves followed by a call to the big statement
  "EXTEND", the main statement of the Camlp5 extensible grammars
  system.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Quotations}

\noindent Quotations are a syntax extension in Camlp5 to build
  expressions and patterns in any syntax independant from the one of
  OCaml. Quotations are \emph{expanded}, i.e. transformed, at parse
  time to produce normal syntax trees, like the rest of the program.
  Quotations \emph{expanders} are normal OCaml functions writable by
  any programmer.

\

\noindent The aim of quotations is to use concrete syntax for manipulating
  abstract values.  That makes programs easier to write, read, modify,
  and understand. The drawback is that quotations are linguistically isolated from the
  rest of the program, in opposition to syntax
  extensions, which are included in the language.


\section{Introduction}

\noindent A quotation is syntactically enclosed by specific quotes formed by
  less (\texttt{<}) and greater (\texttt{>}) signs. Namely:

\begin{itemize}
\item starting with either "\texttt{<<}" or "\texttt{<:ident<}"
    where "\texttt{ident}" is the quotation name,
\item ending with "\texttt{>>}"
\end{itemize}

\noindent Examples:

\begin{verbatim}
  << \x.x x >>
  <:foo< hello, world >>
  <:bar< @#$\%;* >>
\end{verbatim}

\noindent The text between these particular parentheses can be any text. It
  may contain enclosing quotations and the characters "\texttt{<}",
  "\texttt{>}" and "\texttt{$\backslash$}" can be escaped by
  "\texttt{$\backslash$}". Notice that possible double-quote, parentheses, OCaml
  comments do not necessarily have to balanced inside them.

\

\noindent As far as the lexer is concerned, a quotation is just a kind of
  string.

\section{Quotation expander}

\noindent Quotations are treated at parse time. Each quotation name is
  associated with a \emph{quotation expander}, a function
  transforming the content of the quotation into a syntax tree. There
  are actually two expanding functions, depending on whether the
  quotation is in the context of an expression or if it is in the
  context of a pattern.

\

\noindent If a quotation has no associated quotation expander, a parsing
  error is displayed and the compilation fails.

\

\noindent The quotation expander, or, rather, expanders, are functions taking
  the quotation string as parameter and returning a syntax tree. There
  is no constraint about which parsing technology is used. It can be
  stream
  parsers, extensible grammars, string
  scanning, ocamllex and yacc, any.

\

\noindent To build syntax trees, Camlp5 provides a way to easily build them
  see the chapter about them: it is possible
  to build abstract syntax through concrete syntax using,
  precisely... quotations.

\section{Defining a quotation}

\subsection{By syntax tree}

\noindent To define a quotation, it is necessary to program the quotation
  expanders and to, finally, end the source code with a call to:

\begin{verbatim}
  Quotation.add name (Quotation.ExAst (f_expr, f_patt));
\end{verbatim}

\noindent where "\texttt{name}" is the name of the quotation, and
  "\texttt{f\_expr}" and "\texttt{f\_patt}" the respective quotations
  expanders for expressions and patterns.

\

\noindent After compilation of the source file (without linking, i.e.
  using option "-c" of the OCaml compiler), an object file is created
  (ending with ".cmo"), which can be used as syntax
  extension \emph{kit} of Camlp5.

\subsection{By string}

\noindent There is another way to program the expander: a single
  function which returns, not a syntax tree, but a string which is
  parsed, afterwards, by the system. This function takes a boolean as
  first parameter telling whether the quotation is in position of
  expression (True) or in position of a pattern (False).

\

\noindent Used that way, the source file must end with:

\begin{verbatim}
  Quotation.add name (Quotation.ExStr f);
\end{verbatim}

\noindent where "\texttt{f}" is that quotation expander. The advantage of
  this second approach is that it is simple to understand and use.
  The drawback is that there is no way to specify different source
  locations for different parts of the quotation (what may be
  important in semantic error messages).

\subsection{Default quotation}

\noindent It is possible to use some quotation without its name. Use for that
  the variable "\texttt{Quotation.default\_quotation}". For example,
  ending a file by:

\begin{verbatim}
  Quotation.add "foo" (Quotation.ExAst (f_expr, f_patt));
  Quotation.default.val := "foo";
\end{verbatim}

\noindent allows to use the quotation "foo" without its name, i.e.:

\begin{verbatim}
  << ... >>
\end{verbatim}

\noindent instead of:

\begin{verbatim}
  <:foo< ... >>
\end{verbatim}

\noindent If several files set the variable "\texttt{Quotation.default}", the
  default quotation applies to the last loaded one.

\section{Antiquotations}

\noindent A quotation obeys its own rules of lexing and parsing. Its result is
  a syntax tree, of type "\texttt{Pcaml.expr}" if the quotation is in the
  context of an expression, or "\texttt{Pcaml.patt}" if the quotation is
  in the context of a pattern.

\

\noindent It can be interesting to insert portions of expressions or
  patterns of the enclosing context in its own quotations. For that,
  the syntax of the quotation must define a syntax
  for \emph{antiquotations areas}. It can be, for example:

\begin{itemize}
\item A character introducing a variable: in this case the antiquotation
    can just be a variable.
\item A couple of characters enclosing the antiquotations. For
    example, in the predefined syntax tree
    quotations, the antiquotations are enclosed with dollar
    ("\texttt{\$}") signs.
\end{itemize}

\noindent In quotations, the locations in the resulting syntax tree are all
  set to the location of the quotation itself (if this resulting tree
  contains locations, they are overwritten with this
  location). Consequently, if there are semantic (typing) errors, the
  OCaml compiler will underline the entire quotation.

\

\noindent But in antiquotations, since they can be inserted in the resulting
  syntax tree, it is interesting to keep their initial quotations. For
  that, the nodes:

\begin{verbatim}
  <:expr< $anti:...$ >>
  <:patt< $anti:...$ >>
\end{verbatim}

\noindent equivalent to:

\begin{verbatim}
  MLast.ExAnt loc ...
  MLast.PaAnt loc ...
\end{verbatim}

\noindent are provided (see syntax tree
    quotations).

\

\noindent Let us take an example, without this node, and with this specific
  node.

\

\noindent Let us consider an elementary quotation system whose contents is just
  an antiquotation. This is just a school example, since the quotations
  brackets are not necessary, in this case. But we are going to see how
  the source code is underlined in errors messages.

\subsection{Example without antiquotation node}

\noindent The code for this quotation is (file "qa.ml"):

\begin{verbatim}
  #load "q_MLast.cmo";
  let expr s = Grammar.Entry.parse Pcaml.expr (Stream.of_string s) in
  Quotation.add "a" (Quotation.ExAst (expr, fun []));
\end{verbatim}

\noindent The quotation expander "\texttt{expr}" just takes the string
  parameter (the contents of the quotation), and returns the result
  of the expression   parser of the OCaml language.

\

\noindent Compilation:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 -c qa.ml
\end{verbatim}

\noindent Let us test it in the toplevel with a voluntary typing error:

\begin{verbatim}
  $ ocaml -I +camlp5 camlp5r.cma
          Objective Caml version ...

          Camlp5 Parsing version ...

  # #load "qa.cmo";
  # let x = "abc" and y = 25 in <:a< x ^ y >>;
  Characters 28-41:
    let x = "abc" and y = 25 in <:a< x ^ y >>;
                                ^^^^^^^^^^^^^
  This expression has type int but is here used with type string
\end{verbatim}

\noindent We observe that the full quotation is underlined, although it concerns
  only the variable "\texttt{y}".

\subsection{Example with antiquotation node}

\noindent Let us consider this second version (file "qb.ml"):

\begin{verbatim}
  #load "q_MLast.cmo";
  let expr s =
    let ast = Grammar.Entry.parse Pcaml.expr (Stream.of_string s) in
    let loc = Ploc.make 1 0 (0, String.length s) in
    <:expr< $anti:ast$ >>
  in
  Quotation.add "b" (Quotation.ExAst (expr, fun []));
\end{verbatim}

\noindent As above, the quotation expander "\texttt{expr}" takes the string
  parameter (the contents of the quotation) and applies the expression
  parser of the OCaml language. Its result, instead of being
  returned as it is, is enclosed with the antiquotation node. (The
  location built is the location of the whole string.)

\

\noindent Compilation:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 -c qb.ml
\end{verbatim}

\noindent Now the same test gives:

\begin{verbatim}
  $ ocaml -I +camlp5 camlp5r.cma
          Objective Caml version ...

          Camlp5 Parsing version ...

  # #load "qb.cmo";
  # let x = "abc" and y = 25 in <:b< x ^ y >>;
  Characters 37-38:
    let x = "abc" and y = 25 in <:b< x ^ y >>;
                                         ^
  This expression has type int but is here used with type string
\end{verbatim}

\noindent Notice that, now, only the variable "\texttt{y}" is underlined.

\subsection{In conclusion}

\noindent In the resulting tree of the quotation expander:

\begin{itemize}
\item only portions of this tree, which are sons of the expr and patt
    antiquotation nodes, have the right location they have in the
    quotation (provided the quotation expander gives it the right
    location of the antiquation in the quotation),
\item the other nodes inherit, as location, the location of the full
    quotation.
\end{itemize}

\section{Locations in quotations and antiquotations}

\noindent This section explains in details the problem of locations in
  quotations and antiquotations. It is designed for programmers of
  quotation expanders.

\

\noindent Locations are the difficult point in quotations and antiquotations.
  If they are not set correctly, error messages may highlight wrong parts
  of the source.

\

\noindent The locations are controlled:

\begin{itemize}
\item for syntax errors: by the exception "\texttt{Ploc.Exc}", raised
    by the function "\texttt{Ploc.raise}",
\item for typing errors, by the syntax tree nodes
    "\texttt{<:expr<\ \$anti:...\$\ >>}" and
    "\texttt{<:meta<\ \$anti:...\$\ >>}".
\end{itemize}

\noindent If the quotation expander never uses them, all syntax and typing errors
  highlight the whole quotation.

\

\noindent Remark that in extensible grammars,
  syntax errors are automatically enclosed by the exception
  "\texttt{Ploc.Exc}". Therefore, if the quotation is parsed by an
  extensible grammar entry, this exception can be raised.

\

\noindent In the syntax tree nodes
  "\texttt{<:expr<\ \$anti:...\$\ >>}" and
  "\texttt{<:meta<\ \$anti:...\$\ >>}", the location is
  indicated by the implicit variable named "\texttt{loc}". Their usage
  is therefore something like:

\begin{verbatim}
  let loc = ...computation of the location... in
  <:expr< $anti:...$ >>
\end{verbatim}

\subsection{In the quotation}

\noindent All locations must be computed \emph{relatively to the quotation
  string}. The quotation string is the string between
  "\texttt{<<}" or "\texttt{<:name<}" and "\texttt{>>}"
  (excluded), the first character of this string being at location
  zero.

\

\noindent The quotation system automatically shifts all locations with the
  location of the quotation: the programmer of the quotation expander
  does not therefore need to care about where the quotation appears
  in the source.

\subsection{In antiquotations}

\noindent In antiquotations, it is important to control how the antiquotation
  string is parsed. For example, if the function parsing the antiquotation
  string raises "\texttt{Ploc.Exc}", the location of this exception must
  be shifted with the location of the antiquotation in the quotation.

\

\noindent For example, let us suppose that the source contains:

\begin{verbatim}
  << abc^ijk^(xyz) >>
\end{verbatim}

\noindent where the antiquotation is specified between the caret ("\texttt{\^}")
  characters. The antiquotation string is "\texttt{ijk}". It can be built
  in the quotation expander by:

\begin{verbatim}
  <:expr< ijk >>
\end{verbatim}

\noindent If used just like this, without the "\texttt{<:expr< \$anti:x\$ >>}",
  in case of typing error (for example if the variable "\texttt{ijk}" is
  unbound), the OCaml error message will be:

\begin{verbatim}
  << abc^ijk^(xyz) >>
  ^^^^^^^^^^^^^^^^^^^
  Unbound value ijk
\end{verbatim}

\noindent To put a location to "\texttt{ijk}", since its location in the quotation
  is "\texttt{(5, 8)}" (the "\texttt{i}" being the 5th characater of the
  quotation string, starting at zero), the quotation expander can build
  it like this:

\begin{verbatim}
  let e = <:expr< ijk >> in
  let loc = Ploc.make_unlined (5, 8) in
  <:expr< $anti:e$ >>
\end{verbatim}

\noindent In this case, the possible typing error message will be:

\begin{verbatim}
  << abc^ijk^(xyz) >>
         ^^^
  Unbound value ijk
\end{verbatim}

\noindent This case is simple, since the antiquotation is just an identifier,
  and there is no parser computing it.

\

\noindent If the antiquotation has to be parsed, for example if it is a
  complicated expression, there are two points to care about:

\

\noindent First, the syntax error messages. If the parser of the
  antiquotation raises "\texttt{Ploc.Exc}", its location is relative
  to the antiquotation.  It must therefore be shifted to correspond to
  a location in the quotation.  If "\texttt{f}" is the parsing
  function and "\texttt{sh}" the shift of the \emph{antiquotation}
  in the \emph{quotation} (whose value is "\texttt{5}" in the
  example), the code must be something like:

\begin{verbatim}
  try f () with
  [ Ploc.Exc loc exc -> Ploc.raise (Ploc.shift sh loc) exc ]
\end{verbatim}

\noindent Second, the typing error messages. Here, the above code with
  "\texttt{<:expr<\ \$anti:e\$\ >>}" can apply to the
  resulting tree.

\

\noindent The complete code, taking the possible syntax error messages and
  the possible typing error messages into account, can be (where
  "\texttt{len}" is the antiquotation length):

\begin{verbatim}
  let e =
    try f () with
    [ Ploc.Exc loc exc -> Ploc.raise (Ploc.shift sh loc) exc ]
  in
  let loc = Ploc.make_unlined (sh, sh + len) in
  <:expr< $anti:e$ >>
\end{verbatim}

\section{Located errors}

\noindent If the quotation expander raises an exception, by default, the
  whole quotation is underlined:

\begin{verbatim}
  $ cat foo.ml
  #load "q_MLast.cmo";
  let expr s = raise (Failure "hello") in
  Quotation.add "a" (Quotation.ExAst (expr, fun []));

  $ ocaml -I +camlp5 camlp5r.cma
          Objective Caml version ...

          Camlp5 Parsing version ...

  # #use "foo.ml";
  - : unit = ()
  # <:a< good morning >>;
  Toplevel input:
  # <:a< good morning >>;
    ^^^^^^^^^^^^^^^^^^^^
  While expanding quotation "a":
  Failure: hello
\end{verbatim}

\noindent To specify a location of the exception, use the function
  "\texttt{Ploc.raise}" instead of "\texttt{raise}". In this
  example, let us suppose that we want only the characters
  5 to 7 are underlined. This can be done like this:

\begin{verbatim}
  $ cat foo.ml
  #load "q_MLast.cmo";
  let expr s = Ploc.raise (Ploc.make 1 0 (5, 7)) (Failure "hello") in
  Quotation.add "a" (Quotation.ExAst (expr, fun []));

  $ ledit ocaml -I +camlp5 camlp5r.cma
          Objective Caml version ...

          Camlp5 Parsing version ...

  # #use "foo.ml";
  - : unit = ()
  # <:a< good morning >>;
  Toplevel input:
  # <:a< good morning >>;
             ^^
  While expanding quotation "a":
  Failure: hello
\end{verbatim}

\section{The Quotation module}

\begin{verbatim}
type expander =
  [ ExStr of bool -> string -> string
  | ExAst of (string -> MLast.expr * string -> MLast.patt) ]
;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Is the type for quotation expander kinds:
\begin{itemize}
\item "\texttt{Quotation.ExStr exp}" corresponds to an expander
        "\texttt{exp}" returning a string which is parsed by the
        system to create a syntax tree. Its boolean parameter tells
        whether the quotation is in position of an expression (True)
        or in position of a pattern (False). Quotations expanders
        created this way may work for some particular OCaml syntax,
        and not for another one (e.g. may work when used with revised
        syntax and not when used with normal syntax, and
        conversely).
\item "\texttt{Quotation.ExAst (expr\_exp, patt\_exp)}" corresponds
        to expanders returning syntax trees, therefore not necessitating
        to be parsed afterwards.  The function "\texttt{expr\_exp}" is
        called when the quotation is in position of an expression, and
        "\texttt{patt\_exp}" when the quotation is in position of a
        pattern. Quotation expanders created this way are independent
        from the enclosing syntax.
\end{itemize}
\end{description}

\begin{description}
\item[\texttt{value add : string -> expander -> unit;}]

\

"\texttt{Quotation.add name exp}" adds the quotation "\texttt{name}"
    associated with the expander "\texttt{exp}".
\end{description}

\begin{description}
\item[\texttt{value find : string -> expander;}]

\

"\texttt{Quotation.find name}" returns the quotation expander of
    the given name.
\end{description}

\begin{description}
\item[\texttt{value default : ref string;}]

\

The name of the default quotation : it is possible to use this
    quotation between "\texttt{<<}" and "\texttt{>>}"
    without having to specify its name.
\end{description}

\begin{description}
\item[\texttt{value translate : ref (string -> string);}]

\

Function translating quotation names; default = identity. Used
    in the predefined quotation "\texttt{q\_phony.cmo}". See below.
\end{description}

\noindent Some other useful functions for quotations are defined in the
  module "\texttt{Pcaml}". See the chapter "The
  Pcaml module", section "Quotation management".

\section{Predefined quotations}

\subsection{q\_MLast.cmo}

\noindent This extension kit add quotations of OCaml syntax tree, allowing to
  use concrete syntax to represent abstract syntax. See the chapter
  Syntax tree.

\subsection{q\_ast.cmo}

\noindent As with the previous quotation, this extension kit add quotations of
  OCaml syntax tree, but in the current user syntax with all
  extensions, the previous one being restricted to revised syntax
  without extension. See the chapters
  Syntax tree
  and Syntax tree quotations in user
  syntax.

\subsection{q\_phony.cmo}

\noindent This extension kit is designed for pretty printing and must be loaded
  after a language pretty printing kit (in normal or in revised syntax).
  It prevents the expansions of quotations, transforming them
  into variables. The pretty printing then keeps the initial (source) form.

\

\noindent The macros (extension
  "\texttt{pa\_macro.cmo}") are also displayed in their initial form,
  instead of expanded.

\section{A full example: lambda terms}

\noindent This example allows to represent lambda terms by a concrete syntax
  and to be able to combine them using antiquotations.

\

\noindent A lambda term is defined like this:

\begin{verbatim}
  type term =
    [ Lam of string and term
    | App of term and term
    | Var of string ]
  ;
\end{verbatim}

\noindent Examples:

\begin{verbatim}
  value fst = Lam "x" (Lam "y" (Var "x"));
  value snd = Lam "x" (Lam "y" (Var "y"));
  value delta = Lam "x" (App (Var "x") (Var "x"));
  value omega = App delta delta;
  value comb_s =
    Lam "x"
      (Lamb "y"
         (Lamb "z"
            (App (App (Var "x") (Var "y")) (App (Var "x") (Var "z")))));
\end{verbatim}

\noindent Since combinations of lambda term may be complicated, The idea is to
  represent them by quotations in concrete syntax. We want to be able to
  write the examples above like this:

\begin{verbatim}
  value fst = << \x.\y.x >>;
  value snd = << \x.\y.y >>;
  value delta = << \x.x x >>
  value omega = << ^delta ^delta >>;
  value comb_s = << \x.\y.\z.(x y)(x z) >>;
\end{verbatim}

\noindent which is a classic representation of lambda terms.

\

\noindent Notice, in the definition of "\texttt{omega}", the use of the
  caret ("\texttt{\^}") sign to specify antiquotations. Notice also the
  simplicity of the representation of the expression defining
  "\texttt{comb\_s}".

\

\noindent Here is the code of the quotation expander, term.ml. The expander
  uses the extensible grammars. It has its
  own lexer (using the stream lexers)
  because the lexer of OCaml programs ("\texttt{Plexer.gmake ()}"),
  cannot recognize the backslashes alone.

\subsection{Lexer}

\begin{verbatim}
  (* lexer *)

  #load "pa_lexer.cmo";

  value rec ident =
    lexer
    [ [ 'a'-'z' | 'A'-'Z' | '0'-'9' | '-' | '_' | '\128'-'\255' ]
      ident!
    | ]
  ;

  value empty _ = parser [: _ = Stream.empty :] -> [];

  value rec next_tok =
    lexer
    [ "\\" -> ("BSLASH", "")
    | "^" -> ("CARET", "")
    | 'a'-'z' ident! -> ("IDENT", $buf)
    | "(" -> ("", "(")
    | ")" -> ("", ")")
    | "." -> ("", ".")
    | empty -> ("EOS", "")
    | -> raise (Stream.Error "lexing error: bad character") ]
  ;

  value rec skip_spaces =
    lexer
    [ " "/ skip_spaces!
    | "\n"/ skip_spaces!
    | "\r"/ skip_spaces! | ]
  ;

  value record_loc loct i (bp, ep) = do {
    if i >= Array.length loct.val then do {
      let newt =
        Array.init (2 * Array.length loct.val + 1)
          (fun i ->
             if i < Array.length loct.val then loct.val.(i)
             else Ploc.dummy)
      in
      loct.val := newt;
    }
    else ();
    loct.val.(i) := Ploc.make_unlined (bp, ep)
  };

  value lex_func cs =
    let loct = ref [| |] in
    let ts =
      Stream.from
        (fun i -> do {
           ignore (skip_spaces $empty cs : Plexing.Lexbuf.t);
           let bp = Stream.count cs in
           let r = next_tok $empty cs in
           let ep = Stream.count cs in
           record_loc loct i (bp, ep);
           Some r
         })
    in
    let locf i =
      if i < Array.length loct.val then loct.val.(i) else Ploc.dummy
    in
    (ts, locf)
  ;

  value lam_lex =
    {Plexing.tok_func = lex_func;
     Plexing.tok_using _ = (); Plexing.tok_removing _ = ();
     Plexing.tok_match = Plexing.default_match;
     Plexing.tok_text = Plexing.lexer_text;
     Plexing.tok_comm = None}
  ;
\end{verbatim}

\subsection{Parser}

\begin{verbatim}
  (* parser *)

  #load "pa_extend.cmo";
  #load "q_MLast.cmo";

  value g = Grammar.gcreate lam_lex;
  value expr_term_eos = Grammar.Entry.create g "term";
  value patt_term_eos = Grammar.Entry.create g "term";

  EXTEND
    GLOBAL: expr_term_eos patt_term_eos;
    expr_term_eos:
      [ [ x = expr_term; EOS -> x ] ]
    ;
    expr_term:
      [ [ BSLASH; i = IDENT; "."; t = SELF -> <:expr< Lam $str:i$ $t$ >> ]
      | [ x = SELF; y = SELF -> <:expr< App $x$ $y$ >> ]
      | [ i = IDENT -> <:expr< Var $str:i$ >>
        | CARET; r = expr_antiquot -> r
        | "("; t = SELF; ")" -> t ] ]
    ;
    expr_antiquot:
      [ [ i = IDENT ->
           let r =
             let loc = Ploc.make_unlined (0, String.length i) in
             <:expr< $lid:i$ >>
           in
           <:expr< $anti:r$ >> ] ]
    ;
    patt_term_eos:
      [ [ x = patt_term; EOS -> x ] ]
    ;
    patt_term:
      [ [ BSLASH; i = IDENT; "."; t = SELF -> <:patt< Lam $str:i$ $t$ >> ]
      | [ x = SELF; y = SELF -> <:patt< App $x$ $y$ >> ]
      | [ i = IDENT -> <:patt< Var $str:i$ >>
        | CARET; r = patt_antiquot -> r
        | "("; t = SELF; ")" -> t ] ]
    ;
    patt_antiquot:
      [ [ i = IDENT ->
           let r =
             let loc = Ploc.make_unlined (0, String.length i) in
             <:patt< $lid:i$ >>
           in
           <:patt< $anti:r$ >> ] ]
    ;
  END;

  value expand_expr s =
    Grammar.Entry.parse expr_term_eos (Stream.of_string s)
  ;
  value expand_patt s =
    Grammar.Entry.parse patt_term_eos (Stream.of_string s)
  ;

  Quotation.add "term" (Quotation.ExAst (expand_expr, expand_patt));
  Quotation.default.val := "term";
\end{verbatim}

\subsection{Compilation and test}

\noindent Compilation:

\begin{verbatim}
  ocamlc -pp camlp5r -I +camlp5 -c term.ml
\end{verbatim}

\noindent Example, in the toplevel, including a semantic error, correctly
  underlined, thanks to the antiquotation nodes:

\begin{verbatim}
  $ ocaml -I +camlp5 camlp5r.cma
          Objective Caml version ...

          Camlp5 Parsing version ...

  # #load "term.cmo";
  # type term =
     [ Lam of string and term
     | App of term and term
     |   Var of string ]
    ;
  type term =
    [ Lam of string and term | App of term and term | Var of string ]
  # value comb_s = << \x.\y.\z.(x y)(x z) >>;
  value comb_s : term =
    Lam "x"
     (Lam "y"
       (Lam "z" (App (App (Var "x") (Var "y")) (App (Var "x") (Var "z")))))
  # value omega = << ^delta ^delta >>;
  Characters 18-23:
    value omega = << ^delta ^delta >>;
                      ^^^^^
  Unbound value delta
  # value delta = << \x.x x >>;
  value delta : term = Lam "x" (App (Var "x") (Var "x"))
  # value omega = << ^delta ^delta >>;
  value omega : term =
    App (Lam "x" (App (Var "x") (Var "x")))
      (Lam "x" (App (Var "x") (Var "x")))
\end{verbatim}

\clearemptydoublepage

\pagestyle{fancy}\chapter{The revised syntax}

\noindent The revised syntax is an alternative syntax of OCaml. It is close
  to the normal syntax. We present here only the differences between
  the two syntaxes.

\

\noindent Notice that there is a simple way to know how the normal syntax is
  written in revised syntax: write the code in a file "foo.ml" in
  normal syntax and type, in a shell:

\begin{verbatim}
  camlp5o pr_r.cmo pr_rp.cmo foo.ml
\end{verbatim}

\noindent And, conversely, how a file "bar.ml" written in revised syntax is
  displayed in normal syntax:

\begin{verbatim}
  camlp5r pr_o.cmo pr_op.cmo bar.ml
\end{verbatim}

\noindent Even simpler, without creating a file:

\begin{verbatim}
  camlp5o pr_r.cmo pr_op.cmo -impl -
  ... type in normal syntax ...
  ... type control-D ...
  camlp5r pr_o.cmo pr_rp.cmo -impl -
  ... type in revised syntax ...
  ... type control-D ...
\end{verbatim}


\section{Lexing}

\begin{itemize}
\item The character quote (\texttt{'}) can be written without backslash:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{'$\backslash$''}} & {\texttt{'''}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\section{Modules, Structure and Signature items}

\begin{itemize}
\item Structure and signature items always end with a single semicolon
    which is required.

\item In structures, the declaration of a value is introduced by the
    keyword "value", instead of "let":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{let x = 42;;}} & {\texttt{value x = 42;}} \\
{\texttt{let x = 42 in x + 7;;}} & {\texttt{let x = 42 in x + 7;}} \\
\hline
\end{tabular}
\end{center}


\item In signatures, the declaration of a value is also introduced by
    the keyword "value", instead of "val":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{val x : int;;}} & {\texttt{value x : int;}} \\
\hline
\end{tabular}
\end{center}


\item In signatures, abstract module types are represented by a quote
    and an (any) identifier:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{module type MT;;}} & {\texttt{module type MT = 'a;}} \\
\hline
\end{tabular}
\end{center}


\item Functor application uses currying. Parentheses are not
    required for the parameters:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = Set.Make(M).t;;}} & {\texttt{type t = (Set.Make M).t;}} \\
{\texttt{module M = Mod.Make (M1) (M2);;}} & {\texttt{module M = Mod.Make M1 M2;}} \\
\hline
\end{tabular}
\end{center}


\item It is possible to group several declarations together either in
    an interface or in an implementation by enclosing them between
    "declare" and "end" (this is useful when using syntax extensions
    to generate several declarations from one). Example in an
    interface:
\begin{verbatim}
  declare
    type foo = [ Foo of int | Bar ];
    value f : foo -> int;
  end;
\end{verbatim}

\end{itemize}

\section{Expressions and Patterns}

\subsection{Imperative constructions}

\begin{itemize}
\item The sequence is introduced by the keyword "do" followed by "\{"
    and terminated by "\}"; it is possible to put a semicolon after the
    last expression:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{e1; e2; e3; e4}} & {\texttt{do \{ e1; e2; e3; e4 \}}} \\
\hline
\end{tabular}
\end{center}


\item The "do" after the "while" loop and the "for" loop are followed
    by a "\{" and the loop end with "\}"; it is possible to put a
    semicolon after the last expression:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{while e1 do}} & {\texttt{while e1 do \{}} \\
{\texttt{\ \ e1; e2; e3}} & {\texttt{\ \ e1; e2; e3}} \\
{\texttt{done}} & {\texttt{\}}} \\
{\texttt{}} & {\texttt{}} \\
{\texttt{for i = e1 to e2 do\ \ }} & {\texttt{for i = e1 to e2 do \{}} \\
{\texttt{\ \ e1; e2; e3}} & {\texttt{\ \ e1; e2; e3}} \\
{\texttt{done}} & {\texttt{\}}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\subsection{Tuples and Lists}

\begin{itemize}
\item Parentheses are required in tuples:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{1, "hello", World}} & {\texttt{(1, "hello", World)}} \\
\hline
\end{tabular}
\end{center}


\item Lists are always enclosed with brackets. A list is a left
    bracket, followed by a list of elements separated with semicolons,
    optionally followed by colon-colon and an element, and ended by a
    right bracket. Warning: the colon-colon is not an infix but is
    just part of the syntactic construction.
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{x :: y}} & {\texttt{[x :: y]}} \\
{\texttt{[x; y; z]}} & {\texttt{[x; y; z]}} \\
{\texttt{x :: y :: z :: t}} & {\texttt{[x; y; z :: t]}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\subsection{Records}

\begin{itemize}
\item In record update, parentheses are required around the initial
    expression:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{\{e with field = a\}}} & {\texttt{\{(e) with field = a\}}} \\
\hline
\end{tabular}
\end{center}


\item It is allowable to use function binding syntax in record field
    definitions:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{\{field = fun a -> e\}}} & {\texttt{\{field a = e\}}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\subsection{Irrefutable patterns}

\noindent An \emph{irrefutable pattern} is a pattern which is
  syntactically visible and never fails. They are used in some
  syntactic constructions. It is either:

\begin{itemize}
\item A variable,
\item The wildcard "\_",
\item The constructor "()",
\item A tuple with irrefutable patterns,
\item A record with irrefutable patterns,
\item A type constraint with an irrefutable pattern.
\end{itemize}

\noindent Notice that this definition is only syntactic: a constructor
  belonging to a type having only one constructor is not considered as
  an irrefutable pattern (except "()").

\subsection{Constructions with matching}

\begin{itemize}
\item The keyword "function" no longer exists. Only "fun" is used.
\item The pattern matching, in constructions with "fun", "match" and
    "try" is closed with brackets: an open bracket "[" before the
    first case, and a close bracket "]" after the last case:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{match e with}} & {\texttt{match e with}} \\
{\texttt{\ \ p1 -> e1}} & {\texttt{[ p1 -> e1}} \\
{\texttt{| p2 -> e2}} & {\texttt{| p2 -> e2 ]}} \\
\hline
\end{tabular}
\end{center}
    If there is only one case and if the pattern is irrefutable,
      the brackets are not required. These examples work identically
      in OCaml and in revised syntax:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{fun x -> x}} & {\texttt{fun x -> x}} \\
{\texttt{fun \{foo=(y, \_)\} -> y}} & {\texttt{fun \{foo=(y, \_)\} -> y}} \\
\hline
\end{tabular}
\end{center}

\item It is possible to write the empty function which always raises the
    exception "Match\_failure" when a parameter is applied.  It is also possible to write and
    empty "match", raising "Match\_failure" after having evaluated its
    expression and the empty "try", equivalent to its expression
    without try:
\begin{verbatim}
  fun []
  match e with []
  try e with []
\end{verbatim}

\item The patterns after "let" and "value" must be irrefutable. The
    following OCaml expression:
\begin{verbatim}
  let f (x::y) = ...
\end{verbatim}
    must be written:
\begin{verbatim}
  let f = fun [ [x::y] -> ...
\end{verbatim}


\item It is possible to use a construction "where", equivalent to "let",
    but usable only when where is only one binding. The expression:
\begin{verbatim}
  e1 where p = e
\end{verbatim}
    is equivalent to:
\begin{verbatim}
  let p = e in e1
\end{verbatim}

\end{itemize}

\subsection{Mutables and Assignment}

\begin{itemize}
\item The statement "\texttt{<-}" is written "\texttt{:=}":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{x.f <- y}} & {\texttt{x.f := y}} \\
\hline
\end{tabular}
\end{center}


\item The "ref" type is declared as a record type with one field named
    "val", instead of "contents". The operator "!" does not exist any
    more, and references are assigned like the other mutables:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{x := !x + y}} & {\texttt{x.val := x.val + y}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\subsection{Miscellaneous}

\begin{itemize}
\item The "\texttt{else}" is required in the "\texttt{if}"
    statement:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{if a then b}} & {\texttt{if a then b else ()}} \\
\hline
\end{tabular}
\end{center}


\item The boolean operations "\texttt{or}" and "\texttt{and}" can only
    be written with "\texttt{||}" and "\texttt{\&\&}":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{a or b \& c}} & {\texttt{a || b \&\& c}} \\
{\texttt{a || b \&\& c}} & {\texttt{a || b \&\& c}} \\
\hline
\end{tabular}
\end{center}


\item No more "\texttt{begin end}" construction. One must use
    parentheses.

\item The operators as values are written with an backslash:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{(+)}} & {\texttt{$\backslash$+}} \\
{\texttt{(mod)}} & {\texttt{$\backslash$mod}} \\
\hline
\end{tabular}
\end{center}


\item Nested "as" patterns require parenthesis:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{function Some a as b, c ->}} & {\texttt{fun [ ((Some a as b), c) ->}} \\
{\texttt{\ \ ...}} & {\texttt{\ \ ...}} \\
\hline
\end{tabular}
\end{center}
    But they are not required before the right arrow:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{function Some a as b ->}} & {\texttt{fun [ Some a as b ->}} \\
{\texttt{\ \ ...}} & {\texttt{\ \ ...}} \\
\hline
\end{tabular}
\end{center}


\item The operators with special characters are not automatically
    infix. To define infixes, use syntax extensions.

\end{itemize}

\section{Types and Constructors}

\begin{itemize}
\item The type constructors are before their type parameters, which
    are curryfied:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{int list}} & {\texttt{list int}} \\
{\texttt{('a, bool) Hashtbl.t}} & {\texttt{Hashtbl.t 'a bool}} \\
{\texttt{type 'a foo = 'a list list}} & {\texttt{type foo 'a = list (list 'a)}} \\
\hline
\end{tabular}
\end{center}


\item The abstract types are represented by an unbound type variable:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type 'a foo;;}} & {\texttt{type foo 'a = 'b;}} \\
{\texttt{type bar;;}} & {\texttt{type bar = 'a;}} \\
\hline
\end{tabular}
\end{center}


\item Parentheses are required in tuples of types:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{int * bool}} & {\texttt{(int * bool)}} \\
\hline
\end{tabular}
\end{center}


\item In declarations of a concrete type, brackets must enclose the
    constructor declarations:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = A of i | B;;}} & {\texttt{type t = [ A of i | B ];}} \\
\hline
\end{tabular}
\end{center}


\item It is possible to make the empty type, without constructor:
\begin{verbatim}
  type foo = [];
\end{verbatim}


\item There is a syntax difference between data constructors with
    several parameters and data constructors with one parameter of type
    tuple:\\\\

    The declaration of a data constructor with several parameters
    is done by separating the types with "and". In expressions and
    patterns, these constructor parameters must be curryfied:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = C of t1 * t2;;}} & {\texttt{type t = [ C of t1 and t2 ];}} \\
{\texttt{C (x, y);;}} & {\texttt{C x y;}} \\
\hline
\end{tabular}
\end{center}

    The declaration of a data constructor with one parameter of type
    tuple is done by using a tuple type. In expressions and patterns,
    the parameter must not to be curryfied, since it is alone. In that
    case the syntax of constructor parameters is the same between the
    two syntaxes:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = D of (t1 * t2);;}} & {\texttt{type t = [ D of (t1 * t2) ];}} \\
{\texttt{D (x, y);;}} & {\texttt{D (x, y);}} \\
\hline
\end{tabular}
\end{center}


\item The bool constructors start with an uppercase letter. The identifiers
    "true" and "false" are not keywords:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{true \&\& false}} & {\texttt{True \&\& False}} \\
\hline
\end{tabular}
\end{center}


\item In record types, the keyword "mutable" must appear after the
    colon:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = \{mutable x : t1\};;}} & {\texttt{type t = \{x : mutable t1\};}} \\
\hline
\end{tabular}
\end{center}


\item Manifest types are with "==":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type 'a t = 'a option =}} & {\texttt{type t 'a = option 'a ==}} \\
{\texttt{\ \ \ \ None}} & {\texttt{\ \ [ None}} \\
{\texttt{\ \ | Some of 'a}} & {\texttt{\ \ | Some of 'a ]}} \\
\hline
\end{tabular}
\end{center}


\item Polymorphic types start with "\texttt{!}":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t =}} & {\texttt{type t =}} \\
{\texttt{\ \ \{ f : 'a . 'a list \}}} & {\texttt{\ \ \{ f : ! 'a . list 'a \}}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\section{Streams and Parsers}

\begin{itemize}
\item The streams and the stream patterns are bracketed with "\texttt{[:}"
    and "\texttt{:]}" instead of "\texttt{[<}" and "\texttt{>]}".

\item The stream component "terminal" is written with a back-quote
    instead of a quote:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{[< '1; '2; s; '3 >]}} & {\texttt{[: `1; `2; s; `3 :]}} \\
\hline
\end{tabular}
\end{center}

\item The cases of parsers are bracketed with "\texttt{[}" and
     "\texttt{]}", as with "fun", "match" and "try". If there is one
     case, the brackets are not required:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{parser}} & {\texttt{parser}} \\
{\texttt{\ \ [< 'Foo >] -> e}} & {\texttt{[ [: `Foo :] -> e}} \\
{\texttt{| [< p = f >] -> f;;}} & {\texttt{| [: p = f :] -> f ];}} \\
{\texttt{parser [< 'x >] -> x;;}} & {\texttt{parser [: `x :] -> x;}} \\
\hline
\end{tabular}
\end{center}

\item It is possible to write the empty parser raising the exception
     "Stream.Failure" whatever parameter is applied, and the empty
     stream matching always raising "Stream.Failure":
\begin{verbatim}
  parser []
  match e with parser []
\end{verbatim}

\item In normal syntax, the error indicator starts with a double question
     mark, in revised syntax with a simple question mark:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{parser}} & {\texttt{parser}} \\
{\texttt{\ \ [< '1; '2 ?? "error" >] ->}} & {\texttt{\ \ [: `1; `2 ? "error" :] ->}} \\
{\texttt{\ \ \ \ ...}} & {\texttt{\ \ \ \ ...}} \\
\hline
\end{tabular}
\end{center}

\item In normal syntax, the component optimization starts with
     "\texttt{?!}", in revised syntax with "\texttt{!}":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{parser}} & {\texttt{parser}} \\
{\texttt{\ \ [< '1; '2 ?! >] ->}} & {\texttt{\ \ [: `1; `2 ! :] ->}} \\
{\texttt{\ \ \ \ ...}} & {\texttt{\ \ \ \ ...}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\section{Classes and Objects}

\begin{itemize}
\item Object items end with a single semicolon which is required.
\item Class type parameters follow the class identifier:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{class ['a, 'b] point = ...}} & {\texttt{class point ['a, 'b] = ...}} \\
{\texttt{class c = [int] color;;}} & {\texttt{class c = color [int];}} \\
\hline
\end{tabular}
\end{center}

\item In the type of class with parameters, the type of the parameters
    are between brackets. Example in signature:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{class c : int -> point;;}} & {\texttt{class c : [int] -> point;}} \\
\hline
\end{tabular}
\end{center}

\item The keywords "virtual" and "private" must be in this order:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{method virtual private m :}} & {\texttt{method virtual private m :}} \\
{\texttt{\ \ ...}} & {\texttt{\ \ ...}} \\
{\texttt{method private virtual m :}} & {\texttt{method virtual private m :}} \\
{\texttt{\ \ ...}} & {\texttt{\ \ ...}} \\
\hline
\end{tabular}
\end{center}

\item Object variables are introduced with "value" instead of "val":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{object val x = 3 end}} & {\texttt{object value x = 3; end}} \\
\hline
\end{tabular}
\end{center}

\item Type constraints in objects are introduced with "type" instead of
    "constraint":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{object constraint 'a = int end}} & {\texttt{object type 'a = int; end}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\section{Labels and Variants}

\begin{itemize}
\item Labels in types must start with "\texttt{\~{}}":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{val x : num:int -> bool;;}} & {\texttt{value x : \~{}num:int -> bool;}} \\
\hline
\end{tabular}
\end{center}


\item Types whose number of variants are fixed start with "\texttt{[ =}":
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = [`On | `Off];;}} & {\texttt{type t = [ = `On | `Off];}} \\
\hline
\end{tabular}
\end{center}


\item The "\texttt{[}" and the "\texttt{<}" in variant types must
    not be sticked:
\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Revised} \\
\hline
{\texttt{type t = [< `Foo | `Bar ];;}} & {\texttt{type t = [ < `Foo | `Bar ];}} \\
\hline
\end{tabular}
\end{center}

\end{itemize}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Scheme and Lisp syntaxes}

\noindent It is possible to write OCaml programs with Scheme or Lisp
  syntax. They are close to one another, both using parentheses
  to identify and separate statements.


\section{Common}

\noindent The syntax extension kits are named "\texttt{pa\_scheme.cmo}" and
  "\texttt{pa\_lisp.cmo}". The sources (same names ending with ".ml"
  in the Camlp5 sources), are written in their own syntax. They are
  boostrapped thanks to the versions being written in revised syntax and to
  the Camlp5 pretty printing system.

\

\noindent In the OCaml toplevel, it is possible to use them by loading
  "\texttt{camlp5r.cma}" first, then "\texttt{pa\_lisp.cmo}" or
  "\texttt{pa\_scheme.cmo}" after:

\begin{verbatim}
  ocaml -I +camlp5 camlp5r.cma pa_scheme.cmo
          Objective Caml version ...

          Camlp5 Parsing version ...

  # (let ((x 3)) (* 3 x))
  - : int = 9
  # (values 3 4 5)
  - : (int * int * int) = (3, 4, 5)

  ocaml -I +camlp5 camlp5r.cma pa_lisp.cmo
          Objective Caml version ...

          Camlp5 Parsing version ...

  # (let ((x 3)) (* 3 x))
  - : int = 9
  # (, 3 4 5)
  - : (int * int * int) = (3, 4, 5)
\end{verbatim}

\noindent The grammar of Scheme and Lisp are relatively simple, just reading
  s-expressions. The syntax tree nodes are created in the semantic
  actions. Because of this, these grammars are hardly extensible.

\

\noindent However, the syntax extension EXTEND ("\texttt{pa\_extend.cmo}" in
  extensible grammars) works for them:
  only the semantic actions need be written with the Scheme or Lisp
  syntax. Stream parsers are also implemented.

\

\noindent Warning: these syntaxes are incomplete, but can be completed, if
  Camlp5 users are insterested.

\section{Scheme syntax}

\noindent Some examples are given to show the principles:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Scheme} \\
\hline
{\texttt{let x = 42;;}} & {\texttt{(define x  42)}} \\
{\texttt{let f x = 0;;}} & {\texttt{(define (f x) 0)}} \\
{\texttt{let rec f x y = 0;;}} & {\texttt{(definerec (f x y) 0)}} \\
{\texttt{let x = 42 and y = 27 in x + y;;\ \ }} & {\texttt{(let ((x 42) (y 27)) (+ x y))}} \\
{\texttt{let x = 42 in let y = 27 in x + y;;\ \ }} & {\texttt{(let* ((x 42) (y 27)) (+ x y))}} \\
{\texttt{module M = struct ... end;; }} & {\texttt{(module M (struct ...))}} \\
{\texttt{type 'a t = A of 'a * int | B}} & {\texttt{(type (t 'a) (sum (A 'a int) (B)))}} \\
{\texttt{fun x y -> x}} & {\texttt{(lambda (x y) x)}} \\
{\texttt{x; y; z}} & {\texttt{(begin x y z)}} \\
{\texttt{f x y}} & {\texttt{(f x y)}} \\
{\texttt{[1; 2; 3]}} & {\texttt{[1 2 3]}} \\
{\texttt{x :: y :: z :: t}} & {\texttt{[x y z :: t]}} \\
{\texttt{a, b, c}} & {\texttt{(values a b c)}} \\
{\texttt{match x with 'A'..'Z' -> "x"}} & {\texttt{(match x ((range 'A' 'Z') "x")))}} \\
{\texttt{\{x = y; z = t\}}} & {\texttt{\{(x y) (z t)\}}} \\
\hline
\end{tabular}
\end{center}

\section{Lisp syntax}

\noindent The same examples:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\makebox[5.5cm][l]{OCaml} & \makebox[5.5cm][l]{Lisp} \\
\hline
{\texttt{let x = 42;;}} & {\texttt{(value x  42)}} \\
{\texttt{let f x = 0;;}} & {\texttt{(value f (lambda x 0))}} \\
{\texttt{let rec f x y = 0;;}} & {\texttt{(value rec f (lambda (x y) 0))}} \\
{\texttt{let x = 42 and y = 27 in x + y;;\ \ }} & {\texttt{(let ((x 42) (y 27)) (+ x y))}} \\
{\texttt{let x = 42 in let y = 27 in x + y;;\ \ }} & {\texttt{(let* ((x 42) (y 27)) (+ x y))}} \\
{\texttt{module M = struct ... end;; }} & {\texttt{(module M (struct ...))}} \\
{\texttt{type 'a t = A of 'a * int | B}} & {\texttt{(type (t 'a) (sum (A 'a int) (B)))}} \\
{\texttt{fun x y -> x}} & {\texttt{(lambda (x y) x)}} \\
{\texttt{x; y; z}} & {\texttt{(progn x y z)}} \\
{\texttt{f x y}} & {\texttt{(f x y)}} \\
{\texttt{[1; 2; 3]}} & {\texttt{(list 1 2 3)}} \\
{\texttt{x :: y :: z :: t}} & {\texttt{(list x y z :: t)}} \\
{\texttt{a, b, c}} & {\texttt{(, a b c)}} \\
{\texttt{match x with 'A'..'Z' -> "x"}} & {\texttt{(match x ((range 'A' 'Z') "x")))}} \\
{\texttt{\{x = y; z = t\}}} & {\texttt{(\{\} (x y) (z t))}} \\
\hline
\end{tabular}
\end{center}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Macros}

\noindent Camlp5 provides a system of macros, added by the parsing kit
  "\texttt{pa\_macro.cmo}". Macros are values evaluated at parsing
  time.

\

\noindent When loaded, the parsing kit extends the syntax of the language and
  adds command options.


\section{Added syntax}

\noindent The parsing kit "\texttt{pa\_macro.cmo}" extends the structure items
  (= toplevel phrases), the expressions and the patterns by the
  following grammar rules:

\begin{verbatim}
           str-item ::= str-macro-def
           sig-item ::= sig-macro-def
               expr ::= macro-expr
               patt ::= macro-patt
          cons-decl ::= macro-cons-decl
       rec-lab-decl ::= macro-rec-lab-decl
        match-assoc ::= macro-match-assoc
      str_macro-def ::= "DEFINE" uident
                      | "DEFINE" uident "=" expr
                      | "DEFINE" uident params "=" expr
                      | "UNDEF" uident
                      | "IFDEF" dexpr "THEN" st-or-mac else-str "END"
                      | "IFNDEF" dexpr "THEN" st-or-mac else-str "END"
           else-str ::= "ELSIFDEF" dexpr "THEN" st-or-mac else-str
                      | "ELSIFNDEF" dexpr "THEN" st-or-mac else-str
                      | "ELSE" st-or-mac else-str
                      | <nothing>
      sig_macro-def ::= "DEFINE" uident
                      | "DEFINE" uident params "=" type
                      | "UNDEF" uident
                      | "IFDEF" dexpr "THEN" sg-or-mac else-sig "END"
                      | "IFNDEF" dexpr "THEN" sg-or-mac else-sig "END"
           else-sig ::= "ELSIFDEF" dexpr "THEN" sg-or-mac else-sig
                      | "ELSIFNDEF" dexpr "THEN" sg-or-mac else-sig
                      | "ELSE" st-or-mac else-sig
                      | <nothing>
         macro-expr ::= "IFDEF" dexpr "THEN" expr else-expr "END"
                      | "IFNDEF" dexpr "THEN" expr else-expr "END"
                      | "__FILE__"
                      | "__LOCATION__"
          else-expr ::= "ELSIFDEF" dexpr "THEN" expr else-expr
                      | "ELSIFNDEF" dexpr "THEN" expr else-expr
                      | "ELSE" expr else-expr
         macro-patt ::= "IFDEF" dexpr "THEN" patt "ELSE" patt "END"
                      | "IFNDEF" dexpr "THEN" patt "ELSE" patt "END"
    macro-cons-decl ::= "IFDEF" dexpr "THEN" cons-decl "END"
                      | "IFDEF" dexpr "THEN" cons-decl
                        "ELSE" cons-decl "END"
                      | "IFNDEF" dexpr "THEN" cons-decl "END"
                      | "IFNDEF" dexpr "THEN" cons-decl
                        "ELSE" cons-decl "END"
 macro-rec-lab-decl ::= "IFDEF" dexpr "THEN" rec-lab-decl "END"
                      | "IFDEF" dexpr "THEN" rec-lab-decl
                        "ELSE" rec-lab-decl "END"
                      | "IFNDEF" dexpr "THEN" rec-lab-decl "END"
                      | "IFNDEF" dexpr "THEN" rec-lab-decl
                        "ELSE" rec-lab-decl "END"
  macro-match-assoc ::= "IFDEF" dexpr "THEN" match_assoc "END"
                      | "IFDEF" dexpr "THEN" match-assoc
                        "ELSE" match-assoc "END"
                      | "IFNDEF" dexpr "THEN" match-assoc "END"
                      | "IFNDEF" dexpr "THEN" match-assoc
                        "ELSE" match-assoc "END"
          st-or-mac ::= str_macro-def
                      | structure
          sg-or-mac ::= sig-macro-def
                      | signature
             params ::= ident params
                      | ident
              dexpr ::= dexpr "OR" dexpr
                      | dexpr "AND" dexpr
                      | "NOT" dexpr
                      | uident
                      | "(" dexpr ")"
             uident ::= 'A'-'Z' ident
              ident ::= ident-char*
         ident-char ::= ('a'-'a' | 'A'-'Z' | '0'-'9' | '_' | ''' |
                         misc-byte)
          misc-byte ::= '\128'-'\255'
\end{verbatim}

\noindent When a macro has been defined, as name e.g. "NAME", the expressions
  and patterns are extended this way:

\begin{verbatim}
        expr ::= "NAME"
               | "NAME" "(" expr-params ")"
        patt ::= "NAME"
               | "NAME" "(" patt-params ")"
  expr-params := expr "," expr-params
               | expr
  patt-params := patt "," patt-params
               | patt
\end{verbatim}

\noindent Notice that the identifiers "\texttt{DEFINE}", "\texttt{UNDEF}",
  "\texttt{IFDEF}", "\texttt{IFNDEF}", "\texttt{ELSE}",
  "\texttt{END}", "\texttt{OR}", "\texttt{AND}" and "\texttt{NOT}" are
  new keywords (they cannot be used as identifiers of constructors or
  modules.

\

\noindent However, the identifiers "\texttt{\_\_FILE\_\_}" and
  "\texttt{\_\_LOCATION\_\_}" and the new defined macro names are not new
  identifiers.

\section{Added command options}

\noindent The parsing kit "\texttt{pa\_macro.cmo}" also add two options usable
  in all Camlp5 commands:

\begin{description}
\item[\texttt{-D uident}]

\

Define the uident in question like would have been a DEFINE
    (without parameter) in the code.
\item[\texttt{-U uident}]

\

Undefine the uident in question like would have been a UNDEF in
    the code.
\item[\texttt{-defined}]

\

Print the defined macros and exit.
\end{description}

\section{Semantics}

\noindent The statement "\texttt{DEFINE}" defines a new macro with optional
  parameters and an optional value. The macro name must start with an
  uppercase letter.

\

\noindent The test of a macro can be done either:
\begin{itemize}
\item in structure items
\item in signature items
\item in expressions
\item in patterns
\item in a constructor declaration
\item in a match case
\end{itemize}
\noindent using the statement "\texttt{IFDEF}". Its non-existence can be
    tested by "\texttt{IFNDEF}".  In expressions and patterns, the
    "\texttt{ELSE}" part is required, not in structure items.

\

\noindent The expression behind the "\texttt{IFDEF}" or the "\texttt{IFNDEF}"
  statement may use the operators "\texttt{OR}", "\texttt{AND}" and
  "\texttt{NOT}" and contain parentheses.

\

\noindent Notice that in an "\texttt{IFDEF}" where the value is True
  (resp. False), the "\texttt{ELSE}" (resp "\texttt{THEN}") part does
  not need to be semantically correct (well typed), since it does not
  appear in the resulting syntax tree. Same for "\texttt{IFNDEF}" and
  for possible macros parameters which are not used in the
  associated expression.

\

\noindent If a macro is defined twice, its first version is lost.

\

\noindent The statement "\texttt{UNDEF}" removes a macro definition.

\

\noindent When associated with a value, the "\texttt{DEFINE}" macro acts like
  a variable (or like a function call if it has parameters), except that
  the parameters are evaluated at parse time and can also be used also
  in pattern positions. Notice that this is a way to define constants
  by name in patterns. For example:

\begin{verbatim}
  DEFINE WW1 = 1914;
  DEFINE WW2 = 1939;
  value war_or_year =
    fun
    [ WW1 -> "world war I"
    | WW2 -> "world war II"
    | _ -> "not a war" ]
  ;
\end{verbatim}

\noindent In the definition of a macro, if the expression contains an
  evaluation, the evaluation is not done by Camlp5 but just
  transmitted as code. In this case, it does not work in pattern
  position. Example in the toplevel:

\begin{verbatim}
  # DEFINE PLUS(x, y) = x + y;
  # PLUS(3, 4);
  - : int = 7
  #   fun [ PLUS(3, 4) -> () ];
  Toplevel input:
  #   fun [ PLUS(3, 4) -> () ];
            ^^^^^^^^^^
  Failure: this is not a constructor, it cannot be applied in a pattern
\end{verbatim}

\noindent On the other hand, if the expression does not contain evaluation,
  this is possible:

\begin{verbatim}
  # DEFINE FOO(x, y) = (x, Some y);
  # FOO(True, "bar");
  - : (bool * option string) = (True, Some "bar")
  # fun [ FOO(_, "hello") -> 0 | _ -> 1 ];
  - : ('a * option string) -> int = <fun>
\end{verbatim}

\noindent The macro "\texttt{\_\_FILE\_\_}" is replaced by the current compiled source
  file name. In the OCaml toplevel, its value is the empty string.

\

\noindent The macro "\texttt{\_\_LOCATION\_\_}" is replaced by the the current location
  (two integers in number of characters from the beginning of the file,
  starting at zero) of the macro itself.

\

\noindent In signatures, the macro definitions can return types which can be
  used in type definitions.

\

\noindent In constructor declarations and in match cases, it is possible to
  conditionally define some cases by "\texttt{IFDEF}" or
  "\texttt{IFNDEF}". For example:

\begin{verbatim}
  type t =
    [ A of int
    | IFNDEF FOO THEN
        B of string
      END
    | C of bool ]
  ;

  match x with
  [ A i -> j
  | IFNDEF FOO THEN
      B s -> toto
    END
  | C b -> e ];
\end{verbatim}

\section{Predefined macros}

\noindent The macro "\texttt{CAMLP5}" is always predefined.

\

\noindent The macro "\texttt{OCAML\_oversion}" is predefined, where
  "\texttt{oversion}" is the OCaml version the Camlp5 program has been
  compiled with, where all characters but numbers are replaced by
  underscores. For example, if using OCaml 3.09.3, the macro
  "\texttt{OCAML\_3\_09\_3}" is defined.

\

\noindent Moreover, for \emph{some} Camlp5 versions (and all the versions
  which follows them), the macro "\texttt{CAMLP5\_version}" is defined
  where "\texttt{version}" is the Camlp5 version where all characters
  but numbers are replaced by underscores. For example, in version
  4.02, the macro "\texttt{CAMLP5\_4\_02}" had been defined and this
  macro have appeared in all versions of Camlp5 since 4.02.

\

\noindent To see which macros are predefined, type:

\begin{verbatim}
  camlp5r pa_macro.cmo -defined
\end{verbatim}

\clearemptydoublepage

\pagestyle{fancy}\chapter{Pragma directive}

\noindent The directive "\texttt{\#pragma}" allows to evaluate expressions
at parse time, useful, for example, to test syntax extensions by the
statement EXTEND without having to compile it in a separate file.

\

\noindent To use it, add the syntax extension "\texttt{pa\_pragma.cmo}" in
the Camlp5 command line. It adds the ability to use this directive.

\

\noindent As an example, let's add syntax for the statement 'repeat' and
use it immediately:

\begin{verbatim}
  #pragma
    EXTEND
      GLOBAL: expr;
      expr: LEVEL "top"
        [ [ "repeat"; e1 = sequence; "until"; e2 = SELF ->
              <:expr< do { $e1$; while not $e2$ do { $e1$ } } >> ] ]
      ;
      sequence:
        [ [ el = LIST1 expr_semi -> <:expr< do { $list:el$ } >> ] ]
      ;
      expr_semi:
        [ [ e = expr; ";" -> e ] ]
      ;
    END;

  let i = ref 1 in
  repeat print_int i.val; print_endline ""; incr i; until i.val = 10;
\end{verbatim}

\noindent The compilation of this example (naming it "foo.ml") can be done with
the command:

\begin{verbatim}
  ocamlc -pp "camlp5r q_MLast.cmo pa_extend.cmo pa_pragma.cmo" -I +camlp5 foo.ml
\end{verbatim}

\noindent Notice that it is still experimental and probably incomplete, for the
moment.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Extensible functions}

\noindent Extensible functions allows the definition of pattern matching functions
which are extensible by adding new cases that are inserted
automatically at the proper place by comparing the patterns. The pattern
cases are ordered according to syntax trees representing them, "when"
statements being inserted before the cases without "when".

\

\noindent Notice that extensible functions are functional: when extending a
function, a new function is returned.

\

\noindent The extensible functions are used in
the pretty printing system of Camlp5.


\section{Syntax}

\noindent The syntax of the extensible functions, when loading
"pa\_extfun.cmo", is the following:

\begin{verbatim}
           expression ::= extensible-function
  extensible-function ::= "extfun" expression "with" "[" match-cases "]"
          match-cases ::= match-case "|" match-cases
           match-case ::= pattern "->" expression
                        | pattern "when" expression "->" expression
\end{verbatim}

\noindent It is an extension of the same syntax as the "match" and "try"
constructions.

\section{Semantics}

\noindent The statement "extend" defined by the syntax takes an extensible
function and return another extensible function with the new match
cases inserted at the proper place within the initial extensible
function.

\

\noindent Extensible functions are of type "\texttt{Extfun.t a b}", which
is an abstract type, where "\texttt{a}" and "\texttt{b}" are
respectively the type of the patterns and the type of the
expressions. It corresponds to a function of type "\texttt{a ->
b}".

\

\noindent The function "\texttt{Extfun.apply}" takes an extensible
function as parameter and returns a function which can be applied
like a normal function.

\

\noindent The value "\texttt{Extfun.empty}" is an empty extensible
function, of type "\texttt{Extfun.t 'a 'b}". When applied with
"\texttt{Extfun.apply}" and a parameter, it raises the exception
"\texttt{Extfun.Failure}" whatever the parameter.

\

\noindent For debugging, it is possible to use the function
"\texttt{Extfun.print}" which displays the match cases of the
extensible functions. (Only the patterns are displayed in
clear text, the associated expressions are not.)

\

\noindent The match cases are inserted according to the following rules:

\begin{itemize}
\item The match cases are inserted in the order they are defined in
    the syntax "\texttt{extend}"
\item A match case pattern with "when" is inserted before a match case
    pattern without "when".
\item Two match cases patterns both with "when" or both without "when"
    are inserted according to the alphabetic order of some internal
    syntax tree of the patterns where bound variables names are
    not taken into account.
\item If two match cases patterns without "when" have the same
    patterns internal syntax tree, the initial one is silently
    removed.
\item If two match cases patterns with "when" have the same patterns
    internal syntax tree, the new one is inserted before the old
    one.
\end{itemize}

\clearemptydoublepage
\part{Appendix}
\appendix{}
\clearemptydoublepage

\pagestyle{fancy}\chapter{Commands and Files}

\noindent The main command of Camlp5 is "\texttt{camlp5}". It is an OCaml
  program in bytecode (compiled with ocamlc, not ocamlopt), able to
  dynamically load OCaml object files (ending with ".cmo" and
  ".cma").

\

\noindent Most other Camlp5 commands derive from that one: they are the
  command "\texttt{camlp5}" with some implicitely applied
  parameters.

\

\noindent Two other commands are provided: "\texttt{mkcamlp5}" and
  "\texttt{mkcamlp5.opt}". They allow to create camlp5 executables
  with already loaded kits.

\

\noindent All commands have an option "\texttt{-help}" which display all
  possible command parameters and options. Notice that some parameters
  (the parsing and pretting kits) may add new options. For example,
  the command:

\begin{verbatim}
  camlp5 pr_r.cmo -help
\end{verbatim}

\noindent prints more lines than just:

\begin{verbatim}
  camlp5 -help
\end{verbatim}

\noindent The first parameter ("load options") allows to specify parsing and
  printing kits (".cmo" and ".cma" files) which are loaded inside the
  "\texttt{camlp5}" core before any action. Other options may
  follow.


\section{Parsing and Printing Kits}

\subsection{Parsing kits}

\subsubsection{language parsing kits}

\begin{description}
\item[\texttt{pa\_r.cmo}]

\

Revised syntax (without parsers).
\item[\texttt{pa\_rp.cmo}]

\

Add revised syntax parsers.
\item[\texttt{pa\_o.cmo}]

\

Normal syntax (without parsers). Option added:
\begin{description}
\item[\texttt{-no\_quot}]

\

don't parse quotations, allowing to use,
        e.g. "\texttt{<:>}" as token.
    \end{description}
  
\item[\texttt{pa\_op.cmo}]

\

Add normal syntax parsers.
\item[\texttt{pa\_oop.cmo}]

\

Add normal syntax parsers without code optimization.
\item[\texttt{pa\_lexer.cmo}]

\

Add stream lexers.
\end{description}

\subsubsection{extensible grammars}

\begin{description}
\item[\texttt{pa\_extend.cmo}]

\

Add the EXTEND statement. Options added:
\begin{description}
\item[\texttt{-split\_ext}]

\

split EXTEND by functions to turn around a PowerPC problem.
\item[\texttt{-quotify}]

\

generate code for quotations (internally used to synchronize
        q\_MLast and pa\_r)
\item[\texttt{-meta\_action}]

\

undocumented (internally used for compiled version)
    \end{description}
  
\item[\texttt{pa\_extfold.cmo}]

\

Add the specific symbols FOLD0 and FOLD1 to the EXTEND
    statement.
\end{description}

\subsubsection{extensible functions and printers}

\begin{description}
\item[\texttt{pa\_extfun.cmo}]

\

Add the extensible function ("extfun" statement).
\end{description}

\begin{description}
\item[\texttt{pa\_extprint.cmo}]

\

Add the EXTEND\_PRINTER statement.
\end{description}

\subsubsection{functional parsers}

\begin{description}
\item[\texttt{pa\_fstream.cmo}]

\

Add the functional parsers ("fparser" statement) and the
    backtracking parsers ("bparser" statement).
\end{description}

\subsubsection{other languages}

\begin{description}
\item[\texttt{pa\_lisp.cmo}]

\

Lisp syntax.
\item[\texttt{pa\_scheme.cmo}]

\

Scheme syntax.
\item[\texttt{pa\_sml.cmo}]

\

SML syntax.
\end{description}

\subsubsection{other parsing kits}

\begin{description}
\item[\texttt{pa\_lefteval.cmo}]

\

Add guarantee of left evaluation in functions calls.
\item[\texttt{pa\_macro.cmo}]

\

Add macros. Options added:
\begin{description}
\item[\texttt{-D <string>}]

\

define for IFDEF statement
\item[\texttt{-U <string>}]

\

undefine for IFDEF statement
\item[\texttt{-defined}]

\

print the defined macros and exit
    \end{description}
  
\item[\texttt{pa\_pragma.cmo}]

\

Add pragma directive: evaluations at parse time
\end{description}

\subsection{Printing kits}

\subsubsection{language printing kits}

\begin{description}
\item[\texttt{pr\_r.cmo}]

\

Display in revised syntax. Added options:
\begin{description}
\item[\texttt{-flag <str>}]

\


        Change pretty printing behaviour according to
        "\texttt{<str>}":\\
        A/a enable/disable all flags\\
        C/c enable/disable comments in phrases\\
        D/d enable/disable allowing expanding 'declare'\\
        E/e enable/disable equilibrate cases\\
        L/l enable/disable allowing printing 'let..in' horizontally\\
        S/s enable/disable printing sequences beginners at end of lines\\
        default setting is "aS".
\item[\texttt{-wflag <str>}]

\

Change displaying 'where' statements instead of 'let':\\
        A/a enable/disable all flags\\
        I/i enable/disable 'where' after 'in'\\
        L/l enable/disable 'where' after 'let..='\\
        M/m enable/disable 'where' after 'match' and 'try'\\
        P/p enable/disable 'where' after left parenthesis\\
        R/r enable/disable 'where' after 'record\_field..='\\
        S/s enable/disable 'where' in sequences\\
        T/t enable/disable 'where' after 'then' or 'else'\\
        V/v enable/disable 'where' after 'value..='\\
        W/w enable/disable 'where' after '\texttt{->}'\\
        default setting is "Ars".
\item[\texttt{-l <length>}]

\

Maximum line length for pretty printing (default 78)
\item[\texttt{-sep\_src}]

\

Read source file for text between phrases (default).
\item[\texttt{-sep <string>}]

\

Use this string between phrases instead of reading source.
    \end{description}
  
\item[\texttt{pr\_ro.cmo}]

\

Add display objects, labels and variants in revised syntax.
\item[\texttt{pr\_rp.cmo}]

\

Add display parsers with their (revised) syntax.
\item[\texttt{pr\_o.cmo}]

\

Display in normal syntax. Added options:
\begin{description}
\item[\texttt{-flag <str>}]

\

Change pretty printing behaviour according to
        \texttt{<str>}:\\
        A/a enable/disable all flags\\
        C/c enable/disable comments in phrases\\
        E/e enable/disable equilibrate cases\\
        L/l enable/disable allowing printing 'let..in' horizontally\\
        M/m enable/disable printing double semicolons\\
        default setting is "Am".
\item[\texttt{-l <length>}]

\

Maximum line length for pretty printing (default 78)
\item[\texttt{-sep\_src}]

\

Read source file for text between phrases (default).
\item[\texttt{-sep <string>}]

\

Use this string between phrases instead of reading source.
    \end{description}
  
\item[\texttt{pr\_op.cmo}]

\

Add displaying parsers with their (normal) syntax.
\end{description}

\subsubsection{extensible parsers}

\begin{description}
\item[\texttt{pr\_extend.cmo}]

\

Add the displaying of EXTEND statements in their initial
    syntax.Option added:
\begin{description}
\item[\texttt{-no\_slist}]

\

Don't reconstruct SLIST, SOPT, SFLAG
    \end{description}
  
\end{description}

\subsubsection{extensible functions and printers}

\begin{description}
\item[\texttt{pr\_extfun.cmo}]

\

Add displaying extensible functions ("extfun" statement) in
    their initial syntax.
\end{description}

\begin{description}
\item[\texttt{pr\_extprint.cmo}]

\

Add displaying extensible printers ("EXTEND\_PRINTER" statement)
    in their initial syntax.
\end{description}

\subsubsection{other language}

\begin{description}
\item[\texttt{pr\_scheme.cmo}]

\

Display in Scheme syntax. Option added:
\begin{description}
\item[\texttt{-l <length>}]

\

Maximum line length for pretty printing (default 78)
\item[\texttt{-sep <string>}]

\

Use this string between phrases instead of reading source.
    \end{description}
  
\item[\texttt{pr\_schemep.cmo}]

\

Add display parsers with their (Scheme) syntax.
\end{description}

\subsubsection{other printing kits}

\begin{description}
\item[\texttt{pr\_depend.cmo}]

\

Display dependencies. Option added:
\begin{description}
\item[\texttt{-I dir}]

\

Add "dir" to the list of search directories.
    \end{description}
  
\item[\texttt{pr\_dump.cmo}]

\

Dump the syntax tree in binary (for the OCaml compiler)
\item[\texttt{pr\_null.cmo}]

\

No output.
\end{description}

\subsection{Quotations expanders}

\begin{description}
\item[\texttt{q\_MLast.cmo}]

\

Syntax tree quotations. Define the quotations named: "expr",
    "patt", "ctyp", "str\_item", "sig\_item", "module\_type", "module\_expr",
    "class\_type", "class\_expr", "class\_sig\_item", "class\_str\_item",
    "with\_constr" and "poly\_variant".
\item[\texttt{q\_phony.cmo}]

\

Transform quotations into phony variables to be able to pretty
    print the quotations in their initial form (not suitable for
    compilation)
\end{description}

\section{Commands}

\begin{description}
\item[\texttt{camlp5r}]

\

Shortcut for "\texttt{camlp5 pa\_r.cmo pa\_rp.cmo pr\_dump.cmo}"
\item[\texttt{camlp5r.opt}]

\

Same as previous, but in native code instead of bytecode,
    therefore faster. But not extensible: it is not possible to add
    other parsing or printing kits neither in command arguments nor
    with the "load" directive inside sources. Suitable for compiling
    sources not using other syntax extensions.
\item[\texttt{camlp5o}]

\

Shortcut for "\texttt{camlp5 pa\_o.cmo pa\_op.cmo pr\_dump.cmo}"
\item[\texttt{camlp5o.opt}]

\

Same as previous, and like "\texttt{camlp5r.opt}", faster and
    not extensible. Moreover, this has been produced by compilation of
    Camlp5 grammars, resulting in a still faster executable.
\item[\texttt{camlp5sch}]

\

Shortcut for "\texttt{camlp5 pa\_scheme.cmo pr\_dump.cmo}"
\item[\texttt{mkcamlp5}]

\

creates camlp5 executables with almost the same options than
    ocamlmktop. The interfaces to be visible must be explicitly added
    in the command line as ".cmi" files. For example, how to add the
    the OCaml module "str": "\texttt{mkcamlp5 -custom str.cmi str.cma
    -cclib -lstr -o camlp5str}"
\item[\texttt{mkcamlp5.opt}]

\

creates camlp5 executables like \texttt{mkcamlp5}, except that
    it is in native code, therefore faster, but not extensible; the
    added kits must be cmx or cmxa files
\end{description}

\section{Environment variable}

\noindent When running a program using extensible grammars (in particular,
  the camlp5 commands), the environment variable
  "\texttt{CAMLP5PARAM}" is consulted. It sets the grammar parsing
  algoritm parameters.

\

\noindent This variable must be a sequence of parameter specifications. A
  parameter specification is a letter optionally followed by an = and
  a value, with any separator. There are four possible parameters:

\begin{description}
\item[\texttt{b}]

\

Set the backtrack algorithm as default.
\item[\texttt{t}]

\

Trace symbols (terminals and non-terminals) while parsing with
    backtracking.
\item[\texttt{y}]

\

In backtracking, trace the advance in the input stream (number
    of unfrozen tokens) and the possible stalling (number of
    tokens tests).
\item[\texttt{l=value}]

\

Set the maximum stalling value.
\end{description}

\section{OCaml toplevel files}

\noindent These object files can be loaded in the OCaml toplevel to make
  Camlp5 parse the input. It is possible to load them either by
  putting them as parameters of the toplevel, or by using the
  directive "load". The option "\texttt{-I +camlp5}" (or "\texttt{-I
  `camlp5 -where`}") must be added to the "\texttt{ocaml}" command
  (the OCaml toplevel).

\begin{description}
\item[\texttt{camlp5r.cma}]

\

Read phrases and display results in revised syntax
\item[\texttt{camlp5o.cma}]

\

Read phrases and display results in normal syntax
\item[\texttt{camlp5sch.cma}]

\

Read phrases in Scheme syntax
\end{description}

\section{Library files}

\noindent The Camlp5 library is named
  "\texttt{gramlib.cma}" and its native code version is
  "\texttt{gramlib.cmxa}". They contain the modules:

\begin{itemize}
\item Ploc : building and
    combining locations
\item Plexing : lexing for Camlp5 grammars
\item Plexer : lexer used in revised and normal syntax
\item Gramext : implementation of extensible grammars
\item Grammar : extensible grammars
\item Extfold : functions for grammar extensions FOLD0 and FOLD1
\item Extfun : functions for extensible
      functions
\item Eprinter : extensible printers
\item Fstream : functional streams
\item Pretty : pretty printing on
    strings
\end{itemize}

\noindent This is a pure library : when linking with it, the Camlp5 program
  is \emph{not} included.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Library}

\noindent All modules defined in "gramlib.cma", but \emph{not} including
  all Camlp5 modules used by the Camlp5 commands and kits.


\section{Ploc module}

\noindent Building and combining locations. This module also contains some
  pervasive types and functions.

\begin{description}
\item[\texttt{type t = 'abstract;}]

\

Location type.
\end{description}

\subsection{located exceptions}

\begin{description}
\item[\texttt{exception Exc of location and exn;}]

\

"\texttt{Ploc.Exc loc e}" is an encapsulation of the exception
    "\texttt{e}" with the input location "\texttt{loc}". To be used to
    specify a location for an error. This exception must not be raised
    by the OCaml function "\texttt{raise}", but rather by
    "\texttt{Ploc.raise}" (see below), to prevent the risk of several
    encapsulations of "\texttt{Ploc.Exc}".
\item[\texttt{value raise : t -> exn -> 'a;}]

\

"\texttt{Ploc.raise loc e}", if "\texttt{e}" is already the
    exception "\texttt{Ploc.Exc}", re-raise it (ignoring the new
    location "\texttt{loc}"), else raise the exception
    "\texttt{Ploc.Exc loc e}".
\end{description}

\subsection{making locations}

\begin{description}
\item[\texttt{value make\_loc : string -> int -> int -> (int * int) -> string -> t;}]

\

"\texttt{Ploc.make\_loc fname line\_nb bol\_pos (bp, ep) comm}"
    creates a location starting at line number "\texttt{line\_nb}",
    where the position of the beginning of the line is
    "\texttt{bol\_pos}" and between the positions "\texttt{bp}"
    (included) and "\texttt{ep}" excluded. And "\texttt{comm}" is the
    comment before the location. The positions are in number of
    characters since the begin of the stream.
\item[\texttt{value make\_unlined : (int * int) -> t;}]

\

"\texttt{Ploc.make\_unlined}" is like "\texttt{Ploc.make}" except
    that the line number is not provided (to be used e.g. when the
    line number is unknown).
\end{description}

\begin{description}
\item[\texttt{value dummy : t;}]

\

"\texttt{Ploc.dummy}" is a dummy location, used in situations
    when location has no meaning.
\end{description}

\subsection{getting location info}

\begin{description}
\item[\texttt{value file\_name : t -> string;}]

\

"\texttt{Ploc.file\_name loc}" returns the file name of the
    location.
\item[\texttt{value first\_pos : t -> int;}]

\

"\texttt{Ploc.first\_pos loc}" returns the initial position
    of the location in number of characters since the beginning of the
    stream.
\item[\texttt{value last\_pos : t -> int;}]

\

"\texttt{Ploc.last\_pos loc}" returns the final position plus one
    of the location in number of characters since the
    beginning of the stream.
\item[\texttt{value line\_nb : t -> int;}]

\

"\texttt{Ploc.line\_nb loc}" returns the line number of the
    location or "\texttt{-1}" if the location does not contain a line
    number (i.e. built with "\texttt{Ploc.make\_unlined}" above).
\item[\texttt{value bol\_pos : t -> int;}]

\

"\texttt{Ploc.bol\_pos loc}" returns the position of the
    beginning of the line of the location in number of characters
    since the beginning of the stream, or "\texttt{0}" if the location
    does not contain a line number (i.e. built the with
    "\texttt{Ploc.make\_unlined}" above).
\item[\texttt{value comment : t -> string;}]

\

"\texttt{Ploc.comment loc}" returns the comment before the
    location.
\end{description}

\subsection{combining locations}

\begin{description}
\item[\texttt{value encl : t -> t -> t;}]

\

"\texttt{Ploc.encl loc1 loc2}" returns the location starting at
    the smallest start and ending at the greatest end of the locations
    "\texttt{loc1}" and "\texttt{loc2}". In other words, it is the
    location enclosing "\texttt{loc1}" and "\texttt{loc2}".
\item[\texttt{value shift : int -> t -> t;}]

\

"\texttt{Ploc.shift sh loc}" returns the location "\texttt{loc}"
    shifted with "\texttt{sh}" characters. The line number is not
    recomputed.
\item[\texttt{value sub : t -> int -> int -> t;}]

\

"\texttt{Ploc.sub loc sh len}" is the location "\texttt{loc}"
    shifted with "\texttt{sh}" characters and with length
    "\texttt{len}". The previous ending position of the location is
    lost.
\item[\texttt{value after : t -> int -> int -> t;}]

\

"\texttt{Ploc.after loc sh len}" is the location just after loc
    (starting at the end position of "\texttt{loc}") shifted with
    "\texttt{sh}" characters and of length "\texttt{len}".
\item[\texttt{value with\_comment : t -> string -> t;}]

\

Change the comment part of the given location
\end{description}

\subsection{miscellaneous}

\begin{description}
\item[\texttt{value name : ref string;}]

\

"\texttt{Ploc.name.val}" is the name of the location variable
    used in grammars and in the predefined quotations for OCaml syntax
    trees. Default: "\texttt{"loc"}".
\end{description}

\begin{description}
\item[\texttt{value get : string -> t -> (int * int * int * int * int);}]

\

"\texttt{Ploc.get fname loc}" returns in order: 1/ the line
       number of the begin of the location, 2/ its column, 3/ the line
       number of the first character not in the location, 4/ its
       column and 5/ the length of the location. The parameter
       "\texttt{fname}" is the file where the location occurs.
\item[\texttt{value from\_file : string -> t -> (string * int * int * int);}]

\

"\texttt{Ploc.from\_file fname loc}" reads the file
    "\texttt{fname}" up to the location "\texttt{loc}" and returns the
    real input file, the line number and the characters location in
    the line; the real input file can be different from
    "\texttt{fname}" because of possibility of line directives
    typically generated by /lib/cpp.
\end{description}

\subsection{pervasives}

\begin{verbatim}
type vala 'a =
  [ VaAnt of string
  | VaVal of 'a ]
;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Encloser of many abstract syntax tree notes types, in
    "strict" mode. This allow the system of antiquotations of
    abstract syntax tree quotations to work when using the quotation
    kit "\texttt{q\_ast.cmo}".
\end{description}

\begin{description}
\item[\texttt{value call\_with : ref 'a -> 'a -> ('b -> 'c) -> 'b -> 'c;}]

\

"\texttt{Ploc.call\_with r v f a}" sets the reference
    "\texttt{r}" to the value "\texttt{v}", then calls "\texttt{f a}",
    and resets "\texttt{r}" to its initial value. If "\texttt{f a}"
    raises an exception, its initial value is also reset and the
    exception is reraised. The result is the result of "\texttt{f
    a}".
\end{description}

\section{Plexing module}

\noindent Lexing for Camlp5 grammars.

\

\noindent This module defines the Camlp5 lexer type to be used in extensible
  grammars (see module "\texttt{Grammar}"). It also provides some
  useful functions to create lexers.

\begin{description}
\item[\texttt{type pattern = (string * string);}]

\

Type for values used by the generated code of the EXTEND
    statement to represent terminals in entry rules.
\begin{itemize}
\item The first string is the constructor name (must start with an
      uppercase character). When empty, the second string should
      be a keyword.
\item The second string is the constructor parameter. Empty if it
      has no parameter (corresponding to the 'wildcard' pattern).
\item The way tokens patterns are interpreted to parse tokens is
      done by the lexer, function "\texttt{tok\_match}" below.
\end{itemize}
  
\end{description}

\begin{description}
\item[\texttt{exception Error of string;}]

\

A lexing error exception to be used by lexers.
\end{description}

\subsection{lexer type}

\begin{verbatim}
type lexer 'te =
  { tok_func : lexer_func 'te;
    tok_using : pattern -> unit;
    tok_removing : pattern -> unit;
    tok_match : mutable pattern -> 'te -> string;
    tok_text : pattern -> string;
    tok_comm : mutable option (list Ploc.t) }
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The type for lexers compatible with Camlp5 grammars. The parameter
    type "\texttt{'te}" is the type of the tokens.
\begin{itemize}
\item The field "\texttt{tok\_func}" is the main lexer
        function. See "\texttt{lexer\_func}" type below.
\item The field "\texttt{tok\_using}" is a function called by the
        "\texttt{EXTEND}" statement to warn the lexer that a rule uses
        this pattern (given as parameter). This allow the lexer 1/ to
        check that the pattern constructor is really among its
        possible constructors 2/ to enter the keywords in its
        tables.
\item The field "\texttt{tok\_removing}" is a function possibly
        called by the "\texttt{DELETE\_RULE}" statement to warn the
        lexer that this pattern (given as parameter) is no longer used
        in the grammar (the grammar system maintains a number of usages
        of all patterns and calls this function when this number falls
        to zero). If it is a keyword, this allows the lexer to remove
        it in its tables.
\item The field "\texttt{tok\_match}" is a function called by the
        Camlp5 grammar system to ask the lexer how the input tokens
        should be matched against the patterns. Warning: for
        efficiency, this function must be written as a function
        taking patterns as parameters and, for each pattern value,
        returning a function matching a token, \emph{not} as a
        function with two parameters.
\item The field "\texttt{tok\_text}" is a function called by the
        grammar system to get the name of the tokens for the error
        messages, in case of syntax error, or for the displaying of
        the rules of an entry.
\item The field "\texttt{tok\_comm}" is a mutable place where the
        lexer can put the locations of the comments, if its initial
        value is not "\texttt{None}". If it is "\texttt{None}",
        nothing has to be done by the lexer.
\end{itemize}
\end{description}

\begin{description}
\item[\texttt{and lexer\_func 'te = Stream.t char -> (Stream.t 'te *
      location\_function)}]

\

The type of a lexer function (field "\texttt{tok\_func}" of the
    type "\texttt{lexer}"). The character stream is the input stream
    to be lexed. The result is a pair of a token stream and a location
    function (see below) for this tokens stream.
\end{description}

\begin{description}
\item[\texttt{and location\_function = int -> Ploc.t;}]

\

The type of a function giving the location of a token in the
    source from the token number in the stream (starting from
    zero).
\end{description}

\begin{description}
\item[\texttt{value lexer\_text : pattern -> string;}]

\

A simple "\texttt{tok\_text}" function.
\end{description}

\begin{description}
\item[\texttt{value default\_match : pattern -> (string * string) ->
      string;}]

\

A simple "\texttt{tok\_match}" function, appling to the token
       type "\texttt{(string * string)}".
\end{description}

\subsection{lexers from parsers or ocamllex}

\noindent The functions below create lexer functions either from a "\texttt{char
   stream}" parser or for an "\texttt{ocamllex}" function. With
   the returned function "\texttt{f}", it is possible to get a simple
   lexer (of the type "\texttt{Plexing.lexer}" above):

\begin{verbatim}
   {Plexing.tok_func = f;
    Plexing.tok_using = (fun _ -> ());
    Plexing.tok_removing = (fun _ -> ());
    Plexing.tok_match = Plexing.default_match;
    Plexing.tok_text = Plexing.lexer_text}
\end{verbatim}

\noindent Note that a better "\texttt{tok\_using}" function would check the
  used tokens and raise "\texttt{Plexing.Error}" for incorrect
  ones. The other functions "\texttt{tok\_removing}",
  "\texttt{tok\_match}" and "\texttt{tok\_text}" may have other
  implementations as well.

\begin{verbatim}
value lexer_func_of_parser :
  ((Stream.t char * ref int * ref int) -> ('te * Ploc.t)) -> lexer_func 'te;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]A lexer function from a lexer written as a char stream parser
    returning the next token and its location. The two references
    with the char stream contain the current line number and the
    position of the beginning of the current line.
\end{description}

\begin{verbatim}
value lexer_func_of_ocamllex : (Lexing.lexbuf -> 'te) -> lexer_func 'te;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    A lexer function from a lexer created by "\texttt{ocamllex}".
\end{description}

\subsection{function to build a stream and a location function}

\begin{verbatim}
value make_stream_and_location :
  (unit -> ('te * Ploc.t)) -> (Stream.t 'te * location_function);
\end{verbatim}

\subsection{useful functions and values}

\begin{description}
\item[\texttt{value eval\_char : string -> char;}]
\item[\texttt{value eval\_string : Ploc.t -> string -> string;}]

\

Convert a char or a string token, where the backslashes are not
    been interpreted into a real char or string; raise
    "\texttt{Failure}" if a bad backslash sequence is found;
    "\texttt{Plexing.eval\_char (Char.escaped c)}" returns "\texttt{c}"
    and "\texttt{Plexing.eval\_string (String.escaped s)}"
    returns \texttt{s}.
\end{description}

\begin{description}
\item[\texttt{value restore\_lexing\_info : ref (option (int * int));}]
\item[\texttt{value line\_nb : ref (ref int);}]
\item[\texttt{value bol\_pos : ref (ref int);}]

\

Special variables used to reinitialize line numbers and position
    of beginning of line with their correct current values when a parser
    is called several times with the same character stream. Necessary
    for directives (e.g. \#load or \#use) which interrupt the parsing.
    Without usage of these variables, locations after the directives
    can be wrong.
\end{description}

\subsection{backward compatibilities}

\noindent Deprecated since version 4.08.

\begin{description}
\item[\texttt{type location = Ploc.t;}]
\item[\texttt{value make\_loc : (int * int) -> location;}]
\item[\texttt{value dummy\_loc : location;}]
\end{description}

\section{Plexer module}

\noindent This module contains a lexer used for OCaml syntax (revised and
  normal).

\subsection{lexer}

\begin{description}
\item[\texttt{value gmake : unit -> Plexing.lexer (string * string);}]

\

"\texttt{gmake ()}" returns a lexer compatible with the
    extensible grammars.  The returned tokens follow the normal syntax
    and the revised syntax lexing rules.
\end{description}

\noindent The token type is "\texttt{(string * string)}" just like the pattern
  type.

\

\noindent The meaning of the tokens are:

\begin{itemize}
\item \texttt{("", s)} is the keyword \texttt{s},
\item \texttt{("LIDENT", s)} is the ident \texttt{s} starting with a
    lowercase letter,
\item \texttt{("UIDENT", s)} is the ident \texttt{s} starting with an
    uppercase letter,
\item \texttt{("INT", s)} is an integer constant whose string source
    is \texttt{s},
\item \texttt{("INT\_l", s)} is an 32 bits integer constant whose
    string source is \texttt{s},
\item \texttt{("INT\_L", s)} is an 64 bits integer constant whose
    string source is \texttt{s},
\item \texttt{("INT\_n", s)} is an native integer constant whose string
    source is \texttt{s},
\item \texttt{("FLOAT", s)} is a float constant whose string source is
    \texttt{s},
\item \texttt{("STRING", s)} is the string constant \texttt{s},
\item \texttt{("CHAR", s)} is the character constant \texttt{s},
\item \texttt{("TILDEIDENT", s)} is the tilde character "\texttt{\~{}}"
    followed by the ident \texttt{s},
\item \texttt{("TILDEIDENTCOLON", s)} is the tilde character
    "\texttt{\~{}}" followed by the ident \texttt{s} and a colon
    "\texttt{:}",
\item \texttt{("QUESTIONIDENT", s)} is the question mark "\texttt{?}"
    followed by the ident \texttt{s},
\item \texttt{("QUESTIONIDENTCOLON", s)} is the question mark
    "\texttt{?}" followed by the ident \texttt{s} and a colon
    "\texttt{:}",
\item \texttt{("QUOTATION", "t:s")} is a quotation "\texttt{t}"
    holding the string \texttt{s},
\item \texttt{("ANTIQUOT", "t:s")} is an antiquotation "\texttt{t}"
    holding the string \texttt{s},
\item \texttt{("EOI", "")} is the end of input.
\end{itemize}

\noindent The associated token patterns in the EXTEND statement hold the same
  names as the first string (constructor name) of the tokens
  expressions above.

\

\noindent Warning: the string associated with the "\texttt{STRING}"
  constructor is the string found in the source without any
  interpretation. In particular, the backslashes are not
  interpreted. For example, if the input is \texttt{"$\backslash$n"} the string
  is *not* a string with one element containing the "newline"
  character, but a string of two elements: the backslash and the
  \texttt{"n"} letter.

\

\noindent Same thing for the string associated with the "\texttt{CHAR}"
  constructor.

\

\noindent The functions "\texttt{Plexing.eval\_string}" and
  "\texttt{Plexing.eval\_char}" allow to convert them into the real
  corresponding string or char value.

\subsection{flags}

\begin{description}
\item[\texttt{value dollar\_for\_antiquotation : ref bool;}]

\

When True (default), the next call to "\texttt{Plexer.gmake ()}"
    returns a lexer where the dollar sign is used for antiquotations.
    If False, there is no antiquotations and the dollar sign can be
    used as normal token.
\end{description}

\begin{description}
\item[\texttt{value specific\_space\_dot : ref bool;}]

\

When "\texttt{False}" (default), the next call to
    "\texttt{Plexer.gmake ()}" returns a lexer where there is no
    difference between dots which have spaces before and dots which
    don't have spaces before. If "\texttt{True}", dots which have
    spaces before return the keyword \texttt{" ."} (space dot) and the
    ones which don't have spaces before return the
    keyword \texttt{"."}  (dot alone).
\end{description}

\begin{description}
\item[\texttt{value no\_quotations : ref bool;}]

\

When "\texttt{True}", all lexers built by "\texttt{Plexer.gmake
      ()}" do not lex the quotation syntax. Default is
      "\texttt{False}" (quotations are lexed).
\end{description}

\begin{description}
\item[\texttt{value utf8\_lexing : ref bool;}]

\

When "\texttt{True}", all lexers built by "\texttt{Plexer.gmake
       ()]}" use utf-8 encoding to specify letters and punctuation
       marks. Default is False (all characters between '$\backslash$128' and
       '$\backslash$255' are considered as letters).
\end{description}

\section{Gramext module}

\noindent This module is not intended to be used by the casual programmer.

\

\noindent It shows, in clear, the implementations of grammars and entries
 types, the normal access being through the "\texttt{Grammar}" module
 where these types are abstract. It can be useful for programmers
 interested in scanning the contents of grammars and entries, for
 example to make analyses on them.

\subsection{grammar type}

\begin{verbatim}
type grammar 'te =
  { gtokens : Hashtbl.t Plexing.pattern (ref int);
    glexer : mutable Plexing.lexer 'te }
;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
  The visible type of grammars, i.e. the implementation of the abstract
  type "\texttt{Grammar.g}". It is also the implementation of an internal
  grammar type used in the Grammar functorial interface.
\end{description}

\begin{description}
\item[\ \ \ \ \ ]
  The type parameter "\texttt{'te}" is the type of the tokens, which
  is "\texttt{(string * string)}" for grammars built with
  "\texttt{Grammar.gcreate}", and any type for grammars built with the
  functorial interface. The field "\texttt{gtokens}" records the
  count of usages of each token pattern, allowing to call the lexer
  function "\texttt{tok\_removing}" (see the
    Plexing module) when this count
    reaches zero. The field "\texttt{lexer}" is the lexer.
\end{description}

\subsection{entry type}

\begin{verbatim}
type g_entry 'te =
  { egram : grammar 'te;
    ename : string;
    elocal : bool;
    estart : mutable int -> Stream.t 'te -> Obj.t;
    econtinue : mutable int -> int -> Obj.t -> Stream.t 'te -> Obj.t;
    edesc : mutable g_desc 'te }
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The visible type for grammar entries, i.e. the implementation of
    the abstract type "\texttt{Grammar.Entry.e}" and the type of
    entries in the Grammar functorial interface. Notice that these
    entry types have a type parameter which does not appear in the
    "\texttt{g\_entry}" type (the "\texttt{'te}" parameter is, as for
    grammars above, the type of the tokens). This is due to the
    specific typing system of the EXTEND statement which sometimes
    must hide real types, the OCaml normal type system not being
    able to type Camlp5 grammars.
\end{description}

\begin{description}
\item[\ \ \ \ \ ]
    Meaning of the fields:
\begin{itemize}
\item \texttt{egram} : the associated grammar
\item \texttt{ename} : the entry name
\item \texttt{elocal} : True if the entry is local (local entries
        are written with a star character "*" by Grammar.Entry.print)
\item \texttt{estart} and \texttt{econtinue} are parsers of the
        entry used in
        the grammar
        machinery
\item \texttt{edesc} : the entry description (see below)
\end{itemize}
\end{description}

\begin{verbatim}
and g_desc 'te =
  [ Dlevels of list (g_level 'te)
  | Dparser of Stream.t 'te -> Obj.t ]
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The entry description.
\begin{itemize}
\item The constructor "\texttt{Dlevels}" is for entries built by
        "\texttt{Grammar.Entry.create}" and extendable by the EXTEND
        statement.
\item The constructor "\texttt{Dparser}" is for entries built by
        "\texttt{Grammar.Entry.of\_parser}".
\end{itemize}
\end{description}

\begin{verbatim}
and g_level 'te =
  { assoc : g_assoc;
    lname : option string;
    lsuffix : g_tree 'te;
    lprefix : g_tree 'te }
and g_assoc = [ NonA | RightA | LeftA ]
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Description of an entry level.
\begin{itemize}
\item \texttt{assoc} : the level associativity
\item \texttt{lname} : the level name, if any
\item \texttt{lsuffix} : the tree composed of the rules starting with
        "\texttt{SELF}"
\item \texttt{lprefix} : the tree composed of the rules not
        starting with "\texttt{SELF}"
\end{itemize}
\end{description}

\begin{verbatim}
and g_symbol 'te =
  [ Smeta of string and list (g_symbol 'te) and Obj.t
  | Snterm of g_entry 'te
  | Snterml of g_entry 'te and string
  | Slist0 of g_symbol 'te
  | Slist0sep of g_symbol 'te and g_symbol 'te
  | Slist1 of g_symbol 'te
  | Slist1sep of g_symbol 'te and g_symbol 'te
  | Sopt of g_symbol 'te
  | Sflag of g_symbol 'te
  | Sself
  | Snext
  | Stoken of Plexing.pattern
  | Stree of g_tree 'te ]
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Description of a rule symbol.
\begin{itemize}
\item The constructor "\texttt{Smeta}" is used by the extensions
        FOLD0 and
        FOLD1
\item The constructor "\texttt{Snterm}" is the representation of a
        non-terminal (a call to another entry)
\item The constructor "\texttt{Snterml}" is the representation of a
        non-terminal at some given level
\item The constructor "\texttt{Slist0}" is the representation of
        the symbol LIST0
\item The constructor "\texttt{Slist0sep}" is the representation
        of the symbol LIST0 followed by SEP
\item The constructor "\texttt{Slist1}" is the representation of
        the symbol LIST1
\item The constructor "\texttt{Slist1sep}" is the representation
        of the symbol LIST1 followed by SEP
\item The constructor "\texttt{Sopt}" is the representation
        of the symbol OPT
\item The constructor "\texttt{Sflag}" is the representation
        of the symbol FLAG
\item The constructor "\texttt{Sself}" is the representation
        of the symbol SELF
\item The constructor "\texttt{Snext}" is the representation
        of the symbol NEXT
\item The constructor "\texttt{Stoken}" is the representation
        of a token pattern
\item The constructor "\texttt{Stree}" is the representation
        of a anonymous rule list (between brackets).
\end{itemize}
\end{description}

\begin{verbatim}
and g_action = Obj.t
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The semantic action, represented by a type "\texttt{Obj.t}" due
    to the specific typing of the EXTEND statement (the semantic action
    being able to be any function type, depending on the rule).
\end{description}

\begin{verbatim}
and g_tree 'te =
  [ Node of g_node 'te
  | LocAct of g_action and list g_action
  | DeadEnd ]
and g_node 'te =
  { node : g_symbol 'te; son : g_tree 'te; brother : g_tree 'te }
;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The types of tree and tree nodes, representing a list of
    factorized rules in an entry level.
\begin{itemize}
\item The constructor "\texttt{Node}" is a representation of a
        symbol (field "\texttt{node}"), the rest of the rule tree
        (field "\texttt{son}"), and the following node, if this node
        fails (field "\texttt{brother}")
\item The constructor "\texttt{LocAct}" is the representation of an
        action, which is a function having all pattern variables of
        the rule as parameters and returning the rule semantic action.
        The list of actions in the constructor correspond to possible
        previous actions when it happens that rules are masked by
        other rules.
\item The constructor "\texttt{DeadEnd}" is a representation of a
        nodes where the tree fails or is in syntax error.
\end{itemize}
\end{description}

\begin{verbatim}
type position =
  [ First
  | Last
  | Before of string
  | After of string
  | Level of string ]
;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The type of position where an entry extension takes place.
\begin{itemize}
\item \texttt{First} : corresponds to FIRST
\item \texttt{Last} : corresponds to LAST
\item \texttt{Before s} : corresponds to BEFORE "s"
\item \texttt{After s} : corresponds to AFTER "s"
\item \texttt{Level s} : corresponds to LEVEL "s"
\end{itemize}
\end{description}

\noindent The module contains other definitions but for internal use.

\section{Grammar module}

\noindent Extensible grammars.

\

\noindent This module implements the Camlp5 extensible grammars system.
  Grammars entries can be extended using the \texttt{EXTEND}
  statement, added by loading the Camlp5 "\texttt{pa\_extend.cmo}"
  file.

\subsection{main types and values}

\begin{description}
\item[\texttt{type g = 'abstract;}]

\


    The type of grammars, holding entries.
  
\end{description}

\begin{description}
\item[\texttt{value gcreate : Plexing.lexer (string * string) -> g;}]

\


    Create a new grammar, without keywords, using the given lexer.
  
\end{description}

\begin{description}
\item[\texttt{value tokens : g -> string -> list (string * int);}]

\


    Given a grammar and a token pattern constructor, returns the list of
    the corresponding values currently used in all entries of this grammar.
    The integer is the number of times this pattern value is used.

    Examples:

\begin{itemize}
\item The call: \texttt{Grammar.tokens g ""} returns the keywords
        list.
\item The call: \texttt{Grammar.tokens g "IDENT"} returns the
        list of all usages of the pattern "IDENT" in
        the \texttt{EXTEND} statements.
\end{itemize}
  
\end{description}

\begin{description}
\item[\texttt{value glexer : g -> Plexing.lexer token;}]

\


    Return the lexer used by the grammar
  
\end{description}

\begin{description}
\item[\texttt{type parsable = 'abstract;}]
\item[\texttt{value parsable : g -> Stream.t char -> parsable;}]

\


    Type and value allowing to keep the same token stream between
    several calls of entries of the same grammar, to prevent loss of
    tokens. To be used with \texttt{Entry.parse\_parsable} below
  
\end{description}

\begin{verbatim}
module Entry =
  sig
    type e 'a = 'x;
    value create : g -> string -> e 'a;
    value parse : e 'a -> Stream.t char -> 'a;
    value parse_all : e 'a -> Stream.t char -> list 'a;
    value parse_token : e 'a -> Stream.t token -> 'a;
    value parse_parsable : e 'a -> parsable -> 'a;
    value name : e 'a -> string;
    value of_parser : g -> string -> (Stream.t token -> 'a) -> e 'a;
    value print : e 'a -> unit;
    value find : e 'a -> string -> e Obj.t;
    external obj : e 'a -> Gramext.g_entry token = "\%identity";
  end;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Module to handle entries.
\begin{itemize}
\item \texttt{Grammar.Entry.e} : type for entries returning values
        of type "\texttt{'a}".
\item \texttt{Grammar.Entry.create g n} : creates a new entry
        named "\texttt{n}" in the grammar "\texttt{g}".
\item \texttt{Grammar.Entry.parse e} : returns the stream parser
        of the entry "\texttt{e}".
\item \texttt{Grammar.Entry.parse\_all e} : returns the stream
        parser returning all possible values while parsing with the
        entry "\texttt{e}": may return more than one value when the
        parsing algorithm is "\texttt{Grammar.Backtracking}".
\item \texttt{Grammar.Entry.parse\_token e} : returns the token
        parser of the entry "\texttt{e}".
\item \texttt{Grammar.Entry.parse\_parsable e} : returns the
        parsable parser of the entry "\texttt{e}".
\item \texttt{Grammar.Entry.name e} : returns the name of the
        entry "\texttt{e}".
\item \texttt{Grammar.Entry.of\_parser g n p} : makes an entry from
        a token stream parser.
\item \texttt{Grammar.Entry.print e} : displays the entry
        "\texttt{e}" using "\texttt{Format}".
\item \texttt{Grammar.Entry.find e s} : finds the entry named
        \texttt{s} in the rules of "\texttt{e}".
\item \texttt{Grammar.Entry.obj e} : converts an entry into a
        "\texttt{Gramext.g\_entry}" allowing to see what it holds.
\end{itemize}
\end{description}

\begin{description}
\item[\texttt{value of\_entry : Entry.e 'a -> g;}]

\

Return the grammar associated with an entry.
\end{description}

\subsection{printing grammar entries}

\noindent The function "\texttt{Grammar.Entry.print}" displays the current
  contents of an entry. Interesting for debugging, to look at the
  result of a syntax extension, to see the names of the levels.

\

\noindent Try, for example, in the OCaml toplevel:

\begin{verbatim}
  Grammar.Entry.print Format.std_formatter Pcaml.expr
\end{verbatim}

\noindent The display does not include the patterns nor the semantic actions,
  whose sources are not recorded in the grammar entries data.

\

\noindent Moreover, the local entries (not specified in the GLOBAL indicator
  of the EXTEND statement) are indicated with a star ("\texttt{*}") to
  inform that they are not directly accessible.

\subsection{clearing grammars and entries}

\begin{verbatim}
module Unsafe :
  sig
    value gram_reinit : g -> Plexing.lexer token -> unit;
    value clear_entry : Entry.e 'a -> unit;
  end;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
   Module for clearing grammars and entries. To be manipulated
   with care, because: 1) reinitializing a grammar destroys all tokens
   and there may be problems with the associated lexer if there are
   keywords; 2) clearing an entry does not destroy the tokens used
   only by itself.
\begin{itemize}
\item \texttt{Grammar.Unsafe.reinit\_gram g lex} removes the tokens
       of the grammar and sets "\texttt{lex}" as a new lexer for
       "\texttt{g}". Warning: the lexer itself is not
       reinitialized.
\item \texttt{Grammar.Unsafe.clear\_entry e} removes all rules of
       the entry "\texttt{e}".
\end{itemize}
\end{description}

\subsection{scan entries}

\begin{description}
\item[\texttt{value print\_entry : Format.formatter -> Gramext.g\_entry 'te -> unit;}]

\


    General printer for all kinds of entries (obj entries).
  
\end{description}

\begin{verbatim}
value iter_entry :
  (Gramext.g_entry 'te -> unit) -> Gramext.g_entry 'te -> unit;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    "\texttt{Grammar.iter\_entry f e}" applies "\texttt{f}" to the
    entry "\texttt{e}" and transitively all entries called by
    "\texttt{e}". The order in which the entries are passed to
    "\texttt{f}" is the order they appear in each entry. Each entry is
    passed only once.
\end{description}

\begin{description}
\item[\texttt{value fold\_entry : (Gramext.g\_entry 'te -> 'a -> 'a) -> Gramext.g\_entry 'te -> 'a -> 'a;}]

\


    "\texttt{Grammar.fold\_entry f e init}" computes "\texttt{(f eN .. (f
    e2 (f e1 init)))}", where "\texttt{e1 .. eN}" are "\texttt{e}"
    and transitively all entries called by "\texttt{e}".  The order in
    which the entries are passed to "\texttt{f}" is the order they
    appear in each entry. Each entry is passed only once.
  
\end{description}

\subsection{parsing algorithm}

\begin{verbatim}
type parse_algorithm = Gramext.parse_algorithm ==
  [ Imperative | Backtracking | DefaultAlgorithm ]
;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Type of algorithm used in grammar entries.
\begin{itemize}
\item \texttt{Imperative}: use imperative streams
\item \texttt{Backtracking}: use functional streams with full
        backtracking
\item \texttt{DefaultAlgorithm}: found in the variable
        "\texttt{backtrack\_parse}" below.
\end{itemize}
    The default, when a grammar is created,
    is \texttt{DefaultAlgorithm}.
\end{description}

\begin{description}
\item[\texttt{value set\_algorithm : g -> parse\_algorithm -> unit;}]

\


    Set the parsing algorithm for all entries of a given grammar.
  
\end{description}

\begin{description}
\item[\texttt{value backtrack\_parse : ref bool;}]

\


    If \texttt{True}, the default parsing uses full backtracking. If
    \texttt{False}, it uses parsing with normal streams. If the
    environment variable CAMLP5PARAM contains "b", the default is
    \texttt{True}; otherwise, the default is \texttt{False}.
  
\end{description}

\begin{description}
\item[\texttt{value backtrack\_stalling\_limit : ref int;}]

\


    Limitation of backtracking to prevent stalling in case of syntax
    error. In backtracking algorithm, when there is a syntax error,
    the parsing continues trying to find another solution. It some
    grammars, it can be very long before checking all possibilities.
    This number limits the number of tokens tests after a backtrack.
    (The number of tokens tests is reset to zero when the token stream
    overtakes the last reached token.) The default is 10000. If set
    to 0, there is no limit. Can be set by the environment variable
    CAMLP5PARAM by "l=value".
  
\end{description}

\subsection{functorial interface}

\noindent Alternative for grammar use. Grammars are not Ocaml values:
  there is no type for them. Modules generated preserve the rule "an
  entry cannot call an entry of another grammar" by normal OCaml
  typing.

\begin{verbatim}
module type GLexerType =
  sig
    type te = 'x;
    value lexer : Plexing.lexer te;
  end;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    The input signature for the functor "\texttt{Grammar.GMake}":
    "\texttt{te}" is the type of the tokens.
\end{description}

\begin{verbatim}
module type S =
  sig
    type te = 'x;
    type parsable = 'x;
    value parsable : Stream.t char -> parsable;
    value tokens : string -> list (string * int);
    value glexer : Plexing.lexer te;
    value set_algorithm : parse_algorithm -> unit;
    module Entry :
      sig
        type e 'a = 'y;
        value create : string -> e 'a;
        value parse : e 'a -> parsable -> 'a;
        value parse_token : e 'a -> Stream.t te -> 'a;
        value name : e 'a -> string;
        value of_parser : string -> (Stream.t te -> 'a) -> e 'a;
        value print : e 'a -> unit;
        external obj : e 'a -> Gramext.g_entry te = "\%identity";
      end;
    module Unsafe :
      sig
        value gram_reinit : Plexing.lexer te -> unit;
        value clear_entry : Entry.e 'a -> unit;
      end;
  end;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    Signature type of the functor "\texttt{Grammar.GMake}". The types
    and functions are almost the same than in generic interface, but:
\begin{itemize}
\item Grammars are not values. Functions holding a grammar as
         parameter do not have this parameter yet.
\item The type "\texttt{parsable}" is used in function
         "\texttt{parse}" instead of the char stream, avoiding the
         possible loss of tokens.
\item The type of tokens (expressions and patterns) can be any
         type (instead of (string * string)); the module parameter
         must specify a way to show them as (string * string).
\end{itemize}
\end{description}

\begin{description}
\item[\texttt{module GMake (L : GLexerType) : S with type te = L.te;}]

\


\end{description}

\subsection{grammar flags}

\begin{description}
\item[\texttt{value error\_verbose : ref bool;}]

\


    Flag for displaying more information in case of parsing error;
    default = "\texttt{False}".
  
\end{description}

\begin{description}
\item[\texttt{value warning\_verbose : ref bool;}]

\


    Flag for displaying warnings while extension; default =
    "\texttt{True}".
  
\end{description}

\begin{description}
\item[\texttt{value strict\_parsing : ref bool;}]

\


    Flag to apply strict parsing, without trying to recover errors;
    default = "\texttt{False}".
  
\end{description}

\section{Diff module}

\noindent Differences between two arrays. Used in Camlp5 sources, but can
  be used for other applications, independantly from Camlp5 stuff.

\begin{verbatim}
value f : array 'a -> array 'a -> (array bool * array bool);}]
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
    \texttt{Diff.f a1 a2} returns a pair of boolean arrays \texttt{(d1, d2)}.
\begin{itemize}
\item \texttt{d1} has the same size as \texttt{a1}.
\item \texttt{d2} has the same size as \texttt{a2}.
\item \texttt{d1.(i)} is \texttt{True} if \texttt{a1.(i)} has no
        corresponding value in \texttt{a2}.
\item \texttt{d2.(i)} is \texttt{True} if \texttt{a2.(i)} has no
        corresponding value in \texttt{a1}.
\item \texttt{d1} and \texttt{d2} have the same number of values equal to
        \texttt{False}.
\end{itemize}

\noindent Can be used, e.g., to write the \texttt{diff} program
      (comparison of two files), the input arrays being the array of
      lines of each file.

\

\noindent Can be used also to compare two strings (they must have been
      exploded into arrays of chars), or two DNA strings, and so on.

\end{description}

\section{Extfold module}

\noindent Module internally used to make the
  symbols FOLD0
  and FOLD1 work in the EXTEND statement + extension
  "\texttt{pa\_extfold.cmo}".

\section{Extfun module}

\noindent Extensible functions.

\

\noindent This module implements pattern matching extensible functions which
  work with the parsing kit "\texttt{pa\_extfun.cmo}", the syntax of
  an extensible function being:

\begin{verbatim}
  extfun e with [ pattern_matching ]
\end{verbatim}

\noindent See chapter : Extensible functions.

\begin{description}
\item[\texttt{type t 'a 'b = 'x;}]

\

The type of the extensible functions of type \texttt{'a ->
      'b}.
\end{description}

\begin{description}
\item[\texttt{value empty : t 'a 'b;}]

\

Empty extensible function.
\item[\texttt{value apply : t 'a 'b -> 'a -> 'b;}]

\

Apply an extensible function.
\item[\texttt{exception Failure;}]

\

Match failure while applying an extensible function.
\item[\texttt{value print : t 'a 'b -> unit;}]

\

Print patterns in the order they are recorded in the data
    structure.
\end{description}

\section{Eprinter module}

\noindent This module allows creation of printers, apply them and clear them. It
  is also internally used by the "\texttt{EXTEND\_PRINTER}" statement.

\begin{description}
\item[\texttt{type t 'a = 'abstract;}]

\

Printer type, to print values of type "\texttt{'a}".
\end{description}

\begin{description}
\item[\texttt{type pr\_context = Pprintf.pr\_context;}]

\

Printing context.
\end{description}

\begin{description}
\item[\texttt{value make : string -> t 'a;}]

\

Builds a printer. The string parameter is used in error
    messages. The printer is created empty and can be extended with
    the "\texttt{EXTEND\_PRINTER}" statement.
\end{description}

\begin{description}
\item[\texttt{value apply : t 'a -> pr\_context -> 'a -> string;}]

\

Applies a printer, returning the printed string of the
    parameter.
\item[\texttt{value apply\_level : t 'a -> string -> pr\_context -> 'a ->
      string;}]

\

Applies a printer at some specific level. Raises "\texttt{Failure}"
    if the given level does not exist.
\end{description}

\begin{description}
\item[\texttt{value clear : t 'a -> unit;}]

\

Clears a printer, removing all its levels and rules.
\end{description}

\begin{description}
\item[\texttt{value print : t 'a -> unit;}]

\

Print printer patterns, in the order they are recorded, for
    debugging purposes.
\end{description}

\noindent Some other types and functions exist, for internal use.

\section{Fstream module}

\noindent This module implement functional streams and parsers together with
  backtracking parsers.

\

\noindent To be used with syntax "\texttt{pa\_fstream.cmo}". The syntax is:

\begin{itemize}
\item stream: "\texttt{fstream [: ... :]}"
\item functional parser: "\texttt{fparser [ [: ... :] -> ... | ... ]}"
\item backtracking parser: "\texttt{bparser [ [: ... :] -> ... | ... ]}"
\end{itemize}

\noindent Functional parsers are of type:

\begin{verbatim}
  Fstream.t 'a -> option ('b * Fstream.t 'a)
\end{verbatim}

\noindent Backtracking parsers are of type:

\begin{verbatim}
  Fstream.t 'a -> option ('b * Fstream.t 'a * Fstream.kont 'a 'b)
\end{verbatim}

\noindent Functional parsers use limited backtrack, i.e if a rule fails, the
  next rule is tested with the initial stream; limited because in the
  case of a rule with two consecutive symbols "\texttt{a}" and
  "\texttt{b}", if "\texttt{b}" fails, the rule fails: there is no try
  with the next rule of "\texttt{a}".

\

\noindent  Backtracking parsers have full backtrack. If a rule fails, the
  next case of the previous rule is tested.

\subsection{Functional streams}

\begin{description}
\item[\texttt{type t 'a = 'x;}]

\

The type of 'a functional streams.
\end{description}

\begin{description}
\item[\texttt{value from : (int -> option 'a) -> t 'a;}]

\

"\texttt{Fstream.from f}" returns a stream built from the
    function "\texttt{f}".  To create a new stream element, the
    function "\texttt{f}" is called with the current stream
    count. The user function "\texttt{f}" must return either
    "\texttt{Some <value>}" for a value or "\texttt{None}" to
    specify the end of the stream.
\end{description}

\begin{description}
\item[\texttt{value of\_list : list 'a -> t 'a;}]

\

Return the stream holding the elements of the list in the same
    order.
\item[\texttt{value of\_string : string -> t char;}]

\

Return the stream of the characters of the string parameter.
\item[\texttt{value of\_channel : in\_channel -> t char;}]

\

Return the stream of the characters read from the input channel.
\end{description}

\begin{description}
\item[\texttt{value iter : ('a -> unit) -> t 'a -> unit;}]

\

"\texttt{Fstream.iter f s}" scans the whole stream s, applying
    function "\texttt{f}" in turn to each stream element
    encountered.
\end{description}

\begin{description}
\item[\texttt{value next : t 'a -> option ('a * t 'a);}]

\

Return "\texttt{Some (a, s)}" where "\texttt{a}" is the first
    element of the stream and \texttt{s} the remaining stream, or
    "\texttt{None}" if the stream is empty.
\item[\texttt{value empty : t 'a -> option (unit * t 'a);}]

\

Return "\texttt{Some ((), s)}" if the stream is empty where
    \texttt{s} is itself, else "\texttt{None}".
\item[\texttt{value count : t 'a -> int;}]

\

Return the current count of the stream elements, i.e. the number
    of the stream elements discarded.
\item[\texttt{value count\_unfrozen : t 'a -> int;}]

\

Return the number of unfrozen elements in the beginning of the
    stream; useful to determine the position of a parsing error (longest
    path).
\end{description}

\subsection{Backtracking parsers}

\begin{description}
\item[\texttt{type kont 'a 'b = [ K of unit -> option ('b * t 'a * kont 'a 'b) ];}]

\


    The type of continuation of a backtracking parser.
  
\end{description}

\begin{description}
\item[\texttt{type bp 'a 'b = t 'a -> option ('b * t 'a * kont 'a 'b);}]

\


    The type of a backtracking parser.
  
\end{description}

\begin{description}
\item[\texttt{value bcontinue : kont 'a 'b -> option ('b * t 'a * kont 'a 'b);}]

\


    "\texttt{bcontinue k}" return the next solution of a backtracking
    parser.
  
\end{description}

\begin{description}
\item[\texttt{value bparse\_all : bp 'a 'b -> t 'a -> list 'b;}]

\


    "\texttt{bparse\_all p strm}" return the list of all solutions of a
    backtracking parser applied to a functional stream.
  
\end{description}

\section{Pprintf module}

\noindent Definitions for pprintf statement.

\

\noindent This module contains types and functions for the "pprintf"
  statement used by the syntax extension "pa\_pprintf.cmo".

\begin{description}
\item[\texttt{type pr\_context = \{ ind : int; bef : string; aft : string;
      dang : string \};}]

\


    Printing context.
\begin{itemize}
\item "\texttt{ind}" : the current indendation
\item "\texttt{bef}" : what should be printed before, in the same line
\item "\texttt{aft}" : what should be printed after, in the same line
\item "\texttt{dang}" : the dangling token to know whether parentheses
        are necessary
\end{itemize}
  
\end{description}

\begin{description}
\item[\texttt{value empty\_pc : pr\_context;}]

\

Empty printer context, equal to \texttt{\{ind = 0; bef = ""; aft =
      ""; dang = ""\}}
\end{description}

\begin{verbatim}
value sprint_break :
  int -> int -> pr_context -> (pr_context -> string) ->
    (pr_context -> string) -> string;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
  "\texttt{sprint\_break nspaces offset pc f g}" concat the two strings
   returned by "\texttt{f}" and "\texttt{g}", either in one line, if
   it holds without overflowing (see module "\texttt{Pretty}"), with
   "\texttt{nspaces}" spaces betwen them, or in two lines with
   "\texttt{offset}" spaces added in the indentation for the second
   line.\\This function don't need to be called directly. It is
   generated by the "\texttt{pprintf}" statement according to its
   parameters when the format contains breaks, like "\texttt{@;}"
   and "\texttt{@\ }".
\end{description}

\begin{verbatim}
value sprint_break_all :
  bool -> pr_context -> (pr_context -> string) ->
    list (int * int * pr_context -> string) -> string;
\end{verbatim}

\begin{description}
\item[\ \ \ \ \ ]
   "\texttt{sprint\_break\_all force\_newlines pc f fl}" concat all
   strings returned by the list with separators "\texttt{f-fl}", the
   separators being the number of spaces and the offset like in the
   function "\texttt{sprint\_break}". The function works as "all or
   nothing", i.e. if the resulting string does not hold on the line,
   all strings are printed in different lines (even if sub-parts could
   hold in single lines). If the parameter "\texttt{force\_newline}" is
   "\texttt{True}", all strings are printed in different lines, no
   horizontal printing is tested.\\This function don't need to be
   called directly. It is generated by the "\texttt{pprintf}"
   statement according to its parameters when the format contains
   parenthesized parts with "break all" like "\texttt{@[<a>}" and
   "\texttt{@]}", or "\texttt{@[<b>}" and "\texttt{@]}".
\end{description}

\section{Pretty module}

\noindent Pretty printing on strings. Basic functions.

\begin{description}
\item[\texttt{value horiz\_vertic : (unit -> 'a) -> (unit -> 'a) -> 'a;}]

\

"\texttt{horiz\_vertic h v}" first calls "\texttt{h}" to print
    the data horizontally, i.e. without newlines. If the displaying
    contains newlines or if its size exceeds the maximum line length
    (see variable "\texttt{line\_length}" below), then the function
    "\texttt{h}" stops and the function "\texttt{v}" is called which
    can print using several lines.
\end{description}

\begin{description}
\item[\texttt{value sprintf : format 'a unit string -> 'a;}]

\

"\texttt{sprintf fmt ...}" formats some string like
    "\texttt{Printf.sprintf}" does, except that, if it is called in
    the context of the *first* function of "\texttt{horiz\_vertic}"
    above, it checks whether the resulting string has chances to fit
    in the line. If not, i.e. if it contains newlines or if its length
    is greater than "\texttt{max\_line\_length.val}", the function gives
    up (raising some internal exception). Otherwise the built string
    is returned.  "\texttt{sprintf}" behaves like
    "\texttt{Printf.sprintf}" if it is called in the context of the
    *second* function of "\texttt{horiz\_vertic}" or without context at
    all.
\end{description}

\begin{description}
\item[\texttt{value line\_length : ref int;}]

\

"\texttt{line\_length}" is the maximum length (in characters) of
    the line. Default = 78. Can be set to any other value before
    printing.
\end{description}

\begin{description}
\item[\texttt{value horizontally : unit -> bool;}]

\

"\texttt{horizontally ()}" returns the fact that the context is
      an horizontal print.
\end{description}

\section{Deprecated modules Stdpp and Token}

\noindent The modules "\texttt{Stdpp}" and "\texttt{Token}" have been
  deprecated since version 5.00.  The module "\texttt{Stdpp}" was
  renamed "\texttt{Ploc}" and most of its variables and types were also
  renamed. The module "\texttt{Token}" was renamed
  "\texttt{Plexing}"

\

\noindent Backward compatibility is assured. See the files
  "\texttt{stdpp.mli}" and "\texttt{token.mli}" in the Camlp5
  distribution to convert from old to new names, if any. After
  several versions or years, the modules "\texttt{Stdpp}" and
  "\texttt{Token}" will disappear from Camlp5.

\clearemptydoublepage

\pagestyle{fancy}\chapter{Camlp5 sources}

\noindent Information for developpers of the Camlp5 program.


\section{Kernel}

\noindent The sources are composed of:

\begin{itemize}
\item the OCaml stuff, copied from the OCaml compiler
\item the \emph{kernel} composed of the directories:
\begin{itemize}
\item odyl : the dynamic loading system
\item lib : the library
\item main : the main program camlp5
\item meta : the parsers for revised syntax, ast quotations,
        EXTEND statement, etc/
\end{itemize}

\item the rest: directories etc, compile, ocpp
\end{itemize}

\noindent Some other directories contain configuration files, tools,
  documentation and manual pages.

\

\noindent The kernel is sufficient to make the core system work: it is possible
  to compile and bootstrap only it. All sources being in revised syntax,
  the first compilation of Camlp5 is done by a version of this kernel
  in pure OCaml syntax, located in the directory ocaml\_src.

\

\noindent These sources in pure OCaml syntax are not modified by hand. When
  changes are made to the kernel, and a check is done that it
  correctly compiles and bootstraps, the kernel in pure OCaml syntax
  is rebuilt using Camlp5 pretty print. This is done by the command
  "make bootstrap\_sources".

\section{Compatibility}

\noindent This distribution of Camlp5 is compatible with several versions of
  OCaml. The definition of OCaml syntax trees may change from OCaml
  version to version, which can be a problem.  Since OCaml does not
  install the sources nor the compiled versions of its syntax tree, a
  copy of the necessary source files, borrowed from the source of the
  OCaml compiler is in the directory 'ocaml\_stuff', in subdirectories
  with the OCaml version number.

\

\noindent If the present distribution of Camlp5 is not compatible with the
  version of OCaml you have (the command 'configure' tells you), it
  is possible to add it. For that, you need the sources to your specific OCaml
  distribution. If you have them then a 'configure' telling you
  that camlp5 is not compatible, do:

\begin{verbatim}
  make steal OCAML_SRC=<path-to-OCaml-sources>
\end{verbatim}

\noindent This creates a new directory in 'ocaml\_stuff' with sources of the
  syntax tree of your OCaml compiler.

\

\noindent If you want to check that the sources of the syntax tree of OCaml
  are up-to-date (e.g. if this is the current OCaml developpement),
  do:

\begin{verbatim}
  make compare_stolen OCAML_SRC=<path-to-OCaml-sources>
\end{verbatim}

\noindent The compatibility is also done with the file 'lib/versdep.ml',
  which is a module containing miscellaneous features depending to
  the version of OCaml.

\

\noindent In the directory 'ocaml\_src' which contains the pure OCaml sources
  of the Camlp5 core (see chapter TREE STRUCTURE below), there are as
  many versions of this files as versions of OCaml. They are named
  'version.ml' in the directory 'lib/versdep'. If you are adding
  a new version of OCaml, you need this file. As a first step, make a
  copy from a close version:

\begin{verbatim}
  cd ocaml_src/lib/versdep
  cp <close_version>.ml <version>.ml
\end{verbatim}

\noindent Then, you can rerun "configure" and do "make core". If the file
  'ocaml\_src/lib/versdep.ml' has compilation problems, fix them 'make
  core' again. When it compiles, copy it into the subdirectory
  'versdep' as '<version>.ml', overwriting the version you copied
  from the close version.

\

\noindent Later, the same file 'lib/versdep.ml' in Camlp5 syntax may have
  similar compilation problems. There is only a single version of this file,
  thanks to IFDEF constructs used here or there.

\

\noindent While compiling with some specific version of OCaml, this file is
  compiled with 'OCAML\_vers' defined where 'vers' is the version number
  form the beginning to the first space or charcter '+' with all dots
  converted into underscores. For example, if your OCaml version is
  7.04.2+dev35, you can see in the compilation process of versdep.ml
  that OCAML\_7\_04\_2 is defined, and you can add statements defined
  by the syntax extension 'pa\_macro.cmo', for example IFDEF OCAML\_7\_04\_2.
  Add statements like that in 'lib/versdep.ml' to make it compile
  successfully.

\section{Tree structure}

\noindent The directory 'ocaml\_src' contains images in pure OCaml syntax of the
  directories odyl lib main and meta. This allows the creation of a core version
  of Camlp5 with only the OCaml compiler installed.

\

\noindent You can decompose the building of the Camlp5 core into:

\begin{description}
\item[1. make library\_cold]

\

just makes the directory 'ocaml\_src/lib' and copy the cmo and cmi
    files into the directory 'boot'
\item[2. make compile\_cold]

\

makes the other directories of ocaml\_src
\item[3. make promote\_cold]

\

copies the executables "camlp5", "camlp5r" and the syntax
    extensions (cmo files) into the directory 'boot'
\end{description}

\noindent From this point, the core Camlp5 is in directory 'boot'. The real
  sources in the top directories odyl, lib, main and meta, which are
  written in revised syntax with some syntax extensions (grammars,
  quotations) can be compiled. To achieve their compilation, you can
  do:

\begin{verbatim}
  make core
\end{verbatim}

\noindent Or to compile everything do:

\begin{verbatim}
  make all
\end{verbatim}

\noindent or just:

\begin{verbatim}
  make
\end{verbatim}

\noindent Notice that doing "make core" or "make all" from scratch (after a
  make clean), automatically starts by making the core files from
  their pure OCaml versions.

\section{Fast compilation from scratch}

\begin{verbatim}
  ./configure
  make clean core compare
  make coreboot
  make all opt opt.opt
\end{verbatim}

\section{Testing changes}

\noindent 1. do your changes

\

\noindent 2. do:

\begin{verbatim}
  make core compare
\end{verbatim}

\noindent if it says that the bootstrap is ok, you can do:

\begin{verbatim}
  make all
  make opt
  make opt.opt
\end{verbatim}

\noindent otherwise, to make sure everything is ok, first do:

\begin{verbatim}
  make coreboot
\end{verbatim}

\noindent sometimes two bootstraps ('make coreboot' twice) are necessary,
  in particular if you change things in the directory 'lib'. It is
  even possible that three bootstraps are necessary.

\

\noindent If things go wrong, it is possible to return to the previous
  version by typing:

\begin{verbatim}
  make restore clean_hot
\end{verbatim}

\noindent then you can change what is necessary and continue by typing:

\begin{verbatim}
  make core
\end{verbatim}

\noindent and test the bootstrap again:

\begin{verbatim}
  make coreboot
\end{verbatim}

\noindent After several bootstraps (by 'make coreboot' or 'make bootstrap'),
  many versions are pushed in the directory 'boot' (you can type 'find
  boot -type d -print' to see that). If your system correctly
  bootstraps, you can clean that by typing:

\begin{verbatim}
  make cleanboot
\end{verbatim}

\noindent which keeps only two versions. (The command 'make clean' also
  removes these stack of versions.)

\section{Before committing your changes}

\noindent Make sure that the cold start with pure OCaml sources work. For
  that, do:

\begin{verbatim}
  make compare_sources | less
\end{verbatim}

\noindent This shows you the changes that would be done in the OCaml pure sources
  of the directory ocaml\_src.

\

\noindent To make the new versions, do:

\begin{verbatim}
  make new_sources
  make promote_sources
\end{verbatim}

\noindent Notice that these pure OCaml sources are not supposed to be modified
  by hand, but only created by the above commands. Although their source
  is pretty printed they are usually not easy to read, particularly for
  expanded grammars (of the statement 'EXTEND').

\

\noindent If these sources do not compile, due to changes in the OCaml
  compiler, it is possible however to edit them. In this case, similar changes
  may need to be performed in the normal sources in revised syntax.

\

\noindent After doing 'make new\_sources' above, and before doing 'make
  promote\_sources' below, it is possible to do 'make untouch\_sources'
  which changes the dates of the newly created files with the dates of the
  old files if they are not modified. This way, the "svn commit" will not
  need to compare these files, which may be important if your
  network is not fast.

\

\noindent The 'make new\_sources' builds a directory named 'ocaml\_src.new'.
  If this directory still exists, due to a previous 'make new\_sources',
  the command fails. In this case, just delete it (rm -rf ocaml\_src.new)
  without problem: this directory is not part of the distribution, it is
  just temporary.

\

\noindent The 'make clean\_sources' deletes old versions of ocaml\_src, keeping
  only the last and the before last ones.

\

\noindent The command:

\begin{verbatim}
  make bootstrap_sources
\end{verbatim}

\noindent is a shortcut for:

\begin{verbatim}
  make new_sources
  make untouch_sources
  make promote_sources
  make clean_sources
\end{verbatim}

\noindent If there are changes in the specific file 'lib/versdep.ml', do
  also:

\begin{verbatim}
  make compare_all_versdep
\end{verbatim}

\noindent and possibly:

\begin{verbatim}
  make bootstrap_all_versdep
\end{verbatim}

\noindent because this file, in 'ocaml\_src/lib/versdep' directory has different
  versions according to the OCaml version.

\

\noindent After having rebuilt the pure OCaml sources, check that they work by
  rebuilding everything from scratch, starting with "configure".

\section{If you change the main parser}

\noindent If you change the main parser 'meta/pa\_r.ml', you should check that the
  quotations expanders of syntax tree 'meta/q\_MLast.ml' match the new
  version. For that, do:

\begin{verbatim}
  cd meta
  make compare_q_MLast
\end{verbatim}

\noindent If no differences are displayed, it means that 'q\_MLast.ml' is ok,
  relatively to 'pa\_r.ml'.

\

\noindent Otherwise, if the displayed differences seem reasonable, update the
  version by typing:

\begin{verbatim}
  make bootstrap_q_MLast
\end{verbatim}

\noindent Then returning to the top directory, do 'make core compare' and
  possibly 'make coreboot' (one of several times) to check the
  correctness of the file.

\

\noindent And don't forget, if you want to commit, to re-create the pure OCaml
  sources like indicated above.

\section{Adding new nodes to the syntax tree}

\noindent If new nodes are necessary in the syntax tree, for example because
  the OCaml language added itself new nodes, the steps are the
  following (with the example of adding the "lazy" pattern node).

\begin{itemize}
\item Add the node in the file 'main/mLast.mli'. Please respect the design
    of the nodes by looking at the other nodes. Example:
\begin{verbatim}
      PaLaz of loc and patt
\end{verbatim}

\item Try to compile (do 'make' in the main directory). You are going to
    have some errors in files telling you that nodes are missing in some
    pattern matchings. Add them, according to the new nodes of OCaml or
    looking at other nodes.
\item Once the compilation is done, try a 'make bootstrap' to be sure
    everything is OK.
\item When it is, add the possible concrete syntax in the revised syntax,
    i.e. in 'meta/pa\_r.ml'. Since the quotation is not yet implemented,
    put it in syntax without quotation. Example:
\begin{verbatim}
  "lazy"; p = SELF -> MLast.PaLaz loc p
\end{verbatim}

\item Do 'make bootstrap' again.
\item Go to the directory 'meta' and type:
\begin{verbatim}
  make compare_q_MLast
\end{verbatim}
    This command try to compare what should be the AST quotation if it
    perfectly matched the syntax. If this comparison seems reasonable,
    change the file 'q\_MLast.ml' by typing:
\begin{verbatim}
  make bootstrap_q_MLast
\end{verbatim}

\item Do a 'make bootstrap' again to check everything is OK. If it is
    change the line of 'meta/pa\_r.ml'. In the example, from:
\begin{verbatim}
  "lazy"; p = SELF -> MLast.PaLaz loc p
\end{verbatim}
    to:
\begin{verbatim}
  "lazy"; p = SELF -> <:patt< lazy $p$ >>
\end{verbatim}

\item The new syntax should work now in revised syntax. You can complete
    the compilation, do a 'make install' and check with the toplevel that
    it works. Complete with the rest like said above.
\item You can then complete the other syntaxes (the 'normal' syntax, for
    example in 'etc/pa\_o.ml') and the pretty printers.
\end{itemize}

\section{Switching between transitional and strict mode}

\noindent If Camlp5 is compiled in some mode, it is possible to change its
  mode in two boostrapping steps. Type:

\begin{verbatim}
  make MODE=T coreboot
\end{verbatim}

\noindent to switch to transitional mode, or:

\begin{verbatim}
  make MODE=S coreboot
\end{verbatim}

\noindent to switch to strict mode.

\

\noindent After two (necessary) bootstraps, the kernel is compiled in the new
  mode. Complete the compilation by:

\begin{verbatim}
  make MODE=T all opt opt.opt
\end{verbatim}

\noindent or:

\begin{verbatim}
  make MODE=S all opt opt.opt
\end{verbatim}

\noindent according to the new mode you want to use.

\

\noindent Another solution is, of course, recompile everything from scratch:

\begin{verbatim}
  make clean
  ./configure -transitional
  make world.opt
\end{verbatim}

\noindent or:

\begin{verbatim}
  make clean
  ./configure -strict
  make world.opt
\end{verbatim}

\section{Bootstrapping}

\noindent Camlp5 is bootstrapped in numerous ways.

\subsection{Camlp5 executable bootstrapping}

\noindent The file 'main/camlp5r' is rebuilt each time a bootstrapping command
  is used (like 'make coreboot' or 'make bootstrap'). This bootstrapping
  command starts with copying it in the directory 'boot'. The file
  'boot/camlp5r' is used to recompile the sources, creating another
  file 'main/camlp5r'. When both files are the same (byte by byte),
  the Camlp5 executable is bootstrapped.

\

\noindent Sometimes, in particular when changes are done in the library
  (directory 'lib'), it is necessary to bootstrap twice before having
  the message 'Fixpoint reached, bootstrap succeeded'.

\

\noindent The command 'make compare' tells you whether the Camlp5 executable
  is currently bootstrapped or not.

\subsection{Source bootstrapping}

\noindent The compilation of Camlp5 starts with the compilation of files of
  the directory ocaml\_src written in pure OCaml. This creates the
  files 'camlp5' and 'camlp5r' in the directory boot. This is called
  the 'cold start'.

\

\noindent Once done, the sources of Camlp5 can be compiled using revised
  syntax and several syntax extensions, like the statement 'EXTEND',
  for example, and the quotations of syntax trees.

\

\noindent The core files of Camlp5 are in the directories lib, main, meta,
  odyl.  There are the same directories in the directory ocaml\_src
  where all files are equivalent.

\

\noindent When changes are done in the core files, and when the printer kit
  in normal syntax 'etc/pr\_o.cmo' has been created, the files of the
  directory ocaml\_src can be rebuilt using the command 'make
  bootstrap\_sources'. This updates the files in ocaml\_src to exactly
  reflect the ones in the core, but in pure OCaml syntax.

\

\noindent Bootstrap: the1 files in ocaml\_src creates the first Camlp5
  executable. The Camlp5 executable can rebuild the files in
  ocaml\_src.

\subsection{Source file q\_MLast.ml bootstrapping}

\noindent The source file meta/q\_MLast.ml (quotation of syntax trees) can be
  recreated using the file meta/pa\_r.ml (revised syntax). When changes
  are done in the file meta/pa\_r.ml, a good usage is to go to the
  directory 'meta' and type:

\begin{verbatim}
    make compare_q_MLast
\end{verbatim}

\noindent This shows the possible changes that will be applied to
  meta/q\_MLast.ml. If they seem to be reasonable, do:

\begin{verbatim}
    make bootstrap_q_MLast
\end{verbatim}

\noindent This changes the source file meta/q\_MLast.ml. After this command,
  a new 'make compare\_q\_MLast' indicates no differences.

\

\noindent After that, a new 'make bootstrap' in the top directory ensures that
  everythings works.

\

\noindent Bootstrap: the file meta/pa\_r.ml uses the quotation expander
  meta/q\_MLast.cmo. The source file meta/q\_MLast.ml is recreated by
  meta/pa\_r.ml.

\subsection{Source file q\_ast.ml bootstrapping}

\noindent The source file meta/q\_ast.ml contains another version of the
  quotation expander of syntax trees which follows the current
  syntax used (in normal syntax if the current syntax is used).
  This works only in strict mode.

\

\noindent This file depends on the definition of the syntax tree
  main/mLast.mli. When changes are done in this file, it is
  possible to see what changes are impacted in meta/q\_ast.ml. For
  this, go to the directory 'meta' and type:

\begin{verbatim}
    make compare_q_ast
\end{verbatim}

\noindent This shows the possible changes that will be applied to
  meta/q\_ast.ml. If they seem to be reasonable, do:

\begin{verbatim}
    make bootstrap_q_ast
\end{verbatim}

\noindent This changes the source file meta/q\_ast.ml. After this command, a
  new 'make compare\_q\_ast' indicates no differences.

\

\noindent After that, a new 'make bootstrap' in the top directory ensures that
  everythings works.

\subsection{Lisp and Scheme syntax bootstrapping}

\noindent The Lisp syntax is written in Lisp syntax in the directory etc. It
  is the file 'etc/pa\_lisp.ml'. To compile this file, there is another
  file, named 'etc/pa\_lispr.ml' written in revised syntax.

\

\noindent When changes are done in etc/pa\_lisp.ml, the file etc/pa\_lispr.ml
  must be rebuilt. First, go to the directory 'etc' and type:

\begin{verbatim}
    make compare_lisp
\end{verbatim}

\noindent If changes seem to be reasonable, do:

\begin{verbatim}
    make boostrap_lisp
\end{verbatim}

\noindent This rebuilds 'etc/pa\_lispr.ml'. A new 'make' in the directory 'etc'
  will recompile it and recompile the Lisp version 'etc/pa\_lisp.ml'.

\

\noindent Bootstrap: etc/pa\_lispr.ml allows to compile etc/pa\_lisp.ml, and
  changes is etc/pa\_lisp.ml are reported in the source file etc/pa\_lispr.ml
  through 'make bootstrap\_lisp'.

\

\noindent Same for the Scheme syntax: the files are etc/pa\_scheme.ml and
  'etc/pa\_scheme.ml'.

\subsection{EXTEND statement bootstrapping}

\noindent The EXTEND statement of Camlp5 is a syntax extension. The file
  'meta/pa\_extend.ml' contains the statement for the adding of this
  syntax extension, therefore something like:

\begin{verbatim}
    EXTEND
      expr:
        [ [ "EXTEND" .....
\end{verbatim}

\noindent To be compiled, the file 'meta/pa\_extend.ml' needs 'pa\_extend.cmo'.
  This is actually its previous version in the directory 'boot'. When
  checking for a correct bootstrapping of Camlp5 (with the command
  'make compare', for example), a test is done to verify that the
  binary files 'meta/pa\_extend.cmo' and 'boot/pa\_extend.cmo' are the
  same.

\

\noindent Notice that there is also a file 'ocaml\_src/meta/pa\_extend.ml' in
  pure OCaml syntax, but, although this file is pretty printed, is is
  hardly editable, because the expansion of the 'EXTEND' statement is
  a very long expression rather difficult to understand. But this file
  need not to be changes, since the command 'make
  bootstrap\_sources' (see above) rebuilts it.

\clearemptydoublepage

\pagestyle{fancy}\chapter{About Camlp5}

\begin{description}
\item[Version]

\

6.13
\item[Home page]

\

http://pauillac.inria.fr/\~{}ddr/camlp5/
\item[Author]

\

Daniel de Rauglaudre, INRIA
\item[History]

\

The ideas behind Camlp5 were expressed in the 1990s by Michel
    Mauny. In 1996, Daniel de Rauglaudre implemented the first version
    named Camlp4 (the four "p" standing for
    "Pre-Processor-Pretty-Printer"). In 2002, Camlp4 was maintained by
    Michel Mauny, and later extended by Nicolas Pouillard, with
    different basic ideas, introducing some incompatibilities.  In
    2006, Daniel de Rauglaudre restarted this work, renaming it
    Camlp5.
\end{description}

\begin{verbatim}
* Copyright (c) 2007-2014, INRIA (Institut National de Recherches en
* Informatique et Automatique). All rights reserved.
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions are met:
*
*     * Redistributions of source code must retain the above copyright
*       notice, this list of conditions and the following disclaimer.
*     * Redistributions in binary form must reproduce the above copyright
*       notice, this list of conditions and the following disclaimer in the
*       documentation and/or other materials provided with the distribution.
*     * Neither the name of INRIA, nor the names of its contributors may be
*       used to endorse or promote products derived from this software without
*       specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY INRIA AND CONTRIBUTORS ``AS IS'' AND
* ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
* THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
* PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL INRIA AND
* CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
* USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
* ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
* OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
* OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
* SUCH DAMAGE.
\end{verbatim}

\end{document}
