.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) .\" .\" 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 "Term::ProgressBar 3pm" .TH Term::ProgressBar 3pm "2022-10-09" "perl v5.34.0" "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" Term::ProgressBar \- provide a progress meter on a standard terminal .SH "VERSION" .IX Header "VERSION" Version 2.23 .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Term::ProgressBar; \& \& my $progress = Term::ProgressBar\->new ({count => 10_000}); \& $progress\->update(5_000); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Term::ProgressBar provides a simple progress bar on the terminal, to let the user know that something is happening, roughly how much stuff has been done, and maybe an estimate at how long remains. .PP A typical use sets up the progress bar with a number of items to do, and then calls update to update the bar whenever an item is processed. .PP Often, this would involve updating the progress bar many times with no user-visible change. To avoid unnecessary work, the update method returns a value, being the update value at which the user will next see a change. By only calling update when the current value exceeds the next update value, the call overhead is reduced. .PP Remember to call the \f(CW\*(C`$progress\->update($max_value)\*(C'\fR when the job is done to get a nice 100% done bar. .PP A progress bar by default is simple; it just goes from left-to-right, filling the bar with '=' characters. These are called \fBmajor\fR characters. For long-running jobs, this may be too slow, so two additional features are available: a linear completion time estimator, and/or a \fBminor\fR character: this is a character that \fImoves\fR from left-to-right on the progress bar (it does not fill it as the major character does), traversing once for each major-character added. This exponentially increases the granularity of the bar for the same width. .SH "EXAMPLES" .IX Header "EXAMPLES" .SS "A really simple use" .IX Subsection "A really simple use" .Vb 1 \& #!/usr/bin/perl \& \& use Term::ProgressBar 2.00; \& use constant MAX => 100_000; \& \& my $progress = Term::ProgressBar\->new(MAX); \& \& for (0..MAX) { \& my $is_power = 0; \& for (my $i = 0; 2**$i <= $_; $i++) { \& $is_power = 1 if 2**$i == $_; \& } \& \& if ($is_power) { \& $progress\->update($_); \& } \& } .Ve .PP see eg/simle_use.pl .PP Here is a simple example. The process considers all the numbers between 0 and \&\s-1MAX,\s0 and updates the progress bar whenever it finds one. Note that the progress bar update will be very erratic. See below for a smoother example. Note also that the progress bar will never complete; see below to solve this. .PP The complete text of this example is in \fIexamples/powers\fR in the distribution set (it is not installed as part of the module). .SS "A smoother bar update" .IX Subsection "A smoother bar update" .Vb 1 \& my $progress = Term::ProgressBar\->new($max); \& \& for (0..$max) { \& my $is_power = 0; \& for (my $i = 0; 2**$i <= $_; $i++) { \& $is_power = 1 if 2**$i == $_; \& } \& \& $progress\->update($_) \& } .Ve .PP See eg/smooth_bar.pl .PP This example calls update for each value considered. This will result in a much smoother progress update, but more program time is spent updating the bar than doing the \*(L"real\*(R" work. See below to remedy this. This example does \&\fInot\fR call \f(CW\*(C`$progress\->update($max);\*(C'\fR at the end, since it is unnecessary, and ProgressBar will throw an exception at an attempt to update a finished bar. .PP The complete text of this example is in \fIexamples/powers2\fR in the distribution set (it is not installed as part of the module. .SS "A (much) more efficient update" .IX Subsection "A (much) more efficient update" .Vb 3 \& my $progress = Term::ProgressBar\->new({name => \*(AqPowers\*(Aq, count => $max, remove => 1}); \& $progress\->minor(0); \& my $next_update = 0; \& \& for (0..$max) { \& my $is_power = 0; \& for (my $i = 0; 2**$i <= $_; $i++) { \& $is_power = 1 if 2**$i == $_; \& } \& \& $next_update = $progress\->update($_) if $_ >= $next_update; \& } \& \& $progress\->update($max) if $max >= $next_update; .Ve .PP This example does two things to improve efficiency: firstly, it uses the value returned by update to only call it again when needed; secondly, it switches off the use of minor characters to update a lot less frequently (\f(CW\*(C`$progress\->minor(0);\*(C'\fR. The use of the return value of update means that the call of \f(CW\*(C`$progress\->update($max);\*(C'\fR at the end is required to ensure that the bar ends on 100%, which gives the user a nice feeling. .PP This example also sets the name of the progress bar. .PP This example also demonstrates the use of the 'remove' flag, which removes the progress bar from the terminal when done. .PP The complete text of this example is in \fIexamples/powers3\fR in the distribution set (it is not installed as part of the module. .SS "When the maximum number of items is sometimes unknown" .IX Subsection "When the maximum number of items is sometimes unknown" Sometimes you may wish to use the progress bar when the number of items may or may not be known. One common example is when you write a script that can take input piped from the output of another command, and then pipe the output to yet another command. eg: .PP .Vb 1 \& some_command \-\-arg value | my_script.pl | some_other_command .Ve .PP Or ... .PP .Vb 1 \& my_script.pl input_file output_file .Ve .PP This example shows how you can iterate over a file specified on the command line with the progress bar. Since the input file may be read from \s-1STDIN,\s0 the number of lines may not be known. Term::ProgressBar handles this by just taking '\-1' as the count value and with no further changes to the code. By calling update with the same count value, you ensure the progress bar is removed afterwards. .PP .Vb 6 \& my $input_file = shift; \& my $output_file = shift; \& my $in_fh = \e*STDIN; \& my $out_fh = \e*STDOUT; \& my $message_fh = \e*STDERR; \& my $num_lines = \-1; \& \& if (defined($input_file) and $input_file ne \*(Aq\-\*(Aq) { \& open($in_fh, $input_file) or die "Couldn\*(Aqt open file, \*(Aq$input_file\*(Aq: $!"; \& my $wc_output = \`wc \-l $input_file\`; \& chomp($wc_output); \& $wc_output =~ /^\es*(\ed+)(\eD.*)?/ or die "Couldn\*(Aqt parse wc output: $wc_output"; \& $num_lines = $1; \& } \& \& if(defined($output_file)) { \& !\-f $output_file or die "Specified output file, \*(Aq$output_file\*(Aq, already exists"; \& open($out_fh, \*(Aq>\*(Aq, $output_file) or die "Couldn\*(Aqt open output file, \*(Aq$output_file\*(Aq: $!"; \& } \& \& my $progress = Term::ProgressBar\->new({ \& name => \*(Aqfile processor\*(Aq, \& count => $num_lines, \& remove => 1, \& fh => $message_fh, \& }); \& \& while (my $line = <$in_fh>) { \& chomp($line); \& print $out_fh "I found a line: $line\en"; \& $progress\->message("Found 10000!") if($line =~ /10000/); \& $progress\->update(); \& } \& \& $progress\->update($num_lines); \& \& print $message_fh "Finished\en"; .Ve .PP When the file is defined explicitly, the progress bar displays the linewise progress through the file. Since the progress bar by default prints output to stderr, your scripts output to \s-1STDOUT\s0 will not be affected. .SS "Using Completion Time Estimation" .IX Subsection "Using Completion Time Estimation" .Vb 7 \& my $progress = Term::ProgressBar\->new({ \& name => \*(AqPowers\*(Aq, \& count => $max, \& ETA => \*(Aqlinear\*(Aq, \& }); \& $progress\->max_update_rate(1); \& my $next_update = 0; \& \& for (0..$max) { \& my $is_power = 0; \& for (my $i = 0; 2**$i <= $_; $i++) { \& if ( 2**$i == $_ ) { \& $is_power = 1; \& $progress\->message(sprintf "Found %8d to be 2 ** %2d", $_, $i); \& } \& } \& \& $next_update = $progress\->update($_) \& if $_ > $next_update; \& } \& $progress\->update($max) \& if $max >= $next_update; .Ve .PP This example uses the \s-1ETA\s0 option to switch on completion estimation. Also, the update return is tuned to try to update the bar approximately once per second, with the max_update_rate call. See the documentation for the new method for details of the format(s) used. .PP This example also provides an example of the use of the message function to output messages to the same filehandle whilst keeping the progress bar intact .PP The complete text of this example is in \fIexamples/powers5\fR in the distribution set (it is not installed as part of the module. .SH "INSTANCE CONSTRUCTION" .IX Header "INSTANCE CONSTRUCTION" .SS "new" .IX Subsection "new" Create & return a new Term::ProgressBar instance. .IP "\s-1ARGUMENTS\s0" 4 .IX Item "ARGUMENTS" If one argument is provided, and it is a hashref, then the hash is treated as a set of key/value pairs, with the following keys; otherwise, it is treated as a number, being equivalent to the \f(CW\*(C`count\*(C'\fR key. .RS 4 .IP "count" 4 .IX Item "count" The item count. The progress is marked at 100% when update \fIcount\fR is invoked, and proportionally until then. .Sp If you specify a count less than zero, just the name (if specified) will be displayed and (if the remove flag is set) removed when the progress bar is updated with a number lower than zero. This allows you to use the progress bar when the count is sometimes known and sometimes not without making multiple changes throughout your code. .IP "name" 4 .IX Item "name" A name to prefix the progress bar with. .IP "fh" 4 .IX Item "fh" The filehandle to output to. Defaults to stderr. Do not try to use *foo{\s-1THING\s0} syntax if you want Term capabilities; it does not work. Pass in a globref instead. .IP "term_width" 4 .IX Item "term_width" Sometimes we can't correctly determine the terminal width. You can use this parameter to force a term width of a particular size. Use a positive integer, please :) .IP "silent" 4 .IX Item "silent" If passed a true value, Term::ProgressBar will do nothing at all. Useful in scripts where the progress bar is optional (or just plain doesn't work due to issues with modules it relies on). .Sp Instead, tell the constructor you want it to be silent and you don't need to change the rest of your program: .Sp .Vb 3 \& my $progress = Term::ProgressBar\->new( { count => $count, silent => $silent } ); \& # later \& $progress\->update; # does nothing .Ve .IP "\s-1ETA\s0" 4 .IX Item "ETA" A total time estimation to use. If enabled, a time finished estimation is printed on the \s-1RHS\s0 (once sufficient updates have been performed to make such an estimation feasible). Naturally, this is an \fIestimate\fR; no guarantees are made. The format of the estimate .Sp Note that the format is intended to be as compact as possible while giving over the relevant information. Depending upon the time remaining, the format is selected to provide some resolution whilst remaining compact. Since the time remaining decreases, the format typically changes over time. .Sp As the \s-1ETA\s0 approaches, the format will state minutes & seconds left. This is identifiable by the word \f(CW\*(AqLeft\*(Aq\fR at the \s-1RHS\s0 of the line. If the \s-1ETA\s0 is further away, then an estimate time of completion (rather than time left) is given, and is identifiable by \f(CW\*(AqETA\*(Aq\fR at the \s-1LHS\s0 of the \s-1ETA\s0 box (on the right of the progress bar). A time or date may be presented; these are of the form of a 24 hour clock, e.g. \f(CW\*(Aq13:33\*(Aq\fR, a time plus days (e.g., \f(CW\*(Aq 7PM+3\*(Aq\fR for around in over 3 days time) or a day/date, e.g. \f(CW\*(Aq 1Jan\*(Aq\fR or \f(CW\*(Aq27Feb\*(Aq\fR. .Sp If \s-1ETA\s0 is switched on, the return value of update is also affected: the idea here is that if the progress bar seems to be moving quicker than the eye would normally care for (and thus a great deal of time is spent doing progress updates rather than \*(L"real\*(R" work), the next value is increased to slow it. The maximum rate aimed for is tunable via the max_update_rate component. .Sp The available values for this are: .RS 4 .IP "undef" 4 .IX Item "undef" Do not do estimation. The default. .IP "linear" 4 .IX Item "linear" Perform linear estimation. This is simply that the amount of time between the creation of the progress bar and now is divided by the current amount done, and completion estimated linearly. .RE .RS 4 .RE .RE .RS 4 .RE .IP "\s-1EXAMPLES\s0" 4 .IX Item "EXAMPLES" .Vb 2 \& my $progress = Term::ProgressBar\->new(100); # count from 1 to 100 \& my $progress = Term::ProgressBar\->new({ count => 100 }); # same \& \& # Count to 200 thingies, outputting to stdout instead of stderr, \& # prefix bar with \*(Aqthingy\*(Aq \& my $progress = Term::ProgressBar\->new({ count => 200, \& fh => \e*STDOUT, \& name => \*(Aqthingy\*(Aq }); .Ve .SH "INSTANCE COMPONENTS" .IX Header "INSTANCE COMPONENTS" .SS "Scalar Components." .IX Subsection "Scalar Components." See \*(L"get_set\*(R" in Class::MethodMaker for usage. .IP "target" 4 .IX Item "target" The final target. Updates are measured in terms of this. Changes will have no effect until the next update, but the next update value should be relative to the new target. So .Sp .Vb 6 \& $p = Term::ProgressBar({count => 20}); \& # Halfway \& $p\->update(10); \& # Double scale \& $p\->target(40) \& $p\->update(21); .Ve .Sp will cause the progress bar to update to 52.5% .IP "max_update_rate" 4 .IX Item "max_update_rate" This value is taken as being the maximum speed between updates to aim for. \&\fBIt is only meaningful if \s-1ETA\s0 is switched on.\fR It defaults to 0.5, being the number of seconds between updates. .SS "Boolean Components" .IX Subsection "Boolean Components" See \*(L"get_set\*(R" in Class::MethodMaker for usage. .IP "minor" 4 .IX Item "minor" Default: set. If unset, no minor scale will be calculated or updated. .Sp Minor characters are used on the progress bar to give the user the idea of progress even when there are so many more tasks than the terminal is wide that the granularity would be too great. By default, Term::ProgressBar makes a guess as to when minor characters would be valuable. However, it may not always guess right, so this method may be called to force it one way or the other. Of course, the efficiency saving is minimal unless the client is utilizing the return value of update. .Sp See \fIexamples/powers4\fR and \fIexamples/powers3\fR to see minor characters in action, and not in action, respectively. .SS "Configuration" .IX Subsection "Configuration" .IP "lbrack" 4 .IX Item "lbrack" Left bracket ( defaults to [ ) .Sp .Vb 1 \& $progress\->lbrack(\*(Aq<\*(Aq); .Ve .IP "rbrack" 4 .IX Item "rbrack" Right bracket ( defaults to ] ) .Sp .Vb 1 \& $progress\->rbrack(\*(Aq>\*(Aq); .Ve .SH "INSTANCE HIGHER-LEVEL PROCEDURES" .IX Header "INSTANCE HIGHER-LEVEL PROCEDURES" .SS "update" .IX Subsection "update" Update the progress bar. .IP "\s-1ARGUMENTS\s0" 4 .IX Item "ARGUMENTS" .RS 4 .PD 0 .IP "so_far" 4 .IX Item "so_far" .PD Current progress point, in whatever units were passed to \f(CW\*(C`new\*(C'\fR. .Sp If not defined, assumed to be 1+ whatever was the value last time \f(CW\*(C`update\*(C'\fR was called (starting at 0). .RE .RS 4 .RE .IP "\s-1RETURNS\s0" 4 .IX Item "RETURNS" .RS 4 .PD 0 .IP "next_call" 4 .IX Item "next_call" .PD The next value of so_far at which to call \f(CW\*(C`update\*(C'\fR. .RE .RS 4 .RE .SS "message" .IX Subsection "message" Output a message. This is very much like print, but we try not to disturb the terminal. .IP "\s-1ARGUMENTS\s0" 4 .IX Item "ARGUMENTS" .RS 4 .PD 0 .IP "string" 4 .IX Item "string" .PD The message to output. .RE .RS 4 .RE .SH "REPORTING BUGS" .IX Header "REPORTING BUGS" via \s-1RT:\s0 .SH "COMPATIBILITY" .IX Header "COMPATIBILITY" If exactly two arguments are provided, then new operates in v1 compatibility mode: the arguments are considered to be name, and item count. Various other defaults are set to emulate version one (e.g., the major output character is '#', the bar width is set to 50 characters and the output filehandle is not treated as a terminal). This mode is deprecated. .SH "AUTHOR" .IX Header "AUTHOR" Martyn J. Pearce fluffy@cpan.org .PP Significant contributions from Ed Avis, amongst others. .SH "MAINTAINER" .IX Header "MAINTAINER" Gabor Szabo .SH "LICENSE AND COPYRIGHT" .IX Header "LICENSE AND COPYRIGHT" Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.