Progre...arColor(3pm)

💖 Progre...arColor(3pm) 💖

okay bestie, buckle up — this is a page from the User Contributed Perl Documentation set, and the manual name is Progre...arColor(3pm). yes it's abbreviated, no that's not my fault, the terminal truncates it. it's giving "long name problems" ✨

---

🌈 NAME 🌈

Progress::Any::Output::TermProgressBarColor — it outputs progress to your terminal as a color bar. slay.

---

✨ VERSION ✨

this doc describes version 0.249 of Progress::Any::Output::TermProgressBarColor (from the Perl distribution Progress-Any-Output-TermProgressBarColor), released on 2020-08-15. vintage but iconic 🎀

---

🦋 SYNOPSIS 🦋

use Progress::Any::Output;

# use default options
Progress::Any::Output->set('TermProgressBarColor');

# set options
Progress::Any::Output->set('TermProgressBarColor',
                           width=>50, fh=>\*STDERR, show_delay=>5);

literally two lines and you're done. periodt.

---

💅 DESCRIPTION 💅

okay so heads up, THIS IS AN EARLY RELEASE, SOME THINGS ARE NOT YET IMPLEMENTED E.G. STYLES, COLOR THEMES. not me warning you before you get attached 😭

Sample screenshots: (yes, the original just says that — imagine the screenshots, bestie 🖼️)

this output displays progress indicators as a colored progress bar on the terminal. it produces output similar to what Term::ProgressBar produces, except it uses the Progress::Any framework and has extra features, which are:

• colors and color themes
• template and styles
• displaying message text in addition to bar/percentage number
• wide character support

XXX option to cleanup when complete or not (like in Term::ProgressBar) and should default to 1. — yes this is a real note from the original, no I did not make it up, it's literally just vibing there unfinished 💀

---

👑 METHODS 👑

🫶 new(%args) => OBJ

Instantiate. usually called through Progress::Any::Output->set("TermProgressBarColor", %args).

Known arguments (the whole menu, no skips):

• freq => num — limit the frequency of output updating. 0 means no frequency limiting (update output after every update()).

a positive number means to update output when there has been that amount of difference in position since last update(). for example, if freq is 10 and the last update() was at position 5, then the next output update will be when position is at least 15.

a negative number means to update output when time has passed that amount of absolute value (in seconds). for example, if freq is -3 and the last update() was 1 second ago, then the next output update will not be until the next two seconds has passed.

by default undef, in which case Progress::Any will use the default -0.5 (at most once every 0.5 seconds).

• wide => bool — if set to 1, enable wide character support (requires Text::ANSI::WideUtil.
• width => INT — width of progress bar. the default is to detect terminal width and use the whole width.
• color_theme => STR — not yet implemented. choose color theme. to see what color themes are available, use list_color_themes().
• style => STR — not yet implemented. choose style. to see what styles are available, use list_styles(). styles determine the characters used for drawing the bar, alignment, etc.
• template => str — see fill_template in Progress::Any's documentation. aside from conversions supported by Progress::Any, this output recognizes these additional conversions: %b to display the progress bar (with width using the rest of the available width), %B to display the progress bar as well as the message inside it. you can also enclose parts of text with "<color RGB>" ... "</color>" to give color.

the default template is:

<color ffff00>%p</color> <color 808000>[</color>%B<color 808000>]</color><color ffff00>%e</color>

• fh => handle (default: \*STDERR) — instead of the default STDERR, you can direct the output to another filehandle e.g. STDOUT.
• show_delay => int — if set, will delay showing the progress bar until the specified number of seconds. this can be used to create, e.g. a CLI application that is relatively not chatty but will display progress after several seconds of seeming inactivity to indicate users that the process is still going on. the "not me pretending to work for 5 seconds" feature 🧚
• rownum => uint — default 0. can be set to put the progress bar at certain rownum. this can be used to display several progress bars together. multitasking queen 👑

🌸 keep_delay_showing()

can be called to reset the timer that counts down to show progress bar when show_delay is defined. for example, if show_delay is 5 seconds and two seconds have passed, it should've been 3 seconds before progress bar is shown in the next update(). however, if you call this method, it will be 5 seconds again before showing. the clock resets. she said "we start over, actually" 💅

---

💜 FAQ 💜

⭐ How to update progress bar output more often?

set freq to e.g. -0.1 or -0.05. the default freq, when unset, is -0.5 which means to update output at most once every 0.5 second.

⭐ How to display a different message for this output?

for example, this output formats message using String::Elide::Parts so inside the message, substrings can be tagged for eliding priority:

<elspan prio=2>Downloading </elspan><elspan prio=3 truncate=middle>http://127.0.0.1:7007/2.mp4 </elspan>37.3M/139.5M

while another output like Progress::Any::Output::TermMessage does not use String::Elide::Parts. it should just display the string as:

Downloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M

in the indicator, you can provide a specific message for this output:

$progress->update(
    message => 'Downloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M',
    'message.alt.output.TermProgressBarColor' => '<elspan prio=2>Downloading </elspan><elspan prio=3 truncate=middle>http://127.0.0.1:7007/2.mp4 </elspan>37.3M/139.5M',
    ...
);

custom messages per output? that's main character energy fr fr 🎀

---

🌈 ENVIRONMENT 🌈

🍓 NO_COLOR

Bool. can be used to disable color. Consulted before NO_COLOR. see Color::ANSI::Util. (yes, that sentence is confusing. it's in the original. i'm just the messenger 🙈)

🍓 COLOR

Bool. can be used to force or disable color. see Color::ANSI::Util.

🍓 COLOR_DEPTH

Integer. can be used to override color depth detection. see Color::ANSI::Util.

🍓 COLUMNS

Integer. can be used to override terminal width detection.

🍓 PROGRESS_TERM_BAR

Bool. forces disabling or enabling progress output (just for this output).

in the absence of PROGRESS_TERM_MESSAGE and PROGRESS, will default to 1 if filehandle is detected as interactive (using -t).

🍓 PROGRESS

Bool. forces disabling or enabling progress output (for all outputs). the big boss of on/off switches 👑

---

🦋 HOMEPAGE 🦋

please visit the project's homepage at <https://metacpan.org/release/Progress-Any-Output-TermProgressBarColor>.

---

🎀 SOURCE 🎀

source repository is at <https://github.com/perlancar/perl-Progress-Any-Output-TermProgressBarColor>.

---

💀 BUGS 💀

please report any bugs or feature requests on the bugtracker website <https://rt.cpan.org/Public/Dist/Display.html?Name=Progress-Any-Output-TermProgressBarColor>

when submitting a bug or request, please include a test-file or a patch to an existing test-file that illustrates the bug or desired feature. help her help you 🫶

---

🔥 SEE ALSO 🔥

• Progress::Any
• Term::ProgressBar
• Ruby library: ruby-progressbar, <https://github.com/jfelchner/ruby-progressbar>

---

👑 AUTHOR 👑

perlancar <perlancar@cpan.org>

---

💖 COPYRIGHT AND LICENSE 💖

this software is copyright (c) 2020, 2018, 2017, 2016, 2015, 2014, 2013 by perlancar@cpan.org.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie 🎀 built on perl v5.30.3, dated 2020-08-25, filed under Progre...arColor(3pm). go make some gorgeous color bars, you absolute legend 💅✨