Skip to content

class Athena::Console::Helper::ProgressIndicator
inherits Reference #

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

View source

Class methods#

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

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

View source

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

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

View source

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

View source

Methods#

#advance : Nil#

Advance the indicator to display the next indicator character.

View source

#display : Nil#

Display the current state of the indicator.

View source

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

Completes the indicator with the provided message.

View source

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

Sets the message to display alongside the indicator.

View source

#start(message : String) : Nil#

Starts and displays the indicator with the provided message.

View source