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 1

# given: synopsis

package main;

my $set_data = $task->data([1..4]);

# [1..4]

data example 2

# given: synopsis

# given: example-1 data

package main;

my $get_data = $task->data;

# [1..4]

tryer

tryer(Venus::Try $data) (Venus::Try)

The tryer attribute is read-write, accepts (Venus::Try) values, and is optional.

Since 4.11

tryer example 1

# given: synopsis

package main;

my $set_tryer = $task->tryer($task->try('execute'));

# bless(..., "Venus::Try")

tryer example 2

# given: synopsis

# given: example-1 tryer

package main;

my $get_tryer = $task->tryer;

# bless(..., "Venus::Try")

INHERITS

This package inherits behaviors from:

Venus::Kind::Utility

INTEGRATES

This package integrates behaviors from:

Venus::Role::Buildable

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 1

# given: synopsis

package main;

my $args = $task->args;

# {}

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',
#   },
# }

auto

auto(coderef $code) (Venus::Task)

The auto class method is similar to the "run" method but accepts a callback which will be invoked with the instansiated class before calling the "execute" method. 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_AUTO environment variable is truthy.

Since 4.11

auto 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 $auto = $task->auto(sub{});

# bless({...}, 'Venus::Task')

auto example 2

package Example;

use base 'Venus::Task';

sub opts {

  return {
    help => {
      help => 'Display help',
      alias => ['h'],
    },
  }
}

auto Example sub {
  my ($self) = @_;
  $self->tryer->no_default;
};

# bless({...}, 'Venus::Task')

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 "args".

Since 2.91

cmds example 1

# given: synopsis

package main;

my $cmds = $task->cmds;

# {}

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() (Venus::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() (Venus::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. This method is not typically invoked directly, but instead by the "tryer" attribute via the "run" or "auto" class methods.

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(number $code, string | 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. If an exit code of undef is provided, the exit code will be determined by the result of the dispatching.

Since 2.91

exit example 1

# given: synopsis

package main;

my $exit = $task->exit;

# ()

exit example 2

# given: synopsis

package main;

my $exit = $task->exit(0);

# ()

exit example 3

# given: synopsis

package main;

my $exit = $task->exit(1);

# ()

exit example 4

# given: synopsis

package main;

my $exit = $task->exit(1, 'log_error', 'oh no');

# ()

fail

fail(string | 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

fail example 1

# given: synopsis

package main;

my $fail = $task->fail;

# ()

fail example 2

# given: synopsis

package main;

my $fail = $task->fail('log_error', 'oh no');

# ()

footer() (Venus::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

footer example 1

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) (Venus::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() (Venus::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() (string)

The help method can be overridden and returns a string representing "help" text for the CLI. By default this method returns the result of "help" in Venus::Cli, based on the "cli" object.

Since 2.91

help example 1

# given: synopsis

package main;

my $help = $task->help;

# "Usage: application"

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) (Venus::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) (Venus::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) (Venus::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) (Venus::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() (string)

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_level example 1

# given: synopsis

package main;

my $log_level = $task->log_level;

# "info"

log_trace

log_trace(any @log_trace) (Venus::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) (Venus::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() (Venus::Task)

The name method can be overridden and returns the name of the task (and application). This method defaults to $0 if not overridden.

Since 2.91

name example 1

# given: synopsis

package main;

my $name = $task->name;

# "/path/to/application"

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(string | 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

okay example 1

# given: synopsis

package main;

my $okay = $task->okay;

# ()

okay example 2

# given: synopsis

package main;

my $okay = $task->okay('log_info', 'yatta');

# ()

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 1

# given: synopsis

package main;

my $opts = $task->opts;

# {}

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(string $level, string @messages) (Venus::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')

pass

pass(string | coderef $code, any @args) (any)

The pass 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 3.10

pass example 1

# given: synopsis

package main;

my $pass = $task->pass;

# ()

pass example 2

# given: synopsis

package main;

my $pass = $task->pass('log_info', 'yatta');

# ()

prepare

prepare() (Venus::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) (Venus::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_AUTO 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) (Venus::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) (Venus::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(string @args) (Venus::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)

test

test(string $type, string $name) (any)

The test method validates the values for the arg or opt specified and returns the value(s) associated. This method dispatches to "test" in Venus::Cli.

Since 3.10

test 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 ($help) = $task->prepare->test('opt', 'help');

# true

test example 2

package Example;

use base 'Venus::Task';

sub opts {

  return {
    help => {
      type => 'string',
      help => 'Display help',
      alias => ['h'],
    },
  }
}

package main;

my $task = Example->new(['--help']);

my ($help) = $task->prepare->test('opt', 'help');

# Exception! (isa Venus::Cli::Error) (see error_on_arg_validation)

# Invalid option: help: received (undef), expected (string)

usage

usage() (Venus::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 $input = {
  throw => 'error_on_system_call',
  args => ['/path/to/nowhere', 'arg1', 'arg2'],
  error => $?,
};

my $error = $task->catch('error', $input);

# my $name = $error->name;

# "on_system_call"

# my $message = $error->render;

# "Can't make system call \"/path/to/nowhere arg1 arg2\": $?"

# my $args = $error->stash('args');

# []

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.

To install Venus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Venus

CPAN shell

perl -MCPAN -e shell
install Venus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

ABSTRACT

SYNOPSIS

DESCRIPTION

ATTRIBUTES

data

tryer

INHERITS

INTEGRATES

METHODS

args

auto

cmds

description

execute

exit

fail

footer

handler

header

help

log_debug

log_error

log_fatal

log_info

log_level

log_trace

log_warn

name

okay

opts

output

pass

prepare

run

shutdown

startup

system

test

usage

ERRORS

AUTHORS

LICENSE

Module Install Instructions