Commits

Bryan O'Sullivan committed e5240c0

Improve documentation.

Comments (0)

Files changed (3)

Data/Attoparsec.hs

------------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Attoparsec
 -- Copyright   :  Bryan O'Sullivan 2007-2010
 -- Stability   :  experimental
 -- Portability :  unknown
 --
--- Simple, efficient parser combinators for 'ByteString' strings,
--- loosely based on 'Text.ParserCombinators.Parsec'.
--- 
------------------------------------------------------------------------------
+-- Simple, efficient parser combinators for 'B.ByteString' strings,
+-- loosely based on the Parsec library.
+
 module Data.Attoparsec
     (
     -- * Parser types
 
     -- * Running parsers
     , parse
+    , feed
     , parseWith
     , parseTest
-    , feed
 
     -- * Combinators
     , (I.<?>)
 import qualified Data.Attoparsec.Internal as I
 import qualified Data.ByteString as B
 
+-- | The result of a parse.
 data Result r = Fail !B.ByteString [String] String
+              -- ^ The parse failed.  The 'B.ByteString' is the input
+              -- that had not yet been consumed when the failure
+              -- occurred.  The @[@'String'@]@ is a list of contexts
+              -- in which the error occurred.  The 'String' is the
+              -- message describing the error, if any.
               | Partial (B.ByteString -> Result r)
+              -- ^ Pass this continuation more input so that the
+              -- parser can resume.  Pass it an 'B.empty' string to
+              -- indicate that no more input is available.
               | Done !B.ByteString r
+              -- ^ The parse succeeded.  The 'B.ByteString' is the
+              -- input that had not yet been consumed (if any) when
+              -- the parse succeeded.
 
 instance Show r => Show (Result r) where
     show (Fail bs stk msg) =
     show (Partial _)       = "Partial _"
     show (Done bs r)       = "Done " ++ show bs ++ " " ++ show r
 
+-- | If a parser has returned a 'Partial' result, supply it with more
+-- input.
 feed :: Result r -> B.ByteString -> Result r
 feed f@(Fail _ _ _) _ = f
 feed (Partial k) d    = k d
 instance Functor Result where
     fmap = fmapR
 
+-- | Run a parser and print its result to standard output.
 parseTest :: (Show a) => I.Parser a -> B.ByteString -> IO ()
 parseTest p s = print (parse p s)
 
 translate (I.Partial k)       = Partial (translate . k)
 translate (I.Done st r)       = Done (I.input st) r
 
+-- | Run a parser and return its result.
 parse :: I.Parser a -> B.ByteString -> Result a
 parse m s = translate (I.parse m s)
 {-# INLINE parse #-}
 
+-- | Run a parser with an initial input string, and a monadic action
+-- that can supply more input if needed.
 parseWith :: Monad m =>
              (m B.ByteString)
+          -- ^ An action that will be executed to provide the parser
+          -- with more input, if necessary.  The action must return an
+          -- 'B.empty' string when there is no more input available.
           -> I.Parser a
           -> B.ByteString
+          -- ^ Initial input for the parser.
           -> m (Result a)
 parseWith refill p s = step $ I.parse p s
   where step (I.Fail st stk msg) = return $! Fail (I.input st) stk msg

Data/Attoparsec/Char8.hs

------------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Attoparsec.Char8
 -- Copyright   :  Bryan O'Sullivan 2007-2010
 -- ISO-8859-15.  It /does not/ deal with character encodings,
 -- multibyte characters, or wide characters.  Any attempts to use
 -- characters above code point 255 will give wrong answers.
------------------------------------------------------------------------------
 module Data.Attoparsec.Char8
     (
     -- * Parser types

Data/Attoparsec/Internal.hs

 {-# LANGUAGE Rank2Types, RecordWildCards #-}
------------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Attoparsec.Internal
 -- Copyright   :  Bryan O'Sullivan 2007-2010
 -- Stability   :  experimental
 -- Portability :  unknown
 --
--- Simple, efficient parser combinators for 'bB.ByteString' strings,
--- loosely based on 'Text.ParserCombinators.Parsec'.
--- 
------------------------------------------------------------------------------
+-- Simple, efficient parser combinators for 'B.ByteString' strings,
+-- loosely based on the Parsec library.
+
 module Data.Attoparsec.Internal
     (
     -- * Parser types
               | Partial (B.ByteString -> Result r)
               | Done S r
 
--- | The Parser monad is an Exception and State monad.
+-- | The 'Parser' type is a monad.
 newtype Parser a = Parser {
       runParser :: forall r. S
                 -> Failure   r
 type Failure   r = S -> [String] -> String -> Result r
 type Success a r = S -> a -> Result r
 
+-- | Have we read all available input?
 data More = Complete | Incomplete
             deriving (Eq, Show)