Expose shift events in the incremental API.

CHANGES

+2015/01/18:
+Incompatible change of the incremental API.
+The incremental API now exposes shift events too.
+
 2015/01/16:
 Fixed a couple bugs in Makefile and src/Makefile which would cause
 compilation and installation to fail with "TARGET=byte". (Reported

demos/calc-incremental/calc.ml

@@ -20,7 +20,8 @@ let rec loop lexbuf (result : int I.result) =
       and endp = lexbuf.Lexing.lex_curr_p in
       let result = I.offer result (token, startp, endp) in
       loop lexbuf result
-  | I.AboutToReduce (env, prod) ->
+  | I.Shifting _
+  | I.AboutToReduce _ ->
       let result = I.resume result in
       loop lexbuf result
   | I.HandlingError env ->

src/IncrementalEngine.ml

@@ -19,16 +19,18 @@ module type INCREMENTAL_ENGINE = sig
   (* [InputNeeded] is an intermediate result. It means that the parser wishes
      to read one token before continuing. *)
 
+  (* [Shifting] is an intermediate result. It means that the parser is taking
+     a shift transition. It exposes the state of the parser before and after
+     the transition. The Boolean parameter tells whether the parser intends to
+     request a new token after this transition. (It always does, except when
+     it is about to accept.) *)
+
   (* [AboutToReduce] is an intermediate result. It means that the parser is
-     about to perform a reduction step. It does not need more input at this
-     point. The parser suspends itself at this point only in order to give the
-     user an opportunity to observe this reduction step. *)
+     about to perform a reduction step. It exposes the parser's current
+     state as well as the production that is about to be reduced. *)
 
   (* [HandlingError] is an intermediate result. It means that the parser has
-     detected an error and is currently handling it, in several steps. It does
-     not need more input at this point. The parser suspends itself at this
-     point only in order to give the user an opportunity to handle this error
-     in a different manner, if desired. *)
+     detected an error and is currently handling it, in several steps. *)
 
   type env
 
@@ -36,6 +38,7 @@ module type INCREMENTAL_ENGINE = sig
 
   type 'a result = private
     | InputNeeded of env
+    | Shifting of env * env * bool
     | AboutToReduce of env * production
     | HandlingError of env
     | Accepted of 'a

src/engine.ml

@@ -28,6 +28,7 @@ module Make (T : TABLE) = struct
 
   type 'a result =
     | InputNeeded of env
+    | Shifting of env * env * bool
     | AboutToReduce of env * production
     | HandlingError of env
     | Accepted of 'a
@@ -176,9 +177,16 @@ module Make (T : TABLE) = struct
 
     (* Switch to state [s']. *)
 
-    let current = s' in
-    let env = { env with stack; current } in
-    run env please_discard
+    let new_env = { env with stack; current = s' } in
+
+    (* Expose the transition to the user. (In principle, we have a choice
+       between exposing the transition before we take it, after we take
+       it, or at some point in between. This affects the number and type
+       of the parameters carried by [Shifting]. Here, we choose to expose
+       the transition after we take it; this allows [Shifting] to carry
+       only three parameters, whose meaning is simple.) *)
+
+    Shifting (env, new_env, please_discard)
 
   (* --------------------------------------------------------------------------- *)
 
@@ -411,6 +419,8 @@ module Make (T : TABLE) = struct
   let resume : 'a . 'a result -> 'a result = function
     | HandlingError env ->
         Obj.magic error env
+    | Shifting (_, env, please_discard) ->
+        Obj.magic run env please_discard
     | AboutToReduce (env, prod) ->
         Obj.magic reduce env prod
     | _ ->
@@ -458,6 +468,7 @@ module Make (T : TABLE) = struct
         let triple = read() in
         let result = offer result triple in
         loop read result
+    | Shifting _
     | AboutToReduce _
     | HandlingError _ ->
         (* The parser has suspended itself, but does not need