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


-- | Live diagnostics for concurrent activity
--   
--   This library can be used to display a progress bar or other live
--   diagnostics for your application. It supports partial updates from
--   multiple threads without interfering with each other, and it has the
--   correct behaviour when printing diagnostics that are not part of the
--   progress bar and should just scroll by.
--   
--   The <tt>System.Progress</tt> module contains a tutorial.
@package progress-meter
@version 1.0.0


-- | This module implements a progress bar with support for multiple
--   individual text chunks that can be updated independently (called
--   <i>meters</i>).
module System.Progress

-- | Progress bars displaying state information of the given type
data Progress a
Progress :: Int -> Handle -> a -> (a -> String) -> Progress a

-- | Update delay in microseconds
[progressDelay] :: Progress a -> Int

-- | Output handle
[progressHandle] :: Progress a -> Handle

-- | Initial state
[progressInitial] :: Progress a -> a

-- | State renderer
[progressRender] :: Progress a -> a -> String

-- | Display a progress bar for the duration of the given action
--   
--   Note: If the output handle is not a terminal (as determined by
--   <a>hIsTerminalDevice</a>), no progress bar is displayed and no state
--   is maintained. In this case <a>modifyMeter</a> and
--   <a>modifyMeterSTM</a> are no-ops.
--   
--   For most applications the simpler variant <a>withProgress_</a> is
--   sufficient.
withProgress :: Progress a -> (Meter' a -> IO r) -> IO r

-- | Simpler variant of <a>withProgress</a>
--   
--   Uses a delay of 0.1 seconds and displays the progress bar on stderr.
withProgress_ :: a -> (a -> String) -> (Meter' a -> IO r) -> IO r

-- | Perform the given action while temporarily hiding the progress bar
--   
--   The given action is sequenced with concurrent uses of
--   <tt>meterIO</tt>, so it can be used for regular output without
--   artifacts. The function receives the output handle of the progress
--   bar.
meterIO :: Meter a b -> (Handle -> IO r) -> IO r

-- | Variant of <a>putMsgLn</a> that omits the final line feed
--   
--   Note: Use this function only when the given string ends with a line
--   feed, otherwise the progress bar will overwrite its last line when it
--   is redisplayed.
putMsg :: Meter a b -> String -> IO ()

-- | Print the given string to the output handle of the progress bar
--   
--   This is implemented in terms of <a>meterIO</a>, so it does The Right
--   Thing: it temporarily hides the progress bar, prints the string, then
--   redisplays it. It also makes sure that concurrent messages are
--   properly sequenced.
putMsgLn :: Meter a b -> String -> IO ()

-- | A value of type <tt>Meter a b</tt> can be used to update part of the
--   current state of the progress bar by supplying a function of type
--   <tt>(a -&gt; b)</tt>, where <tt>a</tt> is the type of the current
--   value and <tt>b</tt> is the type of the new value. See the
--   <a>modifyMeter</a> function for details.
--   
--   In most cases you can just assume <tt>a = b</tt> and use the
--   <tt>Meter'</tt> alias.
data Meter a b

-- | Handy type alias for the common case where the current state type and
--   the new state type are the same
type Meter' a = Meter a a

-- | Modify the part of the state represented by the given meter using the
--   given function
--   
--   The function receives the current value of type <tt>a</tt> of the
--   meter and should return the new value of type <tt>b</tt>. Note that
--   for most applications those types will be the same.
--   
--   Updates are performed strictly, so they don't pile up when updates are
--   throttled, unless the progress bar is disabled (because the output
--   handle is not a terminal), in which case no state is maintained at
--   all.
modifyMeter :: Meter a b -> (a -> b) -> IO ()

-- | Variant of <a>modifyMeter</a>: set the given meter to the given new
--   state
--   
--   See <a>modifyMeter</a> for details.
setMeter :: Meter a b -> b -> IO ()

-- | Zoom into part of the state
--   
--   This function returns a variant of the given meter that focusses on
--   the value(s) the given setter modifies. You can use this for example
--   to focus on a single key in a map or all the values in a list.
--   
--   Examples:
--   
--   <pre>
--   -- Zoom into all values of a list (warning: non-strict!):
--   zoomMeter map :: Meter' [a] -&gt; Meter' a
--   
--   -- Zoom into the left component of a tuple:
--   zoomMeter (\f (x', y) -&gt; let x = f x' in x `seq` (x, y))
--       :: Meter' (a, b) -&gt; Meter' a
--   
--   -- Zoom into the element indexed by the "foo" key,
--   -- where M = Data.Map.Strict:
--   zoomMeter (\f -&gt; M.alter f "foo")
--       :: Meter' (M.Map String a) -&gt; Meter' (Maybe a)
--   
--   -- Variant of the previous example that always
--   -- adds the element if it didn't exist before:
--   zoomMeter (\f -&gt; M.alter (Just . f) "foo")
--       :: Meter' (M.Map String a) -&gt; Meter (Maybe a) a
--   </pre>
zoomMeter :: ((a -> b) -> s -> t) -> Meter s t -> Meter a b

-- | Variant of <a>zoomMeter</a> that works with van Laarhoven setters as
--   used by libraries like <a>lens</a>:
--   
--   <pre>
--   zoomMeterL f = zoomMeter (over f)
--   </pre>
--   
--   Keep in mind that most predefined lenses are non-strict. See the
--   tutorial section on zooming to understand why this can be a problem.
zoomMeterL :: ((a -> Identity b) -> s -> Identity t) -> Meter s t -> Meter a b

-- | STM variant of <a>modifyMeter</a>: modify the given meter in a
--   transaction
--   
--   You can use this function to modify multiple meters simultaneously.
--   This is useful, if you want to make sure that users don't observe
--   partial updates.
modifyMeterSTM :: Meter a b -> (a -> b) -> STM ()

-- | Variant of <a>modifyMeterSTM</a>: set the given meter to the given new
--   state in a transaction
--   
--   See <a>modifyMeterSTM</a> for details.
setMeterSTM :: Meter a b -> b -> STM ()