@@ -8,8 +8,8 @@
88-- Stability : experimental
99-- Portability : unknown
1010--
11−-- Simple, efficient parser combinators for strings, loosely based on
12−-- the Parsec library.
11+-- Simple, efficient parser combinators, loosely based on the Parsec
12+-- library.
1313
1414module Data.Attoparsec.Internal.Types
1515 (
@@ -31,24 +31,26 @@ import Control.Monad (MonadPlus(..))
3131import Data.Monoid (Monoid(..))
3232import Prelude hiding (getChar, take, takeWhile)
3333
34−-- | The result of a parse.
34+-- | The result of a parse. This is parameterised over the type @t@
35+-- of string that was processed.
3536--
3637-- This type is an instance of 'Functor', where 'fmap' transforms the
3738-- value in a 'Done' result.
3839data IResult t r = Fail t [String] String
39− -- ^ The parse failed. The 't' is the input that had
40− -- not yet been consumed when the failure occurred.
41− -- The @[@'String'@]@ is a list of contexts in which
42− -- the error occurred. The 'String' is the message
43− -- describing the error, if any.
40+ -- ^ The parse failed. The 't' parameter is the
41+ -- input that had not yet been consumed when the
42+ -- failure occurred. The @[@'String'@]@ is a list of
43+ -- contexts in which the error occurred. The
44+ -- 'String' is the message describing the error, if
45+ -- any.
4446 | Partial (t -> IResult t r)
4547 -- ^ Supply this continuation with more input so that
4648 -- the parser can resume. To indicate that no more
4749 -- input is available, use an empty string.
4850 | Done t r
49− -- ^ The parse succeeded. The 't' is the input that
50− -- had not yet been consumed (if any) when the parse
51− -- succeeded.
51+ -- ^ The parse succeeded. The 't' parameter is the
52+ -- input that had not yet been consumed (if any) when
53+ -- the parse succeeded.
5254
5355instance (Show t, Show r) => Show (IResult t r) where
5456 show (Fail t stk msg) =
@@ -57,7 +59,7 @@ instance (Show t, Show r) => Show (IResult t r) where
5759 show (Done t r) = "Done " ++ show t ++ " " ++ show r
5860
5961instance (NFData t, NFData r) => NFData (IResult t r) where
60− rnf (Fail t _ _) = rnf t
62+ rnf (Fail t stk msg) = rnf t `seq` rnf stk `seq` rnf msg
6163 rnf (Partial _) = ()
6264 rnf (Done t r) = rnf t `seq` rnf r
6365 {-# INLINE rnf #-}
@@ -74,7 +76,8 @@ instance Functor (IResult t) where
7476newtype Input t = I {unI :: t}
7577newtype Added t = A {unA :: t}
7678
77−-- | The 'Parser' type.
79+-- | The core parser type. This is parameterised over the type @t@ of
80+-- string being processed.
7881--
7982-- This type is an instance of the following classes:
8083--
@@ -85,7 +88,10 @@ newtype Added t = A {unA :: t}
8588--
8689-- * 'MonadPlus', where 'mzero' fails (with no error message) and
8790-- 'mplus' executes the right-hand parser if the left-hand one
88−-- fails.
91+-- fails. When the parser on the right executes, the input is reset
92+-- to the same state as the parser on the left started with. (In
93+-- other words, Attoparsec is a backtracking parser that supports
94+-- arbitrary lookahead.)
8995--
9096-- * 'Alternative', which follows 'MonadPlus'.
9197newtype Parser t a = Parser {