@@ -15,6 +15,9 @@ module Data.Attoparsec
1515 -- * Differences from Parsec
1616 -- $parsec
1717
18+ -- * Incremental input
19+ -- $incremental
20+
1821 -- * Performance considerations
1922 -- $performance
2023
@@ -90,12 +93,11 @@ import Data.Attoparsec.Internal (Result(..), parse)
9093-- * Much of the performance advantage of Attoparsec is gained via
9194-- high-performance parsers such as 'I.takeWhile' and 'I.string'.
9295-- If you use complicated combinators that return lists of bytes or
93−-- characters, there really isn't much performance difference the
94−-- two libraries.
96+-- characters, there is less performance difference between the two
97+-- libraries.
9598--
9699-- * Unlike Parsec 3, Attoparsec does not support being used as a
97−-- monad transformer. This is mostly a matter of the implementor
98−-- not having needed that functionality.
100+-- monad transformer.
99101--
100102-- * Attoparsec is specialised to deal only with strict 'B.ByteString'
101103-- input. Efficiency concernts rule out both lists and lazy
@@ -103,12 +105,37 @@ import Data.Attoparsec.Internal (Result(..), parse)
103105-- allow consumption of very large input without a large footprint.
104106-- For this need, Attoparsec's incremental input provides an
105107-- excellent substitute, with much more control over when input
106−-- takes place.
108+-- takes place. If you must use lazy bytestrings, see the 'Lazy'
109+-- module, which feeds lazy chunks to a regular parser.
107110--
108111-- * Parsec parsers can produce more helpful error messages than
109112-- Attoparsec parsers. This is a matter of focus: Attoparsec avoids
110113-- the extra book-keeping in favour of higher performance.
111114
115+-- $incremental
116+--
117+-- Attoparsec supports incremental input, meaning that you can feed it
118+-- a bytestring that represents only part of the expected total amount
119+-- of data to parse. If your parser reaches the end of a fragment of
120+-- input and could consume more input, it will suspend parsing and
121+-- return a 'Partial' continuation.
122+--
123+-- Supplying the 'Partial' continuation with another bytestring will
124+-- resume parsing at the point where it was suspended. You must be
125+-- prepared for the result of the resumed parse to be another
126+-- 'Partial' continuation.
127+--
128+-- To indicate that you have no more input, supply the 'Partial'
129+-- continuation with an empty bytestring.
130+--
131+-- Remember that some parsing combinators will not return a result
132+-- until they reach the end of input. They may thus cause 'Partial'
133+-- results to be returned.
134+--
135+-- If you do not need support for incremental input, consider using
136+-- the 'I.parseOnly' function to run your parser. It will never
137+-- prompt for more input.
138+
112139-- $performance
113140--
114141-- If you write an Attoparsec-based parser carefully, it can be