NAME

Venus::Run - Runner Class

ABSTRACT

Runner Class for Perl 5

SYNOPSIS

  package main;

  use Venus::Run;

  my $run = Venus::Run->new;

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

DESCRIPTION

This package is a Venus::Task which provides generic task running capabilities. A simple CLI using this package has been made available in vns.

USAGES

Here is an example configuration file in YAML (e.g. in .vns.yaml).

  ---
  data:
    ECHO: true
  exec:
    okay: \$PERL -c
    cpan: cpanm -llocal -qn
    deps: cpan --installdeps .
    each: \$PERL -MVenus=log -nE
    exec: \$PERL -MVenus=log -E
    repl: \$PERL -dE0
    says: exec "map log(\$_), map eval, \@ARGV"
    test: \$PROVE
  libs:
  - -Ilib
  - -Ilocal/lib/perl5
  load:
  - -MVenus=true,false
  path:
  - ./bin
  - ./dev
  - -Ilocal/bin
  perl:
    perl: perl
    prove: prove
  vars:
    PERL: perl
    PROVE: prove

The following describes the configuration file sections and how they're used:

The data section provides a non-dynamic list of key/value pairs that will be used as environment variables.
The exec section provides the main dynamic tasks which can be recursively resolved and expanded.
The find section provides aliases which can be recursively resolved and expanded for use in other tasks.
The libs section provides a list of -I/path/to/lib "include" statements that will be automatically added to tasks expanded from the perl section.
The load section provides a list of -MPackage "import" statements that will be automatically added to tasks expanded from the perl section.
The path section provides a list of paths to be prepended to the PATH environment variable which allows programs to be found.
The perl section provides the dynamic perl tasks which can serve as tasks with default commands (with options) and which can be recursively resolved and expanded.
The task section provides the dynamic perl tasks which "load" Venus::Task derived packages, and which can be recursively resolved and expanded. These tasks will typically take the form of perl -Ilib -MMyApp::Task -E0 -- and will be automatically executed as a CLI.
The vars section provides a list of dynamic key/value pairs that can be recursively resolved and expanded and will be used as environment variables.

Here are example usages using the example YAML configuration file and the vns CLI.

  # Mint a new configuration file
  vns init

  ...

  # Install a distribution
  vns cpan $DIST

  i.e. $(which cpanm) --llocal -qn $DIST

  # Install dependencies in the CWD
  vns deps

  i.e. $(which cpanm) --llocal -qn --installdeps .

  # Check that a package can be compiled
  vns okay $FILE

  i.e. $(which perl) -Ilib -Ilocal/lib/perl5 -c $FILE

  # Use the Perl debugger as a REPL
  vns repl

  i.e. $(which perl) -Ilib -Ilocal/lib/perl5 -dE0

  # Evaluate arbitrary Perl expressions
  vns exec ...

  i.e. $(which perl) -Ilib -Ilocal/lib/perl5 -MVenus=log -E $@

  # Test the Perl project in the CWD
  vns test t

  i.e. $(which prove) -Ilib -Ilocal/lib/perl5 t

This package and CLI allows you to define task definitions for any application, which you can run using the name of the task. You can reuse existing task definitions in new tasks which will be recursively resolved when needed. You can define static and dynamic environment variables, and also pre-define "includes" and the order in which they're declared.

INHERITS

This package inherits behaviors from:

Venus::Task

METHODS

This package provides the following methods:

args

  args() (HashRef)

The args method returns the task argument declarations.

Since 2.91

args example 1

  # given: synopsis

  package main;

  my $args = $run->args;

  # {
  #   'command' => {
  #     help => 'Command to run',
  #     required => 1,
  #   }
  # }

cmds

  cmds() (HashRef)

The cmds method returns the task command declarations.

Since 2.91

cmds example 1

  # given: synopsis

  package main;

  my $cmds = $run->cmds;

  # {
  #   'help' => {
  #     help => 'Display help and usages',
  #     arg => 'command',
  #   },
  #   'init' => {
  #     help => 'Initialize the configuration file',
  #     arg => 'command',
  #   },
  # }

conf

  conf() (HashRef)

The conf method loads the configuration file returned by "file", then decodes and returns the information as a hashref.

Since 2.91

conf example 1

  # given: synopsis

  package main;

  my $conf = $run->conf;

  # {}

conf example 2

  # given: synopsis

  package main;

  local $ENV{VENUS_FILE} = 't/conf/.vns.pl';

  my $conf = $run->conf;

  # {...}

conf example 3

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.yaml file

  my $conf = $run->conf;

  # {...}

conf example 4

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.yml file

  my $conf = $run->conf;

  # {...}

conf example 5

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.json file

  my $conf = $run->conf;

  # {...}

conf example 6

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.js file

  my $conf = $run->conf;

  # {...}

conf example 7

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.perl file

  my $conf = $run->conf;

  # {...}

conf example 8

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.pl file

  my $conf = $run->conf;

  # {...}

file

  file() (Str)

The file method returns the configuration file specified in the VENUS_FILE environment variable, or the discovered configuration file in the current directory. The default name for a configuration file is in the form of .vns.*. Configuration files will be decoded based on their file extensions. Valid file extensions are yaml, yml, json, js, perl, and pl.

Since 2.91

file example 1

  # given: synopsis

  package main;

  my $file = $run->file;

  # undef

file example 2

  # given: synopsis

  package main;

  local $ENV{VENUS_FILE} = 't/conf/.vns.pl';

  my $file = $run->file;

  # "t/conf/.vns.pl"

file example 3

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.yaml file

  my $file = $run->file;

  # ".vns.yaml"

file example 4

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.yml file

  my $file = $run->file;

  # ".vns.yml"

file example 5

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.json file

  my $file = $run->file;

  # ".vns.json"

file example 6

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.js file

  my $file = $run->file;

  # ".vns.js"

file example 7

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.perl file

  my $file = $run->file;

  # ".vns.perl"

file example 8

  # given: synopsis

  package main;

  # e.g. current directory has only a .vns.pl file

  my $file = $run->file;

  # ".vns.pl"

  footer() (Str)

The footer method returns examples and usage information used in usage text.

Since 2.91

footer example 1

  # given: synopsis

  package main;

  my $footer = $run->footer;

  # "..."

handler

  handler(HashRef $data) (Any)

The handler method processes the data provided and executes the request then returns the invocant unless the program is exited.

Since 2.91

handler example 1

  package main;

  use Venus::Run;

  my $run = Venus::Run->new;

  $run->execute;

  # ()

handler example 2

  package main;

  use Venus::Run;

  my $run = Venus::Run->new(['help']);

  $run->execute;

  # ()

handler example 3

  package main;

  use Venus::Run;

  my $run = Venus::Run->new(['--help']);

  $run->execute;

  # ()

handler example 4

  package main;

  use Venus::Run;

  my $run = Venus::Run->new(['init']);

  $run->execute;

  # ()

handler example 5

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['echo']);

  $run->execute;

  # ()

  # i.e. ['echo']

handler example 6

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['cpan', 'Venus']);

  $run->execute;

  # ()

  # i.e. cpanm '-llocal' '-qn' Venus

handler example 7

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['deps']);

  $run->execute;

  # ()

  # i.e. cpanm '-llocal' '-qn' '--installdeps' '.'

handler example 8

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['okay', 'lib/Venus.pm']);

  $run->execute;

  # ()

  # i.e. perl '-Ilib' '-Ilocal/lib/perl5' '-c'

handler example 9

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['repl']);

  $run->execute;

  # ()

  # i.e. perl '-Ilib' '-Ilocal/lib/perl5' '-dE0'

handler example 10

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['exec', '-MVenus=date', 'say date']);

  $run->execute;

  # ()

  # i.e. perl '-Ilib' '-Ilocal/lib/perl5' '-MVenus=date' 'say date'

handler example 11

  package main;

  use Venus::Run;

  # on linux

  my $run = Venus::Run->new(['test', 't']);

  $run->execute;

  # ()

  # i.e. prove '-Ilib' '-Ilocal/lib/perl5' t

init

  init() (HashRef)

The init method returns the default configuration to be used when initializing the system with a new configuration file.

Since 2.91

init example 1

  # given: synopsis

  package main;

  my $init = $run->init;

  # {
  #   data => {
  #     ECHO => 1,
  #   },
  #   exec => {
  #     brew => 'perlbrew',
  #     cpan => 'cpanm -llocal -qn',
  #     deps => 'cpan --installdeps .',
  #     each => '$PERL -MVenus=true,false,log -nE',
  #     eval => '$PERL -MVenus=true,false,log -E',
  #     exec => '$PERL',
  #     info => '$PERL -V',
  #     okay => '$PERL -c',
  #     repl => '$PERL -dE0',
  #     says => 'eval "map log($_), map eval, @ARGV"',
  #     test => '$PROVE'
  #   },
  #   find => {
  #   },
  #   libs => [
  #     '-Ilib',
  #     '-Ilocal/lib/perl5',
  #   ],
  #   load => [
  #   ],
  #   path => [
  #     './bin',
  #     './dev',
  #     './local/bin',
  #   ],
  #   perl => {
  #     perl => 'perl',
  #     prove => 'prove',
  #     'perl-5.18.0' => 'perlbrew exec --with perl-5.18.0 perl',
  #     'prove-5.18.0' => 'perlbrew exec --with perl-5.18.0 prove'
  #   },
  #   task => {
  #   },
  #   vars => {
  #     PERL => 'perl',
  #     PROVE => 'prove'
  #   },
  # }

name

  name() (Str)

The name method returns the default name for the task. This is used in usage text and can be controlled via the VENUS_RUN_NAME environment variable, or the NAME package variable.

Since 2.91

name example 1

  # given: synopsis

  package main;

  my $name = $run->name;

  # "Venus::Run"

name example 2

  # given: synopsis

  package main;

  local $ENV{VENUS_RUN_NAME} = 'venus-runner';

  my $name = $run->name;

  # "venus-runner"

name example 3

  # given: synopsis

  package main;

  local $Venus::Run::NAME = 'venus-runner';

  my $name = $run->name;

  # "venus-runner"

opts

  opts() (HashRef)

The opts method returns the task options declarations.

Since 2.91

opts example 1

  # given: synopsis

  package main;

  my $opts = $run->opts;

  # {
  #   'help' => {
  #     help => 'Show help information',
  #   }
  # }

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

USAGES

INHERITS

METHODS

args

cmds

conf

file

footer

handler

init

name

opts

AUTHORS

LICENSE

Module Install Instructions