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


-- | Utility functions for running a parser against a socket
--   
--   Utility functions for running a parser against a socket, without the
--   need of a bigger framework such as Pipes or Conduit.
@package network-attoparsec
@version 0.12.2


-- | Utility functions for running a parser against a socket, without the
--   need of a bigger framework such as Pipes or Conduit.
--   
--   <b>WARNING</b>: In certain situations while using the attoparsec
--   string parser, it is possible that a network parser ends in a
--   forever-blocking state, expecting more input. This is a side effect of
--   the way attoparsec is written. I have written a thorough explanation
--   on this issue, and <a>how to avoid attoparsec returning a partial
--   result</a> when a different branch should be evaluated.
module Network.Attoparsec

-- | The parsing continuation form of a <a>Data.Attoparsec</a> parser. This
--   is typically created by running the attoparsec "parse" function:
--   
--   <pre>
--   createParser = AttoParsec.parse myParser
--   </pre>
type ParseC a = ByteString -> Result a

-- | Consumes input from socket and attempts to parse as many objects from
--   the socket as possible. Use this function only when you expect more
--   than one parse operation to succeed.
--   
--   The function is continuation based, so you must provide the next
--   parser state in successing calls as follows:
--   
--   <pre>
--   doParse sock = do
--     (p1, xs1) &lt;- parseMany sock (AttoParsec.parse myParser) (AttoParsec.parse myParser)
--     (_,  xs2) &lt;- parseMany sock (AttoParsec.parse myParser) p1
--     return (xs1 ++ xs2)
--   </pre>
--   
--   For more usage examples, see the test directory.
parseMany :: (MonadIO m, MonadMask m, Show a) => Socket -> ParseC a -> ParseC a -> m (ParseC a, [a])

-- | Similar to parseMany, but assumes that there will only be enough data
--   for a single succesful parse on the socket, and guarantees that
--   exactly one item will be parsed.
--   
--   <b>Warning:</b> In order to make this function work stable with
--   pipelined data, we read in data one byte at a time, which causes many
--   context switches and kernel syscalls, and furthermore causes a lot of
--   separate calls to attoparsec. So only use if performance is not a
--   consideration.
--   
--   The is typically used as follows:
--   
--   <pre>
--   doParse sock = parseOne sock (AttoParsec.parse myParser)
--   </pre>
parseOne :: (MonadIO m, MonadMask m, Show a) => Socket -> ParseC a -> m a
