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


-- | A library for tracking the consumption of a lazy ByteString
--   
--   In some cases, it is useful to know how fast a ByteString is being
--   consumed. Typically, this could be to report some measure of progress
--   to a waiting user, but it could also be to perform some form of
--   testing on input / consumption code.
@package bytestring-progress
@version 1.2


-- | This module defines core functions for tracking the consumption of a
--   ByteString, as well as several helper functions for making tracking
--   ByteStrings easier.
module Data.ByteString.Lazy.Progress

-- | Given a function, return a bytestring that will call that function
--   when it is partially consumed. The Words provided to the function will
--   be the number of bytes that were just consumed and the total bytes
--   consumed thus far.
trackProgress :: (Word64 -> Word64 -> IO ()) -> ByteString -> IO ByteString

-- | Works like <a>trackProgress</a>, except uses fixed-size chunks of the
--   given size. Thus, for this function, the first number passed to your
--   function will always be the given size *except* for the last call to
--   the function, which will be less then or equal to the final size.
trackProgressWithChunkSize :: Word64 -> (Word64 -> Word64 -> IO ()) -> ByteString -> IO ByteString

-- | Given a format string (described below), track the progress of a
--   function. The argument to the callback will be the string expanded
--   with the given progress information.
--   
--   Format string items:
--   
--   <ul>
--   <li>%b is the number of bytes read</li>
--   <li>%B is the number of bytes read, formatted into a human-readable
--   string</li>
--   <li>%c is the size of the last chunk read</li>
--   <li>%C is the size of the last chunk read, formatted
--   human-readably</li>
--   <li>%r is the rate in bytes per second</li>
--   <li>%R is the rate, formatted human-readably</li>
--   <li>%% is the character <tt>%</tt></li>
--   </ul>
--   
--   If you provide a total size (the maybe argument, in bytes), then you
--   may also use the following items:
--   
--   <ul>
--   <li>%t is the estimated time to completion in seconds</li>
--   <li>%T is the estimated time to completion, formatted as HH:MM:SS</li>
--   <li>%p is the percentage complete</li>
--   </ul>
trackProgressString :: String -> Maybe Word64 -> (String -> IO ()) -> IO (ByteString -> IO ByteString)

-- | Exactly as <a>trackProgressString</a>, but use the given chunkSize
--   instead of the default chunk size.
trackProgressStringWithChunkSize :: String -> Word64 -> Maybe Word64 -> (String -> IO ()) -> IO (ByteString -> IO ByteString)

-- | Convert a number of bytes to a string represenation that uses a
--   reasonable unit to make the number human-readable.
bytesToUnittedStr :: Word64 -> String

module System.ProgressBar.ByteString

-- | Track the progress of a ByteString as it is consumed by some
--   computation. This is the most general version in the library, and will
--   render a progress string and pass it to the given function. See other
--   functions for interacting with fixed-size files, the console, or
--   generic Handles.
mkByteStringProgressBar :: ByteString -> (String -> IO ()) -> ℤ -> ℤ -> Label -> Label -> IO ByteString

-- | As mkByteStringProgressBar, but simply print the output to the given
--   Handle instead of using a callback.
mkByteStringProgressWriter :: ByteString -> Handle -> ℤ -> ℤ -> Label -> Label -> IO ByteString

-- | Track the loading of a file as it is consumed by some computation. The
--   use of this function should be essentially similar to ByteString's
--   readFile, but with a lot more arguments and side effects.
fileReadProgressBar :: FilePath -> (String -> IO ()) -> ℤ -> Label -> Label -> IO ByteString

-- | As fileReadProgressBar, but simply write the progress bar to the given
--   Handle instead of calling a generic function.
fileReadProgressWriter :: FilePath -> Handle -> ℤ -> Label -> Label -> IO ByteString