@@ -125,8 +125,26 @@ derive newtype instance monadErrorParserT :: Monad m => MonadError ParseError (P
125125-- | While we are parsing down the `p_left` branch we may reach a point where
126126-- | we know this is the correct branch, but we cannot parse further. At
127127-- | that point we want to fail the entire parse instead of trying the `p_right`
128- -- | branch. To control the point at which we commit to the `p_left` branch
129- -- | use the `try` combinator.
128+ -- | branch.
129+ -- |
130+ -- | For example, consider this `fileParser` which can parse either an HTML
131+ -- | file that begins with `<html>` or a shell script file that begins with `#!`.
132+ -- |
133+ -- | ```
134+ -- | fileParser =
135+ -- | string "<html>" *> parseTheRestOfTheHtml
136+ -- | <|>
137+ -- | string "#!" *> parseTheRestOfTheScript
138+ -- | ```
139+ -- |
140+ -- | If we read a file from disk and run this `fileParser` on it and the
141+ -- | `string "<html>"` parser succeeds, then we know that the first branch
142+ -- | is the correct branch. Even if the `parseTheRestOfTheHtml` parser fails
143+ -- | we don’t want to try the other branch.
144+ -- |
145+ -- | To control the point at which we commit to the `p_left` branch
146+ -- | use the `try` combinator and the `lookAhead` combinator and
147+ -- | the `consume` function.
130148-- |
131149-- | The `alt` combinator works this way because it gives us good localized
132150-- | error messages while also allowing an efficient implementation.
@@ -151,6 +169,10 @@ instance monadTransParserT :: MonadTrans (ParserT s) where
151169 lift = ParserT <<< lift <<< lift
152170
153171-- | Set the consumed flag.
172+ -- |
173+ -- | Setting the consumed flag means that we're committed to this parsing branch
174+ -- | of an alternative (`<|>`), so that if this branch fails then we want to
175+ -- | fail the entire parse instead of trying the other alternative.
154176consume :: forall s m . Monad m => ParserT s m Unit
155177consume = modify_ \(ParseState input pos _) ->
156178 ParseState input pos true
0 commit comments