Renamed main_incremental to Incremental.main.

This guarantees the absence of name clashes.

CHANGES

+2015/01/01:
+Incompatible change of the incremental API.
+The entry point main_incremental is now named Incremental.main.
+
 2014/12/29:
 Incompatible change of the incremental API.
 The API now exposes reduction events.

TODO

-* Introduce a submodule Incremental for the incremental entry
-  points. Move also the types terminal, nonterminal, symbol
-  to a sub-module, to avoid any name clashes.
-
-* Clean up Interface and tableBackend. Decide whether we need
-  a new switch (--inspect) for the inspection API. Condition
-  [terminal], [nonterminal], etc. to this new switch.
-
 * IncrementalEngine: document [lr1state], [element], [view].
 
 * Define MenhirLib.Stream?

demos/calc-incremental/calc.ml

@@ -107,7 +107,7 @@ let rec loop linebuf (result : int I.result) =
 let process (line : string) =
   let linebuf = Lexing.from_string line in
   try
-    loop linebuf (Parser.main_incremental())
+    loop linebuf (Parser.Incremental.main())
   with
   | Lexer.Error msg ->
       Printf.fprintf stderr "%s%!" msg

doc/main.tex

@@ -1797,7 +1797,8 @@ We assume that the grammar specification has just one start symbol
 \label{sec:monolithic}
 
 The monolithic API consists in just one parsing function, named after the
-start symbol:
+start symbol. The generated file \texttt{parser.mli} contains the following
+declaration:
 \begin{verbatim}
   val main: (Lexing.lexbuf -> token) -> Lexing.lexbuf -> thing
 \end{verbatim}
@@ -1839,10 +1840,14 @@ $O(n)$ space in memory.
 % TEMPORARY actually, live parsing also requires a way of performing
 % error recovery, up to a complete parse... as in Merlin.
 
-In this API, the parser is started by invoking \verb+main_incremental+,
-where \mystartsymbol is the name of the start symbol:
+In this API, the parser is started by invoking
+\texttt{Incremental.\mystartsymbol}.  (Recall that we assume \mystartsymbol is
+the name of the start symbol.) The generated file \texttt{parser.mli} contains
+the following declaration:
 \begin{verbatim}
-  val main_incremental: unit -> thing MenhirInterpreter.result
+  module Incremental : sig
+    val main: unit -> thing MenhirInterpreter.result
+  end
 \end{verbatim}
 
 The sub-module \menhirinterpreter is also part of the incremental API.
@@ -1932,10 +1937,10 @@ parser has suspended itself with a result of the form
 This function expects just the previous result \verb+result+. It produces a new
 result. It does not raise any exception.
 
-The incremental API subsumes the monolithic API. Indeed, \verb+main+ can
-be (and is in fact) implemented by first using \verb+main_incremental+, then
-calling \verb+offer+ and \verb+resume+ in a loop, until a final result is
-obtained.
+The incremental API subsumes the monolithic API. Indeed, \mystartsymbol can be
+(and is in fact) implemented by first using
+\texttt{Incremental.\mystartsymbol}, then calling \verb+offer+ and
+\verb+resume+ in a loop, until a final result is obtained.
 
 At this time, because the type \verb+env+ is opaque, the state of the parser
 cannot be inspected by the user. We plan to offer an inspection API in the

src/interface.ml

@@ -40,13 +40,10 @@ let result t =
 
 (* -------------------------------------------------------------------------- *)
 
-(* The name of the incremental entry point for the start symbol [symbol]. *)
+(* The name of the sub-module that contains the incremental entry points. *)
 
-let incremental symbol =
-  (* This convention is not great. A name clash with a non-incremental
-     entry point is possible if there exists a nonterminal symbol whose name
-     ends with [_incremental]. It would be preferable to introduce a sub-module. *)
-  Misc.normalize symbol ^ "_incremental"
+let incremental =
+  "Incremental"
 
 (* The type of the incremental entry point for the start symbol [symbol]. *)
 
@@ -93,11 +90,13 @@ let incremental_api grammar () =
   ) ::
 
   IIComment "The entry point(s) to the incremental API." ::
+  IIModule (incremental, MTSigEnd [
     IIValDecls (
       StringSet.fold (fun symbol decls ->
-      (incremental symbol, entrytypescheme_incremental grammar symbol) :: decls
+        (symbol, entrytypescheme_incremental grammar symbol) :: decls
       ) grammar.start_symbols []
-  ) ::
+    )
+  ]) ::
 
   []
 

src/interface.mli

@@ -19,9 +19,9 @@ val interpreter: string
 
 val result: IL.typ -> IL.typ
 
-(* The name of the incremental entry point for the start symbol [symbol]. *)
+(* The name of the sub-module that contains the incremental entry points. *)
 
-val incremental: string -> string
+val incremental: string
 
 (* This writes the interface of the generated parser to the [.mli] file. *)
 

src/tableBackend.ml

@@ -687,7 +687,9 @@ let application =
 
 (* ------------------------------------------------------------------------ *)
 
-(* The client API invokes the interpreter with an appropriate start state. *)
+(* The client APIs invoke the interpreter with an appropriate start state.
+   The monolithic API calls [entry] (see [Engine]), while the incremental
+   API calls [start]. *)
 
 (* An entry point to the monolithic API. *)
 
@@ -713,11 +715,19 @@ let monolithic_entry_point state nt t =
     )
   )
 
+(* The whole monolithic API. *)
+
+let monolithic_api : IL.valdef list =
+  Lr1.fold_entry (fun _prod state nt t api ->
+    monolithic_entry_point state nt t ::
+    api
+  ) []
+
 (* An entry point to the incremental API. *)
 
 let incremental_entry_point state nt t =
   define (
-    incremental (Nonterminal.print true nt),
+    Nonterminal.print true nt,
     (* In principle the abstraction [fun () -> ...] should not be
        necessary, since [start] is a pure function. However, when
        [--trace] is enabled, [start] will log messages to the
@@ -737,9 +747,10 @@ let incremental_entry_point state nt t =
     )
   )
 
-let api : IL.valdef list =
+(* The whole incremental API. *)
+
+let incremental_api : IL.valdef list =
   Lr1.fold_entry (fun _prod state nt t api ->
-    monolithic_entry_point state nt t ::
     incremental_entry_point state nt t ::
     api
   ) []
@@ -859,7 +870,11 @@ let program =
 
     SIModuleDef (interpreter, application) ::
 
-    SIValDefs (false, api) ::
+    SIValDefs (false, monolithic_api) ::
+
+    SIModuleDef (incremental, MStruct [
+      SIValDefs (false, incremental_api)
+    ]) ::
 
     listiflazy Settings.inspection (fun () ->