Progress indicators are useful to let users know that a command isn't stalled.
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!"
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)
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...
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
ACON::Helper::ProgressIndicator.set_placeholder_formatter "message" do # Return any arbitrary string "My Custom Message" end
Placeholder customization is global and would affect any indicator used after calling
.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)#
.placeholder_formatter(name : String) : ACON::Helper::ProgressIndicator::PlaceholderFormatter | Nil#
Returns the global formatter for the provided name if it exists, otherwise
.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.
#message=(message : String | Nil) : Nil#
Sets the message to display alongside the indicator.