Bryan O'Sullivan avatar Bryan O'Sullivan committed 0e4d0bf

More work on docs.

Comments (0)

Files changed (3)

Data/Attoparsec.hs

 
 module Data.Attoparsec
     (
+    -- * Performance
+    -- $performance
+
     -- * Parser types
       I.Parser
     , Result(..)
 
+    -- ** Typeclass instances
+    -- $instances
+
     -- * Running parsers
     , parse
     , feed
     , I.ensure
     ) where
 
+import Control.Applicative (Alternative(..), Applicative)
+import Control.Monad (MonadPlus(..))
 import Data.Attoparsec.Combinator
 import Prelude hiding (takeWhile)
 import qualified Data.Attoparsec.Internal as I
 import qualified Data.ByteString as B
 
+-- $performance
+--
+-- If you write an Attoparsec-based parser carefully, it can be
+-- entirely reasonable to expect it to perform within a factor of 2 of
+-- a hand-rolled C parser (measuring megabytes parsed per second).
+--
+-- To actually achieve high performance, there are a few guidelines
+-- that it is useful to follow.
+--
+-- Use the 'B.ByteString'-oriented parsers whenever possible,
+-- e.g. 'I.takeWhile1' instead of 'many1' 'I.anyWord8'.  There is
+-- about a factor of 100 difference in performance between the two.
+--
+-- For very simple byte-testing predicates, write them by hand instead
+-- of using 'I.inClass' or 'I.notInClass'.  For instance, both of
+-- these predicates test for an end-of-line byte, but the first is
+-- much faster than the second:
+--
+-- >endOfLine_fast w = w == 13 || w == 10
+-- >endOfLine_slow   = inClass "\r\n"
+--
+-- Make active use of benchmarking and profiling tools to measure,
+-- find the problems with, and improve the performance of your parser.
+
+-- $instances
+--
+-- The 'I.Parser' type is an instance of the following classes:
+--
+-- * 'Monad', where 'fail' throws an exception (i.e. fails) with an
+--   error message.
+--
+-- * 'Functor' and 'Applicative', which follow the usual definitions.
+--
+-- * 'MonadPlus', where 'mzero' fails (with no error message) and
+--   'mplus' executes the right-hand parser if the left-hand one
+--   fails.
+--
+-- * 'Alternative', which follows 'MonadPlus'.
+--
+-- The 'Result' type is an instance of 'Functor', where 'fmap'
+-- transforms the value in a 'Done' result.
+
 -- | The result of a parse.
 data Result r = Fail !B.ByteString [String] String
               -- ^ The parse failed.  The 'B.ByteString' is the input

Data/Attoparsec/Combinator.hs

 {-# LANGUAGE BangPatterns, CPP #-}
------------------------------------------------------------------------------
 -- |
 -- Module      :  Data.Attoparsec.Combinator
--- Copyright   :  Daan Leijen 1999-2001, Bryan O'Sullivan 2009
+-- Copyright   :  Daan Leijen 1999-2001, Bryan O'Sullivan 2009-2010
 -- License     :  BSD3
 -- 
 -- Maintainer  :  bos@serpentine.com
 -- Portability :  portable
 --
 -- Useful parser combinators, similar to those provided by Parsec.
--- 
------------------------------------------------------------------------------
 module Data.Attoparsec.Combinator
     (
       choice
     , skipMany
     , skipMany1
     , eitherP
+
     -- * Inlined implementations of existing functions
+    --
+    -- These are exact duplicates of functions already exported by the
+    -- 'Control.Applicative' module, but whose definitions are
+    -- inlined.  In many cases, this leads to 2x performance
+    -- improvements.
     , many
     ) where
 
 eitherP a b = (Left <$> a) <|> (Right <$> b)
 {-# INLINE eitherP #-}
 
+-- | Zero or more.
 many :: (Alternative f) => f a -> f [a]
 many v = many_v
     where many_v = some_v <|> pure []
 author:          Bryan O'Sullivan <bos@serpentine.com>
 maintainer:      Bryan O'Sullivan <bos@serpentine.com>
 stability:       experimental
-tested-with:     GHC == 6.8.3, GHC == 6.10.1
-synopsis:        Fast bytestring combinator parsing
-description:     Fast bytestring combinator parsing
+tested-with:     GHC == 6.10.4, GHC == 6.12.1
+synopsis:        Fast combinator parsing for bytestrings
 cabal-version:   >= 1.2
 build-type:      Simple
-description:     Fast, flexible text-oriented parsing of lazy ByteStrings.
+description:
+    A fast parser combinator library, aimed particularly at dealing
+    efficiently with network protocols and complicated text/binary
+    file formats.
 
 flag split-base
 flag applicative-in-base
     -- bytestring was in base-2.0 and 2.1.1
     build-depends: base >= 2.0 && < 2.2
   else
-    -- in base 1.0 and 3.0 bytestring is a separate package
+    -- in base 1.0 and >= 3.0 bytestring is a separate package
     build-depends: base < 2.0 || >= 3, bytestring >= 0.9, containers >= 0.1.0.1
 
   if flag(applicative-in-base)
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.