@@ -1,4 +1,3 @@
1−-----------------------------------------------------------------------------
21-- |
32-- Module : Data.Attoparsec
43-- Copyright : Bryan O'Sullivan 2007-2010
@@ -8,10 +7,9 @@
87-- Stability : experimental
98-- Portability : unknown
109--
11−-- Simple, efficient parser combinators for 'ByteString' strings,
12−-- loosely based on 'Text.ParserCombinators.Parsec'.
13−--
14−-----------------------------------------------------------------------------
10+-- Simple, efficient parser combinators for 'B.ByteString' strings,
11+-- loosely based on the Parsec library.
12+
1513module Data.Attoparsec
1614 (
1715 -- * Parser types
@@ -20,9 +18,9 @@ module Data.Attoparsec
2018
2119 -- * Running parsers
2220 , parse
21+ , feed
2322 , parseWith
2423 , parseTest
25− , feed
2624
2725 -- * Combinators
2826 , (I.<?>)
@@ -58,9 +56,21 @@ import Prelude hiding (takeWhile)
5856import qualified Data.Attoparsec.Internal as I
5957import qualified Data.ByteString as B
6058
59+-- | The result of a parse.
6160data Result r = Fail !B.ByteString [String] String
61+ -- ^ The parse failed. The 'B.ByteString' is the input
62+ -- that had not yet been consumed when the failure
63+ -- occurred. The @[@'String'@]@ is a list of contexts
64+ -- in which the error occurred. The 'String' is the
65+ -- message describing the error, if any.
6266 | Partial (B.ByteString -> Result r)
67+ -- ^ Pass this continuation more input so that the
68+ -- parser can resume. Pass it an 'B.empty' string to
69+ -- indicate that no more input is available.
6370 | Done !B.ByteString r
71+ -- ^ The parse succeeded. The 'B.ByteString' is the
72+ -- input that had not yet been consumed (if any) when
73+ -- the parse succeeded.
6474
6575instance Show r => Show (Result r) where
6676 show (Fail bs stk msg) =
@@ -68,6 +78,8 @@ instance Show r => Show (Result r) where
6878 show (Partial _) = "Partial _"
6979 show (Done bs r) = "Done " ++ show bs ++ " " ++ show r
7080
81+-- | If a parser has returned a 'Partial' result, supply it with more
82+-- input.
7183feed :: Result r -> B.ByteString -> Result r
7284feed f@(Fail _ _ _) _ = f
7385feed (Partial k) d = k d
@@ -81,6 +93,7 @@ fmapR f (Done bs r) = Done bs (f r)
8193instance Functor Result where
8294 fmap = fmapR
8395
96+-- | Run a parser and print its result to standard output.
8497parseTest :: (Show a) => I.Parser a -> B.ByteString -> IO ()
8598parseTest p s = print (parse p s)
8699
@@ -89,14 +102,21 @@ translate (I.Fail st stk msg) = Fail (I.input st) stk msg
89102translate (I.Partial k) = Partial (translate . k)
90103translate (I.Done st r) = Done (I.input st) r
91104
105+-- | Run a parser and return its result.
92106parse :: I.Parser a -> B.ByteString -> Result a
93107parse m s = translate (I.parse m s)
94108{-# INLINE parse #-}
95109
110+-- | Run a parser with an initial input string, and a monadic action
111+-- that can supply more input if needed.
96112parseWith :: Monad m =>
97113 (m B.ByteString)
114+ -- ^ An action that will be executed to provide the parser
115+ -- with more input, if necessary. The action must return an
116+ -- 'B.empty' string when there is no more input available.
98117 -> I.Parser a
99118 -> B.ByteString
119+ -- ^ Initial input for the parser.
100120 -> m (Result a)
101121parseWith refill p s = step $ I.parse p s
102122 where step (I.Fail st stk msg) = return $! Fail (I.input st) stk msg