-- 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 System.ProgressBar 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.2

-- | 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 ProgressBar value contains the state of a progress bar.
--   
--   Create a progress bar with newProgressBar or
--   hNewProgressBar. Update a progress bar with
--   updateProgress or incProgress.
data ProgressBar s

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

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

-- | Renders a progress bar.
--   
--   
--   >>> let t = UTCTime (ModifiedJulianDay 0) 0
--   
--   >>> renderProgressBar defStyle (Progress 30 100 ()) (Timing t t)
--   "[============>..............................]  30%"
--   
--   
--   Note that this function can not use TerminalWidth because it
--   doesn't use IO. Use newProgressBar or
--   hNewProgressBar 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 :: ProgressBar s -> (Progress s -> Progress s) -> IO ()

-- | Increment the progress of an existing progress bar.
--   
--   See updateProgress 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:
--   
--   
--   <prefix><open><done><current><todo><close><postfix>
--   
--   Where <done> and <todo> are repeated as
--   often as necessary.
--   
--   Consider the following progress bar
--   
--   
--   "Working [=======>.................]  30%"
--   
--   
--   This bar can be specified using the following style:
--   
--   
--   Style
--   { styleOpen    = "["
--   , styleClose   = "]"
--   , styleDone    = '='
--   , styleCurrent = '>'
--   , styleTodo    = '.'
--   , stylePrefix  = msg "Working"
--   , stylePostfix = percentage
--   , styleWidth   = ConstantWidth 40
--   , styleEscapeOpen    = const empty
--   , styleEscapeClose   = const empty
--   , styleEscapeDone    = const empty
--   , styleEscapeCurrent = const empty
--   , styleEscapeTodo    = const empty
--   , styleEscapePrefix  = const empty
--   , styleEscapePostfix = const empty
--   , styleOnComplete = WriteNewline
--   }
--   
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 styleOpen symbol.
[styleEscapeOpen] :: Style s -> EscapeCode s

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

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

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

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

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

-- | Escape code printed just before the stylePostfix 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 -> Text

-- | 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 Style 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 ConstantWidth 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 ProgressBar.
--   
--   This information is used by Labels to calculate elapsed time,
--   remaining time, total time, etc.
--   
--   See elapsedTime, remainingTime and totalTime.
data Timing
Timing :: !UTCTime -> !UTCTime -> Timing

-- | Moment in time when a progress bar was created. See
--   newProgressBar.
[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.
--   
--   
--   >>> msg "foo" st
--   "foo"
--   
msg :: Text -> Label s

-- | Progress as a percentage.
--   
--   
--   >>> runLabel $ percentage (Progress 30 100 ()) someTiming
--   " 30%"
--   
--   
--   Note: 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.
--   
--   
--   >>> runLabel $ exact (Progress 30 100 ()) someTiming
--   " 30/100"
--   
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 renderDuration or
--   formatTime from time >= 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 renderDuration or
--   formatTime from the time >= 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
--   renderDuration or formatTime from the time >= 1.9
--   package.
totalTime :: (NominalDiffTime -> Text) -> Text -> Label s

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