Debian Codegraph @

README

raw
1 NAME
2 Progress::Any - Record progress to any output
3
4 VERSION
5 This document describes version 0.220 of Progress::Any (from Perl
6 distribution Progress-Any), released on 2022-10-18.
7
8 SYNOPSIS
9 Example of using in a script with terminal progress bar as output
10 (progress bar will be cleared on "finish()") (you'll need to install
11 Progress::Any::Output::TermProgressBarColor as well):
12
13 use Progress::Any '$progress';
14 use Progress::Any::Output 'TermProgressBarColor';
15
16 $progress->target(10);
17 for (1..10) {
18 $progress->update(message => "Doing item $_");
19 sleep 1;
20 }
21 $progress->finish();
22
23 Sample output:
24
25 % ./script.pl
26 60% [Doing item 6==== ]3s left
27
28 Another example, this time with terminal message as output:
29
30 use Progress::Any '$progress';
31 use Progress::Any::Output 'TermMessage', template => '[%n] %P/%T (%6.2p%%) %m';
32
33 $progress->target(10);
34 for (1..10) {
35 $progress->update(message => "Item $_/10");
36 sleep 1;
37 }
38 sleep 1;
39 $progress->finish(message => "Finished!");
40
41 Sample output:
42
43 % ./script.pl
44 [] 1/10 ( 10.00%) Item 1/10
45 [] 2/10 ( 20.00%) Item 2/10
46 ...
47 [] 10/10 (100.00%) Item 10/10
48 [] 10/10 (100.00%) Finished!
49
50 Example of using in a module as well as script:
51
52 # in lib/MyApp.pm
53 package MyApp;
54 use Progress::Any;
55
56 sub download {
57 my @urls = @_;
58 return unless @urls;
59 my $progress = Progress::Any->get_indicator(
60 task => "download", pos=>0, target=>scalar @urls);
61 for my $url (@urls) {
62 # download the $url ...
63 $progress->update(message => "Downloaded $url");
64 }
65 $progress->finish;
66 }
67
68 # in script.pl
69 use MyApp;
70 use Progress::Any::Output;
71 Progress::Any::Output->set('TermProgressBarColor');
72
73 MyApp::download("url1", "url2", "url3", "url4", "url5");
74
75 Sample output:
76
77 % ./script.pl
78 20% [====== Downloaded url1 ]0m00s Left
79
80 Example that demonstrates multiple indicator objects:
81
82 use Progress::Any;
83 use Progress::Any::Output;
84
85 my $pdl = Progress::Any->get_indicator(task => 'download');
86 Progress::Any::Output->set({task=>'download'}, 'TermMessage', template => '[%-8t] [%P/%2T] %m');
87 my $pcp = Progress::Any->get_indicator(task => 'copy');
88 Progress::Any::Output->set({task=>'copy' }, 'TermMessage', template => '[%-8t] [%P/%2T] %m');
89
90 $pdl->target(10);
91 $pdl->update(message => "downloading A");
92 $pcp->update(message => "copying A");
93 sleep 1;
94 $pdl->update(message => "downloading B");
95 $pcp->update(message => "copying B");
96
97 will show something like:
98
99 [download] [1/10] downloading A
100 [copy ] [1/ ?] copying A
101 [download] [2/10] downloading B
102 [copy ] [2/ ?] copying B
103
104 Example of using with Perinci::CmdLine
105 If you use Perinci::CmdLine, you can mark your function as expecting a
106 Progress::Any object and it will be supplied to you in a special
107 argument "-progress":
108
109 use File::chdir;
110 use Perinci::CmdLine;
111 $SPEC{check_dir} = {
112 v => 1.1,
113 args => {
114 dir => {summary=>"Path to check", schema=>"str*", req=>1, pos=>0},
115 },
116 features => {progress=>1},
117 };
118 sub check_dir {
119 my %args = @_;
120 my $progress = $args{-progress};
121 my $dir = $args{dir};
122 (-d $dir) or return [412, "No such dir: $dir"];
123 local $CWD = $dir;
124 opendir my($dh), $dir;
125 my @ent = readdir($dh);
126 $progress->pos(0);
127 $progress->target(scalar @ent);
128 for (@ent) {
129 # do the check ...
130 $progress->update(message => $_);
131 sleep 1;
132 }
133 $progress->finish;
134 [200];
135 }
136 Perinci::CmdLine->new(url => '/main/check_dir')->run;
137
138 DESCRIPTION
139 "Progress::Any" is an interface for applications that want to display
140 progress to users. It decouples progress updating and output, rather
141 similar to how Log::Any decouples log producers and consumers (output).
142 The API is also rather similar to Log::Any, except *Adapter* is called
143 *Output* and *category* is called *task*.
144
145 Progress::Any records position/target and calculates elapsed time,
146 estimated remaining time, and percentage of completion. One or more
147 output modules (Progress::Any::Output::*) display this information.
148
149 In your modules, you typically only need to use Progress::Any, get one
150 or more indicators, set target and update it during work. In your
151 application, you use Progress::Any::Output and set/add one or more
152 outputs to display the progress (you'll need to install one of the
153 output modules as they are not included in this minimal distribution).
154 By setting output only in the application and not in modules, you
155 separate the formatting/display concern from the logic.
156
157 Screenshots:
158
159 STATUS
160 API might still change, will be stabilized in 1.0.
161
162 The list of features:
163
164 * multiple progress indicators
165
166 You can use different indicator for each task/subtask.
167
168 * customizable output
169
170 Output is handled by one of "Progress::Any::Output::*" modules.
171 Currently available outputs: "Null" (no output), "TermMessage"
172 (display as simple message on terminal), "TermProgressBarColor"
173 (display as color progress bar on terminal), "LogAny" (log using
174 Log::Any), "Callback" (call a subroutine). Other possible output
175 ideas: IM/Twitter/SMS, GUI, web/AJAX, remote/RPC (over Riap for
176 example, so that Perinci::CmdLine-based command-line clients can
177 display progress update from remote functions).
178
179 * multiple outputs
180
181 One or more outputs can be used to display one or more indicators.
182
183 * hierarchical progress
184
185 A task can be divided into subtasks. If a subtask is updated, its
186 parent task (and its parent, and so on) are also updated
187 proportionally.
188
189 * message
190
191 Aside from setting a number/percentage, allow including a message
192 when updating indicator.
193
194 * undefined target
195
196 Target can be undefined, so a bar output might not show any bar (or
197 show them, but without percentage indicator), but can still show
198 messages.
199
200 * retargetting
201
202 Target can be changed in the middle of things.
203
204 EXPORTS
205 $progress => OBJ
206 The root indicator. Equivalent to:
207
208 Progress::Any->get_indicator(task => '')
209
210 ATTRIBUTES
211 Below are the attributes of an indicator/task:
212
213 task
214 String. Default: from caller's package, or "main".
215
216 Task name. If not specified will be set to caller's package ("::" will
217 be replaced with "."), e.g. if you are calling this method from
218 "Foo::Bar::baz()", then task will be set to "Foo.Bar". If caller is code
219 inside eval, "main" will be used instead.
220
221 title
222 String. Default: task name.
223
224 Specify task title. Task title is a longer description for a task and
225 can contain spaces and other characters. It is displayed in some
226 outputs, as well as using %t in "fill_template()". For example, for a
227 task called "copy", its title might be "Copying files to remote server".
228
229 target
230 Non-negative number. Default: 0.
231
232 The total number of items to finish. Can be set to undef to mean that we
233 don't know (yet) how many items there are to finish (in which case, we
234 cannot estimate percent of completion and remaining time).
235
236 pos
237 Non-negative number. Default: 0.
238
239 The number of items that are already done. It cannot be larger than
240 "target", if "target" is defined. If "target" is set to a value smaller
241 than "pos" or "pos" is set to a value larger than "target", "pos" will
242 be changed to be "target".
243
244 state
245 String. Default: "stopped".
246
247 State of task/indicator. Either: "stopped", "started", or "finished".
248 Initially it will be set to "stopped", which means elapsed time won't be
249 running and will stay at 0. "update()" will set the state to "started"
250 to get elapsed time to run. At the end of task, you can call "finish()"
251 (or alternatively set "state" to "finished") to stop the elapsed time
252 again.
253
254 The difference between "stopped" and "finished" is: when "target" and
255 "pos" are both at 0, percent completed is assumed to be 0% when state is
256 "stopped", but 100% when state is "finished".
257
258 METHODS
259 get_indicator
260 Usage:
261
262 Progress::Any->get_indicator(%args) => obj
263
264 Get a progress indicator for a certain task. %args contain attribute
265 values, at least "task" must be specified.
266
267 Note that this module maintains a list of indicator singleton objects
268 for each task (in %indicators package variable), so subsequent
269 "get_indicator()" for the same task will return the same object.
270
271 update
272 Usage:
273
274 $progress->update(%args)
275
276 Update indicator. Will also, usually, update associated output(s) if
277 necessary.
278
279 Arguments:
280
281 * pos => NUM
282
283 Set the new position. If unspecified, defaults to current position +
284 1. If pos is larger than target, outputs will generally still show
285 100%. Note that fractions are allowed.
286
287 * message => str|code
288
289 Set a message to be displayed when updating indicator.
290
291 Aside from a string, you can also pass a coderef here. It can be
292 used to delay costly calculation. The message will only be
293 calculated when actually sent to output.
294
295 * priority => str ("normal"|"low"|"high", default: "normal")
296
297 Set importance level of this update. Default is "normal". Output can
298 choose to ignore updates lower than a certain level.
299
300 * state => STR
301
302 Can be set to "finished" to finish a task.
303
304 * force_update => BOOL
305
306 Default false. Some outputs choose only to update themselves after a
307 certain amount of time or number of updates have passed; this forces
308 their update.
309
310 finish
311 Usage:
312
313 $progress->finish(%args)
314
315 Equivalent to:
316
317 $progress->update(
318 ( pos => $progress->target ) x !!defined($progress->target),
319 state => 'finished',
320 %args,
321 );
322
323 reset
324 Usage:
325
326 $progress->reset(%args)
327
328 Equivalent to:
329
330 $progress->update(
331 pos => 0,
332 state => 'started',
333 %args,
334 );
335
336 start
337 Usage:
338
339 $progress->start()
340
341 Set state to "started".
342
343 stop
344 Usage:
345
346 $progress->stop()
347
348 Set state to "stopped".
349
350 elapsed
351 Usage:
352
353 $progress->elapsed() => float
354
355 Get elapsed time. Just like a stop-watch, when state is "started"
356 elapsed time will run and when state is "stopped", it will freeze.
357
358 remaining
359 Usage:
360
361 $progress->remaining() => undef|float
362
363 Give estimated remaining time until task is finished, which will depend
364 on how fast the "update()" is called, i.e. how fast "pos" is approaching
365 "target". Will be undef if "target" is undef.
366
367 total_remaining
368 Usage:
369
370 $progress->total_remaining() => undef|FLOAT
371
372 Give estimated remaining time added by all its subtasks' remaining.
373 Return undef if any one of those time is undef.
374
375 total_pos
376 Usage:
377
378 $progress->total_pos() => float
379
380 Total of indicator's pos and all of its subtasks'.
381
382 total_target
383 Usage:
384
385 $progress->total_target() => undef|float
386
387 Total of indicator's target and all of its subtasks'. Return undef if
388 any one of those is undef.
389
390 percent_complete
391 Usage:
392
393 $progress->percent_complete() => undef|float
394
395 Give percentage of completion, calculated using "total_pos /
396 total_target * 100". Undef if total_target is undef.
397
398 fill_template
399 Usage:
400
401 $progress->fill_template($template) => str
402
403 Fill template with values, like in "sprintf()". Usually used by output
404 modules. Available templates:
405
406 * "%(width)n"
407
408 Task name (the value of the "task" attribute). "width" is optional,
409 an integer, like in "sprintf()", can be negative to mean
410 left-justify instead of right.
411
412 * "%(width)t"
413
414 Task title (the value of the "title" attribute).
415
416 * "%(width)e"
417
418 Elapsed time (the result from the "elapsed()" method). Currently
419 using Time::Duration concise format, e.g. 10s, 1m40s, 16m40s, 1d4h,
420 and so on. Format might be configurable and localizable in the
421 future. Default width is -8. Examples:
422
423 2m30s
424 10s
425
426 * "%(width)r"
427
428 Estimated remaining time (the result of the "total_remaining()"
429 method). Currently using Time::Duration concise format, e.g. 10s,
430 1m40s, 16m40s, 1d4h, and so on. Will show "?" if unknown. Format
431 might be configurable and localizable in the future. Default width
432 is -8. Examples:
433
434 1m40s
435 5s
436
437 * "%(width)R"
438
439 Estimated remaining time *or* elapsed time, if estimated remaining
440 time is not calculatable (e.g. when target is undefined). Format
441 might be configurable and localizable in the future. Default width
442 is -(8+1+7). Examples:
443
444 30s left
445 1m40s elapsed
446
447 * "%(width).(prec)p"
448
449 Percentage of completion (the result of the "percent_complete()"
450 method). "width" and "precision" are optional, like %f in Perl's
451 "sprintf()", default is "%3.0p". If percentage is unknown (due to
452 target being undef), will show "?".
453
454 * "%(width)P"
455
456 Current position (the result of the "total_pos()" method).
457
458 * "%(width)T"
459
460 Target (the result of the "total_target()" method). If undefined,
461 will show "?".
462
463 * %m
464
465 Message (the "update()" parameter). If message is unspecified, will
466 show empty string.
467
468 * "%%"
469
470 A literal "%" sign.
471
472 FAQ
473 ENVIRONMENT
474 PROGRESS
475 Boolean. Default 1. Can be set to 0 to supress display progress output.
476
477 HOMEPAGE
478 Please visit the project's homepage at
479 <https://metacpan.org/release/Progress-Any>.
480
481 SOURCE
482 Source repository is at
483 <https://github.com/perlancar/perl-Progress-Any>.
484
485 SEE ALSO
486 Progress::Any::Examples distribution contains example scripts.
487
488 Other progress modules on CPAN: Term::ProgressBar,
489 Term::ProgressBar::Simple, Time::Progress, among others.
490
491 Output modules: "Progress::Any::Output::*". You need to install at least
492 one module to actually see progress being outputted/displayed somewhere,
493 e.g. <> to Progress::Any::Output::TermProgressBarColor.
494
495 See examples on how Progress::Any is used by other modules:
496 Perinci::CmdLine (supplying progress object to functions), Git::Bunch
497 (using progress object).
498
499 AUTHOR
500 perlancar <[email protected]>
501
502 CONTRIBUTOR
503 Steven Haryanto <[email protected]>
504
505 CONTRIBUTING
506 To contribute, you can send patches by email/via RT, or send pull
507 requests on GitHub.
508
509 Most of the time, you don't need to build the distribution yourself. You
510 can simply modify the code, then test via:
511
512 % prove -l
513
514 If you want to build the distribution (e.g. to try to install it locally
515 on your system), you can install Dist::Zilla,
516 Dist::Zilla::PluginBundle::Author::PERLANCAR,
517 Pod::Weaver::PluginBundle::Author::PERLANCAR, and sometimes one or two
518 other Dist::Zilla- and/or Pod::Weaver plugins. Any additional steps
519 required beyond that are considered a bug and can be reported to me.
520
521 COPYRIGHT AND LICENSE
522 This software is copyright (c) 2022, 2020, 2018, 2015, 2014, 2013, 2012
523 by perlancar <[email protected]>.
524
525 This is free software; you can redistribute it and/or modify it under
526 the same terms as the Perl 5 programming language system itself.
527
528 BUGS
529 Please report any bugs or feature requests on the bugtracker website
530 <https://rt.cpan.org/Public/Dist/Display.html?Name=Progress-Any>
531
532 When submitting a bug or request, please include a test-file or a patch
533 to an existing test-file that illustrates the bug or desired feature.
534