.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Progress::Any::Output::TermProgressBarColor 3pm"
.TH Progress::Any::Output::TermProgressBarColor 3pm "2020-08-25" "perl v5.30.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Progress::Any::Output::TermProgressBarColor \- Output progress to terminal as color bar
.SH "VERSION"
.IX Header "VERSION"
This document describes version 0.249 of Progress::Any::Output::TermProgressBarColor (from Perl distribution Progress-Any-Output-TermProgressBarColor), released on 2020\-08\-15.
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Progress::Any::Output;
\&
\& # use default options
\& Progress::Any::Output\->set(\*(AqTermProgressBarColor\*(Aq);
\&
\& # set options
\& Progress::Any::Output\->set(\*(AqTermProgressBarColor\*(Aq,
\&                            width=>50, fh=>\e*STDERR, show_delay=>5);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fB\s-1THIS IS AN EARLY RELEASE, SOME THINGS ARE NOT YET IMPLEMENTED E.G. STYLES,
COLOR THEMES\s0\fR.
.PP
Sample screenshots:
.PP
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:
.IP "\(bu" 4
colors and color themes
.IP "\(bu" 4
template and styles
.IP "\(bu" 4
displaying message text in addition to bar/percentage number
.IP "\(bu" 4
wide character support
.PP
\&\s-1XXX\s0 option to cleanup when complete or not (like in Term::ProgressBar) and
should default to 1.
.SH "METHODS"
.IX Header "METHODS"
.SS "new(%args) => \s-1OBJ\s0"
.IX Subsection "new(%args) => OBJ"
Instantiate. Usually called through \f(CW\*(C`Progress::Any::Output\->set("TermProgressBarColor", %args)\*(C'\fR.
.PP
Known arguments:
.IP "\(bu" 4
freq => num
.Sp
Limit the frequency of output updating. 0 means no frequency limiting (update
output after every \f(CW\*(C`update()\*(C'\fR).
.Sp
A positive number means to update output when there has been that amount of
difference in position since last \f(CW\*(C`update()\*(C'\fR. For example, if \f(CW\*(C`freq\*(C'\fR is 10 and
the last \f(CW\*(C`update()\*(C'\fR was at position 5, then the next output update will be when
position is at least 15.
.Sp
A negative number means to update output when time has passed that amount of
absolute value (in seconds). For example, if \f(CW\*(C`freq\*(C'\fR is \-3 and the last
\&\f(CW\*(C`update()\*(C'\fR was 1 second ago, then the next output update will not be until the
next two seconds has passed.
.Sp
By default undef, in which case Progress::Any will use the default \-0.5 (at most
once every 0.5 seconds).
.IP "\(bu" 4
wide => bool
.Sp
If set to 1, enable wide character support (requires Text::ANSI::WideUtil.
.IP "\(bu" 4
width => \s-1INT\s0
.Sp
Width of progress bar. The default is to detect terminal width and use the whole
width.
.IP "\(bu" 4
color_theme => \s-1STR\s0
.Sp
Not yet implemented.
.Sp
Choose color theme. To see what color themes are available, use
\&\f(CW\*(C`list_color_themes()\*(C'\fR.
.IP "\(bu" 4
style => \s-1STR\s0
.Sp
Not yet implemented.
.Sp
Choose style. To see what styles are available, use \f(CW\*(C`list_styles()\*(C'\fR. Styles
determine the characters used for drawing the bar, alignment, etc.
.IP "\(bu" 4
template => str
.Sp
See \fBfill_template\fR in Progress::Any's documentation. Aside from conversions
supported by Progress::Any, this output recognizes these additional conversions:
\&\f(CW%b\fR to display the progress bar (with width using the rest of the available
width), \f(CW%B\fR to display the progress bar as well as the message inside it. You
can also enclose parts of text with \*(L"<color \s-1RGB\s0>\*(R" ... \*(L"</color>\*(R" to give color.
.Sp
The default template is:
.Sp
.Vb 1
\& <color ffff00>%p</color> <color 808000>[</color>%B<color 808000>]</color><color ffff00>%e</color>
.Ve
.IP "\(bu" 4
fh => handle (default: \e*STDERR)
.Sp
Instead of the default \s-1STDERR,\s0 you can direct the output to another filehandle
e.g. \s-1STDOUT.\s0
.IP "\(bu" 4
show_delay => int
.Sp
If set, will delay showing the progress bar until the specified number of
seconds. This can be used to create, e.g. a \s-1CLI\s0 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.
.IP "\(bu" 4
rownum => uint
.Sp
Default 0. Can be set to put the progress bar at certain rownum. This can be
used to display several progress bars together.
.SS "\fBkeep_delay_showing()\fP"
.IX Subsection "keep_delay_showing()"
Can be called to reset the timer that counts down to show progress bar when
\&\f(CW\*(C`show_delay\*(C'\fR is defined. For example, if \f(CW\*(C`show_delay\*(C'\fR is 5 seconds and two
seconds have passed, it should've been 3 seconds before progress bar is shown in
the next \f(CW\*(C`update()\*(C'\fR. However, if you call this method, it will be 5 seconds
again before showing.
.SH "FAQ"
.IX Header "FAQ"
.SS "How to update progress bar output more often?"
.IX Subsection "How to update progress bar output more often?"
Set \f(CW\*(C`freq\*(C'\fR to e.g. \-0.1 or \-0.05. The default \f(CW\*(C`freq\*(C'\fR, when unset, is \-0.5
which means to update output at most once every 0.5 second.
.SS "How to display a different message for this output?"
.IX Subsection "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:
.PP
.Vb 1
\& <elspan prio=2>Downloading </elspan><elspan prio=3 truncate=middle>http://127.0.0.1:7007/2.mp4 </elspan>37.3M/139.5M
.Ve
.PP
while another output like Progress::Any::Output::TermMessage does not use
String::Elide::Parts. It should just display the string as:
.PP
.Vb 1
\& Downloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M
.Ve
.PP
In the indicator, you can provide a specific message for this output:
.PP
.Vb 5
\& $progress\->update(
\&     message => \*(AqDownloading http://127.0.0.1:7007/2.mp4 37.3M/139.5M\*(Aq,
\&     \*(Aqmessage.alt.output.TermProgressBarColor\*(Aq => \*(Aq<elspan prio=2>Downloading </elspan><elspan prio=3 truncate=middle>http://127.0.0.1:7007/2.mp4 </elspan>37.3M/139.5M\*(Aq,
\&     ...
\& );
.Ve
.SH "ENVIRONMENT"
.IX Header "ENVIRONMENT"
.SS "\s-1NO_COLOR\s0"
.IX Subsection "NO_COLOR"
Bool. Can be used to disable color. Consulted before \s-1NO_COLOR\s0. See
Color::ANSI::Util.
.SS "\s-1COLOR\s0"
.IX Subsection "COLOR"
Bool. Can be used to force or disable color. See Color::ANSI::Util.
.SS "\s-1COLOR_DEPTH\s0"
.IX Subsection "COLOR_DEPTH"
Integer. Can be used to override color depth detection. See
Color::ANSI::Util.
.SS "\s-1COLUMNS\s0"
.IX Subsection "COLUMNS"
Integer. Can be used to override terminal width detection.
.SS "\s-1PROGRESS_TERM_BAR\s0"
.IX Subsection "PROGRESS_TERM_BAR"
Bool. Forces disabling or enabling progress output (just for this output).
.PP
In the absence of \s-1PROGRESS_TERM_MESSAGE\s0 and \s-1PROGRESS,\s0 will default to 1 if
filehandle is detected as interactive (using \f(CW\*(C`\-t\*(C'\fR).
.SS "\s-1PROGRESS\s0"
.IX Subsection "PROGRESS"
Bool. Forces disabling or enabling progress output (for all outputs).
.SH "HOMEPAGE"
.IX Header "HOMEPAGE"
Please visit the project's homepage at <https://metacpan.org/release/Progress\-Any\-Output\-TermProgressBarColor>.
.SH "SOURCE"
.IX Header "SOURCE"
Source repository is at <https://github.com/perlancar/perl\-Progress\-Any\-Output\-TermProgressBarColor>.
.SH "BUGS"
.IX Header "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>
.PP
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.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Progress::Any
.PP
Term::ProgressBar
.PP
Ruby library: ruby-progressbar, <https://github.com/jfelchner/ruby\-progressbar>
.SH "AUTHOR"
.IX Header "AUTHOR"
perlancar <perlancar@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2020, 2018, 2017, 2016, 2015, 2014, 2013 by perlancar@cpan.org.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.