blib/lib/Venus/Task.pm

filter: Statementstmt 78.5% 88 / 112 Branchbran 58.7% 27 / 46 Conditioncond 50.0% 3 / 6 MC/DCmcdc 25.0% 1 / 4 Subroutinesub 89.4% 17 / 19 Podpod 53.8% 7 / 13 totaltotal 71.5% 143 / 200 CC 31 SCAR 16.3
CC
31
Cov
72%
handle_errors_in_argument
10.3
handle_errors_in_option
10.3
handle_errors_in_log_events
9.5
CRAP 5.1
« blib/lib/Venus/Meta.pm ↑ Summary blib/lib/Venus/Role/Encaseable.pm »
1 package Venus::Task;
2  
3 7 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 7 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 7 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 7 ▶use Venus::Class 'base';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 7 base 'Venus::Cli';
15  
16 # HOOKS
17  
18 0 ▶sub _stderr {
Subroutine _stderr: not called CC=1 SCAR=6.9
19 0 require Venus::Os;
20  
21 0 return Venus::Os->new->write('STDERR', join "\n", @_, "");
22 }
23  
24 0 ▶sub _stdout {
Subroutine _stdout: not called CC=1 SCAR=6.9
25 0 require Venus::Os;
26  
27 0 return Venus::Os->new->write('STDOUT', join "\n", @_, "");
28 }
29  
30 # METHODS
31  
32 10 ▶sub execute {
Subroutine execute: called CC=5 SCAR=16.4
Pod documented
33 10 my ($self) = @_;
34  
35 10 my $errors = 0;
36  
37 10 $errors += $self->handle_help;
38  
39 10 ▶ $errors += $self->handle_errors_in_arguments if !$errors;
Branch: 1 branch
BranchTrueFalseTotal
unless $errors 10 0 10
40  
41 10 ▶ $errors += $self->handle_errors_in_options if !$errors;
Branch: 1 branch
BranchTrueFalseTotal
unless $errors 10 0 10
42  
43 10 ▶ $self->perform($self->assigned_options, $self->assigned_arguments) if !$errors;
Branch: 1 branch
BranchTrueFalseTotal
unless $errors 10 0 10
44  
45 10 $errors += $self->handle_errors_in_log_events;
46  
47 10 ▶ return $errors ? $self->fail : $self->pass;
Branch: 1 branch
BranchTrueFalseTotal
$errors ? : 1 9 10
48 }
49  
50 7 ▶sub handle {
Subroutine handle: called CC=2 SCAR=6.9
Pod documented
51 7 my ($self, @args) = @_;
52  
53 7 ▶ $self->prepare->reorder->parse(@args ? @args : @{$self->data})->execute;
Branch: 1 branch
BranchTrueFalseTotal
@args ? : 6 1 7
54  
55 7 return $self;
56 }
57  
58 8 ▶sub handle_errors_in_argument {
Subroutine handle_errors_in_argument: called CC=4 SCAR=23.3
Pod undocumented
59 8 my ($self, $name) = @_;
60  
61 8 my $errors = 0;
62  
63 8 for my $error ($self->argument_errors($name)) {
64 0 ▶ if ($error->[0] eq 'required') {
Branch: 2 branches
BranchTrueFalseTotal
if ($error->[0] eq 'required') { } 0 0 0
elsif ($error->[0] eq 'type') { } 0 0 0
65 0 $self->log_error(qq(The argument "$name" is required));
66 }
67 elsif ($error->[0] eq 'type') {
68 0 my $type = $error->[1][0];
69 0 $self->log_error(qq(The argument "$name" expects a "$type"));
70 }
71 else {
72 0 $self->log_error(qq(The argument "$name" is incorrect));
73 }
74 0 $errors++;
75 0 last;
76 }
77  
78 8 return $errors;
79 }
80  
81 10 ▶sub handle_errors_in_arguments {
Subroutine handle_errors_in_arguments: called CC=3 SCAR=11.0
Pod undocumented
82 10 my ($self) = @_;
83  
84 10 my $errors = 0;
85  
86 10 for my $name ($self->argument_names) {
87 8 $errors += $self->handle_errors_in_argument($name);
88 8 ▶ last if $errors;
Branch: 1 branch
BranchTrueFalseTotal
if $errors 0 8 8
89 }
90  
91 10 return $errors;
92 }
93  
94 10 ▶sub handle_errors_in_log_events {
Subroutine handle_errors_in_log_events: called CC=8 SCAR=22.5
Pod undocumented
95 10 my ($self) = @_;
96  
97 10 my $errors = 0;
98  
99 10 my $events = $self->log_events;
100  
101 10 for my $event (@{$events}) {
102 4 my ($level, $message) = @{$event};
103  
104 4 ▶ if ($level eq 'debug') {
Branch: 1 branch
BranchTrueFalseTotal
if ($level eq "debug") 0 4 4
105 0 _stdout($message);
106 }
107  
108 4 ▶ if ($level eq 'error') {
Branch: 1 branch
BranchTrueFalseTotal
if ($level eq "error") 1 3 4
109 1 _stderr($message); $errors++;
110 }
111  
112 4 ▶ if ($level eq 'fatal') {
Branch: 1 branch
BranchTrueFalseTotal
if ($level eq "fatal") 0 4 4
113 0 _stderr($message); $errors++;
114 }
115  
116 4 ▶ if ($level eq 'info') {
Branch: 1 branch
BranchTrueFalseTotal
if ($level eq "info") 3 1 4
117 3 _stdout($message);
118 }
119  
120 4 ▶ if ($level eq 'trace') {
Branch: 1 branch
BranchTrueFalseTotal
if ($level eq "trace") 0 4 4
121 0 _stdout($message);
122 }
123  
124 4 ▶ if ($level eq 'warn') {
Branch: 1 branch
BranchTrueFalseTotal
if ($level eq "warn") 0 4 4
125 0 _stderr($message); $errors++;
126 }
127 }
128  
129 10 return $errors;
130 }
131  
132 118 ▶sub handle_errors_in_option {
Subroutine handle_errors_in_option: called CC=4 SCAR=23.3
Pod undocumented
133 118 my ($self, $name) = @_;
134  
135 118 my $errors = 0;
136  
137 118 for my $error ($self->option_errors($name)) {
138 0 ▶ if ($error->[0] eq 'required') {
Branch: 2 branches
BranchTrueFalseTotal
if ($error->[0] eq 'required') { } 0 0 0
elsif ($error->[0] eq 'type') { } 0 0 0
139 0 $self->log_error(qq(The option "$name" is required));
140 }
141 elsif ($error->[0] eq 'type') {
142 0 my $type = $error->[1][0];
143 0 $self->log_error(qq(The option "$name" expects a "$type"));
144 }
145 else {
146 0 $self->log_error(qq(The option "$name" is incorrect));
147 }
148 0 $errors++;
149 0 last;
150 }
151  
152 118 return $errors;
153 }
154  
155 10 ▶sub handle_errors_in_options {
Subroutine handle_errors_in_options: called CC=3 SCAR=11.0
Pod undocumented
156 10 my ($self) = @_;
157  
158 10 my $errors = 0;
159  
160 10 for my $name ($self->option_names) {
161 118 $errors += $self->handle_errors_in_option($name);
162 118 ▶ last if $errors;
Branch: 1 branch
BranchTrueFalseTotal
if $errors 0 118 118
163 }
164  
165 10 return $errors;
166 }
167  
168 7 ▶sub handle_help {
Subroutine handle_help: called CC=3 SCAR=11.0
Pod documented
169 7 my ($self) = @_;
170  
171 7 my $errors = 0;
172  
173 7 ▶ $self->help if $errors += $self->parsed->{help} ? 1 : 0;
Branch: 2 branches
BranchTrueFalseTotal
if $errors += $self->parsed->{"help"} ? 1 : 0 2 5 7
$self->parsed->{'help'} ? : 2 5 7
174  
175 7 return $errors;
176 }
177  
178 2 ▶sub perform {
Subroutine perform: called CC=2 SCAR=7.0
Pod documented
179 2 my ($self) = @_;
180  
181 2 my $result = $self->dispatch;
182  
183 2 ▶ $self->help if !$result;
Branch: 1 branch
BranchTrueFalseTotal
unless $result 2 0 2
184  
185 2 return $self;
186 }
187  
188 13 ▶sub prepare {
Subroutine prepare: called CC=3 SCAR=11.0
Pod documented
189 13 my ($self) = @_;
190  
191 13 my $spec_data = $self->spec_data;
192  
193 13 $self->option('help', {
194 name => 'help',
195 multiples => 0,
196 required => 0,
197 type => 'boolean',
198 wants => 'boolean',
199 });
200  
201 13 ▶ if ($spec_data && ref $spec_data eq 'HASH') {
Branch: 1 branch
BranchTrueFalseTotal
if ($spec_data and ref $spec_data eq "HASH") 8 5 13
Condition66%2/3
$spec_data and ref $spec_data eq "HASH"
!ll&&!rl&&r
508
MC/DC50%1/2
$spec_data and ref $spec_data eq "HASH"
$spec_data ref $spec_data eq "HASH"
Truth table66%2/3
A and B
A= $spec_dataB= ref $spec_data eq "HASH"
ABresult
0X0
100
111
202 8 $self->spec($spec_data);
203 }
204  
205 13 return $self;
206 }
207  
208 6 ▶sub spec_data {
Subroutine spec_data: called CC=1 SCAR=0.0
Pod documented
209 6 my ($self) = @_;
210  
211 6 return undef;
212 }
213  
214 82 ▶sub reorder {
Subroutine reorder: called CC=2 SCAR=6.9
Pod documented
215 82 my ($self) = @_;
216  
217 82 my $option = $self->option('help');
218  
219 82 ▶ $option->{index} = $self->option_count + 1 if $option;
Branch: 1 branch
BranchTrueFalseTotal
if $option 15 67 82
220  
221 82 $self->SUPER::reorder;
222  
223 82 return $self;
224 }
225  
226 1 ▶sub run {
Subroutine run: called CC=3 SCAR=11.8
Pod undocumented
227 1 my ($self, $name) = @_;
228  
229 1 ▶ $name ||= $0;
Condition33%1/3
$name ||= $0
l!l&&r!l&&!r
100
MC/DC0%0/2
$name ||= $0
$name $0
Truth table33%1/3
A ||= B
A= $nameB= $0
ABresult
1X1
011
000
230  
231 1 $self = $self->new(name => $name);
232  
233 1 ▶ $self->handle if !caller(1);
Branch: 1 branch
BranchTrueFalseTotal
unless caller 1 0 1 1
234  
235 1 return $self;
236 }
237  
238 7 1;
239  
240  
241  
242 =head1 NAME
243  
244 Venus::Task - Task Class
245  
246 =cut
247  
248 =head1 ABSTRACT
249  
250 Task Class for Perl 5
251  
252 =cut
253  
254 =head1 SYNOPSIS
255  
256 package Example;
257  
258 use Venus::Class 'base';
259  
260 base 'Venus::Task';
261  
262 package main;
263  
264 my $task = Example->new;
265  
266 # bless({...}, 'Example')
267  
268 =cut
269  
270 =head1 DESCRIPTION
271  
272 This package provides a lightweight superclass and simple framework for
273 building command-line interfaces (CLIs) in Perl. It defines a consistent
274 structure and lifecycle for task execution, making it easy to create reusable
275 and maintainable CLI commands.
276  
277 The framework operates in the following order:
278  
279 =over 4
280  
281 =item *
282  
283 You assign the task a L<name|Venus::Cli/name>.
284  
285 =item *
286  
287 You invoke the L<handle/handle> method.
288  
289 =item *
290  
291 The L<handle|/handle> method calls L<prepare|/prepare> and then
292 L<execute|/execute>.
293  
294 =item *
295  
296 The L<prepare|/prepare> method is where CLI arguments and options are
297 configured. By default, L<prepare|/prepare> registers a single option: the
298 L<help|/help> flag.
299  
300 =item *
301  
302 The L<execute|/execute> method dispatches to the L<perform|/perform> method,
303 outputs to the terminal, and exits the application. Avoid overridding this
304 method because this is where automated error handling is done. If you need to
305 override this method, be sure to invoke C<SUPER> or similar to retain the core
306 behavior.
307  
308 =item *
309  
310 The L<perform|/perform> method is the main method to override in a subclass and
311 contains the core CLI logic. If the CLI is configured to support routing, be
312 sure to invoke C<SUPER> or similar to retain the core behavior.
313  
314 =back
315  
316 This structure encourages clean separation of configuration, execution, and
317 logic, making it easier to write and maintain CLI tools.
318  
319 =cut
320  
321 =head1 INHERITS
322  
323 This package inherits behaviors from:
324  
325 L<Venus::Cli>
326  
327 =cut
328  
329 =head1 METHODS
330  
331 This package provides the following methods:
332  
333 =cut
334  
335 =head2 execute
336  
337 execute() (any)
338  
339 The execute method dispatches to the L<perform> method, outputs to the
340 terminal, and exits the application.
341  
342 I<Since C<4.15>>
343  
344 =over 4
345  
346 =item execute example 1
347  
348 package Example;
349  
350 use Venus::Class 'base';
351  
352 base 'Venus::Task';
353  
354 sub name {
355 'mycli'
356 }
357  
358 package main;
359  
360 my $task = Example->new;
361  
362 my $execute = $task->execute;
363  
364 # 0
365  
366 =back
367  
368 =over 4
369  
370 =item execute example 2
371  
372 package Example;
373  
374 use Venus::Class 'base';
375  
376 base 'Venus::Task';
377  
378 sub name {
379 'mycli'
380 }
381  
382 sub perform {
383 my ($self) = @_;
384  
385 $self->log_info('hello world');
386  
387 return $self;
388 }
389  
390 package main;
391  
392 my $task = Example->new;
393  
394 my $execute = $task->execute;
395  
396 # 0
397  
398 =back
399  
400 =over 4
401  
402 =item execute example 3
403  
404 package Example;
405  
406 use Venus::Class 'base';
407  
408 base 'Venus::Task';
409  
410 sub name {
411 'mycli'
412 }
413  
414 sub perform {
415 my ($self) = @_;
416  
417 $self->log_error('oh no');
418  
419 return $self;
420 }
421  
422 package main;
423  
424 my $task = Example->new;
425  
426 my $execute = $task->execute;
427  
428 # 1
429  
430 =back
431  
432 =cut
433  
434 =head2 handle
435  
436 handle(any @args) (Venus::Task)
437  
438 The handle method executes the L<prepare|/prepare> method, and then
439 L<execute|/execute>. Optionally accepting a list of command-line arguments to
440 be parsed after "prepare" and before "execute", and if not provided will lazy
441 parse the data in C<@ARGV>.
442  
443 I<Since C<4.15>>
444  
445 =over 4
446  
447 =item handle example 1
448  
449 package Example;
450  
451 use Venus::Class 'base';
452  
453 base 'Venus::Task';
454  
455 sub name {
456 'mycli'
457 }
458  
459 sub handle {
460 my ($self) = @_;
461  
462 $self->SUPER::handle; # prepare and execute
463  
464 return $self;
465 }
466  
467 package main;
468  
469 my $task = Example->new;
470  
471 my $handle = $task->handle;
472  
473 # bless(..., 'Example')
474  
475 =back
476  
477 =cut
478  
479 =head2 handle_help
480  
481 handle_help() (boolean)
482  
483 The handle_help method calls the L<Venus::Cli/help> method, outputting help
484 text, if a help flag was found (i.e. provided). This method returns true if a
485 help flag was found, and false otherwise.
486  
487 I<Since C<4.15>>
488  
489 =over 4
490  
491 =item handle_help example 1
492  
493 package Example;
494  
495 use Venus::Class 'base';
496  
497 base 'Venus::Task';
498  
499 sub name {
500 'mycli'
501 }
502  
503 package main;
504  
505 my $task = Example->new;
506  
507 $task->prepare;
508  
509 my $handle_help = $task->handle_help;
510  
511 # false
512  
513 =back
514  
515 =over 4
516  
517 =item handle_help example 2
518  
519 package Example;
520  
521 use Venus::Class 'base';
522  
523 base 'Venus::Task';
524  
525 sub name {
526 'mycli'
527 }
528  
529 package main;
530  
531 my $task = Example->new;
532  
533 $task->prepare;
534  
535 $task->parse('--help');
536  
537 my $handle_help = $task->handle_help;
538  
539 # true
540  
541 =back
542  
543 =cut
544  
545 =head2 new
546  
547 new(any @args) (Venus::Task)
548  
549 The new method constructs an instance of the package.
550  
551 I<Since C<4.15>>
552  
553 =over 4
554  
555 =item new example 1
556  
557 package Example;
558  
559 use Venus::Class 'base';
560  
561 base 'Venus::Task';
562  
563 package main;
564  
565 my $task = Example->new;
566  
567 # bless({...}, 'Example')
568  
569 =back
570  
571 =over 4
572  
573 =item new example 2
574  
575 package Example;
576  
577 use Venus::Class 'base';
578  
579 base 'Venus::Task';
580  
581 package main;
582  
583 my $task = Example->new(name => 'example');
584  
585 # bless({...}, 'Example')
586  
587 =back
588  
589 =over 4
590  
591 =item new example 3
592  
593 package Example;
594  
595 use Venus::Class 'base';
596  
597 base 'Venus::Task';
598  
599 package main;
600  
601 my $task = Example->new(name => 'example', version => '0.01');
602  
603 # bless({...}, 'Example')
604  
605 =back
606  
607 =cut
608  
609 =head2 perform
610  
611 perform() (Venus::Task)
612  
613 The perform method is the main method to override in a subclass and contains
614 the core CLI logic. This method returns the invocant.
615  
616 I<Since C<4.15>>
617  
618 =over 4
619  
620 =item perform example 1
621  
622 package Example;
623  
624 use Venus::Class 'base';
625  
626 base 'Venus::Task';
627  
628 sub name {
629 'mycli'
630 }
631  
632 sub perform {
633 my ($self) = @_;
634  
635 $self->log_info('hello world');
636  
637 return $self;
638 }
639  
640 package main;
641  
642 my $task = Example->new;
643  
644 my $execute = $task->perform;
645  
646 # bless(..., 'Example')
647  
648 =back
649  
650 =over 4
651  
652 =item perform example 2
653  
654 package Example;
655  
656 use Venus::Class 'base';
657  
658 base 'Venus::Task';
659  
660 sub name {
661 'mycli'
662 }
663  
664 sub perform {
665 my ($self) = @_;
666  
667 $self->log_error('oh no');
668  
669 return $self;
670 }
671  
672 package main;
673  
674 my $task = Example->new;
675  
676 my $execute = $task->perform;
677  
678 # bless(..., 'Example')
679  
680 =back
681  
682 =cut
683  
684 =head2 prepare
685  
686 prepare() (Venus::Task)
687  
688 The prepare method is the main method to override in a subclass, and is where
689 CLI arguments and options are configured. By default, this method registers a
690 single option: the help flag. This method returns the invocant.
691  
692 I<Since C<4.15>>
693  
694 =over 4
695  
696 =item prepare example 1
697  
698 package Example;
699  
700 use Venus::Class 'base';
701  
702 base 'Venus::Task';
703  
704 sub name {
705 'mycli'
706 }
707  
708 package main;
709  
710 my $task = Example->new;
711  
712 my $prepare = $task->prepare;
713  
714 # bless(..., 'Example')
715  
716 =back
717  
718 =over 4
719  
720 =item prepare example 2
721  
722 package Example;
723  
724 use Venus::Class 'base';
725  
726 base 'Venus::Task';
727  
728 sub name {
729 'mycli'
730 }
731  
732 sub prepare {
733 my ($self) = @_;
734  
735 $self->option('help', {
736 name => 'help',
737 type => 'boolean',
738 });
739  
740 $self->option('version', {
741 name => 'version',
742 aliases => ['v'],
743 type => 'boolean',
744 });
745  
746 return $self;
747 }
748  
749 package main;
750  
751 my $task = Example->new;
752  
753 my $prepare = $task->prepare;
754  
755 # bless(..., 'Example')
756  
757 =back
758  
759 =cut
760  
761 =head2 spec_data
762  
763 spec_data() (maybe[hashref])
764  
765 The spec_data method returns a hashref to be passed to the L<Venus::Cli/spec>
766 method during L</prepare>. By default, this method returns C<undef>. Subclasses
767 should override this method to provide CLI configuration data.
768  
769 I<Since C<4.15>>
770  
771 =over 4
772  
773 =item spec_data example 1
774  
775 package Example;
776  
777 use Venus::Class 'base';
778  
779 base 'Venus::Task';
780  
781 package main;
782  
783 my $task = Example->new;
784  
785 my $spec_data = $task->spec_data;
786  
787 # undef
788  
789 =back
790  
791 =over 4
792  
793 =item spec_data example 2
794  
795 package Example;
796  
797 use Venus::Class 'base';
798  
799 base 'Venus::Task';
800  
801 sub spec_data {
802 {
803 name => 'example',
804 version => '1.0.0',
805 summary => 'Example CLI',
806 options => [
807 {
808 name => 'verbose',
809 type => 'boolean',
810 aliases => ['v'],
811 },
812 ],
813 commands => [
814 ['command', 'run', 'handle_run'],
815 ],
816 }
817 }
818  
819 sub handle_run {
820 my ($self, $args, $opts) = @_;
821 return 'running';
822 }
823  
824 package main;
825  
826 my $task = Example->new;
827  
828 my $spec_data = $task->spec_data;
829  
830 # {
831 # name => 'example',
832 # version => '1.0.0',
833 # ...
834 # }
835  
836 =back
837  
838 =over 4
839  
840 =item spec_data example 3
841  
842 package Example;
843  
844 use Venus::Class 'base';
845  
846 base 'Venus::Task';
847  
848 sub spec_data {
849 {
850 name => 'example',
851 commands => [
852 ['command', 'hello', 'handle_hello'],
853 ],
854 }
855 }
856  
857 sub handle_hello {
858 my ($self, $args, $opts) = @_;
859 return 'hello world';
860 }
861  
862 package main;
863  
864 my $task = Example->new;
865  
866 $task->prepare;
867  
868 my $result = $task->dispatch('hello');
869  
870 # "hello world"
871  
872 =back
873  
874 =cut
875  
876 =head1 AUTHORS
877  
878 Awncorp, C<awncorp@cpan.org>
879  
880 =cut
881  
882 =head1 LICENSE
883  
884 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
885  
886 This program is free software, you can redistribute it and/or modify it under
887 the terms of the Apache license version 2.0.
888  
889 =cut
« blib/lib/Venus/Meta.pm ↑ Summary blib/lib/Venus/Role/Encaseable.pm »