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


-- | Simple streaming in IO
--   
--   This library provides a new simpler approach to the IO-streaming
--   problem.
--   
--   In difference to libraries like "pipes", "conduit", "streaming", this
--   library is specialised to streaming in the IO monad, which greatly
--   simplifies the abstractions that it provides. This simplification is
--   motivated by the fact that the majority of streaming tasks are
--   performed in IO anyway.
--   
--   Also, unlike the mentioned libraries, "potoki" API doesn't treat
--   streaming as a side operation in its abstractions, which allows it to
--   express the composition of streams using the standard typeclass
--   instances, thus simplifying the API even further.
--   
--   Naturally, being simpler limits the application area of this library.
--   Thus it is not capable of transforming custom context monads and etc.
--   It is a tradeoff, but, as we expect, the user will rarely be affected
--   by it.
--   
--   Another benefit of being specialized to IO is the ability to optimize
--   for performance better. It must however be mentioned that this is only
--   theoretical and no benchmarks have yet been performed.
--   
--   In some of the mentioned regards "potoki" is similar to the
--   "io-streams" library. However, unlike that library it approaches
--   composition with the standard typeclass instances. Also, in difference
--   to "io-streams", "potoki" doesn't use exceptions for control-flow. In
--   fact, "potoki" doesn't use exceptions whatsoever, instead it makes
--   failures explicit, using the standard <tt>Either</tt> type.
--   
--   "potoki" comes with automated resource-management (acquisition and
--   clean-up), concurrency and buffering features.
@package potoki
@version 0.10

module Potoki.IO
produceAndConsume :: () => Produce input -> Consume input output -> IO output
produce :: () => Produce input -> forall x. () => IO x -> (input -> IO x) -> IO x
consume :: () => (forall x. () => x -> (input -> x) -> IO x) -> Consume input output -> IO output

module Potoki.Produce

-- | Passive producer of elements with support for early termination.
--   
--   Automates the management of resources.
data Produce element :: * -> *
transform :: () => Transform input output -> Produce input -> Produce output
list :: () => [input] -> Produce input
vector :: Vector input -> Produce input
hashMapRows :: HashMap a b -> Produce (a, b)

-- | Read from a file by path.
--   
--   <ul>
--   <li>Exception-free</li>
--   <li>Automatic resource management</li>
--   </ul>
fileBytes :: FilePath -> Produce (Either IOException ByteString)

-- | Read from a file by path.
--   
--   <ul>
--   <li>Exception-free</li>
--   <li>Automatic resource management</li>
--   </ul>
fileBytesAtOffset :: FilePath -> Int -> Produce (Either IOException ByteString)

-- | Read from a file by path.
--   
--   <ul>
--   <li>Exception-free</li>
--   <li>Automatic resource management</li>
--   </ul>
fileText :: FilePath -> Produce (Either IOException Text)

-- | Sorted subpaths of the directory.
directoryContents :: FilePath -> Produce (Either IOException FilePath)

-- | Read from MVar. Nothing gets interpreted as the end of input.
finiteMVar :: MVar (Maybe element) -> Produce element

-- | Read from MVar. Never stops.
infiniteMVar :: MVar element -> Produce element

module Potoki.Transform
data Transform input output :: * -> * -> *
consume :: () => Consume input output -> Transform input output
produce :: () => (input -> Produce output) -> Transform input output
ioTransform :: IO (Transform a b) -> Transform a b
take :: () => Int -> Transform input input
takeWhile :: (input -> Bool) -> Transform input input
mapFilter :: (input -> Maybe output) -> Transform input output
filter :: (input -> Bool) -> Transform input input
just :: Transform (Maybe input) input
list :: Transform [a] a
distinctBy :: (Eq comparable, Hashable comparable) => (element -> comparable) -> Transform element element
distinct :: (Eq element, Hashable element) => Transform element element
builderChunks :: Transform Builder ByteString

-- | Execute the IO action.
executeIO :: () => Transform IO a a
mapInIO :: (a -> IO b) -> Transform a b

-- | Notice that you can control the emission of output of each step by
--   producing a list of outputs and then composing the transform with the
--   "list" transform.
state :: (a -> State s b) -> s -> Transform a b

-- | Lift an Attoparsec ByteString parser.
parseBytes :: Parser parsed -> Transform ByteString (Either Text parsed)

-- | Lift an Attoparsec Text parser.
parseText :: Parser parsed -> Transform Text (Either Text parsed)
bufferize :: Int -> Transform element element

-- | Execute the transform on the specified amount of threads. The order of
--   the outputs produced is indiscriminate.
concurrently :: Int -> Transform input output -> Transform input output

-- | A transform, which fetches the inputs asynchronously on the specified
--   number of threads.
async :: Int -> Transform input input
deleteFile :: Transform FilePath (Either IOException ())
appendBytesToFile :: Transform (FilePath, ByteString) (Either IOException ())

module Potoki.Consume

-- | Active consumer of input into output. Sort of like a reducer in
--   Map/Reduce.
--   
--   Automates the management of resources.
data Consume input output :: * -> * -> *
transform :: () => Transform input output -> Consume output sinkOutput -> Consume input sinkOutput
count :: Consume input Int
sum :: Num num => Consume num num
head :: Consume input (Maybe input)
list :: () => Consume input [input]

-- | A faster alternative to "list", which however constructs the list in
--   the reverse order.
reverseList :: Consume input [input]
concat :: Monoid monoid => Consume monoid monoid
fold :: Fold input output -> Consume input output
foldInIO :: FoldM IO input output -> Consume input output

-- | Overwrite a file.
--   
--   <ul>
--   <li>Exception-free</li>
--   <li>Automatic resource management</li>
--   </ul>
writeBytesToFile :: FilePath -> Consume ByteString (Either IOException ())

-- | Append to a file.
--   
--   <ul>
--   <li>Exception-free</li>
--   <li>Automatic resource management</li>
--   </ul>
appendBytesToFile :: FilePath -> Consume ByteString (Either IOException ())
deleteFiles :: Consume FilePath (Either IOException ())
printBytes :: Consume ByteString ()
printText :: Consume Text ()
printString :: Consume String ()
parseBytes :: Parser output -> Consume ByteString (Either Text output)
parseText :: Parser output -> Consume Text (Either Text output)

-- | Execute a Consume concurrently and consume its results.
concurrently :: Int -> Consume a b -> Consume b c -> Consume a c