Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Progress::Any(3)      User Contributed Perl Documentation     Progress::Any(3)

NAME
       Progress::Any - Record progress to any output

VERSION
       This document describes version 0.219 of	Progress::Any (from Perl
       distribution Progress-Any), released on 2020-08-15.

SYNOPSIS
       Example of using	in a script with terminal progress bar as output
       (progress bar will be cleared on	"finish()"):

	use Progress::Any '$progress';
	use Progress::Any::Output 'TermProgressBarColor';

	$progress->target(10);
	for (1..10) {
	    $progress->update(message => "Doing	item $_");
	    sleep 1;
	}
	$progress->finish();

       Sample output:

	% ./script.pl
	 60% [Doing item 6====		 ]3s left

       Another example,	this time with terminal	message	as output:

	use Progress::Any '$progress';
	use Progress::Any::Output 'TermMessage', template => '[%n] %P/%T (%6.2p%%) %m';

	$progress->target(10);
	for (1..10) {
	    $progress->update(message => "Item $_/10");
	    sleep 1;
	}
	sleep 1;
	$progress->finish(message => "Finished!");

       Sample output:

	% ./script.pl
	[] 1/10	( 10.00%) Item 1/10
	[] 2/10	( 20.00%) Item 2/10
	...
	[] 10/10 (100.00%) Item	10/10
	[] 10/10 (100.00%) Finished!

       Example of using	in a module as well as script:

	# in lib/MyApp.pm
	package	MyApp;
	use Progress::Any;

	sub download {
	    my @urls = @_;
	    return unless @urls;
	    my $progress = Progress::Any->get_indicator(
		task =>	"download", pos=>0, target=>~~@urls);
	    for	my $url	(@urls)	{
		# download the $url ...
		$progress->update(message => "Downloaded $url");
	    }
	    $progress->finish;
	}

	# in script.pl
	use MyApp;
	use Progress::Any::Output;
	Progress::Any::Output->set('TermProgressBarColor');

	MyApp::download("url1",	"url2",	"url3",	"url4",	"url5");

       Sample output:

	% ./script.pl
	 20% [====== Downloaded	url1	       ]0m00s Left

       Example that demonstrates multiple indicator objects:

	use Progress::Any;
	use Progress::Any::Output;

	my $pdl	= Progress::Any->get_indicator(task => 'download');
	Progress::Any::Output->set({task=>'download'}, 'TermMessage', template => '[%-8t] [%P/%2T] %m');
	my $pcp	= Progress::Any->get_indicator(task => 'copy');
	Progress::Any::Output->set({task=>'copy'    }, 'TermMessage', template => '[%-8t] [%P/%2T] %m');

	$pdl->target(10);
	$pdl->update(message =>	"downloading A");
	$pcp->update(message =>	"copying A");
	sleep 1;
	$pdl->update(message =>	"downloading B");
	$pcp->update(message =>	"copying B");

       will show something like:

	[download] [1/10] downloading A
	[copy	 ] [1/ ?] copying A
	[download] [2/10] downloading B
	[copy	 ] [2/ ?] copying B

   Example of using with Perinci::CmdLine
       If you use Perinci::CmdLine, you	can mark your function as expecting a
       Progress::Any object and	it will	be supplied to you in a	special
       argument	"-progress":

	use File::chdir;
	use Perinci::CmdLine;
	$SPEC{check_dir} = {
	    v => 1.1,
	    args => {
		dir => {summary=>"Path to check", schema=>"str*", req=>1, pos=>0},
	    },
	    features =>	{progress=>1},
	};
	sub check_dir {
	    my %args = @_;
	    my $progress = $args{-progress};
	    my $dir = $args{dir};
	    (-d	$dir) or return	[412, "No such dir: $dir"];
	    local $CWD = $dir;
	    opendir my($dh), $dir;
	    my @ent = readdir($dh);
	    $progress->pos(0);
	    $progress->target(~~@ent);
	    for	(@ent) {
		# do the check ...
		$progress->update(message => $_);
		sleep 1;
	    }
	    $progress->finish;
	    [200];
	}
	Perinci::CmdLine->new(url => '/main/check_dir')->run;

DESCRIPTION
       "Progress::Any" is an interface for applications	that want to display
       progress	to users. It decouples progress	updating and output, rather
       similar to how Log::Any decouples log producers and consumers (output).
       The API is also rather similar to Log::Any, except Adapter is called
       Output and category is called task.

       Progress::Any records position/target and calculates elapsed time,
       estimated remaining time, and percentage	of completion. One or more
       output modules (Progress::Any::Output::*) display this information.

       In your modules,	you typically only need	to use Progress::Any, get one
       or more indicators, set target and update it during work. In your
       application, you	use Progress::Any::Output and set/add one or more
       outputs to display the progress.	 By setting output only	in the
       application and not in modules, you separate the	formatting/display
       concern from the	logic.

       Screenshots:

STATUS
       API might still change, will be stabilized in 1.0.

       The list	of features:

       o   multiple progress indicators

	   You can use different indicator for each task/subtask.

       o   customizable	output

	   Output is handled by	one of "Progress::Any::Output::*" modules.
	   Currently available outputs:	"Null" (no output), "TermMessage"
	   (display as simple message on terminal), "TermProgressBarColor"
	   (display as color progress bar on terminal),	"LogAny" (log using
	   Log::Any), "Callback" (call a subroutine).  Other possible output
	   ideas: IM/Twitter/SMS, GUI, web/AJAX, remote/RPC (over Riap for
	   example, so that Perinci::CmdLine-based command-line	clients	can
	   display progress update from	remote functions).

       o   multiple outputs

	   One or more outputs can be used to display one or more indicators.

       o   hierarchical	progress

	   A task can be divided into subtasks.	If a subtask is	updated, its
	   parent task (and its	parent,	and so on) are also updated
	   proportionally.

       o   message

	   Aside from setting a	number/percentage, allow including a message
	   when	updating indicator.

       o   undefined target

	   Target can be undefined, so a bar output might not show any bar (or
	   show	them, but without percentage indicator), but can still show
	   messages.

       o   retargetting

	   Target can be changed in the	middle of things.

EXPORTS
   $progress =>	OBJ
       The root	indicator. Equivalent to:

	Progress::Any->get_indicator(task => '')

ATTRIBUTES
       Below are the attributes	of an indicator/task:

   task
       String. Default:	from caller's package, or "main".

       Task name. If not specified will	be set to caller's package ("::" will
       be replaced with	"."), e.g. if you are calling this method from
       "Foo::Bar::baz()", then task will be set	to "Foo.Bar". If caller	is
       code inside eval, "main"	will be	used instead.

   title
       String. Default:	task name.

       Specify task title. Task	title is a longer description for a task and
       can contain spaces and other characters.	It is displayed	in some
       outputs,	as well	as using %t in "fill_template()". For example, for a
       task called "copy", its title might be "Copying files to	remote
       server".

   target
       Non-negative number. Default: 0.

       The total number	of items to finish. Can	be set to undef	to mean	that
       we don't	know (yet) how many items there	are to finish (in which	case,
       we cannot estimate percent of completion	and remaining time).

   pos
       Non-negative number. Default: 0.

       The number of items that	are already done. It cannot be larger than
       "target", if "target" is	defined. If "target" is	set to a value smaller
       than "pos" or "pos" is set to a value larger than "target", "pos" will
       be changed to be	"target".

   state
       String. Default:	"stopped".

       State of	task/indicator.	Either:	"stopped", "started", or "finished".
       Initially it will be set	to "stopped", which means elapsed time won't
       be running and will stay	at 0. "update()" will set the state to
       "started" to get	elapsed	time to	run. At	the end	of task, you can call
       "finish()" (or alternatively set	"state"	to "finished") to stop the
       elapsed time again.

       The difference between "stopped"	and "finished" is: when	"target" and
       "pos" are both at 0, percent completed is assumed to be 0% when state
       is "stopped", but 100% when state is "finished".

METHODS
   get_indicator
       Usage:

	Progress::Any->get_indicator(%args) => obj

       Get a progress indicator	for a certain task. %args contain attribute
       values, at least	"task" must be specified.

       Note that this module maintains a list of indicator singleton objects
       for each	task (in %indicators package variable),	so subsequent
       "get_indicator()" for the same task will	return the same	object.

   update
       Usage:

	$progress->update(%args)

       Update indicator. Will also, usually, update associated output(s) if
       necessary.

       Arguments:

       o   pos => NUM

	   Set the new position. If unspecified, defaults to current position
	   + 1.	If pos is larger than target, outputs will generally still
	   show	100%. Note that	fractions are allowed.

       o   message => str|code

	   Set a message to be displayed when updating indicator.

	   Aside from a	string,	you can	also pass a coderef here. It can be
	   used	to delay costly	calculation. The message will only be
	   calculated when actually sent to output.

       o   priority => str ("normal"|"low"|"high", default: "normal")

	   Set importance level	of this	update.	Default	is "normal". Output
	   can choose to ignore	updates	lower than a certain level.

       o   state => STR

	   Can be set to "finished" to finish a	task.

       o   force_update	=> BOOL

	   Default false. Some outputs choose only to update themselves	after
	   a certain amount of time or number of updates have passed; this
	   forces their	update.

   finish
       Usage:

	$progress->finish(%args)

       Equivalent to:

	$progress->update(
	    ( pos => $progress->target ) x !!defined($progress->target),
	    state => 'finished',
	    %args,
	);

   reset
       Usage:

	$progress->reset(%args)

       Equivalent to:

	$progress->update(
	    pos	=> 0,
	    state => 'started',
	    %args,
	);

   start
       Usage:

	$progress->start()

       Set state to "started".

   stop
       Usage:

	$progress->stop()

       Set state to "stopped".

   elapsed
       Usage:

	$progress->elapsed() =>	float

       Get elapsed time. Just like a stop-watch, when state is "started"
       elapsed time will run and when state is "stopped", it will freeze.

   remaining
       Usage:

	$progress->remaining() => undef|float

       Give estimated remaining	time until task	is finished, which will	depend
       on how fast the "update()" is called, i.e. how fast "pos" is
       approaching "target".  Will be undef if "target"	is undef.

   total_remaining
       Usage:

	$progress->total_remaining() =>	undef|FLOAT

       Give estimated remaining	time added by all its subtasks'	remaining.
       Return undef if any one of those	time is	undef.

   total_pos
       Usage:

	$progress->total_pos() => float

       Total of	indicator's pos	and all	of its subtasks'.

   total_target
       Usage:

	$progress->total_target() => undef|float

       Total of	indicator's target and all of its subtasks'. Return undef if
       any one of those	is undef.

   percent_complete
       Usage:

	$progress->percent_complete() => undef|float

       Give percentage of completion, calculated using "total_pos /
       total_target * 100". Undef if total_target is undef.

   fill_template
       Usage:

	$progress->fill_template($template) => str

       Fill template with values, like in "sprintf()". Usually used by output
       modules.	 Available templates:

       o   "%(width)n"

	   Task	name (the value	of the "task" attribute). "width" is optional,
	   an integer, like in "sprintf()", can	be negative to mean left-
	   justify instead of right.

       o   "%(width)t"

	   Task	title (the value of the	"title"	attribute).

       o   "%(width)e"

	   Elapsed time	(the result from the "elapsed()" method). Currently
	   using Time::Duration	concise	format,	e.g. 10s, 1m40s, 16m40s, 1d4h,
	   and so on.  Format might be configurable and	localizable in the
	   future. Default width is -8.	 Examples:

	    2m30s
	    10s

       o   "%(width)r"

	   Estimated remaining time (the result	of the "total_remaining()"
	   method).  Currently using Time::Duration concise format, e.g. 10s,
	   1m40s, 16m40s, 1d4h,	and so on. Will	show "?" if unknown. Format
	   might be configurable and localizable in the	future.	Default	width
	   is -8. Examples:

	    1m40s
	    5s

       o   "%(width)R"

	   Estimated remaining time or elapsed time, if	estimated remaining
	   time	is not calculatable (e.g. when target is undefined). Format
	   might be configurable and localizable in the	future.	Default	width
	   is -(8+1+7).	Examples:

	    30s	left
	    1m40s elapsed

       o   "%(width).(prec)p"

	   Percentage of completion (the result	of the "percent_complete()"
	   method).  "width" and "precision" are optional, like	%f in Perl's
	   "sprintf()",	default	is "%3.0p". If percentage is unknown (due to
	   target being	undef),	will show "?".

       o   "%(width)P"

	   Current position (the result	of the "total_pos()" method).

       o   "%(width)T"

	   Target (the result of the "total_target()" method). If undefined,
	   will	show "?".

       o   %m

	   Message (the	"update()" parameter). If message is unspecified, will
	   show	empty string.

       o   "%%"

	   A literal "%" sign.

FAQ
ENVIRONMENT
   PROGRESS
       Boolean.	Default	1. Can be set to 0 to display progress output.

HOMEPAGE
       Please visit the	project's homepage at
       <https://metacpan.org/release/Progress-Any>.

SOURCE
       Source repository is at
       <https://github.com/perlancar/perl-Progress-Any>.

BUGS
       Please report any bugs or feature requests on the bugtracker website
       <https://rt.cpan.org/Public/Dist/Display.html?Name=Progress-Any>

       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.

SEE ALSO
       Progress::Any::Examples distribution contains example scripts.

       Other progress modules on CPAN: Term::ProgressBar,
       Term::ProgressBar::Simple, Time::Progress, among	others.

       Output modules: "Progress::Any::Output::*"

       See examples on how Progress::Any is used by other modules:
       Perinci::CmdLine	(supplying progress object to functions), Git::Bunch
       (using progress object).

AUTHOR
       perlancar <perlancar@cpan.org>

COPYRIGHT AND LICENSE
       This software is	copyright (c) 2020, 2018, 2015,	2014, 2013, 2012 by
       perlancar@cpan.org.

       This is free software; you can redistribute it and/or modify it under
       the same	terms as the Perl 5 programming	language system	itself.

perl v5.32.0			  2020-08-15		      Progress::Any(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | STATUS | EXPORTS | ATTRIBUTES | METHODS | FAQ | ENVIRONMENT | HOMEPAGE | SOURCE | BUGS | SEE ALSO | AUTHOR | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Progress::Any&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help