-- 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 2

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 input1 input2 -> Consume input2 output -> Consume input1 output
count :: () => Consume input Int
sum :: Num num => Consume num num
head :: () => Consume input Maybe input
last :: () => 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]
vector :: () => Consume input Vector input
concat :: Monoid monoid => Consume monoid monoid
fold :: () => Fold input output -> Consume input output
foldInIO :: () => FoldM IO input output -> Consume input output
folding :: () => Fold a b -> Consume a c -> Consume a (b, c)
foldingInIO :: () => FoldM IO a b -> Consume a c -> Consume a (b, c)
execState :: () => (a -> State s b) -> s -> Consume a s

-- | 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

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

module Potoki.Produce

-- | Passive producer of elements with support for early termination and
--   resource management.
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
stdinBytes :: Produce Either IOException ByteString

-- | 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
drop :: () => Int -> 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
vector :: () => Transform Vector a a
distinctBy :: (Eq comparable, Hashable comparable) => (element -> comparable) -> Transform element element
distinct :: (Eq element, Hashable element) => Transform element element

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

-- | Convert freeform bytestring chunks into chunks, which are strictly
--   separated by newline no matter how long they may be.
extractLines :: Transform ByteString ByteString

-- | 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.
runState :: () => (a -> State s b) -> s -> Transform a (s, b)
execState :: () => (a -> State s b) -> s -> Transform a s
evalState :: () => (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 ()
writeTextToFile :: Transform (FilePath, Text) Either IOException ()

-- | Useful for debugging
traceWithCounter :: () => (Int -> String) -> Transform a a