-# (X)Emacs mode: -*- cperl -*-
-
package Term::ProgressBar;
#XXX TODO Redo original test with count=20
# If name is wider than term, trim name
# Don't update progress bar on new?
-=head1 NAME
+=head1 NAME
Term::ProgressBar - provide a progress meter on a standard terminal
-=head1 SYNOPSIS
+=head1 SYNOPSIS
use Term::ProgressBar;
$progress = Term::ProgressBar->new ({count => $count});
$progress->update ($so_far);
-=head1 DESCRIPTION
+=head1 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,
calls L<update|"update"> to update the bar whenever an item is processed.
Often, this would involve updating the progress bar many times with no
-user-visible change. To avoid uneccessary work, the update method returns a
+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.
my $progress = Term::ProgressBar->new({name => 'Powers',
count => $max,
- ETA => linear, });
+ ETA => 'linear', });
$progress->max_update_rate(1);
my $next_update = 0;
term_width => undef,
term => undef,
remove => 0,
+ silent => 0,
};
use constant ETA_TYPES => { map { $_ => 1 } qw( linear ) };
use vars qw($PACKAGE $VERSION);
$PACKAGE = 'Term-ProgressBar';
-$VERSION = '2.09';
+$VERSION = '2.14';
# ----------------------------------
# CLASS CONSTRUCTION
# ----------------------------------
sub term_size {
- my ($fh) = @_;
+ my ( $self, $fh ) = @_;
+ return if $self->silent;
eval {
require Term::ReadKey;
*foo{THING} syntax if you want Term capabilities; it does not work. Pass in a
globref instead.
+=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 :)
+
+=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).
+
+Instead, tell the constructor you want it to be silent and you don't need to
+change the rest of your program:
+
+ my $progress = Term::ProgressBar->new( { count => $count, silent => $silent } );
+ # later
+ $progress->update; # does nothing
+
=item ETA
A total time estimation to use. If enabled, a time finished estimation is
sub init {
my $self = shift;
+ return if $self->silent;
# V1 Compatibility
return $self->init({count => $_[1], name => $_[0],
term_width => 50, bar_width => 50,
major_char => '#', minor_char => '',
lbrack => '', rbrack => '',
- term => '0 but true', })
+ term => '0 but true',
+ silent => 0,})
if @_ == 2;
my $target;
die "term width $config{term_width} (from __force_term) too small"
if $config{term_width} < 5;
} elsif ( $config{term} and ! defined $config{term_width}) {
- $config{term_width} = term_size($config{fh});
+ $config{term_width} = $self->term_size($config{fh});
die if $config{term_width} < 5;
}
} else {
$config{bar_width} = $target;
die "configured bar_width $config{bar_width} < 1"
- if $config{bar_width} < 1;
+ if $config{bar_width} < 1;
}
}
=back
+=head2 Configuration
+
+=over 4
+
+=item lbrack
+
+Left bracket ( defaults to [ )
+
+ $progress->lbrack('<');
+
+=item rbrack
+
+Right bracket ( defaults to ] )
+
+ $progress->rbrack('>');
+
+=back
+
=cut
# Private Scalar Components
offset scale
fh start
max_update_rate
+ silent
/],
counter => [qw/ last_position last_update /],
boolean => [qw/ minor name_printed pb_ended remove /],
# We generate these by hand since we want to check the values.
sub bar_width {
my $self = shift;
+ return if $self->silent;
return $self->{bar_width} if not @_;
croak 'wrong number of arguments' if @_ != 1;
croak 'bar_width < 1' if $_[0] < 1;
}
sub term_width {
my $self = shift;
+ return if $self->silent;
return $self->{term_width} if not @_;
croak 'wrong number of arguments' if @_ != 1;
croak 'term_width must be at least 5' if $self->term and $_[0] < 5;
sub target {
my $self = shift;
+ return if $self->silent;
if ( @_ ) {
my ($target) = @_;
sub ETA {
my $self = shift;
-
+ return if $self->silent;
if (@_) {
my ($type) = @_;
croak "Invalid ETA type: $type\n"
sub update {
my $self = shift;
+ return if $self->silent;
my ($so_far) = @_;
if ( ! defined $so_far ) {
}
}
for ($self->{last_printed}) {
- unless (defined and $_ eq $to_print) {
- print $fh $to_print;
- }
- $_ = $to_print;
+ unless (defined and $_ eq $to_print) {
+ print $fh $to_print;
+ }
+ $_ = $to_print;
}
$next -= $self->offset;
sub message {
my $self = shift;
+ return if $self->silent;
my ($string) = @_;
chomp ($string);
# ----------------------------------------------------------------------
-=head1 BUGS
-
-Z<>
-
=head1 REPORTING BUGS
-Email the author.
+via RT: L<https://rt.cpan.org/Dist/Display.html?Name=Pipe>
=head1 COMPATIBILITY
character is '#', the bar width is set to 50 characters and the output
filehandle is not treated as a terminal). This mode is deprecated.
-=head1 AUTHOR
+=head1 AUTHOR
Martyn J. Pearce fluffy@cpan.org
Significant contributions from Ed Avis, amongst others.
+=head1 MAINTAINER
+
+Gabor Szabo L<http://szabgab.com/>
+
=head1 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.
-=head1 SEE ALSO
-
-Z<>
-
=cut
1; # keep require happy.