@@ -8,8 +8,8 @@
8-- Stability : experimental
8-- Stability : experimental
9-- Portability : unknown
9-- Portability : unknown
11−-- Simple, efficient parser combinators for strings, loosely based on
11+-- Simple, efficient parser combinators, loosely based on the Parsec
12−-- the Parsec library.
12+-- library.
14module Data.Attoparsec.Internal.Types
14module Data.Attoparsec.Internal.Types
@@ -31,24 +31,26 @@ import Control.Monad (MonadPlus(..))
31import Data.Monoid (Monoid(..))
31import Data.Monoid (Monoid(..))
32import Prelude hiding (getChar, take, takeWhile)
32import Prelude hiding (getChar, take, takeWhile)
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.
36-- This type is an instance of 'Functor', where 'fmap' transforms the
37-- This type is an instance of 'Functor', where 'fmap' transforms the
37-- value in a 'Done' result.
38-- value in a 'Done' result.
38data IResult t r = Fail t [String] String
39data IResult t r = Fail t [String] String
39− -- ^ The parse failed. The 't' is the input that had
40+ -- ^ The parse failed. The 't' parameter is the
40− -- not yet been consumed when the failure occurred.
41+ -- input that had not yet been consumed when the
41− -- The @[@'String'@]@ is a list of contexts in which
42+ -- failure occurred. The @[@'String'@]@ is a list of
42− -- the error occurred. The 'String' is the message
43+ -- contexts in which the error occurred. The
43− -- describing the error, if any.
44+ -- 'String' is the message describing the error, if
44 | Partial (t -> IResult t r)
46 | Partial (t -> IResult t r)
45 -- ^ Supply this continuation with more input so that
47 -- ^ Supply this continuation with more input so that
46 -- the parser can resume. To indicate that no more
48 -- the parser can resume. To indicate that no more
47 -- input is available, use an empty string.
49 -- input is available, use an empty string.
48 | Done t r
50 | Done t r
49− -- ^ The parse succeeded. The 't' is the input that
51+ -- ^ The parse succeeded. The 't' parameter is the
50− -- had not yet been consumed (if any) when the parse
52+ -- input that had not yet been consumed (if any) when
51− -- succeeded.
53+ -- the parse succeeded.
53instance (Show t, Show r) => Show (IResult t r) where
55instance (Show t, Show r) => Show (IResult t r) where
54 show (Fail t stk msg) =
56 show (Fail t stk msg) =
@@ -57,7 +59,7 @@ instance (Show t, Show r) => Show (IResult t r) where
57 show (Done t r) = "Done " ++ show t ++ " " ++ show r
59 show (Done t r) = "Done " ++ show t ++ " " ++ show r
59instance (NFData t, NFData r) => NFData (IResult t r) where
61instance (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
61 rnf (Partial _) = ()
63 rnf (Partial _) = ()
62 rnf (Done t r) = rnf t `seq` rnf r
64 rnf (Done t r) = rnf t `seq` rnf r
63 {-# INLINE rnf #-}
65 {-# INLINE rnf #-}
@@ -74,7 +76,8 @@ instance Functor (IResult t) where
74newtype Input t = I {unI :: t}
76newtype Input t = I {unI :: t}
75newtype Added t = A {unA :: t}
77newtype Added t = A {unA :: t}
77−-- | The 'Parser' type.
79+-- | The core parser type. This is parameterised over the type @t@ of
80+-- string being processed.
79-- This type is an instance of the following classes:
82-- This type is an instance of the following classes:
@@ -85,7 +88,10 @@ newtype Added t = A {unA :: t}
86-- * 'MonadPlus', where 'mzero' fails (with no error message) and
89-- * 'MonadPlus', where 'mzero' fails (with no error message) and
87-- 'mplus' executes the right-hand parser if the left-hand one
90-- '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.)
90-- * 'Alternative', which follows 'MonadPlus'.
96-- * 'Alternative', which follows 'MonadPlus'.
91newtype Parser t a = Parser {
97newtype Parser t a = Parser {