--- name: "Progress::Any::Output::TermProgressBarColor" section: "3pm" platform: "linux" package: "libprogress-any-output-termprogressbarcolor-perl" version: "0.249-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/Progress::Any::Output::TermProgressBarColor" --- # Progress::Any::Output::TermProgressBarColor(3pm) Output progress to terminal as color bar ## NAME Progress::Any::Output::TermProgressBarColor - Output progress to terminal as color bar ## VERSION This document describes version 0.249 of Progress::Any::Output::TermProgressBarColor (from Perl distribution Progress-Any-Output-TermProgressBarColor), released on 2020-08-15. ## 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); ``` ## DESCRIPTION **THIS IS AN EARLY RELEASE, SOME THINGS ARE NOT YET IMPLEMENTED E.G. STYLES,** **COLOR THEMES**. Sample screenshots: This output displays progress indicators as colored progress bar on terminal. It produces output similar to that produced by Term::ProgressBar, except that it uses the Progress::Any framework and has additional features: - • 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. ## METHODS ### new(%args) =\> OBJ Instantiate. Usually called through `"Progress::Any::Output->set("TermProgressBarColor", %args)"`. Known arguments: - • 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 "\" ... "\" to give color. The default template is: ``` %p [%B]%e ``` - • 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. - • 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. ### 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. ## 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: ``` Downloading http://127.0.0.1:7007/2.mp4 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' => 'Downloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M', ... ); ``` ## ENVIRONMENT ### NO\_COLOR Bool. Can be used to disable color. Consulted before NO\_COLOR. See Color::ANSI::Util. ### 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). ## HOMEPAGE Please visit the project's homepage at \. ## SOURCE Source repository is at \. ## BUGS Please report any bugs or feature requests on the bugtracker website \ 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. ## SEE ALSO Progress::Any Term::ProgressBar Ruby library: ruby-progressbar, \ ## AUTHOR perlancar \ ## 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.