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

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 :: (Semigroup monoid, 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
writeBytesToStdout :: Consume ByteString ()

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

-- | A more efficient implementation than just writing to file without
--   buffering. It uses an explicit buffer of input chunks and flushes all
--   the chunks that have been so far aggregated at once.
writeBytesToFileWithoutBuffering :: 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 :: NFData b => 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 vector input => vector input -> Produce input
vectorWithIndices :: Vector vector a => vector a -> Produce (Int, a)
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
tbmChan :: () => TBMChan element -> Produce element
tmChan :: () => TMChan element -> Produce element
enumInRange :: (Enum a, Ord a) => a -> a -> Produce a

-- | Merge two ordered sequences into one
mergeOrdering :: () => (a -> a -> Bool) -> Produce a -> Produce a -> Produce a
unfoldr :: () => Unfoldr a -> Produce a

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 :: Vector vector a => Transform (vector a) a

-- | Chunk the stream to vector batches of the given size.
--   
--   It's useful in combination with <tt>concurrently</tt> in cases where
--   the lifted transform's iteration is too light. Actually, there is a
--   composed variation of <tt>concurrently</tt>, which utilizes it:
--   <tt>concurrentlyWithBatching</tt>.
batch :: Vector vector a => Int -> Transform a (vector 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
reportProgress :: () => (Text -> IO ()) -> Transform a a
handleProgressAndCountOnInterval :: () => NominalDiffTime -> (Int -> Int -> IO ()) -> Transform a a
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
extractLinesWithoutTrail :: Transform ByteString ByteString
extractLinesConcurrently :: Int -> 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 :: () => (input -> State state output) -> state -> Transform input (output, state)
execState :: () => (input -> State state output) -> state -> Transform input state
evalState :: () => (input -> State state output) -> state -> Transform input output
scan :: () => Scanner a -> Transform ByteString (Either Text a)

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

-- | Lift an Attoparsec ByteString parser to a transform, which parses the
--   lines concurrently.
parseLineBytesConcurrently :: NFData a => Int -> Parser a -> Transform ByteString (Either Text a)

-- | Lift an Attoparsec ByteString parser to a transform, which parses the
--   lines concurrently.
parseNonEmptyLineBytesConcurrently :: NFData a => Int -> Parser a -> Transform ByteString (Either Text a)
bufferize :: NFData element => Int -> Transform element element
bufferizeFlushing :: () => Int -> Transform input [input]

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

-- | A transform, which fetches the inputs asynchronously on the specified
--   number of threads.
async :: NFData input => Int -> Transform input input
concurrentlyWithBatching :: (NFData a, NFData b) => Int -> Int -> Transform a b -> Transform a b
concurrentlyInOrderWithBatching :: NFData b => Int -> Int -> Transform a b -> Transform a b
deleteFile :: Transform FilePath (Either IOException ())
appendBytesToFile :: Transform (FilePath, ByteString) (Either IOException ())
writeTextToFile :: Transform (FilePath, Text) (Either IOException ())
count :: () => Transform a Int
mapInIOWithCounter :: () => (Int -> a -> IO b) -> Transform a b
handleCount :: () => (Int -> IO ()) -> Transform a a

-- | Provides for progress monitoring by means of periodic measurement.
handleCountOnInterval :: () => NominalDiffTime -> (Int -> IO ()) -> Transform a a

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