@@ -327,21 +327,20 @@ instance Functor (Initial s) where
327{-# ANN type Step Fuse #-}
327{-# ANN type Step Fuse #-}
328data Step s b =
328data Step s b =
329 Partial !Int !s
329 Partial !Int !s
330− -- ^ Partial result with an optional backtrack request.
330+ -- ^ @Partial count state@. The following hold:
332− -- @Partial count state@ means a partial result is available which
332+ -- 1. @extract@ on @state@ would succeed and give a result.
333− -- can be extracted successfully, @state@ is the opaque state of the
333+ -- 2. Current input stream position is reset to @current position - count@.
334− -- parser to be supplied to the next invocation of the step operation.
334+ -- 3. All input before the new current position is dropped. The parser can
335− -- The current input position is reset to @count@ elements back and any
335+ -- never backtrack beyond this position.
336− -- input before that is dropped from the backtrack buffer.
338 | Continue !Int !s
337 | Continue !Int !s
339− -- ^ Need more input with an optional backtrack request.
338+ -- ^ @Continue count state@. The following hold:
341− -- @Continue count state@ means the parser has consumed the current input
340+ -- 1. @extract@ on @state@ would give the last 'Partial' result or throw
342− -- but no new result is generated, @state@ is the next state of the parser.
341+ -- 'ParseError' if there is none.
342+ -- 2. Current input stream position is reset to @current position - count@.
343− -- The current input is retained in the backtrack buffer and the input
343+ -- 3. the input is retained in a backtrack buffer.
344− -- position is reset to @count@ elements back.
346 | Done !Int !b
345 | Done !Int !b
347 -- ^ Done with leftover input count and result.
346 -- ^ Done with leftover input count and result.
@@ -950,7 +949,7 @@ alt (Parser stepL initialL extractL) (Parser stepR initialR extractR) =
950 -- restriction helps us make backtracking more efficient, as we do not need
949 -- restriction helps us make backtracking more efficient, as we do not need
951 -- to keep the consumed items buffered after a yield. Note that we do not
950 -- to keep the consumed items buffered after a yield. Note that we do not
952 -- enforce this and if a misbehaving parser does not honor this then we can
951 -- enforce this and if a misbehaving parser does not honor this then we can
953− -- get unexpected results.
952+ -- get unexpected results. XXX Can we detect and flag this?
954 step (AltParseL cnt st) a = do
953 step (AltParseL cnt st) a = do
955 r <- stepL st a
954 r <- stepL st a
956 case r of
955 case r of