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


-- | A progress bar in the terminal
--   
--   A progress bar conveys the progress of a task. This package implements
--   a progress bar that is displayed in a terminal.
--   
--   See the module <a>System.ProgressBar</a> to get started or look at the
--   terminal-progress-bar-example package.
--   
--   The animated progress bar depends entirely on the interpretation of
--   the carriage return character ('\r'). If your terminal interprets it
--   as something else than "move cursor to beginning of line", the
--   animation won't work.
@package terminal-progress-bar
@version 0.4.1


-- | A progress bar in the terminal.
--   
--   A progress bar conveys the progress of a task. Use a progress bar to
--   provide a visual cue that processing is underway.
module System.ProgressBar

-- | A terminal progress bar.
--   
--   A <a>ProgressBar</a> value contains the state of a progress bar.
--   
--   Create a progress bar with <a>newProgressBar</a> or
--   <a>hNewProgressBar</a>. Update a progress bar with
--   <a>updateProgress</a> or <a>incProgress</a>.
data ProgressBar s

-- | Creates a progress bar.
--   
--   The progress bar is drawn immediately. Update the progress bar with
--   <a>updateProgress</a> or <a>incProgress</a>. Do not output anything to
--   your terminal between updates. It will mess up the animation.
--   
--   The progress bar is written to <a>stderr</a>. Write to another handle
--   with <a>hNewProgressBar</a>.
newProgressBar :: Style s -> Double -> Progress s -> IO (ProgressBar s)

-- | Creates a progress bar which outputs to the given handle.
--   
--   See <a>newProgressBar</a>.
hNewProgressBar :: Handle -> Style s -> Double -> Progress s -> IO (ProgressBar s)

-- | Renders a progress bar.
--   
--   <pre>
--   &gt;&gt;&gt; let t = UTCTime (ModifiedJulianDay 0) 0
--   
--   &gt;&gt;&gt; renderProgressBar defStyle (Progress 30 100 ()) (Timing t t)
--   "[============&gt;..............................]  30%"
--   </pre>
--   
--   Note that this function can not use <a>TerminalWidth</a> because it
--   doesn't use <a>IO</a>. Use <a>newProgressBar</a> or
--   <a>hNewProgressBar</a> to get automatic width.
renderProgressBar :: Style s -> Progress s -> Timing -> Text

-- | Change the progress of a progress bar.
--   
--   This function is thread safe. Multiple threads may update a single
--   progress bar at the same time.
--   
--   There is a maximum refresh rate. This means that some updates might
--   not be drawn.
updateProgress :: forall s. ProgressBar s -> (Progress s -> Progress s) -> IO ()

-- | Increment the progress of an existing progress bar.
--   
--   See <a>updateProgress</a> for more information.
incProgress :: ProgressBar s -> Int -> IO ()

-- | Visual style of a progress bar.
--   
--   The style determines how a progress bar is rendered to text.
--   
--   The textual representation of a progress bar follows the following
--   template:
--   
--   
--   &lt;<b>prefix</b>&gt;&lt;<b>open</b>&gt;&lt;<b>done</b>&gt;&lt;<b>current</b>&gt;&lt;<b>todo</b>&gt;&lt;<b>close</b>&gt;&lt;<b>postfix</b>&gt;
--   
--   Where &lt;<b>done</b>&gt; and &lt;<b>todo</b>&gt; are repeated as
--   often as necessary.
--   
--   Consider the following progress bar
--   
--   <pre>
--   "Working [=======&gt;.................]  30%"
--   </pre>
--   
--   This bar can be specified using the following style:
--   
--   <pre>
--   <a>Style</a>
--   { <a>styleOpen</a>    = "["
--   , <a>styleClose</a>   = "]"
--   , <a>styleDone</a>    = '='
--   , <a>styleCurrent</a> = '&gt;'
--   , <a>styleTodo</a>    = '.'
--   , <a>stylePrefix</a>  = <a>msg</a> "Working"
--   , <a>stylePostfix</a> = <a>percentage</a>
--   , <a>styleWidth</a>   = <a>ConstantWidth</a> 40
--   , <a>styleEscapeOpen</a>    = const <a>empty</a>
--   , <a>styleEscapeClose</a>   = const <a>empty</a>
--   , <a>styleEscapeDone</a>    = const <a>empty</a>
--   , <a>styleEscapeCurrent</a> = const <a>empty</a>
--   , <a>styleEscapeTodo</a>    = const <a>empty</a>
--   , <a>styleEscapePrefix</a>  = const <a>empty</a>
--   , <a>styleEscapePostfix</a> = const <a>empty</a>
--   , <a>styleOnComplete</a> = <a>WriteNewline</a>
--   }
--   </pre>
data Style s
Style :: !Text -> !Text -> !Char -> !Char -> !Char -> Label s -> Label s -> !ProgressBarWidth -> EscapeCode s -> EscapeCode s -> EscapeCode s -> EscapeCode s -> EscapeCode s -> EscapeCode s -> EscapeCode s -> !OnComplete -> Style s

-- | Bar opening symbol.
[styleOpen] :: Style s -> !Text

-- | Bar closing symbol
[styleClose] :: Style s -> !Text

-- | Completed work.
[styleDone] :: Style s -> !Char

-- | Symbol used to denote the current amount of work that has been done.
[styleCurrent] :: Style s -> !Char

-- | Work not yet completed.
[styleTodo] :: Style s -> !Char

-- | Prefixed label.
[stylePrefix] :: Style s -> Label s

-- | Postfixed label.
[stylePostfix] :: Style s -> Label s

-- | Total width of the progress bar.
[styleWidth] :: Style s -> !ProgressBarWidth

-- | Escape code printed just before the <a>styleOpen</a> symbol.
[styleEscapeOpen] :: Style s -> EscapeCode s

-- | Escape code printed just before the <a>styleClose</a> symbol.
[styleEscapeClose] :: Style s -> EscapeCode s

-- | Escape code printed just before the first <a>styleDone</a> character.
[styleEscapeDone] :: Style s -> EscapeCode s

-- | Escape code printed just before the <a>styleCurrent</a> character.
[styleEscapeCurrent] :: Style s -> EscapeCode s

-- | Escape code printed just before the first <a>styleTodo</a> character.
[styleEscapeTodo] :: Style s -> EscapeCode s

-- | Escape code printed just before the <a>stylePrefix</a> label.
[styleEscapePrefix] :: Style s -> EscapeCode s

-- | Escape code printed just before the <a>stylePostfix</a> label.
[styleEscapePostfix] :: Style s -> EscapeCode s

-- | What happens when progress is finished.
[styleOnComplete] :: Style s -> !OnComplete

-- | An escape code is a sequence of bytes which the terminal looks for and
--   interprets as commands, not as character codes.
--   
--   It is vital that the output of this function, when send to the
--   terminal, does not result in characters being drawn.
type EscapeCode s = Progress s " Current progress bar state." -> Text " Resulting escape code. Must be non-printable."

-- | What happens when a progress bar is finished.
data OnComplete

-- | Write a new line when the progress bar is finished. The completed
--   progress bar will remain visible.
WriteNewline :: OnComplete

-- | Clear the progress bar once it is finished.
Clear :: OnComplete

-- | The default style.
--   
--   This style shows the progress as a percentage. It does not use any
--   escape sequences.
--   
--   Override some fields of the default instead of specifying all the
--   fields of a <a>Style</a> record.
defStyle :: Style s

-- | Width of progress bar in characters.
data ProgressBarWidth

-- | A constant width.
ConstantWidth :: !Int -> ProgressBarWidth

-- | Use the entire width of the terminal.
--   
--   Identical to <a>ConstantWidth</a> if the width of the terminal can not
--   be determined.
TerminalWidth :: !Int -> ProgressBarWidth

-- | An amount of progress.
data Progress s
Progress :: !Int -> !Int -> !s -> Progress s

-- | Amount of work completed.
[progressDone] :: Progress s -> !Int

-- | Total amount of work.
[progressTodo] :: Progress s -> !Int

-- | A value which is used by custom labels. The builtin labels do not care
--   about this field. You can ignore it by using the unit value '()'.
[progressCustom] :: Progress s -> !s

-- | A label is a part of a progress bar that changes based on the
--   progress.
--   
--   Labels can be at the front (prefix) or at the back (postfix) of a
--   progress bar.
--   
--   Labels can use both the current amount of progress and the timing
--   information to generate some text.
newtype Label s
Label :: (Progress s -> Timing -> Text) -> Label s
[runLabel] :: Label s -> Progress s -> Timing -> Text

-- | Timing information about a <a>ProgressBar</a>.
--   
--   This information is used by <a>Label</a>s to calculate elapsed time,
--   remaining time, total time, etc.
--   
--   See <a>elapsedTime</a>, <a>remainingTime</a> and <a>totalTime</a>.
data Timing
Timing :: !UTCTime -> !UTCTime -> Timing

-- | Moment in time when a progress bar was created. See
--   <a>newProgressBar</a>.
[timingStart] :: Timing -> !UTCTime

-- | Moment in time of the most recent progress update.
[timingLastUpdate] :: Timing -> !UTCTime

-- | Static text.
--   
--   The output does not depend on the input.
--   
--   <pre>
--   &gt;&gt;&gt; msg "foo" st
--   "foo"
--   </pre>
msg :: Text -> Label s

-- | Progress as a percentage.
--   
--   <pre>
--   &gt;&gt;&gt; runLabel $ percentage (Progress 30 100 ()) someTiming
--   " 30%"
--   </pre>
--   
--   <b>Note</b>: if no work is to be done (todo == 0) the percentage will
--   be shown as 100%.
percentage :: Label s

-- | Progress as a fraction of the total amount of work.
--   
--   <pre>
--   &gt;&gt;&gt; runLabel $ exact (Progress 30 100 ()) someTiming
--   " 30/100"
--   </pre>
exact :: Label s

-- | Amount of time that has elapsed.
--   
--   Time starts when a progress bar is created.
--   
--   The user must supply a function which actually renders the amount of
--   time that has elapsed. You can use <a>renderDuration</a> or
--   <tt>formatTime</tt> from time &gt;= 1.9.
elapsedTime :: (NominalDiffTime -> Text) -> Label s

-- | Estimated remaining time.
--   
--   Tells you how much longer some task is expected to take.
--   
--   This label uses a simple estimation algorithm. It assumes progress is
--   linear. To prevent nonsense results it won't estimate remaining time
--   until at least 1 second of work has been done.
--   
--   When it refuses to estimate the remaining time it will show an
--   alternative message instead.
--   
--   The user must supply a function which actually renders the amount of
--   time that has elapsed. Use <a>renderDuration</a> or
--   <tt>formatTime</tt> from the time &gt;= 1.9 package.
remainingTime :: (NominalDiffTime -> Text) -> Text -> Label s

-- | Estimated total time.
--   
--   This label uses a simple estimation algorithm. It assumes progress is
--   linear. To prevent nonsense results it won't estimate the total time
--   until at least 1 second of work has been done.
--   
--   When it refuses to estimate the total time it will show an alternative
--   message instead.
--   
--   The user must supply a function which actually renders the total
--   amount of time that a task will take. You can use
--   <a>renderDuration</a> or <tt>formatTime</tt> from the time &gt;= 1.9
--   package.
totalTime :: (NominalDiffTime -> Text) -> Text -> Label s

-- | Show amount of time.
--   
--   <pre>
--   renderDuration (fromInteger 42)
--   </pre>
--   
--   42
--   
--   <pre>
--   renderDuration (fromInteger $ 5 * 60 + 42)
--   </pre>
--   
--   05:42
--   
--   <pre>
--   renderDuration (fromInteger $ 8 * 60 * 60 + 5 * 60 + 42)
--   </pre>
--   
--   08:05:42
--   
--   Use the time &gt;= 1.9 package to get a formatTime function which
--   accepts <a>NominalDiffTime</a>.
renderDuration :: NominalDiffTime -> Text
instance GHC.Generics.Generic (System.ProgressBar.Style s)
instance Control.DeepSeq.NFData (System.ProgressBar.Label s)
instance GHC.Generics.Generic System.ProgressBar.OnComplete
instance GHC.Generics.Generic System.ProgressBar.ProgressBarWidth
instance Control.DeepSeq.NFData s => Control.DeepSeq.NFData (System.ProgressBar.ProgressBar s)
instance Control.DeepSeq.NFData s => Control.DeepSeq.NFData (System.ProgressBar.Style s)
instance GHC.Base.Semigroup (System.ProgressBar.Label s)
instance GHC.Base.Monoid (System.ProgressBar.Label s)
instance Data.String.IsString (System.ProgressBar.Label s)
instance Control.DeepSeq.NFData System.ProgressBar.OnComplete
instance Control.DeepSeq.NFData System.ProgressBar.ProgressBarWidth
