File Coverage

blib/lib/Venus/Task.pm
Criterion Covered Total %
statement 115 120 95.8
branch 22 32 68.7
condition 15 29 51.7
subroutine 35 40 87.5
pod 26 30 86.6
total 213 251 84.8


line stmt bran cond sub pod time code
1             package Venus::Task;
2              
3 1     1   456 use 5.018;
  1         4  
4              
5 1     1   5 use strict;
  1         2  
  1         20  
6 1     1   4 use warnings;
  1         2  
  1         26  
7              
8 1     1   5 use Venus::Class 'attr', 'base', 'with';
  1         5  
  1         7  
9              
10             base 'Venus::Kind::Utility';
11              
12             with 'Venus::Role::Buildable';
13              
14             require POSIX;
15              
16             # ATTRIBUTES
17              
18             attr 'data';
19              
20             # BUILDERS
21              
22             sub build_arg {
23 44     44 0 135 my ($self, $data) = @_;
24              
25             return {
26 44         195 data => $data,
27             };
28             }
29              
30             sub build_args {
31 57     57 0 151 my ($self, $args) = @_;
32              
33 57         121 my $data = $args->{data};
34              
35 57 50       200 $data = defined $data ? (ref $data eq 'ARRAY' ? $data : [$data]) : [@ARGV];
    100          
36              
37 57         100 $args->{data} = $data;
38              
39 57         161 return $args;
40             }
41              
42             # HOOKS
43              
44             sub _exit {
45 0     0   0 POSIX::_exit(shift);
46             }
47              
48             sub _system {
49 0     0   0 local $SIG{__WARN__} = sub {};
        0      
50 0 0       0 CORE::system(@_) or return 0;
51             }
52              
53             sub _print {
54 0     0   0 CORE::print(@_);
55             }
56              
57             # METHODS
58              
59             sub args {
60 10     10 1 35 my ($self) = @_;
61              
62 10         34 return {};
63             }
64              
65             sub cli {
66 38     38 0 3115 my ($self) = @_;
67              
68 38         1179 require Venus::Cli;
69              
70 38   66     377 return $self->{'$cli'} ||= Venus::Cli->new(data => $self->data);
71             }
72              
73             sub cmds {
74 13     13 1 33 my ($self) = @_;
75              
76 13         47 return {};
77             }
78              
79             sub execute {
80 3     3 1 8 my ($self) = @_;
81              
82 3         16 $self->prepare;
83              
84 3         23 my $parsed = $self->cli->parsed;
85              
86 3         55 $self->startup($parsed);
87 3         50 $self->handler($parsed);
88 3         27 $self->shutdown($parsed);
89              
90 3         29 return $self;
91             }
92              
93             sub exit {
94 12     12 1 45 my ($self, $code, $method, @args) = @_;
95              
96 12 50       55 my $result = $self->$method(@args) ? 0 : 1 if $method;
    100          
97              
98 12   50     42 $code //= $result // 0;
      66        
99              
100 12         47 _exit($code);
101             }
102              
103             sub fail {
104 4     4 1 17 my ($self, $method, @args) = @_;
105              
106 4         17 return $self->exit(1, $method, @args);
107             }
108              
109             sub handler {
110 3     3 1 11 my ($self, $data) = @_;
111              
112 3 100       17 $self->usage if $data->{help};
113              
114 3         24 return $self;
115             }
116              
117             sub help {
118 4     4 1 14 my ($self) = @_;
119              
120 4         14 return $self->cli->help;
121             }
122              
123             sub log {
124 26     26 0 57 my ($self) = @_;
125              
126 26         152 require Venus::Log;
127              
128 26   33     295 return $self->{'$log'} ||= Venus::Log->new(
129             level => $self->log_level,
130             handler => $self->defer('output')
131             );
132             }
133              
134             sub log_debug {
135 1     1 1 4 my ($self, @args) = @_;
136              
137 1         4 return $self->log->debug(@args);
138             }
139              
140             sub log_error {
141 3     3 1 13 my ($self, @args) = @_;
142              
143 3         15 return $self->log->error(@args);
144             }
145              
146             sub log_fatal {
147 1     1 1 5 my ($self, @args) = @_;
148              
149 1         4 return $self->log->fatal(@args);
150             }
151              
152             sub log_info {
153 5     5 1 76 my ($self, @args) = @_;
154              
155 5         28 return $self->log->info(@args);
156             }
157              
158             sub log_level {
159              
160 0     0   0 return 'info';
161             }
162              
163             sub log_trace {
164 1     1 1 5 my ($self, @args) = @_;
165              
166 1         7 return $self->log->trace(@args);
167             }
168              
169             sub log_warn {
170 1     1 1 5 my ($self, @args) = @_;
171              
172 1         4 return $self->log->warn(@args);
173             }
174              
175             sub name {
176 13     13 1 31 my ($self) = @_;
177              
178 13         94 return $0;
179             }
180              
181             sub okay {
182 2     2 1 8 my ($self, $method, @args) = @_;
183              
184 2         15 return $self->exit(0, $method, @args);
185             }
186              
187             sub opts {
188 8     8 1 23 my ($self) = @_;
189              
190 8         32 return {};
191             }
192              
193             sub output {
194 13     13 1 46 my ($self, $level, @data) = @_;
195              
196 13         84 local $|=1;
197              
198 13 50       82 _print(@data, "\n") if @data;
199              
200 13         130 return $self;
201             }
202              
203             sub prepare {
204 13     13 1 46 my ($self) = @_;
205              
206 13         55 my $cli = $self->cli;
207              
208 13         54 $cli->data($self->data);
209              
210 13         171 my $args = $self->args;
211 13         67 my $cmds = $self->cmds;
212 13         73 my $name = $self->name;
213 13         144 my $opts = $self->opts;
214              
215 13         27 $cli->set('arg', $_, $args->{$_}) for sort keys %{$args};
  13         69  
216 13         36 $cli->set('cmd', $_, $cmds->{$_}) for sort keys %{$cmds};
  13         42  
217 13         24 $cli->set('opt', $_, $opts->{$_}) for sort keys %{$opts};
  13         53  
218              
219 13 50 33     59 $cli->set('str', 'name', $name) if !$cli->str('name') && $name;
220              
221 13 100 66     118 if ($self->can('description') && (my $description = $self->description)) {
222 1 50       6 $cli->set('str', 'description', $description) if !$cli->str('description');
223             }
224              
225 13 100 66     106 if ($self->can('header') && (my $header = $self->header)) {
226 1 50       5 $cli->set('str', 'header', $header) if !$cli->str('header');
227             }
228              
229 13 100 66     101 if ($self->can('footer') && (my $footer = $self->footer)) {
230 1 50       5 $cli->set('str', 'footer', $footer) if !$cli->str('footer');
231             }
232              
233 13         52 $self->log->do('level' => $self->log_level)->handler($self->defer('output'));
234              
235 13         182 return $self;
236             }
237              
238             sub pass {
239 2     2 1 11 my ($self, $method, @args) = @_;
240              
241 2         9 return $self->exit(0, $method, @args);
242             }
243              
244             sub run {
245 2     2 1 10 my ($self, @args) = @_;
246              
247 2   33     14 my $CAN_RUN = not(caller(1)) || scalar(caller(1)) eq 'main';
248              
249 2 50 33     54 $self->class->new(@args)->maybe('execute') if $ENV{VENUS_TASK_AUTO} && $CAN_RUN;
250              
251 2         22 return $self;
252             }
253              
254             sub startup {
255 3     3 1 13 my ($self, $data) = @_;
256              
257 3         13 return $self;
258             }
259              
260             sub shutdown {
261 3     3 1 6 my ($self, $data) = @_;
262              
263 3         19 return $self;
264             }
265              
266             sub system {
267 2     2 1 9 my ($self, @args) = @_;
268              
269 2 100       10 (_system(@args) == 0) or $self->error({
270             throw => 'error_on_system_call',
271             args => [@args],
272             error => $?
273             });
274              
275 1         16 return $self;
276             }
277              
278             sub test {
279 2     2 1 11 my ($self, @args) = @_;
280              
281 2         6 return $self->cli->test(@args);
282             }
283              
284             sub usage {
285 2     2 1 6 my ($self) = @_;
286              
287 2     2   19 $self->fail(sub{$self->log_info($self->help)});
  2         9  
288              
289 2         23 return $self;
290             }
291              
292             # ERRORS
293              
294             sub error_on_system_call {
295 2     2 1 8 my ($self, $data) = @_;
296              
297 2         5 my $message = 'Can\'t make system call "{{command}}": {{error}}';
298              
299             my $stash = {
300             args => $data->{args},
301 2         13 command => (join ' ', @{$data->{args}}),
302             error => $data->{error},
303 2         8 };
304              
305 2         9 my $result = {
306             name => 'on.system.call',
307             raise => true,
308             stash => $stash,
309             message => $message,
310             };
311              
312 2         8 return $result;
313             }
314              
315             1;
316              
317              
318              
319             =head1 NAME
320              
321             Venus::Task - Task Class
322              
323             =cut
324              
325             =head1 ABSTRACT
326              
327             Task Class for Perl 5
328              
329             =cut
330              
331             =head1 SYNOPSIS
332              
333             package Example;
334              
335             use base 'Venus::Task';
336              
337             package main;
338              
339             my $task = Example->new(['--help']);
340              
341             # bless({...}, 'Example')
342              
343             =cut
344              
345             =head1 DESCRIPTION
346              
347             This package provides a superclass, methods, and a simple framework for
348             creating CLIs (command-line interfaces).
349              
350             =cut
351              
352             =head1 ATTRIBUTES
353              
354             This package has the following attributes:
355              
356             =cut
357              
358             =head2 data
359              
360             data(ArrayRef $data) (ArrayRef)
361              
362             The data attribute is read-write, accepts C<(ArrayRef)> values, and is
363             optional.
364              
365             I>
366              
367             =over 4
368              
369             =item data example 1
370              
371             # given: synopsis
372              
373             package main;
374              
375             my $set_data = $task->data([1..4]);
376              
377             # [1..4]
378              
379             =back
380              
381             =over 4
382              
383             =item data example 2
384              
385             # given: synopsis
386              
387             # given: example-1 data
388              
389             package main;
390              
391             my $get_data = $task->data;
392              
393             # [1..4]
394              
395             =back
396              
397             =cut
398              
399             =head1 INHERITS
400              
401             This package inherits behaviors from:
402              
403             L
404              
405             =cut
406              
407             =head1 INTEGRATES
408              
409             This package integrates behaviors from:
410              
411             L
412              
413             =cut
414              
415             =head1 METHODS
416              
417             This package provides the following methods:
418              
419             =cut
420              
421             =head2 args
422              
423             args() (HashRef)
424              
425             The args method can be overridden and returns a hashref suitable to be passed
426             to the L method as type C<"arg">. An C<"arg"> is a CLI
427             positional argument.
428              
429             I>
430              
431             =over 4
432              
433             =item args example 1
434              
435             # given: synopsis
436              
437             package main;
438              
439             my $args = $task->args;
440              
441             # {}
442              
443             =back
444              
445             =over 4
446              
447             =item args example 2
448              
449             package Example;
450              
451             use base 'Venus::Task';
452              
453             sub args {
454              
455             return {
456             name => {
457             help => 'Name of user',
458             },
459             }
460             }
461              
462             package main;
463              
464             my $task = Example->new;
465              
466             my $args = $task->args;
467              
468             # {
469             # name => {
470             # help => 'Name of user',
471             # },
472             # }
473              
474             =back
475              
476             =cut
477              
478             =head2 cmds
479              
480             cmds() (HashRef)
481              
482             The cmds method can be overridden and returns a hashref suitable to be passed
483             to the L method as type C<"cmd">. A C<"cmd"> is a CLI command
484             which maps to an positional argument declare by L.
485              
486             I>
487              
488             =over 4
489              
490             =item cmds example 1
491              
492             # given: synopsis
493              
494             package main;
495              
496             my $cmds = $task->cmds;
497              
498             # {}
499              
500             =back
501              
502             =over 4
503              
504             =item cmds example 2
505              
506             package Example;
507              
508             use base 'Venus::Task';
509              
510             sub args {
511              
512             return {
513             op => {
514             help => 'Name of operation',
515             },
516             }
517             }
518              
519             sub cmds {
520              
521             return {
522             init => {
523             help => 'Initialize the system',
524             arg => 'op',
525             },
526             }
527             }
528              
529             package main;
530              
531             my $task = Example->new;
532              
533             my $cmds = $task->cmds;
534              
535             # {
536             # init => {
537             # help => 'Initialize the system',
538             # arg => 'op',
539             # },
540             # }
541              
542             =back
543              
544             =cut
545              
546             =head2 description
547              
548             description() (Task)
549              
550             The description method doesn't exist on the L superclass but if
551             defined returns a string that will be used as the CLI "description" (before the
552             arguments, options, and commands text).
553              
554             I>
555              
556             =over 4
557              
558             =item description example 1
559              
560             package Example;
561              
562             use base 'Venus::Task';
563              
564             sub description {
565              
566             "This text used in the description area of the usage text"
567             }
568              
569             package main;
570              
571             my $task = Example->new;
572              
573             my $description = $task->description;
574              
575             # "..."
576              
577             =back
578              
579             =cut
580              
581             =head2 execute
582              
583             execute() (Task)
584              
585             The execute method can be overridden and returns the invocant. This method
586             prepares the L via L, and runs the L,
587             L, and L sequences, passing L to each
588             method.
589              
590             I>
591              
592             =over 4
593              
594             =item execute example 1
595              
596             # given: synopsis
597              
598             package main;
599              
600             my $execute = $task->execute;
601              
602             # bless({...}, 'Venus::Task')
603              
604             =back
605              
606             =over 4
607              
608             =item execute example 2
609              
610             package Example;
611              
612             use base 'Venus::Task';
613              
614             sub args {
615              
616             return {
617             name => {
618             help => 'Name of user',
619             },
620             }
621             }
622              
623             sub opts {
624              
625             return {
626             sudo => {
627             help => 'Elevate user privileges',
628             alias => ['s'],
629             },
630             help => {
631             help => 'Display help',
632             alias => ['h'],
633             },
634             }
635             }
636              
637             sub startup {
638             my ($self) = @_;
639              
640             $self->{startup} = time;
641              
642             return $self;
643             }
644              
645             sub handler {
646             my ($self, $data) = @_;
647              
648             $self->{handler} = time;
649             $self->{parsed} = $data;
650              
651             return $self;
652             }
653              
654             sub shutdown {
655             my ($self) = @_;
656              
657             $self->{shutdown} = time;
658              
659             return $self;
660             }
661              
662             package main;
663              
664             my $task = Example->new(['admin', '-s']);
665              
666             my $execute = $task->execute;
667              
668             # bless({...}, 'Venus::Task')
669              
670             =back
671              
672             =over 4
673              
674             =item execute example 3
675              
676             package Example;
677              
678             use base 'Venus::Task';
679              
680             sub args {
681              
682             return {
683             name => {
684             help => 'Name of user',
685             },
686             }
687             }
688              
689             sub opts {
690              
691             return {
692             sudo => {
693             help => 'Elevate user privileges',
694             alias => ['s'],
695             },
696             help => {
697             help => 'Display help',
698             alias => ['h'],
699             },
700             }
701             }
702              
703             sub handler {
704             my ($self, $data) = @_;
705              
706             $self->{handler} = time;
707             $self->{parsed} = $data;
708              
709             return $self;
710             }
711              
712             package main;
713              
714             my $task = Example->new(['-s']);
715              
716             my $execute = $task->execute;
717              
718             # bless({...}, 'Venus::Task')
719              
720             =back
721              
722             =cut
723              
724             =head2 exit
725              
726             exit(Int $code, Str|CodeRef $code, Any @args) (Any)
727              
728             The exit method exits the program using the exit code provided. The exit code
729             defaults to C<0>. Optionally, you can dispatch before exiting by providing a
730             method name or coderef, and arguments. If an exit code of C is provided,
731             the exit code will be determined by the result of the dispatching.
732              
733             I>
734              
735             =over 4
736              
737             =item exit example 1
738              
739             # given: synopsis
740              
741             package main;
742              
743             my $exit = $task->exit;
744              
745             # ()
746              
747             =back
748              
749             =over 4
750              
751             =item exit example 2
752              
753             # given: synopsis
754              
755             package main;
756              
757             my $exit = $task->exit(0);
758              
759             # ()
760              
761             =back
762              
763             =over 4
764              
765             =item exit example 3
766              
767             # given: synopsis
768              
769             package main;
770              
771             my $exit = $task->exit(1);
772              
773             # ()
774              
775             =back
776              
777             =over 4
778              
779             =item exit example 4
780              
781             # given: synopsis
782              
783             package main;
784              
785             my $exit = $task->exit(1, 'log_error', 'oh no');
786              
787             # ()
788              
789             =back
790              
791             =cut
792              
793             =head2 fail
794              
795             fail(Str|CodeRef $code, Any @args) (Any)
796              
797             The fail method exits the program with the exit code C<1>. Optionally, you can
798             dispatch before exiting by providing a method name or coderef, and arguments.
799              
800             I>
801              
802             =over 4
803              
804             =item fail example 1
805              
806             # given: synopsis
807              
808             package main;
809              
810             my $fail = $task->fail;
811              
812             # ()
813              
814             =back
815              
816             =over 4
817              
818             =item fail example 2
819              
820             # given: synopsis
821              
822             package main;
823              
824             my $fail = $task->fail('log_error', 'oh no');
825              
826             # ()
827              
828             =back
829              
830             =cut
831              
832             =head2 footer
833              
834             footer() (Task)
835              
836             The footer method doesn't exist on the L superclass but if defined
837             returns a string that will be used as the CLI "footer" (after the arguments,
838             options, and commands text).
839              
840             I>
841              
842             =over 4
843              
844             =item footer example 1
845              
846             package Example;
847              
848             use base 'Venus::Task';
849              
850             sub footer {
851              
852             "This text used in the footer area of the usage text"
853             }
854              
855             package main;
856              
857             my $task = Example->new;
858              
859             my $footer = $task->footer;
860              
861             # "..."
862              
863             =back
864              
865             =cut
866              
867             =head2 handler
868              
869             handler(HashRef $data) (Task)
870              
871             The handler method can and should be overridden and returns the invocant. This
872             method is where the central task operations are meant to happen. By default, if
873             not overriden this method calls L if a "help" flag is detected.
874              
875             I>
876              
877             =over 4
878              
879             =item handler example 1
880              
881             # given: synopsis
882              
883             package main;
884              
885             my $handler = $task->handler({});
886              
887             # bless({...}, 'Venus::Task')
888              
889             =back
890              
891             =over 4
892              
893             =item handler example 2
894              
895             # given: synopsis
896              
897             package main;
898              
899             my $handler = $task->handler({help => 1});
900              
901             # bless({...}, 'Venus::Task')
902              
903             =back
904              
905             =over 4
906              
907             =item handler example 3
908              
909             package Example;
910              
911             use base 'Venus::Task';
912              
913             sub handler {
914             my ($self, $data) = @_;
915              
916             $self->{handler} = time;
917             $self->{parsed} = $data;
918              
919             return $self;
920             }
921              
922             package main;
923              
924             my $task = Example->new;
925              
926             my $handler = $task->handler({});
927              
928             # bless({...}, 'Venus::Task')
929              
930             =back
931              
932             =cut
933              
934             =head2 header
935              
936             header() (Task)
937              
938             The header method doesn't exist on the L superclass but if defined
939             returns a string that will be used as the CLI "header" (after the title, before
940             the arguments, options, and commands text).
941              
942             I>
943              
944             =over 4
945              
946             =item header example 1
947              
948             package Example;
949              
950             use base 'Venus::Task';
951              
952             sub header {
953              
954             "This text used in the header area of the usage text"
955             }
956              
957             package main;
958              
959             my $task = Example->new;
960              
961             my $header = $task->header;
962              
963             # "..."
964              
965             =back
966              
967             =cut
968              
969             =head2 help
970              
971             help() (Str)
972              
973             The help method can be overridden and returns a string representing "help" text
974             for the CLI. By default this method returns the result of L,
975             based on the L object.
976              
977             I>
978              
979             =over 4
980              
981             =item help example 1
982              
983             # given: synopsis
984              
985             package main;
986              
987             my $help = $task->help;
988              
989             # "Usage: application"
990              
991             =back
992              
993             =over 4
994              
995             =item help example 2
996              
997             package Example;
998              
999             use base 'Venus::Task';
1000              
1001             sub name {
1002              
1003             return 'eg';
1004             }
1005              
1006             package main;
1007              
1008             my $task = Example->new;
1009              
1010             $task->prepare;
1011              
1012             my $help = $task->help;
1013              
1014             # "Usage: application"
1015              
1016             =back
1017              
1018             =cut
1019              
1020             =head2 log_debug
1021              
1022             log_debug(Any @log_debug) (Log)
1023              
1024             The log_debug method dispatches to the L method and returns the
1025             result.
1026              
1027             I>
1028              
1029             =over 4
1030              
1031             =item log_debug example 1
1032              
1033             # given: synopsis
1034              
1035             package main;
1036              
1037             my $log_debug = $task->log_debug('something' ,'happened');
1038              
1039             # bless({...}, 'Venus::Log')
1040              
1041             =back
1042              
1043             =cut
1044              
1045             =head2 log_error
1046              
1047             log_error(Any @log_error) (Log)
1048              
1049             The log_error method dispatches to the L method and returns the
1050             result.
1051              
1052             I>
1053              
1054             =over 4
1055              
1056             =item log_error example 1
1057              
1058             # given: synopsis
1059              
1060             package main;
1061              
1062             my $log_error = $task->log_error('something' ,'happened');
1063              
1064             # bless({...}, 'Venus::Log')
1065              
1066             =back
1067              
1068             =cut
1069              
1070             =head2 log_fatal
1071              
1072             log_fatal(Any @log_fatal) (Log)
1073              
1074             The log_fatal method dispatches to the L method and returns the
1075             result.
1076              
1077             I>
1078              
1079             =over 4
1080              
1081             =item log_fatal example 1
1082              
1083             # given: synopsis
1084              
1085             package main;
1086              
1087             my $log_fatal = $task->log_fatal('something' ,'happened');
1088              
1089             # bless({...}, 'Venus::Log')
1090              
1091             =back
1092              
1093             =cut
1094              
1095             =head2 log_info
1096              
1097             log_info(Any @log_info) (Log)
1098              
1099             The log_info method dispatches to the L method and returns the
1100             result.
1101              
1102             I>
1103              
1104             =over 4
1105              
1106             =item log_info example 1
1107              
1108             # given: synopsis
1109              
1110             package main;
1111              
1112             my $log_info = $task->log_info('something' ,'happened');
1113              
1114             # bless({...}, 'Venus::Log')
1115              
1116             =back
1117              
1118             =cut
1119              
1120             =head2 log_level
1121              
1122             log_level() (Str)
1123              
1124             The log_level method can be overridden and returns a valid L
1125             value. This method defaults to returning L.
1126              
1127             I>
1128              
1129             =over 4
1130              
1131             =item log_level example 1
1132              
1133             # given: synopsis
1134              
1135             package main;
1136              
1137             my $log_level = $task->log_level;
1138              
1139             # "info"
1140              
1141             =back
1142              
1143             =cut
1144              
1145             =head2 log_trace
1146              
1147             log_trace(Any @log_trace) (Log)
1148              
1149             The log_trace method dispatches to the L method and returns the
1150             result.
1151              
1152             I>
1153              
1154             =over 4
1155              
1156             =item log_trace example 1
1157              
1158             # given: synopsis
1159              
1160             package main;
1161              
1162             my $log_trace = $task->log_trace('something' ,'happened');
1163              
1164             # bless({...}, 'Venus::Log')
1165              
1166             =back
1167              
1168             =cut
1169              
1170             =head2 log_warn
1171              
1172             log_warn(Any @log_warn) (Log)
1173              
1174             The log_warn method dispatches to the L method and returns the
1175             result.
1176              
1177             I>
1178              
1179             =over 4
1180              
1181             =item log_warn example 1
1182              
1183             # given: synopsis
1184              
1185             package main;
1186              
1187             my $log_warn = $task->log_warn('something' ,'happened');
1188              
1189             # bless({...}, 'Venus::Log')
1190              
1191             =back
1192              
1193             =cut
1194              
1195             =head2 name
1196              
1197             name() (Task)
1198              
1199             The name method can be overridden and returns the name of the task (and
1200             application). This method defaults to C<$0> if not overridden.
1201              
1202             I>
1203              
1204             =over 4
1205              
1206             =item name example 1
1207              
1208             # given: synopsis
1209              
1210             package main;
1211              
1212             my $name = $task->name;
1213              
1214             # "/path/to/application"
1215              
1216             =back
1217              
1218             =over 4
1219              
1220             =item name example 2
1221              
1222             package Example;
1223              
1224             use base 'Venus::Task';
1225              
1226             sub name {
1227              
1228             return 'eg';
1229             }
1230              
1231             package main;
1232              
1233             my $task = Example->new;
1234              
1235             my $name = $task->name;
1236              
1237             # "eg"
1238              
1239             =back
1240              
1241             =cut
1242              
1243             =head2 okay
1244              
1245             okay(Str|CodeRef $code, Any @args) (Any)
1246              
1247             The okay method exits the program with the exit code C<0>. Optionally, you can
1248             dispatch before exiting by providing a method name or coderef, and arguments.
1249              
1250             I>
1251              
1252             =over 4
1253              
1254             =item okay example 1
1255              
1256             # given: synopsis
1257              
1258             package main;
1259              
1260             my $okay = $task->okay;
1261              
1262             # ()
1263              
1264             =back
1265              
1266             =over 4
1267              
1268             =item okay example 2
1269              
1270             # given: synopsis
1271              
1272             package main;
1273              
1274             my $okay = $task->okay('log_info', 'yatta');
1275              
1276             # ()
1277              
1278             =back
1279              
1280             =cut
1281              
1282             =head2 opts
1283              
1284             opts() (HashRef)
1285              
1286             The opts method can be overridden and returns a hashref suitable to be passed
1287             to the L method as type C<"opt">. An C<"opt"> is a CLI option
1288             (or flag).
1289              
1290             I>
1291              
1292             =over 4
1293              
1294             =item opts example 1
1295              
1296             # given: synopsis
1297              
1298             package main;
1299              
1300             my $opts = $task->opts;
1301              
1302             # {}
1303              
1304             =back
1305              
1306             =over 4
1307              
1308             =item opts example 2
1309              
1310             package Example;
1311              
1312             use base 'Venus::Task';
1313              
1314             sub opts {
1315              
1316             return {
1317             help => {
1318             help => 'Display help',
1319             alias => ['h'],
1320             },
1321             }
1322             }
1323              
1324             package main;
1325              
1326             my $task = Example->new;
1327              
1328             my $opts = $task->opts;
1329              
1330             # {
1331             # help => {
1332             # help => 'Display help',
1333             # alias => ['h'],
1334             # },
1335             # }
1336              
1337             =back
1338              
1339             =cut
1340              
1341             =head2 output
1342              
1343             output(Str $level, Str @messages) (Task)
1344              
1345             The output method is configured as the L by L,
1346             can be overridden and returns the invocant.
1347              
1348             I>
1349              
1350             =over 4
1351              
1352             =item output example 1
1353              
1354             # given: synopsis
1355              
1356             package main;
1357              
1358             $task->prepare;
1359              
1360             $task = $task->output('info', 'something happened');
1361              
1362             # bless({...}, 'Example')
1363              
1364             =back
1365              
1366             =cut
1367              
1368             =head2 pass
1369              
1370             pass(Str|CodeRef $code, Any @args) (Any)
1371              
1372             The pass method exits the program with the exit code C<0>. Optionally, you can
1373             dispatch before exiting by providing a method name or coderef, and arguments.
1374              
1375             I>
1376              
1377             =over 4
1378              
1379             =item pass example 1
1380              
1381             # given: synopsis
1382              
1383             package main;
1384              
1385             my $pass = $task->pass;
1386              
1387             # ()
1388              
1389             =back
1390              
1391             =over 4
1392              
1393             =item pass example 2
1394              
1395             # given: synopsis
1396              
1397             package main;
1398              
1399             my $pass = $task->pass('log_info', 'yatta');
1400              
1401             # ()
1402              
1403             =back
1404              
1405             =cut
1406              
1407             =head2 prepare
1408              
1409             prepare() (Task)
1410              
1411             The prepare method can be overridden, but typically shouldn't, is responsible
1412             for configuring the L and L objects, parsing the arguments, and
1413             after returns the invocant.
1414              
1415             I>
1416              
1417             =over 4
1418              
1419             =item prepare example 1
1420              
1421             # given: synopsis
1422              
1423             package main;
1424              
1425             my $prepare = $task->prepare;
1426              
1427             # bless({...}, 'Venus::Task')
1428              
1429             =back
1430              
1431             =over 4
1432              
1433             =item prepare example 2
1434              
1435             package Example;
1436              
1437             use base 'Venus::Task';
1438              
1439             sub args {
1440              
1441             return {
1442             name => {
1443             help => 'Name of user',
1444             },
1445             }
1446             }
1447              
1448             sub opts {
1449              
1450             return {
1451             sudo => {
1452             help => 'Elevate user privileges',
1453             alias => ['s'],
1454             },
1455             help => {
1456             help => 'Display help',
1457             alias => ['h'],
1458             },
1459             }
1460             }
1461              
1462             package main;
1463              
1464             my $task = Example->new;
1465              
1466             my $prepare = $task->prepare;
1467              
1468             # bless({...}, 'Venus::Task')
1469              
1470             =back
1471              
1472             =over 4
1473              
1474             =item prepare example 3
1475              
1476             package Example;
1477              
1478             use base 'Venus::Task';
1479              
1480             sub args {
1481              
1482             return {
1483             name => {
1484             help => 'Name of user',
1485             },
1486             }
1487             }
1488              
1489             sub cmds {
1490              
1491             return {
1492             admin => {
1493             help => 'Run as an admin',
1494             arg => 'name',
1495             },
1496             user => {
1497             help => 'Run as a user',
1498             arg => 'name',
1499             },
1500             }
1501             }
1502              
1503             sub opts {
1504              
1505             return {
1506             sudo => {
1507             help => 'Elevate user privileges',
1508             alias => ['s'],
1509             },
1510             help => {
1511             help => 'Display help',
1512             alias => ['h'],
1513             },
1514             }
1515             }
1516              
1517             package main;
1518              
1519             my $task = Example->new(['admin', '-s']);
1520              
1521             my $prepare = $task->prepare;
1522              
1523             # bless({...}, 'Venus::Task')
1524              
1525             =back
1526              
1527             =cut
1528              
1529             =head2 run
1530              
1531             run(Any @args) (Task)
1532              
1533             The run class method will automatically execute the task class by instansiating
1534             the class and calling the L method and returns the invocant. This
1535             method is meant to be used directly in package scope outside of any routine,
1536             and will only auto-execute under the conditions that the caller is the "main"
1537             package space and the C environment variable is truthy.
1538              
1539             I>
1540              
1541             =over 4
1542              
1543             =item run example 1
1544              
1545             package Example;
1546              
1547             use base 'Venus::Task';
1548              
1549             sub opts {
1550              
1551             return {
1552             help => {
1553             help => 'Display help',
1554             alias => ['h'],
1555             },
1556             }
1557             }
1558              
1559             package main;
1560              
1561             my $task = Example->new(['--help']);
1562              
1563             my $run = $task->run;
1564              
1565             # bless({...}, 'Venus::Task')
1566              
1567             =back
1568              
1569             =over 4
1570              
1571             =item run example 2
1572              
1573             package Example;
1574              
1575             use base 'Venus::Task';
1576              
1577             sub opts {
1578              
1579             return {
1580             help => {
1581             help => 'Display help',
1582             alias => ['h'],
1583             },
1584             }
1585             }
1586              
1587             run Example;
1588              
1589             # 'Example'
1590              
1591             =back
1592              
1593             =cut
1594              
1595             =head2 shutdown
1596              
1597             shutdown(HashRef $data) (Task)
1598              
1599             The shutdown method can be overridden and returns the invocant. This method is
1600             called by L automatically after L and is passed the result
1601             of L.
1602              
1603             I>
1604              
1605             =over 4
1606              
1607             =item shutdown example 1
1608              
1609             # given: synopsis
1610              
1611             package main;
1612              
1613             my $shutdown = $task->shutdown({});
1614              
1615             # bless({...}, 'Venus::Task')
1616              
1617             =back
1618              
1619             =cut
1620              
1621             =head2 startup
1622              
1623             startup(HashRef $data) (Task)
1624              
1625             The startup method can be overridden and returns the invocant. This method is
1626             called by L automatically after L and before L,
1627             and is passed the result of L.
1628              
1629             I>
1630              
1631             =over 4
1632              
1633             =item startup example 1
1634              
1635             # given: synopsis
1636              
1637             package main;
1638              
1639             my $startup = $task->startup({});
1640              
1641             # bless({...}, 'Venus::Task')
1642              
1643             =back
1644              
1645             =cut
1646              
1647             =head2 system
1648              
1649             system(Str @args) (Task)
1650              
1651             The system method attempts to make a L call and returns the
1652             invocant. If the system call is unsuccessful an error is thrown.
1653              
1654             I>
1655              
1656             =over 4
1657              
1658             =item system example 1
1659              
1660             # given: synopsis
1661              
1662             package main;
1663              
1664             my $system = $task->system($^X, '-V');
1665              
1666             # bless({...}, 'Example')
1667              
1668             =back
1669              
1670             =over 4
1671              
1672             =item system example 2
1673              
1674             # given: synopsis
1675              
1676             package main;
1677              
1678             my $system = $task->system('/path/to/nowhere');
1679              
1680             # Exception! (isa Example::Error) (see error_on_system_call)
1681              
1682             =back
1683              
1684             =cut
1685              
1686             =head2 test
1687              
1688             test(Str $type, Str $name) (Any)
1689              
1690             The test method validates the values for the C or C specified and
1691             returns the value(s) associated. This method dispatches to L.
1692              
1693             I>
1694              
1695             =over 4
1696              
1697             =item test example 1
1698              
1699             package Example;
1700              
1701             use base 'Venus::Task';
1702              
1703             sub opts {
1704              
1705             return {
1706             help => {
1707             help => 'Display help',
1708             alias => ['h'],
1709             },
1710             }
1711             }
1712              
1713             package main;
1714              
1715             my $task = Example->new(['--help']);
1716              
1717             my ($help) = $task->prepare->test('opt', 'help');
1718              
1719             # true
1720              
1721             =back
1722              
1723             =over 4
1724              
1725             =item test example 2
1726              
1727             package Example;
1728              
1729             use base 'Venus::Task';
1730              
1731             sub opts {
1732              
1733             return {
1734             help => {
1735             type => 'string',
1736             help => 'Display help',
1737             alias => ['h'],
1738             },
1739             }
1740             }
1741              
1742             package main;
1743              
1744             my $task = Example->new(['--help']);
1745              
1746             my ($help) = $task->prepare->test('opt', 'help');
1747              
1748             # Exception! (isa Venus::Cli::Error) (see error_on_arg_validation)
1749              
1750             # Invalid option: help: received (undef), expected (string)
1751              
1752             =back
1753              
1754             =cut
1755              
1756             =head2 usage
1757              
1758             usage() (Task)
1759              
1760             The usage method exits the program with the exit code C<1> after calling
1761             L with the result of L. This method makes it easy to output
1762             the default help text and end the program if some condition isn't met.
1763              
1764             I>
1765              
1766             =over 4
1767              
1768             =item usage example 1
1769              
1770             # given: synopsis
1771              
1772             package main;
1773              
1774             my $usage = $task->usage;
1775              
1776             # bless({...}, 'Venus::Task')
1777              
1778             =back
1779              
1780             =cut
1781              
1782             =head1 ERRORS
1783              
1784             This package may raise the following errors:
1785              
1786             =cut
1787              
1788             =over 4
1789              
1790             =item error: C
1791              
1792             This package may raise an error_on_system_call exception.
1793              
1794             B
1795              
1796             # given: synopsis;
1797              
1798             my $input = {
1799             throw => 'error_on_system_call',
1800             args => ['/path/to/nowhere', 'arg1', 'arg2'],
1801             error => $?,
1802             };
1803              
1804             my $error = $task->catch('error', $input);
1805              
1806             # my $name = $error->name;
1807              
1808             # "on_system_call"
1809              
1810             # my $message = $error->render;
1811              
1812             # "Can't make system call \"/path/to/nowhere arg1 arg2\": $?"
1813              
1814             # my $args = $error->stash('args');
1815              
1816             # []
1817              
1818             =back
1819              
1820             =head1 AUTHORS
1821              
1822             Awncorp, C
1823              
1824             =cut
1825              
1826             =head1 LICENSE
1827              
1828             Copyright (C) 2000, Al Newkirk.
1829              
1830             This program is free software, you can redistribute it and/or modify it under
1831             the terms of the Apache license version 2.0.
1832              
1833             =cut