-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Attoparsec integration for the streaming ecosystem
--   
--   Attoparsec integration for the streaming ecosystem.
@package streaming-attoparsec
@version 1.0.0


-- | Here is a simple use of <a>parsed</a> and standard <tt>Streaming</tt>
--   segmentation devices to parse a file in which groups of numbers are
--   separated by blank lines. Such a problem of 'nesting streams' is
--   described in the <tt>conduit</tt> context in <a>this StackOverflow
--   question</a>.
--   
--   <pre>
--   -- $ cat nums.txt
--   -- 1
--   -- 2
--   -- 3
--   --
--   -- 4
--   -- 5
--   -- 6
--   --
--   -- 7
--   -- 8
--   </pre>
--   
--   We will sum the groups and stream the results to standard output:
--   
--   <pre>
--   import Streaming
--   import qualified Streaming.Prelude as S
--   import qualified Data.ByteString.Streaming.Char8 as Q
--   import qualified Data.Attoparsec.ByteString.Char8 as A
--   import qualified Data.Attoparsec.ByteString.Streaming as AS
--   import Data.Function ((&amp;))
--   
--   main :: IO ()
--   main = Q.getContents           -- raw bytes
--          &amp; AS.parsed lineParser  -- stream of parsed `Maybe Int`s; blank lines are `Nothing`
--          &amp; void                  -- drop any unparsed nonsense at the end
--          &amp; S.split Nothing       -- split on blank lines
--          &amp; S.maps S.concat       -- keep `Just x` values in the sub-streams (cp. catMaybes)
--          &amp; S.mapped S.sum        -- sum each substream
--          &amp; S.print               -- stream results to stdout
--   
--   lineParser = Just &lt;$&gt; A.scientific &lt;* A.endOfLine &lt;|&gt; Nothing &lt;$ A.endOfLine
--   </pre>
--   
--   <pre>
--   -- $ cat nums.txt | ./atto
--   -- 6.0
--   -- 15.0
--   -- 15.0
--   </pre>
module Data.Attoparsec.ByteString.Streaming

-- | Output from parsing errors.
type Errors = ([String], String)

-- | The result of a parse (<tt>Either ([String], String) a</tt>), with the
--   unconsumed byte stream.
--   
--   <pre>
--   &gt;&gt;&gt; :set -XOverloadedStrings  -- the string literal below is a streaming bytestring
--   
--   &gt;&gt;&gt; (r,rest1) &lt;- AS.parse (A.scientific &lt;* A.many' A.space) "12.3  4.56  78.3"
--   
--   &gt;&gt;&gt; print r
--   Left 12.3
--   
--   &gt;&gt;&gt; (s,rest2) &lt;- AS.parse (A.scientific &lt;* A.many' A.space) rest1
--   
--   &gt;&gt;&gt; print s
--   Left 4.56
--   
--   &gt;&gt;&gt; (t,rest3) &lt;- AS.parse (A.scientific &lt;* A.many' A.space) rest2
--   
--   &gt;&gt;&gt; print t
--   Left 78.3
--   
--   &gt;&gt;&gt; Q.putStrLn rest3
--      -- Nothing left, this prints an empty string.
--   </pre>
parse :: Monad m => Parser a -> ByteString m x -> m (Either Errors a, ByteString m x)

-- | Apply a parser repeatedly to a stream of bytes, streaming the parsed
--   values, but ending when the parser fails or the bytes run out.
--   
--   <pre>
--   &gt;&gt;&gt; S.print . void $ AS.parsed (A.scientific &lt;* A.many' A.space) "12.3  4.56  78.9"
--   12.3
--   4.56
--   78.9
--   </pre>
parsed :: Monad m => Parser a -> ByteString m r -> Stream (Of a) m (Either (Errors, ByteString m r) r)
