ruby-progressbar

Use ProgressBar.create to initialize a new progress bar. By default, it starts at 0 with a maximum capacity of 100 and begins rendering immediately.

progressbar = ProgressBar.create

The ProgressBar::Output.detect method automatically determines the most appropriate output handler based on the provided options and the environment:

1. Custom Class: If :output is a class that inherits from ProgressBar::Output, it instantiates that class.
2. TTY (Interactive Terminal): If the output stream (or $stdout by default) is a TTY, it uses Outputs::Tty to enable interactive features like clearing lines.
3. Non-TTY: If the stream is not a TTY (e.g., a redirected file or a pipe), it uses Outputs::NonTty to ensure progress doesn't clutter logs with escape sequences or attempt interactive line clearing.

To advance the progress bar, call the #increment method. Each call advances the bar by exactly 1 unit.

50.times { progressbar.increment }

The smoothing and running_average_rate options are deprecated and will be removed in version 2.0. To ensure future compatibility, migrate these options into a projector configuration block.

Deprecated way:

ProgressBar.new(smoothing: 0.5)

New way:

ProgressBar.new(projector: { type: 'smoothing', strength: 0.5 })

The ProgressBar::InvalidProgressError is raised when you attempt to set the progress state to an impossible value. This includes:

• Setting progress to a value greater than total.
• Setting total to a value less than the current progress.
• (In v2.0.0+) Attempting to increment when progress is already at total or decrement when progress is at 0.

The ProgressBar::Progress object provides methods to calculate how much of the task is complete:

• percentage_completed: Returns an integer representing the percentage (e.g., 50). It uses integer math to avoid float conversion issues.
• percentage_completed_with_precision: Returns a formatted string with two decimal places (e.g., " 50.00").
• none?: Returns true if the current progress is zero.
• finished?: Returns true if the current progress equals the total.

The to_s method on a ProgressBar::Components::Bar instance allows you to render the bar using different visual formats.

Supported :format options:

• :standard: Returns a string consisting of the completed progress marks followed by the remainder marks (e.g., ==== ).
• :integrated_percentage: Returns a string where the percentage is centered within the completed progress section (e.g., == 50% == ).

Note: If the progress is 'unknown', the bar will automatically use the 'Unknown Progress Animation' (UPA) regardless of the format requested.

The ProgressBar::Components::Rate component calculates the rate of progress (e.g., items per second). It requires a timer object (to track elapsed time) and a progress object (to track the absolute progress value). You can provide a rate_scale lambda to transform the raw rate (e.g., for scaling units).

To use it, initialize the component with the necessary objects and call rate_of_change or rate_of_change_with_precision.

The ProgressBar::Components::Bar class provides several convenience methods for rendering specific bar states:

• bar(length): Sets the bar length and returns the standard complete string.
• complete_bar(length): Sets the bar length and returns the bar in :standard format.
• complete_bar_with_percentage(length): Sets the bar length and returns the bar in :integrated_percentage format.
• incomplete_space(length): Sets the bar length and returns the incomplete portion of the bar (or the unknown animation if progress is unknown).
• bar_with_percentage(length): Sets the bar length and returns the integrated_percentage_complete_string.