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::ProgressBar
s, 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
.
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)
#
Class methods#
.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.
Methods#
#advance : Nil
#
Advance the indicator to display the next indicator character.
#display : Nil
#
Display the current state of the indicator.
#finish(message : String) : 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.