Commits

Bryan O'Sullivan committed 9664036

Improve doco about incremental input

  • Participants
  • Parent commits 56a7a75

Comments (0)

Files changed (1)

Data/Attoparsec.hs

     -- * Differences from Parsec
     -- $parsec
 
+    -- * Incremental input
+    -- $incremental
+
     -- * Performance considerations
     -- $performance
 
 -- * Much of the performance advantage of Attoparsec is gained via
 --   high-performance parsers such as 'I.takeWhile' and 'I.string'.
 --   If you use complicated combinators that return lists of bytes or
---   characters, there really isn't much performance difference the
---   two libraries.
+--   characters, there is less performance difference between the two
+--   libraries.
 --
 -- * Unlike Parsec 3, Attoparsec does not support being used as a
---   monad transformer.  This is mostly a matter of the implementor
---   not having needed that functionality.
+--   monad transformer.
 --
 -- * Attoparsec is specialised to deal only with strict 'B.ByteString'
 --   input.  Efficiency concernts rule out both lists and lazy
 --   allow consumption of very large input without a large footprint.
 --   For this need, Attoparsec's incremental input provides an
 --   excellent substitute, with much more control over when input
---   takes place.
+--   takes place.  If you must use lazy bytestrings, see the 'Lazy'
+--   module, which feeds lazy chunks to a regular parser.
 --
 -- * Parsec parsers can produce more helpful error messages than
 --   Attoparsec parsers.  This is a matter of focus: Attoparsec avoids
 --   the extra book-keeping in favour of higher performance.
 
+-- $incremental
+--
+-- Attoparsec supports incremental input, meaning that you can feed it
+-- a bytestring that represents only part of the expected total amount
+-- of data to parse. If your parser reaches the end of a fragment of
+-- input and could consume more input, it will suspend parsing and
+-- return a 'Partial' continuation.
+--
+-- Supplying the 'Partial' continuation with another bytestring will
+-- resume parsing at the point where it was suspended. You must be
+-- prepared for the result of the resumed parse to be another
+-- 'Partial' continuation.
+--
+-- To indicate that you have no more input, supply the 'Partial'
+-- continuation with an empty bytestring.
+--
+-- Remember that some parsing combinators will not return a result
+-- until they reach the end of input.  They may thus cause 'Partial'
+-- results to be returned.
+--
+-- If you do not need support for incremental input, consider using
+-- the 'I.parseOnly' function to run your parser.  It will never
+-- prompt for more input.
+
 -- $performance
 --
 -- If you write an Attoparsec-based parser carefully, it can be