class

Athena::Console::Helper::ProgressIndicator

Inherits Reference / Object

Progress indicators are useful to let users know that a command isn't stalled. However, unlike ACON::Helper::ProgressBars, these indicators are used when the command's duration is indeterminate, such as long-running commands or tasks that are quantifiable.

Progress Indicator

# Create a new progress indicator.
indicator = ACON::Helper::ProgressIndicator.new output

# Start and display the progress indicator with a custom message.
indicator.start "Processing..."

50.times do
  # Do work

  # Advance the progress indicator.
  indicator.advance
end

# Ensure the progress indicator shows a final completion message
indicator.finish "Finished!"

Customizing

Built-in Formats

The progress indicator comes with a few built-in formats based on the ACON::Output::Verbosity the command was executed with:

# Verbosity::NORMAL (CLI with no verbosity flag)
 \ Processing...
 | Processing...
 / Processing...
 - Processing...

# Verbosity::VERBOSE (-v)
 \ Processing... (1 sec)
 | Processing... (1 sec)
 / Processing... (1 sec)
 - Processing... (1 sec)

# Verbosity::VERY_VERBOSE (-vv) and Verbosity::DEBUG (-vvv)
 \ Processing... (1 sec, 1kiB)
 | Processing... (1 sec, 1kiB)
 / Processing... (1 sec, 1kiB)
 - Processing... (1 sec, 1kiB)

NOTE: If a command called with ACON::Output::Verbosity::QUIET, the progress bar will not be displayed.

The format may also be set explicitly in code within the constructor:

# If the progress bar has a maximum number of steps.
ACON::Helper::ProgressIndicator.new output, format: :very_verbose

Custom Indicator Values

Custom indicator values may also be used:

indicator = ACON::Helper::ProgressIndicator.new output, indicator_values: %w(⠏ ⠛ ⠹ ⢸ ⣰ ⣤ ⣆ ⡇)

The progress indicator would now look like:

⠏ Processing...
⠛ Processing...
⠹ Processing...
⢸ Processing...

Custom Placeholders

A progress indicator uses placeholders (a name enclosed with the % character) to determine the output format. The built-in placeholders include:

%indicator% - The current indicator
%elapsed% - The time elapsed since the start of the progress indicator
%memory% - The current memory usage
%message% - Used to display arbitrary messages

These can be customized via .set_placeholder_formatter.

ACON::Helper::ProgressIndicator.set_placeholder_formatter "message" do
  # Return any arbitrary string
  "My Custom Message"
end

NOTE: Placeholder customization is global and would affect any indicator used after calling .set_placeholder_formatter.

Constructors

new(output : ACON::Output::Interface, format : ACON::Helper::ProgressIndicator::Format | Nil = nil, indicator_change_interval : Time::Span = 100.milliseconds, indicator_values : Indexable(String) | Nil = nil, clock : ACLK::Interface = ACLK::Native.new, finished_indicator : String = "✔")

Source