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.

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.

Creates a progress bar which outputs to the given handle.

See newProgressBar.

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.

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.

Increment the progress of an existing progress bar.

See updateProgress for more information.

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
}

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.

What happens when a progress bar is finished.

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.

Width of progress bar in characters.

An amount of progress.

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.

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.

Static text.

The output does not depend on the input.

>>> msg "foo" st"foo"

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

Progress as a fraction of the total amount of work.

>>> runLabel $ exact (Progress 30 100 ()) someTiming" 30/100"

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.

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.

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.

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.