class Athena::Console::Helper::ProgressIndicator

• Athena::Console::Helper::ProgressIndicator
• Reference
• Object

Overview

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.

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

Defined in:

helper/progress_indicator.cr

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::Monotonic.new, finished_indicator : String = "✔")

Class Method Summary

• .placeholder_formatter(name : String) : ACON::Helper::ProgressIndicator::PlaceholderFormatter | Nil

  Returns the global formatter for the provided name if it exists, otherwise nil.

• .set_placeholder_formatter(name : String, &block : self -> String) : Nil

  Registers a custom placeholder with the provided name with the block being the formatter.

• .set_placeholder_formatter(name : String, callable : ACON::Helper::ProgressIndicator::PlaceholderFormatter) : Nil

  Registers a custom placeholder with the provided name, using the provided callable as the formatter.

Instance Method Summary

• #advance : Nil

  Advance the indicator to display the next indicator character.

• #display : Nil

  Display the current state of the indicator.

• #finish(message : String, finished_indicator : String | Nil = nil) : Nil

  Completes the indicator with the provided message.

• #message=(message : String | Nil) : Nil

  Sets the message to display alongside the indicator.

• #start(message : String) : Nil

  Starts and displays the indicator with the provided message.

Constructor Detail

Class Method Detail

Instance Method Detail