Defined the signature INCREMENTAL_ENGINE in a new file

IncrementalEngine, so as to reduce confusion and allow
including this file in the documentation.

GNUmakefile

@@ -81,6 +81,7 @@ LIBFILES := \
   src/infiniteArray.{ml,mli} \
   src/packedIntArray.{ml,mli} \
   src/rowDisplacement.{ml,mli} \
+  src/IncrementalEngine.ml \
   src/engineTypes.ml \
   src/engine.{ml,mli} \
   src/tableFormat.ml \

LICENSE

@@ -4,6 +4,7 @@ In the following, "the Library" refers to the following files:
   src/infiniteArray.{ml,mli}
   src/packedIntArray.{ml,mli}
   src/rowDisplacement.{ml,mli}
+  src/IncrementalEngine.ml
   src/engineTypes.ml
   src/engine.{ml,mli}
   src/tableFormat.ml

TODO

-* Place INCREMENTAL_ENGINE in a separate file, so as to reduce confusion        
-  and allow including this file in the documentation
-
 * Test incremental interface in conjunction with %parameter
 
 * Include comments in the generated .mli file (Interface)?

src/IncrementalEngine.ml

+(* This signature describes the incremental LR engine. *)
+
+(* In this mode, the user controls the lexer, and the parser suspends
+   itself when it needs to read a new token. *)
+
+module type INCREMENTAL_ENGINE = sig
+
+  type token
+
+  (* The type ['a result] represents an intermediate or final result of the
+     parser. An intermediate result can be thought of as a suspension: it
+     records the parser's current state, and allows parsing to be resumed.
+     The parameter ['a] is the type of the final semantic value that will
+     be produced if the parser succeeds. *)
+
+  (* [InputNeeded] is an intermediate result, which means that the parser
+     wishes to read one token before continuing. [HandlingError] is also
+     an intermediate result, which means that the parser has detected and
+     is trying to handle an error. It does not need more input at this
+     point; it is suspending itself only in order to give the user an
+     opportunity to handle this error in a different manner, if desired.
+     [Accepted] and [Rejected] are final results. *)
+
+  (* The type [('a, 'pc) env] is shared by [InputNeeded] and [HandlingError].
+     As above, the parameter ['a] is the type of the final semantic value.
+     The phantom type parameter ['pc] is instantiated with [input_needed]
+     or [handling_error], as appropriate. This prevents the user from
+     calling [offer] when she should call [handle], or vice-versa. *)
+
+  type input_needed
+  type handling_error
+
+  type ('a, 'pc) env
+
+  type 'a result =
+    | InputNeeded of ('a, input_needed) env
+    | HandlingError of ('a, handling_error) env
+    | Accepted of 'a
+    | Rejected
+
+  (* [offer] allows the user to resume the parser after it has suspended
+     itself with a result of the form [InputNeeded env] result. [offer]
+     expects [env] as well as a new token and produces a new result. It
+     does not raise any exception. *)
+
+  val offer:
+    ('a, input_needed) env ->
+    token * Lexing.position * Lexing.position ->
+    'a result
+
+  (* [handle] allows the user to resume the parser after it has suspended
+     itself with a result of the form [HandlingError env]. [handle] expects
+     [env] and produces a new result. It does not raise any exception. *)
+
+  val handle:
+    ('a, handling_error) env ->
+    'a result
+
+  (* The incremental interface is more general than the monolithic one.
+     [entry] can be (and is indeed) implemented by first calling [start],
+     then calling [offer] and [handle] in a loop, until a final result
+     is obtained. *)
+
+end

src/_tags

@@ -17,10 +17,12 @@
 
 # Every module that is part of MenhirLib must be tagged as such.
 # If you change this list, please also update the files LICENSE
-# and GNUmakefile in the toplevel directory.
+# and GNUmakefile in the toplevel directory, and update the file
+# menhirLib.mlpack in this directory.
 <infiniteArray.cmx>: for-pack(MenhirLib)
 <packedIntArray.cmx>: for-pack(MenhirLib)
 <rowDisplacement.cmx>: for-pack(MenhirLib)
+<IncrementalEngine.cmx>: for-pack(MenhirLib)
 <engineTypes.cmx>: for-pack(MenhirLib)
 <engine.cmx>: for-pack(MenhirLib)
 <tableFormat.cmx>: for-pack(MenhirLib)

src/engineTypes.ml

@@ -306,70 +306,14 @@ end
 
 (* --------------------------------------------------------------------------- *)
 
-(* This signature describes the incremental LR engine. *)
+(* The following signatures describe the incremental LR engine. *)
 
-(* In this interface, the user controls the lexer, and the parser suspends
-   itself when it needs to read a new token. *)
+(* First, see [INCREMENTAL_ENGINE] in the file [IncrementalEngine.ml]. *)
 
-module type INCREMENTAL_ENGINE = sig
-
-  type token
-
-  (* The type ['a result] represents an intermediate or final result of the
-     parser. An intermediate result can be thought of as a suspension: it
-     records the parser's current state, and allows parsing to be resumed.
-     The parameter ['a] is the type of the final semantic value that will
-     be produced if the parser succeeds. *)
-
-  (* [InputNeeded] is an intermediate result, which means that the parser
-     wishes to read one token before continuing. [HandlingError] is also
-     an intermediate result, which means that the parser has detected and
-     is trying to handle an error. It does not need more input at this
-     point; it is suspending itself only in order to give the user an
-     opportunity to handle this error in a different manner, if desired.
-     [Accepted] and [Rejected] are final results. *)
-
-  (* The type [('a, 'pc) env] is shared by [InputNeeded] and [HandlingError].
-     As above, the parameter ['a] is the type of the final semantic value.
-     The phantom type parameter ['pc] is instantiated with [input_needed]
-     or [handling_error], as appropriate. This prevents the user from
-     calling [offer] when she should call [handle], or vice-versa. *)
-
-  type input_needed
-  type handling_error
-
-  type ('a, 'pc) env
-
-  type 'a result =
-    | InputNeeded of ('a, input_needed) env
-    | HandlingError of ('a, handling_error) env
-    | Accepted of 'a
-    | Rejected
-
-  (* [offer] allows the user to resume the parser after it has suspended
-     itself with a result of the form [InputNeeded env] result. [offer]
-     expects [env] as well as a new token and produces a new result. It
-     does not raise any exception. *)
-
-  val offer:
-    ('a, input_needed) env ->
-    token * Lexing.position * Lexing.position ->
-    'a result
-
-  (* [handle] allows the user to resume the parser after it has suspended
-     itself with a result of the form [HandlingError env]. [handle] expects
-     [env] and produces a new result. It does not raise any exception. *)
-
-  val handle:
-    ('a, handling_error) env ->
-    'a result
-
-  (* The incremental interface is more general than the monolithic one.
-     [entry] can be (and is indeed) implemented by first calling [start],
-     then calling [offer] and [handle] in a loop, until a final result
-     is obtained. *)
-
-end
+(* The [start] function is set apart because we do not wish to publish
+   it as part of the generated [parser.mli] file. Instead, the table
+   back-end will publish specialized versions of it, with a suitable
+   type cast. *)
 
 module type INCREMENTAL_ENGINE_START = sig
 
@@ -399,16 +343,11 @@ end
 (* This signature describes the LR engine, which combines the monolithic
    and incremental interfaces. *)
 
-(* The [start] function is set apart because we do not wish to publish
-   it as part of the generated [parser.mli] file. Instead, the table
-   back-end will publish specialized versions of it, with a suitable
-   type cast. *)
-
 module type ENGINE = sig
 
   include MONOLITHIC_ENGINE
 
-  include INCREMENTAL_ENGINE
+  include IncrementalEngine.INCREMENTAL_ENGINE
     with type token := token
 
   include INCREMENTAL_ENGINE_START

src/interface.ml

@@ -65,7 +65,7 @@ let table_interface =
     IIModule (
       interpreter,
       MTWithType (
-        MTNamedModuleType "MenhirLib.EngineTypes.INCREMENTAL_ENGINE",
+        MTNamedModuleType "MenhirLib.IncrementalEngine.INCREMENTAL_ENGINE",
         tctoken, WKDestructive, ttoken
       )
     );

src/menhirLib.mlpack

 # If you change this list, please also update the files LICENSE
-# and GNUmakefile in the toplevel directory.
+# and GNUmakefile in the toplevel directory, and update the file
+# _tags in this directory.
 InfiniteArray
 PackedIntArray
 RowDisplacement
+IncrementalEngine
 EngineTypes
 Engine
 TableFormat