NAME
Venus::Task - Task Class
ABSTRACT
Task Class for Perl 5
SYNOPSIS
package Example;
use base 'Venus::Task';
package main;
my $task = Example->new(['--help']);
# bless({...}, 'Example')
DESCRIPTION
This package provides a superclass, methods, and a simple framework for creating CLIs (command-line interfaces).
ATTRIBUTES
This package has the following attributes:
data
data(ArrayRef $data) (ArrayRef)
The data attribute is read-write, accepts (ArrayRef)
values, and is optional.
Since 2.91
- data example 2
-
# given: synopsis # given: example-1 data package main; my $get_data = $task->data; # [1..4]
INHERITS
This package inherits behaviors from:
INTEGRATES
This package integrates behaviors from:
METHODS
This package provides the following methods:
args
args() (HashRef)
The args method can be overridden and returns a hashref suitable to be passed to the "set" in Venus::Cli method as type "arg"
. An "arg"
is a CLI positional argument.
Since 2.91
- args example 2
-
package Example; use base 'Venus::Task'; sub args { return { name => { help => 'Name of user', }, } } package main; my $task = Example->new; my $args = $task->args; # { # name => { # help => 'Name of user', # }, # }
cmds
cmds() (HashRef)
The cmds method can be overridden and returns a hashref suitable to be passed to the "set" in Venus::Cli method as type "cmd"
. A "cmd"
is a CLI command which maps to an positional argument declare by "arg".
Since 2.91
- cmds example 2
-
package Example; use base 'Venus::Task'; sub args { return { op => { help => 'Name of operation', }, } } sub cmds { return { init => { help => 'Initialize the system', arg => 'op', }, } } package main; my $task = Example->new; my $cmds = $task->cmds; # { # init => { # help => 'Initialize the system', # arg => 'op', # }, # }
description
description() (Task)
The description method doesn't exist on the Venus::Task superclass but if defined returns a string that will be used as the CLI "description" (before the arguments, options, and commands text).
Since 2.91
- description example 1
-
package Example; use base 'Venus::Task'; sub description { "This text used in the description area of the usage text" } package main; my $task = Example->new; my $description = $task->description; # "..."
execute
execute() (Task)
The execute method can be overridden and returns the invocant. This method prepares the Venus::Cli via "prepare", and runs the "startup", "handler", and "shutdown" sequences, passing "parsed" in Venus::Cli to each method.
Since 2.91
- execute example 1
-
# given: synopsis package main; my $execute = $task->execute; # bless({...}, 'Venus::Task')
- execute example 2
-
package Example; use base 'Venus::Task'; sub args { return { name => { help => 'Name of user', }, } } sub opts { return { sudo => { help => 'Elevate user privileges', alias => ['s'], }, help => { help => 'Display help', alias => ['h'], }, } } sub startup { my ($self) = @_; $self->{startup} = time; return $self; } sub handler { my ($self, $data) = @_; $self->{handler} = time; $self->{parsed} = $data; return $self; } sub shutdown { my ($self) = @_; $self->{shutdown} = time; return $self; } package main; my $task = Example->new(['admin', '-s']); my $execute = $task->execute; # bless({...}, 'Venus::Task')
- execute example 3
-
package Example; use base 'Venus::Task'; sub args { return { name => { help => 'Name of user', }, } } sub opts { return { sudo => { help => 'Elevate user privileges', alias => ['s'], }, help => { help => 'Display help', alias => ['h'], }, } } sub handler { my ($self, $data) = @_; $self->{handler} = time; $self->{parsed} = $data; return $self; } package main; my $task = Example->new(['-s']); my $execute = $task->execute; # bless({...}, 'Venus::Task')
exit
exit(Int $code, Str|CodeRef $code, Any @args) (Any)
The exit method exits the program using the exit code provided. The exit code defaults to 0
. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.
Since 2.91
- exit example 4
-
# given: synopsis package main; my $exit = $task->exit(1, 'log_error', 'oh no'); # ()
fail
fail(Str|CodeRef $code, Any @args) (Any)
The fail method exits the program with the exit code 1
. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.
Since 2.91
footer
footer() (Task)
The footer method doesn't exist on the Venus::Task superclass but if defined returns a string that will be used as the CLI "footer" (after the arguments, options, and commands text).
Since 2.91
-
package Example; use base 'Venus::Task'; sub footer { "This text used in the footer area of the usage text" } package main; my $task = Example->new; my $footer = $task->footer; # "..."
handler
handler(HashRef $data) (Task)
The handler method can and should be overridden and returns the invocant. This method is where the central task operations are meant to happen. By default, if not overriden this method calls "usage" if a "help" flag is detected.
Since 2.91
- handler example 1
-
# given: synopsis package main; my $handler = $task->handler({}); # bless({...}, 'Venus::Task')
- handler example 2
-
# given: synopsis package main; my $handler = $task->handler({help => 1}); # bless({...}, 'Venus::Task')
- handler example 3
-
package Example; use base 'Venus::Task'; sub handler { my ($self, $data) = @_; $self->{handler} = time; $self->{parsed} = $data; return $self; } package main; my $task = Example->new; my $handler = $task->handler({}); # bless({...}, 'Venus::Task')
header
header() (Task)
The header method doesn't exist on the Venus::Task superclass but if defined returns a string that will be used as the CLI "header" (after the title, before the arguments, options, and commands text).
Since 2.91
- header example 1
-
package Example; use base 'Venus::Task'; sub header { "This text used in the header area of the usage text" } package main; my $task = Example->new; my $header = $task->header; # "..."
help
help() (Str)
The help method can be overridden and returns the result of "help" in Venus::Cli. This method is returns the default help text based on the configuration of the "cli" object.
Since 2.91
- help example 2
-
package Example; use base 'Venus::Task'; sub name { return 'eg'; } package main; my $task = Example->new; $task->prepare; my $help = $task->help; # "Usage: application"
log_debug
log_debug(Any @log_debug) (Log)
The log_debug method dispatches to the "debug" in Venus::Log method and returns the result.
Since 2.91
- log_debug example 1
-
# given: synopsis package main; my $log_debug = $task->log_debug('something' ,'happened'); # bless({...}, 'Venus::Log')
log_error
log_error(Any @log_error) (Log)
The log_error method dispatches to the "error" in Venus::Log method and returns the result.
Since 2.91
- log_error example 1
-
# given: synopsis package main; my $log_error = $task->log_error('something' ,'happened'); # bless({...}, 'Venus::Log')
log_fatal
log_fatal(Any @log_fatal) (Log)
The log_fatal method dispatches to the "fatal" in Venus::Log method and returns the result.
Since 2.91
- log_fatal example 1
-
# given: synopsis package main; my $log_fatal = $task->log_fatal('something' ,'happened'); # bless({...}, 'Venus::Log')
log_info
log_info(Any @log_info) (Log)
The log_info method dispatches to the "info" in Venus::Log method and returns the result.
Since 2.91
- log_info example 1
-
# given: synopsis package main; my $log_info = $task->log_info('something' ,'happened'); # bless({...}, 'Venus::Log')
log_level
log_level() (Str)
The log_level method can be overridden and returns a valid "level" in Venus::Log value. This method defaults to returning info.
Since 2.91
log_trace
log_trace(Any @log_trace) (Log)
The log_trace method dispatches to the "trace" in Venus::Log method and returns the result.
Since 2.91
- log_trace example 1
-
# given: synopsis package main; my $log_trace = $task->log_trace('something' ,'happened'); # bless({...}, 'Venus::Log')
log_warn
log_warn(Any @log_warn) (Log)
The log_warn method dispatches to the "warn" in Venus::Log method and returns the result.
Since 2.91
- log_warn example 1
-
# given: synopsis package main; my $log_warn = $task->log_warn('something' ,'happened'); # bless({...}, 'Venus::Log')
name
name() (Task)
The name method can be overridden and returns the name of the task (and application). This method is default to $0
if not overridden.
Since 2.91
- name example 2
-
package Example; use base 'Venus::Task'; sub name { return 'eg'; } package main; my $task = Example->new; my $name = $task->name; # "eg"
okay
okay(Str|CodeRef $code, Any @args) (Any)
The okay method exits the program with the exit code 0
. Optionally, you can dispatch before exiting by providing a method name or coderef, and arguments.
Since 2.91
opts
opts() (HashRef)
The opts method can be overridden and returns a hashref suitable to be passed to the "set" in Venus::Cli method as type "opt"
. An "opt"
is a CLI option (or flag).
Since 2.91
- opts example 2
-
package Example; use base 'Venus::Task'; sub opts { return { help => { help => 'Display help', alias => ['h'], }, } } package main; my $task = Example->new; my $opts = $task->opts; # { # help => { # help => 'Display help', # alias => ['h'], # }, # }
output
output(Str $level, Str @messages) (Task)
The output method is configured as the "handler" in Venus::Log by "prepare", can be overridden and returns the invocant.
Since 2.91
- output example 1
-
# given: synopsis package main; $task->prepare; $task = $task->output('info', 'something happened'); # bless({...}, 'Example')
prepare
prepare() (Task)
The prepare method can be overridden, but typically shouldn't, is responsible for configuring the "cli" and "log" objects, parsing the arguments, and after returns the invocant.
Since 2.91
- prepare example 1
-
# given: synopsis package main; my $prepare = $task->prepare; # bless({...}, 'Venus::Task')
- prepare example 2
-
package Example; use base 'Venus::Task'; sub args { return { name => { help => 'Name of user', }, } } sub opts { return { sudo => { help => 'Elevate user privileges', alias => ['s'], }, help => { help => 'Display help', alias => ['h'], }, } } package main; my $task = Example->new; my $prepare = $task->prepare; # bless({...}, 'Venus::Task')
- prepare example 3
-
package Example; use base 'Venus::Task'; sub args { return { name => { help => 'Name of user', }, } } sub cmds { return { admin => { help => 'Run as an admin', arg => 'name', }, user => { help => 'Run as a user', arg => 'name', }, } } sub opts { return { sudo => { help => 'Elevate user privileges', alias => ['s'], }, help => { help => 'Display help', alias => ['h'], }, } } package main; my $task = Example->new(['admin', '-s']); my $prepare = $task->prepare; # bless({...}, 'Venus::Task')
run
run(Any @args) (Task)
The run class method will automatically execute the task class by instansiating the class and calling the "execute" method and returns the invocant. This method is meant to be used directly in package scope outside of any routine, and will only auto-execute under the conditions that the caller is the "main" package space and the VENUS_TASK_RUN
environment variable is truthy.
Since 2.91
- run example 1
-
package Example; use base 'Venus::Task'; sub opts { return { help => { help => 'Display help', alias => ['h'], }, } } package main; my $task = Example->new(['--help']); my $run = $task->run; # bless({...}, 'Venus::Task')
- run example 2
-
package Example; use base 'Venus::Task'; sub opts { return { help => { help => 'Display help', alias => ['h'], }, } } run Example; # 'Example'
shutdown
shutdown(HashRef $data) (Task)
The shutdown method can be overridden and returns the invocant. This method is called by "execute" automatically after "handler" and is passed the result of "parsed" in Venus::Cli.
Since 2.91
- shutdown example 1
-
# given: synopsis package main; my $shutdown = $task->shutdown({}); # bless({...}, 'Venus::Task')
startup
startup(HashRef $data) (Task)
The startup method can be overridden and returns the invocant. This method is called by "execute" automatically after "prepare" and before "handler", and is passed the result of "parsed" in Venus::Cli.
Since 2.91
- startup example 1
-
# given: synopsis package main; my $startup = $task->startup({}); # bless({...}, 'Venus::Task')
system
system(Str @args) (Task)
The system method attempts to make a "system" in perlfunc call and returns the invocant. If the system call is unsuccessful an error is thrown.
Since 2.91
- system example 1
-
# given: synopsis package main; my $system = $task->system($^X, '-V'); # bless({...}, 'Example')
- system example 2
-
# given: synopsis package main; my $system = $task->system('/path/to/nowhere'); # Exception! (isa Example::Error) (see error_on_system_call)
usage
usage() (Task)
The usage method exits the program with the exit code 1
after calling "log_info" with the result of "help". This method makes it easy to output the default help text and end the program if some condition isn't met.
Since 2.91
- usage example 1
-
# given: synopsis package main; my $usage = $task->usage; # bless({...}, 'Venus::Task')
ERRORS
This package may raise the following errors:
- error:
error_on_system_call
-
This package may raise an error_on_system_call exception.
example 1
# given: synopsis; my @args = (['/path/to/nowhere', 'arg1', 'arg2'], $?); my $error = $task->throw('error_on_system_call', @args)->catch('error'); # my $name = $error->name; # "on_system_call" # my $message = $error->message; # "Can't make system call \"/path/to/nowhere arg1 arg2\": $?" # my $args = $error->stash('args'); # []
AUTHORS
Awncorp, awncorp@cpan.org
LICENSE
Copyright (C) 2000, Al Newkirk.
This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.