<html><head><meta name="color-scheme" content="light dark"></head><body><pre style="word-wrap: break-word; white-space: pre-wrap;"># autolatex - Progress.pm
# Copyright (C) 2013  Stephane Galland &lt;galland@arakhne.org&gt;
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 2 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program; see the file COPYING.  If not, write to
# the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
# Boston, MA 02111-1307, USA.

=pod

=head1 NAME

Progress.pm - Implementation of a progress indicator

=head1 DESCRIPTION

Provides a tool to show the progress of the tasks.

To use this library, type C&lt;use AutoLaTeX::Core::Progress;&gt;.

=head1 GETTING STARTED

=head2 Initialization

To create a progress tool, say something like this:

    use AutoLaTeX::Core::Progress;

    my $max = 100;
    my $progress = AutoLaTeX::Core::Progress-&gt;new($max) ;

...or something similar.

=head1 METHOD DESCRIPTIONS

This section contains only the methods in Progress.pm itself.

=over

=cut
package AutoLaTeX::Core::Progress;

our @ISA = qw( Exporter );
our @EXPORT = qw( );
our @EXPORT_OK = qw();

require 5.014;
use strict;
use utf8;
use vars qw(@ISA @EXPORT @EXPORT_OK $VERSION);
use Exporter;
use Carp;
use AutoLaTeX::Core::IntUtils;
use AutoLaTeX::Core::Util qw($INTERNAL_MESSAGE_PREFIX);

our $VERSION = '4.0';

#------------------------------------------------------
#
# Constructor
#
#------------------------------------------------------

sub new(;$) : method {
	my $proto = shift;
	my $class = ref($proto) || $proto;
	my $parent = ref($proto) &amp;&amp; $proto ;
	my $max = $_[0];
	if (!defined($max) || $max&lt;0) {
		$max = 100;
	}
	my $self;
	if ( $parent ) {
		%{$self} = %{$parent} ;
	}
	else {
		$self = {
			'child' =&gt; undef,
			'max' =&gt; $max,
			'value' =&gt; 0,
			'parent' =&gt; undef,
			'bar-width' =&gt; 30,
			'comment' =&gt; '',
			'comment-to-display' =&gt; '',
			'previous-message-size' =&gt; 0,
			'carriage-return' =&gt; 1,
		};
	}
	bless( $self, $class );

	return $self;
}

sub _newChild($$$) : method {
	my $proto = shift;
	my $class = ref($proto) || $proto;
	my $parent = shift;
	my $min = shift;
	my $max = shift;
	my $self = {
		'child' =&gt; undef,
		'value' =&gt; 0,
		'parent' =&gt; $parent,
		'min-in-parent' =&gt; $min,
		'max-in-parent' =&gt; $max,
		'max' =&gt; 0,
		'comment' =&gt; '',
	};
	bless( $self, $class );
	return $self;
}

=pod

=item * setCarriageReturn($)

Enable or disable the use of the carraige-return character
C&lt;\r&gt; at the end of the lines. If the carriage-return
character is not used, the new-line character C&lt;\n&gt; is
used.

=over 4

=item B&lt;use_carriage_return&gt;

=over

=cut
sub setCarriageReturn($) : method {
	my $self = shift;
	$self-&gt;{'carriage-return'} = shift;
}

=pod

=item * getCarriageReturn()

Replies if the carriage-return character is used at the end
of the output lines.

=cut
sub getCarriageReturn() : method {
	my $self = shift;
	return $self-&gt;{'carriage-return'};
}

=pod

=item * setBarWidth($)

Set the number of characters for rendering the progress bar.

=over 4

=item B&lt;width&gt; is the number of characters of the bar.

=over

=cut
sub setBarWidth($) : method {
	my $self = shift;
	my $width = shift;
	if ($self-&gt;{'parent'}) {
		$self-&gt;{'parent'}-&gt;setBarWidth($width);
	}
	else {
		$self-&gt;{'bar-width'} = $width;
	}
}

=pod

=item * getBarWidth()

Replies the number of characters for rendering the progress bar.

=cut
sub getBarWidth() : method {
	my $self = shift;
	if ($self-&gt;{'parent'}) {
		return $self-&gt;{'parent'}-&gt;getBarWidth();
	}
	else {
		return $self-&gt;{'bar-width'};
	}
}

=pod

=item * setComment($)

Set the comment associated to the progress process.

=over 4

=item B&lt;label&gt; is the comment text.

=over

=cut
sub setComment($) : method {
	my $self = shift;
	my $label = shift || '';
	$self-&gt;{'comment'} = $label || '';
	my $c = '';
	my $p = $self;
	while ($p-&gt;{'parent'}) {
		if (!$c &amp;&amp; $p-&gt;{'comment'}) {
			$c = $p-&gt;{'comment'};
		}
		$p = $p-&gt;{'parent'};
	}
	if ($p &amp;&amp; $p-&gt;{'comment-to-display'} ne $c) {
		$p-&gt;{'comment-to-display'} = $c;
		$p-&gt;_report();
		return 1;
	}
	return 0;
}

=pod

=item * getComment()

Replies the comment in the progress bar.

=cut
sub getComment() : method {
	my $self = shift;
	if ($self-&gt;{'parent'}) {
		return $self-&gt;{'parent'}-&gt;getComment();
	}
	else {
		return $self-&gt;{'comment-to-display'};
	}
}

=pod

=item * setMax()

Set the maximal value. It must be greater than the previous
value of max. This function does not output on the console.

=cut
sub setMax($) : method {
	my $self = shift;
	my $max = shift;
	if ($max&gt;$self-&gt;{'max'}) {
		$self-&gt;{'max'} = $max;
	}
}

=pod

=item * getMax()

Replies the maximal value.

=cut
sub getMax() : method {
	my $self = shift;
	return $self-&gt;{'max'};
}

=pod

=item * getValue()

Replies the current value.

=cut
sub getValue() : method {
	my $self = shift;
	return $self-&gt;{'value'};
}

=pod

=item * setValue($)

Change the progress value and display the progress message.

=over 4

=item B&lt;value&gt; is the current value of the progress indicator.

=back

Returns a boolean value that indicates if something was setValueed.

=cut
sub setValue($;$) : method {
	my $self = shift;
	my $value = shift;
	my $comment = shift;
	my $max = $self-&gt;getMax();
	my $currentValue = $self-&gt;getValue();
	my $reported = undef;
	confess('undef $value') unless (defined($value));
	if ($value&gt;$currentValue) {
		$self-&gt;_set_value($value);
		$currentValue = $self-&gt;getValue();
		# Close any child progress
		if ($self-&gt;{'child'}) {
			my $mip = $self-&gt;{'child'}{'max-in-parent'};
			if ($currentValue&gt;=$mip) {
				$reported = $self-&gt;_disconnectChildProgress();
			}
		}
		# Notify parent
		if ($self-&gt;{'parent'}) {
			my $range = $self-&gt;{'max-in-parent'} - $self-&gt;{'min-in-parent'};
			my $parent_value = ($value * $range) / $max;
			$parent_value += $self-&gt;{'min-in-parent'};
			if (!defined($comment) &amp;&amp; $self-&gt;{'comment'}) {
				$comment = $self-&gt;{'comment'};
			}
			my $reported2 = $self-&gt;{'parent'}-&gt;setValue($parent_value, $comment);
			$reported = $reported || $reported2;
		}
		# Change the comment to be displayed
		elsif (defined($comment) &amp;&amp; $comment ne $self-&gt;{'comment-to-display'}) {
			$self-&gt;{'comment-to-display'} = $comment;
			$reported = undef;
		}
		# Force reporting
		if (!$reported) {
			$reported = $self-&gt;_report();
		}
	}
	return $reported ;
}

sub _set_value($) : method {
	my $self = shift;
	my $value = shift;
	if ($value&gt;=$self-&gt;{'max'}) {
		$self-&gt;{'value'} = $self-&gt;{'max'};
	}
	else {
		$self-&gt;{'value'} = $value;
	}
}

sub _report() : method {
	my $self = shift;
	my $value = $self-&gt;getValue();
	my $max = $self-&gt;getMax();
	if (!$self-&gt;{'parent'}) {
		my $message = "[".$self-&gt;_formatPercent($value, $max)."] ".$self-&gt;_formatBar($value, $max);
		if ($self-&gt;{'comment-to-display'}) {
			$message .= ' '.$self-&gt;{'comment-to-display'};
		}
		my $l = length($message);
		my $tmp_l = $l;
		while ($tmp_l&lt;$self-&gt;{'previous-message-size'}) {
			$message .= ' ';
			$tmp_l++;
		}
		$self-&gt;{'previous-message-size'} = $l;
		if (!$self-&gt;{'carriage-return'} || ($value&gt;=$max)) {
			print STDOUT "$message\n";
		}
		else {
			print STDOUT "$message\r";
		}
		$INTERNAL_MESSAGE_PREFIX = "\n";
		return 1;
	}
	return undef;
}

sub _formatPercent($$) : method {
	my $self = shift;
	my $value = shift;
	my $max = shift;
	my $percent = int(($value * 100) / $max);
	while (length($percent)&lt;3) {
		$percent = " $percent";
	}
	return "$percent\%";
}

sub _formatBar($$) : method {
	my $self = shift;
	my $value = shift;
	my $max = shift;
	my $bar_width = $self-&gt;getBarWidth();
	my $nchars = int(($value * $bar_width) / $max);
	my $i = 0;
	my $bar = '';
	while ($i&lt;$nchars) {
		$bar .= '#';
		$i++;
	}
	while ($i&lt;$bar_width) {
		$bar .= '.';
		$i++;
	}
	return $bar;
}

sub _disconnectChildProgress() : method {
	my $self = shift;
	if ($self-&gt;{'child'}) {
		my $max_in_parent = $self-&gt;{'child'}{'max-in-parent'};
		$self-&gt;{'child'} = undef;
		return $self-&gt;setValue($max_in_parent);
	}
	return undef;
}

=pod

=item * subProgress($$)

Create a subtask.

=over 4

=item B&lt;size&gt; (optional) is the size of the subtask in this progress. If not given, the rest of the parent task is covered by the sub task.

=back

Replies the subtask progress object.

=cut
sub subProgress(;$) : method {
	my $self = shift;
	my $size = shift;

	my $parent_max = $self-&gt;getMax();
	my $min_in_parent = $self-&gt;getValue();

	if (!defined($size) || $size&lt;0) {
		$size = $parent_max - $min_in_parent;
	}

	my $max_in_parent = $min_in_parent + $size;
	if ($max_in_parent&gt;$parent_max) {
		$max_in_parent = $parent_max;
	}

	$self-&gt;{'child'} = AutoLaTeX::Core::Progress-&gt;_newChild(
				$self,
				$min_in_parent,
				$max_in_parent);

	return $self-&gt;{'child'};
}

=pod

=item * increment(;$)

Increment the current value by the given amount, or by 1 if the amount is not given or invalid.

=cut
sub increment(;$) : method {
	my $self = shift;
	my $inc = shift;
	if (!defined($inc) || $inc&lt;=0) {
		$inc = 1;
	}
	my $value = $self-&gt;getValue();
	$self-&gt;setValue($value+$inc);
}

=pod

=item * stop()

Stop the progress.

=cut
sub stop() : method {
	my $self = shift;
	my $max = $self-&gt;getMax();
	$self-&gt;setValue($max);
}

=pod

=item * debug()

Output the state of this progress.

=cut
sub debug(;$) : method {
	my $self = shift;
	my $level = shift || 0;
	printf STDERR ("%s[\%3d] value: 0&lt;=\%f&lt;=\%f\n", $INTERNAL_MESSAGE_PREFIX, $level, $self-&gt;{'value'}, $self-&gt;{'max'});
	$INTERNAL_MESSAGE_PREFIX = '';
	if ($self-&gt;{'parent'}) {
		my $parent_value = $self-&gt;{'parent'}-&gt;getValue();
		printf STDERR ("[\%3d] in-parent: \%f&lt;=%f&lt;=\%f\n", $level, $self-&gt;{'min-in-parent'}, $parent_value, $self-&gt;{'max-in-parent'});
	}
	else {
		printf STDERR ("[\%3d] comment: \%s\n", $level, $self-&gt;{'comment'});
	}
	if ($self-&gt;{'child'}) {
		$self-&gt;{'child'}-&gt;debug($level+1);
	}
}

1;
__END__
=back

=head1 BUG REPORT AND FEEDBACK

To report bug, provide feedback, suggest new features, etc. visit the AutoLaTeX Project management page at &lt;http://www.arakhne.org/autolatex/&gt; or send email to the author at L&lt;galland@arakhne.org&gt;.

=head1 LICENSE

S&lt;GNU Public License (GPL)&gt;

=head1 COPYRIGHT

S&lt;Copyright (c) 2013 StÃŠphane Galland E&lt;lt&gt;galland@arakhne.orgE&lt;gt&gt;&gt;

=head1 SEE ALSO

L&lt;autolatex-dev&gt;
</pre></body></html>