1 package Term::ProgressBar;
3 #XXX TODO Redo original test with count=20
7 # Test use of last_update (with update(*undef*)) with scales
8 # Choice of FH other than STDERR
9 # If no term, output no progress bar; just progress so far
10 # Use of simple term with v2.0 bar
11 # If name is wider than term, trim name
12 # Don't update progress bar on new?
16 Term::ProgressBar - provide a progress meter on a standard terminal
20 use Term::ProgressBar;
22 $progress = Term::ProgressBar->new ({count => $count});
23 $progress->update ($so_far);
27 Term::ProgressBar provides a simple progress bar on the terminal, to let the
28 user know that something is happening, roughly how much stuff has been done,
29 and maybe an estimate at how long remains.
31 A typical use sets up the progress bar with a number of items to do, and then
32 calls L<update|"update"> to update the bar whenever an item is processed.
34 Often, this would involve updating the progress bar many times with no
35 user-visible change. To avoid unnecessary work, the update method returns a
36 value, being the update value at which the user will next see a change. By
37 only calling update when the current value exceeds the next update value, the
38 call overhead is reduced.
40 Remember to call the C<< $progress->update($max_value) >> when the job is done
41 to get a nice 100% done bar.
43 A progress bar by default is simple; it just goes from left-to-right, filling
44 the bar with '=' characters. These are called B<major> characters. For
45 long-running jobs, this may be too slow, so two additional features are
46 available: a linear completion time estimator, and/or a B<minor> character:
47 this is a character that I<moves> from left-to-right on the progress bar (it
48 does not fill it as the major character does), traversing once for each
49 major-character added. This exponentially increases the granularity of the
50 bar for the same width.
54 =head2 A really simple use
58 use Term::ProgressBar 2.00;
60 use constant MAX => 100_000;
62 my $progress = Term::ProgressBar->new(MAX);
66 for(my $i = 0; 2**$i <= $_; $i++) {
72 $progress->update($_);
78 Here is a simple example. The process considers all the numbers between 0 and
79 MAX, and updates the progress bar whenever it finds one. Note that the
80 progress bar update will be very erratic. See below for a smoother example.
81 Note also that the progress bar will never complete; see below to solve this.
83 The complete text of this example is in F<examples/powers> in the
84 distribution set (it is not installed as part of the module).
86 =head2 A smoother bar update
88 my $progress = Term::ProgressBar->new($max);
92 for(my $i = 0; 2**$i <= $_; $i++) {
102 This example calls update for each value considered. This will result in a
103 much smoother progress update, but more program time is spent updating the bar
104 than doing the "real" work. See below to remedy this. This example does
105 I<not> call C<< $progress->update($max); >> at the end, since it is
106 unnecessary, and ProgressBar will throw an exception at an attempt to update a
109 The complete text of this example is in F<examples/powers2> in the
110 distribution set (it is not installed as part of the module.
112 =head2 A (much) more efficient update
114 my $progress = Term::ProgressBar->new({name => 'Powers', count => $max, remove => 1});
120 for(my $i = 0; 2**$i <= $_; $i++) {
125 $next_update = $progress->update($_)
126 if $_ >= $next_update;
128 $progress->update($max)
129 if $max >= $next_update;
131 This example does two things to improve efficiency: firstly, it uses the value
132 returned by L<update|"update"> to only call it again when needed; secondly, it
133 switches off the use of minor characters to update a lot less frequently (C<<
134 $progress->minor(0); >>. The use of the return value of L<update|"update">
135 means that the call of C<< $progress->update($max); >> at the end is required
136 to ensure that the bar ends on 100%, which gives the user a nice feeling.
138 This example also sets the name of the progress bar.
140 This example also demonstrates the use of the 'remove' flag, which removes the
141 progress bar from the terminal when done.
143 The complete text of this example is in F<examples/powers3> in the
144 distribution set (it is not installed as part of the module.
146 =head2 Using Completion Time Estimation
148 my $progress = Term::ProgressBar->new({name => 'Powers',
151 $progress->max_update_rate(1);
156 for(my $i = 0; 2**$i <= $_; $i++) {
159 $progress->message(sprintf "Found %8d to be 2 ** %2d", $_, $i);
163 $next_update = $progress->update($_)
164 if $_ > $next_update;
166 $progress->update($max)
167 if $max >= $next_update;
169 This example uses the L<ETA|"ETA"> option to switch on completion estimation.
170 Also, the update return is tuned to try to update the bar approximately once
171 per second, with the L<max_update_rate|"max_update_rate"> call. See the
172 documentation for the L<new|new> method for details of the format(s) used.
174 This example also provides an example of the use of the L<message|"message">
175 function to output messages to the same filehandle whilst keeping the progress bar intact
177 The complete text of this example is in F<examples/powers5> in the
178 distribution set (it is not installed as part of the module.
182 # ----------------------------------------------------------------------
184 # Pragmas --------------------------
188 # Inheritance ----------------------
190 use base qw( Exporter );
191 use vars '@EXPORT_OK';
192 @EXPORT_OK = qw( $PACKAGE $VERSION );
194 # Utility --------------------------
196 use Carp qw( croak );
197 use Class::MethodMaker 1.02 qw( );
198 use Fatal qw( open sysopen close seek );
199 use POSIX qw( ceil strftime );
201 # ----------------------------------------------------------------------
203 # CLASS METHODS --------------------------------------------------------
205 # ----------------------------------
207 # ----------------------------------
209 =head1 CLASS CONSTANTS
215 use constant MINUTE => 60;
216 use constant HOUR => 60 * MINUTE;
217 use constant DAY => 24 * HOUR;
219 # The point past which to give ETA of just date, rather than time
220 use constant ETA_DATE_CUTOFF => 3 * DAY;
221 # The point past which to give ETA of time, rather time left
222 use constant ETA_TIME_CUTOFF => 10 * MINUTE;
223 # The ratio prior to which to not dare any estimates
224 use constant PREDICT_RATIO => 0.01;
226 use constant DEFAULTS => {
234 max_update_rate => 0.5,
236 # The following defaults are never used, but the keys
237 # are valuable for error checking
246 use constant ETA_TYPES => { map { $_ => 1 } qw( linear ) };
248 use constant ALREADY_FINISHED => 'progress bar already finished';
250 use constant DEBUG => 0;
252 # -------------------------------------
254 use vars qw($PACKAGE $VERSION);
255 $PACKAGE = 'Term-ProgressBar';
258 # ----------------------------------
260 # ----------------------------------
262 # ----------------------------------
264 # ----------------------------------
266 # This is here to allow testing to redirect away from the terminal but still
267 # see terminal output, IYSWIM
268 my $__FORCE_TERM = 0;
270 # ----------------------------------
271 # CLASS HIGHER-LEVEL FUNCTIONS
272 # ----------------------------------
274 # ----------------------------------
275 # CLASS HIGHER-LEVEL PROCEDURES
276 # ----------------------------------
280 ($__FORCE_TERM) = @_;
283 # ----------------------------------
284 # CLASS UTILITY FUNCTIONS
285 # ----------------------------------
288 my ( $self, $fh ) = @_;
289 return if $self->silent;
292 require Term::ReadKey;
294 warn "Guessing terminal width due to problem with Term::ReadKey\n";
300 $result = (Term::ReadKey::GetTerminalSize($fh))[0];
301 $result-- if ($^O eq "MSWin32");
303 warn "error from Term::ReadKey::GetTerminalSize(): $@";
306 # If GetTerminalSize() failed it should (according to its docs)
307 # return an empty list. It doesn't - that's why we have the eval {}
308 # above - but also it may appear to succeed and return a width of
313 warn "guessing terminal width $result\n";
320 # INSTANCE METHODS -----------------------------------------------------
322 # ----------------------------------
323 # INSTANCE CONSTRUCTION
324 # ----------------------------------
326 =head1 INSTANCE CONSTRUCTION
332 # Don't document hash keys until tested that the give the desired affect!
336 Create & return a new Term::ProgressBar instance.
342 If one argument is provided, and it is a hashref, then the hash is treated as
343 a set of key/value pairs, with the following keys; otherwise, it is treated as
344 a number, being equivalent to the C<count> key.
350 The item count. The progress is marked at 100% when update I<count> is
351 invoked, and proportionally until then.
355 A name to prefix the progress bar with.
359 The filehandle to output to. Defaults to stderr. Do not try to use
360 *foo{THING} syntax if you want Term capabilities; it does not work. Pass in a
365 Sometimes we can't correctly determine the terminal width. You can use this
366 parameter to force a term width of a particular size. Use a positive integer,
371 If passed a true value, Term::ProgressBar will do nothing at all. Useful in
372 scripts where the progress bar is optional (or just plain doesn't work due to
373 issues with modules it relies on).
375 Instead, tell the constructor you want it to be silent and you don't need to
376 change the rest of your program:
378 my $progress = Term::ProgressBar->new( { count => $count, silent => $silent } );
380 $progress->update; # does nothing
384 A total time estimation to use. If enabled, a time finished estimation is
385 printed on the RHS (once sufficient updates have been performed to make such
386 an estimation feasible). Naturally, this is an I<estimate>; no guarantees are
387 made. The format of the estimate
389 Note that the format is intended to be as compact as possible while giving
390 over the relevant information. Depending upon the time remaining, the format
391 is selected to provide some resolution whilst remaining compact. Since the
392 time remaining decreases, the format typically changes over time.
394 As the ETA approaches, the format will state minutes & seconds left. This is
395 identifiable by the word C<'Left'> at the RHS of the line. If the ETA is
396 further away, then an estimate time of completion (rather than time left) is
397 given, and is identifiable by C<'ETA'> at the LHS of the ETA box (on the right
398 of the progress bar). A time or date may be presented; these are of the form
399 of a 24 hour clock, e.g. C<'13:33'>, a time plus days (e.g., C<' 7PM+3'> for
400 around in over 3 days time) or a day/date, e.g. C<' 1Jan'> or C<'27Feb'>.
402 If ETA is switched on, the return value of L<update|"update"> is also
403 affected: the idea here is that if the progress bar seems to be moving quicker
404 than the eye would normally care for (and thus a great deal of time is spent
405 doing progress updates rather than "real" work), the next value is increased
406 to slow it. The maximum rate aimed for is tunable via the
407 L<max_update_rate|"max_update_rate"> component.
409 The available values for this are:
415 Do not do estimation. The default.
419 Perform linear estimation. This is simply that the amount of time between the
420 creation of the progress bar and now is divided by the current amount done,
421 and completion estimated linearly.
429 my $progress = Term::ProgressBar->new(100); # count from 1 to 100
430 my $progress = Term::ProgressBar->new({ count => 100 }); # same
432 # Count to 200 thingies, outputting to stdout instead of stderr,
433 # prefix bar with 'thingy'
434 my $progress = Term::ProgressBar->new({ count => 200,
442 Class::MethodMaker->import (new_with_init => 'new',
443 new_hash_init => 'hash_init',);
447 return if $self->silent;
450 return $self->init({count => $_[1], name => $_[0],
451 term_width => 50, bar_width => 50,
452 major_char => '#', minor_char => '',
453 lbrack => '', rbrack => '',
454 term => '0 but true',
461 sprintf("Term::ProgressBar::new We don't handle this many arguments: %d",
467 if ( UNIVERSAL::isa ($_[0], 'HASH') ) {
468 ($target) = @{$_[0]}{qw(count)};
469 %config = %{$_[0]}; # Copy in, so later playing does not tinker externally
474 if ( my @bad = grep ! exists DEFAULTS->{$_}, keys %config ) {
475 croak sprintf("Input parameters (%s) to %s not recognized\n",
476 join(':', @bad), 'Term::ProgressBar::new');
479 croak "Target count required for Term::ProgressBar new\n"
480 unless defined $target;
482 $config{$_} = DEFAULTS->{$_}
483 for grep ! exists $config{$_}, keys %{DEFAULTS()};
484 delete $config{count};
486 $config{term} = -t $config{fh}
487 unless defined $config{term};
489 if ( $__FORCE_TERM ) {
491 $config{term_width} = $__FORCE_TERM;
492 die "term width $config{term_width} (from __force_term) too small"
493 if $config{term_width} < 5;
494 } elsif ( $config{term} and ! defined $config{term_width}) {
495 $config{term_width} = $self->term_size($config{fh});
496 die if $config{term_width} < 5;
499 unless ( defined $config{bar_width} ) {
500 if ( defined $config{term_width} ) {
502 $config{bar_width} = $config{term_width} - 5;
503 $config{bar_width} -= $_
504 for map(( defined $config{$_} ? length($config{$_}) : 0),
505 qw( lbrack rbrack name ));
506 $config{bar_width} -= 2 # Extra for ': '
507 if defined $config{name};
508 $config{bar_width} -= 10
509 if defined $config{ETA};
510 if ( $config{bar_width} < 1 ) {
511 warn "terminal width $config{term_width} too small for bar; defaulting to 10\n";
512 $config{bar_width} = 10;
514 # } elsif ( ! $config{term} ) {
515 # $config{bar_width} = 1;
516 # $config{term_width} = defined $config{ETA} ? 12 : 5;
518 $config{bar_width} = $target;
519 die "configured bar_width $config{bar_width} < 1"
520 if $config{bar_width} < 1;
524 $config{start} = time;
526 select(((select $config{fh}), $| = 1)[0]);
528 $self->ETA(delete $config{ETA});
530 $self->hash_init (%config,
538 $self->target($target);
539 $self->minor($config{term} && $target > $config{bar_width} ** 1.5);
541 $self->update(0); # Initialize the progress bar
545 # ----------------------------------
546 # INSTANCE FINALIZATION
547 # ----------------------------------
549 # ----------------------------------
550 # INSTANCE COMPONENTS
551 # ----------------------------------
553 =head1 INSTANCE COMPONENTS
557 =head2 Scalar Components.
559 See L<Class::MethodMaker/get_set> for usage.
565 The final target. Updates are measured in terms of this. Changes will have
566 no effect until the next update, but the next update value should be relative
567 to the new target. So
569 $p = Term::ProgressBar({count => 20});
576 will cause the progress bar to update to 52.5%
578 =item max_update_rate
580 This value is taken as being the maximum speed between updates to aim for.
581 B<It is only meaningful if ETA is switched on.> It defaults to 0.5, being the
582 number of seconds between updates.
586 =head2 Boolean Components
588 See L<Class::MethodMaker/get_set> for usage.
594 Default: set. If unset, no minor scale will be calculated or updated.
596 Minor characters are used on the progress bar to give the user the idea of
597 progress even when there are so many more tasks than the terminal is wide that
598 the granularity would be too great. By default, Term::ProgressBar makes a
599 guess as to when minor characters would be valuable. However, it may not
600 always guess right, so this method may be called to force it one way or the
601 other. Of course, the efficiency saving is minimal unless the client is
602 utilizing the return value of L<update|"update">.
604 See F<examples/powers4> and F<examples/powers3> to see minor characters in
605 action, and not in action, respectively.
615 Left bracket ( defaults to [ )
617 $progress->lbrack('<');
621 Right bracket ( defaults to ] )
623 $progress->rbrack('>');
629 # Private Scalar Components
630 # offset ) Default: 0. Added to any value supplied to update.
631 # scale ) Default: 1. Any value supplied to update is multiplied by
633 # major_char) Default: '='. The character printed for the major scale.
634 # minor_char) Default: '*'. The character printed for the minor scale.
635 # name ) Default: undef. The name to print to the side of the bar.
636 # fh ) Default: STDERR. The filehandle to output progress to.
638 # Private Counter Components
639 # last_update ) Default: 0. The so_far value last time update was invoked.
640 # last_position) Default: 0. The number of the last progress mark printed.
642 # Private Boolean Components
643 # term ) Default: detected (by C<Term::ReadKey>).
644 # If unset, we assume that we are not connected to a terminal (or
645 # at least, not a suitably intelligent one). Then, we attempt
646 # minimal functionality.
648 Class::MethodMaker->import
650 get_set => [qw/ major_units major_char
651 minor_units minor_char
659 counter => [qw/ last_position last_update /],
660 boolean => [qw/ minor name_printed pb_ended remove /],
661 # let it be boolean to handle 0 but true
662 get_set => [qw/ term /],
665 # We generate these by hand since we want to check the values.
668 return if $self->silent;
669 return $self->{bar_width} if not @_;
670 croak 'wrong number of arguments' if @_ != 1;
671 croak 'bar_width < 1' if $_[0] < 1;
672 $self->{bar_width} = $_[0];
676 return if $self->silent;
677 return $self->{term_width} if not @_;
678 croak 'wrong number of arguments' if @_ != 1;
679 croak 'term_width must be at least 5' if $self->term and $_[0] < 5;
680 $self->{term_width} = $_[0];
685 return if $self->silent;
691 $self->major_units($self->bar_width / $target);
692 $self->minor_units($self->bar_width ** 2 / $target);
693 $self->minor ( defined $self->term_width and
694 $self->term_width < $target );
696 $self->{target} = $target;
699 return $self->{target};
704 return if $self->silent;
707 croak "Invalid ETA type: $type\n"
708 if defined $type and ! exists ETA_TYPES->{$type};
709 $self->{ETA} = $type;
715 # ----------------------------------
716 # INSTANCE HIGHER-LEVEL FUNCTIONS
717 # ----------------------------------
719 # ----------------------------------
720 # INSTANCE HIGHER-LEVEL PROCEDURES
721 # ----------------------------------
723 =head1 INSTANCE HIGHER-LEVEL PROCEDURES
730 warn sprintf("%s: This method is deprecated. Please use %s instead\n",
731 (caller (0))[3], '$x->minor (0)',);
732 $_[0]->clear_minor (0);
735 # -------------------------------------
739 Update the progress bar.
749 Current progress point, in whatever units were passed to C<new>.
751 If not defined, assumed to be 1+ whatever was the value last time C<update>
752 was called (starting at 0).
762 The next value of so_far at which to call C<update>.
772 return if $self->silent;
775 if ( ! defined $so_far ) {
776 $so_far = $self->last_update + 1;
779 my $input_so_far = $so_far;
780 $so_far *= $self->scale
781 unless $self->scale == 1;
782 $so_far += $self->offset;
784 my $target = my $next = $self->target;
785 my $name = $self->name;
792 print $fh "(nothing to do)\n";
796 my $biggies = $self->major_units * $so_far;
797 my @chars = (' ') x $self->bar_width;
798 $chars[$_] = $self->major_char
801 if ( $self->minor ) {
802 my $smally = $self->minor_units * $so_far % $self->bar_width;
803 $chars[$smally] = $self->minor_char
804 unless $so_far == $target;
805 $next *= ($self->minor_units * $so_far + 1) / ($self->bar_width ** 2);
807 $next *= ($self->major_units * $so_far + 1) / $self->bar_width;
812 if ( $self->term > 0 ) {
815 $to_print .= "$name: "
817 my $ratio = $so_far / $target;
819 $to_print .= (sprintf ("%3d%% %s%s%s",
821 $self->lbrack, join ('', @chars), $self->rbrack));
822 my $ETA = $self->ETA;
823 if ( defined $ETA and $ratio > 0 ) {
824 if ( $ETA eq 'linear' ) {
826 my $taken = time - $self->start;
827 my $ss = $taken % 60;
828 my $mm = int(($taken % 3600) / 60);
829 my $hh = int($taken / 3600);
831 $to_print .= sprintf('D %2dh%02dm', $hh, $mm, $ss);
833 $to_print .= sprintf('D%2dh%02dm%02ds', $hh, $mm, $ss);
835 } elsif ( $ratio < PREDICT_RATIO ) {
836 # No safe prediction yet
837 $to_print .= 'ETA ------';
840 my $left = (($time - $self->start) * ((1 - $ratio) / $ratio));
841 if ( $left < ETA_TIME_CUTOFF ) {
842 $to_print .= sprintf '%1dm%02ds Left', int($left / 60), $left % 60;
844 my $eta = $time + $left;
847 $format = 'ETA %H:%M';
848 } elsif ( $left < ETA_DATE_CUTOFF ) {
849 $format = sprintf('ETA %%l%%p+%d',$left/DAY);
851 $format = 'ETA %e%b';
853 $to_print .= strftime($format, localtime $eta);
855 # Calculate next to be at least SEC_PER_UPDATE seconds away
857 my $incr = ($target - $so_far) / ($left / $self->max_update_rate);
858 $next = $so_far + $incr
859 if $so_far + $incr > $next;
863 croak "Bad ETA type: $ETA\n";
866 for ($self->{last_printed}) {
867 unless (defined and $_ eq $to_print) {
873 $next -= $self->offset;
874 $next /= $self->scale
875 unless $self->scale == 1;
877 if ( $so_far >= $target and $self->remove and ! $self->pb_ended) {
878 print $fh "\r", ' ' x $self->term_width, "\r";
885 if ( $self->term ) { # special case for backwards compat.
886 if ( $so_far == 0 and defined $name and ! $self->name_printed ) {
888 $self->set_name_printed;
891 my $position = int($self->bar_width * ($input_so_far / $target));
892 my $add = $position - $self->last_position;
893 $self->last_position_incr ($add)
896 print $fh $self->major_char x $add;
898 $next -= $self->offset;
899 $next /= $self->scale
900 unless $self->scale == 1;
902 my $pc = int(100*$input_so_far/$target);
903 printf $fh "[%s] %s: %3d%%\n", scalar(localtime), $name, $pc;
905 $next = ceil($target * ($pc+1)/100);
908 if ( $input_so_far >= $target ) {
909 if ( $self->pb_ended ) {
910 croak ALREADY_FINISHED;
921 $next = $target if $next > $target;
923 $self->last_update($input_so_far);
927 # -------------------------------------
931 Output a message. This is very much like print, but we try not to disturb the
942 The message to output.
952 return if $self->silent;
959 print $fh "\r", ' ' x $self->term_width;
960 print $fh "\r$string\n";
962 print $fh "\n$string\n";
963 print $fh $self->major_char x $self->last_position;
965 undef $self->{last_printed};
966 $self->update($self->last_update);
970 # ----------------------------------------------------------------------
972 =head1 REPORTING BUGS
974 via RT: L<https://rt.cpan.org/Dist/Display.html?Name=Pipe>
978 If exactly two arguments are provided, then L<new|"new"> operates in v1
979 compatibility mode: the arguments are considered to be name, and item count.
980 Various other defaults are set to emulate version one (e.g., the major output
981 character is '#', the bar width is set to 50 characters and the output
982 filehandle is not treated as a terminal). This mode is deprecated.
986 Martyn J. Pearce fluffy@cpan.org
988 Significant contributions from Ed Avis, amongst others.
992 Gabor Szabo L<http://szabgab.com/>
996 Copyright (c) 2001, 2002, 2003, 2004, 2005 Martyn J. Pearce. This program is
997 free software; you can redistribute it and/or modify it under the same terms
1002 1; # keep require happy.