@@ -18,6 +18,9 @@
1818-----------------------------------------------------------------------------
1919module Data.Attoparsec.Incremental
2020 (
21+ -- * Incremental parsing
22+ -- $incremental
23+
2124 -- * Parser types
2225 Parser
2326 , Result(..)
@@ -62,6 +65,18 @@ import qualified Data.ByteString.Lazy as L
6265import qualified Data.ByteString.Lazy.Internal as L
6366import Prelude hiding (takeWhile)
6467
68+-- $incremental
69+-- Incremental parsing makes it possible to supply a parser with only
70+-- a limited amount of input. If the parser cannot complete due to
71+-- lack of data, it will return a 'Partial' result with a continuation
72+-- to which more input can be supplied, as follows:
73+--
74+-- > case parse myParser someInput of
75+-- > Partial k -> k moreInput
76+--
77+-- To signal that no more input is available, pass an empty
78+-- string to this continuation.
79+
6580data S = S {-# UNPACK #-} !S.ByteString -- first chunk of input
6681 L.ByteString -- rest of input
6782 [L.ByteString] -- input acquired during backtracks