Data::Object::Cli

Simple CLIs

Command-line Interface Abstraction for Perl 5

method: auto method: exit method: fail method: handle method: help method: main method: okay method: run method: spec method: subs

package Command;

use parent 'Data::Object::Cli';

sub main {
  my ($self) = @_;

  return $self->help;
}

my $command = run Command;

Data::Object::Types

args: ro, opt, ArgsObject data: ro, opt, DataObject opts: ro, opt, OptsObject vars: ro, opt, VarsObject

This package provides an abstract base class for defining command-line interface classes, which can be run as scripts or passed as objects in a more complex system.

The auto method is expected to be overridden by the subclass and should return a hashref where the keys represent a subcommand at $ARGV[0] and the value represents the subroutine to be dispatched to using the handle method. To enable this functionality, the command name be declare a "command" token.

auto(Any %args) : HashRef

=example-1 auto

package Todo;

use parent 'Data::Object::Cli';

our $name = 'todo <{command}>';

sub auto {
  {
    init => '_handle_init'
  }
}

sub _handle_init {
  1234567890
}

my $todo = run Todo;

The exit method exits the program using the exit code provided. The exit code defaults to 0. Optionally, you can call a handler before exiting by providing a method name with arguments. The handler will be called using the handle method so the arguments should be key/value pairs.

exit(Int $code, Maybe[Str] $name, Any %args) : Any

=example-1 exit

# given: synopsis

$command->exit(0);

# $command->exit($code, $method_name, %args);
# $command->exit($code, $method_name);
# $command->exit($code);

=example-2 exit

# given: synopsis

$command->exit(1);

# $command->exit($code, $method_name, %args);
# $command->exit($code, $method_name);
# $command->exit($code);

The fail method exits the program with a 1 exit code. Optionally, you can call a handler before exiting by providing a method name with arguments. The handler will be called using the handle method so the arguments should be key/value pairs.

fail(Maybe[Str] $name, Any %args) : Any

=example-1 fail

# given: synopsis

$command->fail;

# $command->fail($method_name, %args);
# $command->fail($method_name);

The handle method dispatches to the method whose name is provided as the first argument. The forwarded method will receive arguments as key/value pairs. This method injects the args, data, vars, and opts attributes as arguments for convenience of use in the forwarded method. Any additional arguments should be passed as key/value pairs.

handle(Str $name, Any %args) : Any

=example-1 handle

# given: synopsis

$command->handle('main');

# $command->handle($method_name, %args);
# $command->handle($method_name);

The help method returns the help text documented in POD if available.

help() : Str

=example-1 help

package Todolist;

use parent 'Data::Object::Cli';

my $todolist = run Todolist;

# $todolist->help

=example-2 help

package Todolist;

use parent 'Data::Object::Cli';

our $name = 'todolist';

my $todolist = run Todolist;

# $todolist->help

=example-3 help

package Todolist;

use parent 'Data::Object::Cli';

sub name {
  'todolist'
}

my $todolist = run Todolist;

# $todolist->help

=example-4 help

package Todolist;

use parent 'Data::Object::Cli';

our $name = 'todolist';
our $info = 'manage your todo list';

my $todolist = run Todolist;

# $todolist->help

=example-5 help

package Todolist;

use parent 'Data::Object::Cli';

sub name {
  'todolist'
}

sub info {
  'manage your todo list'
}

my $todolist = run Todolist;

# $todolist->help

=example-6 help

package Todolist::Command::Show;

use parent 'Data::Object::Cli';

sub name {
  'todolist show [<{priority}>]'
}

sub info {
  'show your todo list tasks by priority levels'
}

my $command = run Todolist::Command::Show;

# $command->help

The main method is the "main method" and entrypoint into the program. It's called automatically by the run method if your package is configured as recommended. This method accepts arguments as key/value pairs, and if called by run will receive the args, data, opts, and vars objects.

main(Any %args) : Any

=example-1 main

package Todolist;

use parent 'Data::Object::Cli';

sub main {
  my ($self, %args) = @_;

  return {%args} # no args
}

my $todolist = run Todolist;

$todolist->main;

=example-2 main

package Todolist;

use parent 'Data::Object::Cli';

sub main {
  my ($self, %args) = @_;

  # has $args{args}
  # has $args{data}
  # has $args{opts}
  # has $args{vars}

  return {%args}
}

# $args{args} = $self->args; # isa <Data::Object::Args>
# represents @ARGV

# $args{data} = $self->data; # isa <Data::Object::Data>
# represents __DATA__

# $args{opts} = $self->opts; # isa <Data::Object::Opts>
# represents Getopt::Long

# $args{vars} = $self->vars; # isa <Data::Object::Vars>
# represents %ENV

my $todolist = run Todolist;

$todolist->handle('main'); # called automatically by run

The okay method exits the program with a 0 exit code. Optionally, you can call a handler before exiting by providing a method name with arguments. The handler will be called using the handle method so the arguments should be key/value pairs.

okay(Maybe[Str] $name, Any %args) : Any

=example-1 okay

# given: synopsis

$command->okay;

# $command->okay($method_name, %args);
# $command->okay($method_name);

The run method is designed to bootstrap the program. It detects whether the package is being invoked as a script or class and behaves accordingly. It will be called automatically when the package is looaded if your package is configured as recommended. This method will, if invoked as a script, call the main method passing the args, data, opts, and vars objects.

run() : Object

=example-1 run

package Todolist;

use parent 'Data::Object::Cli';

run Todolist;

The spec method returns a hashref of flag definitions used to configure Getopt::Long. These options are accessible as methods on the Data::Object::Opts object through the opts attribute. Each flag definition can optionally declare args, flag, and type values as follows. The args property denotes that multiple flags are permitted and its value can be any valid Getopt::Long repeat specifier. The type property denotes the type of data allowed and defaults to type flag. Allowed values are string, integer, number, float, or flag. The flag property denotes the flag aliases and should be a pipe-delimited string, e.g. userid|id|u, if multiple aliases are used.

spec() : HashRef[HashRef]

=example-1 spec

package Todolist::Task;

use parent 'Data::Object::Cli';

our $name = 'todotask {id}';

# id accessible as $self->args->id; alias of $ARGV[0]

sub spec {
  {
    #
    # represented in Getopt::Long as
    # title|t=s
    #
    # title is accessible as $self->opts->title
    #
    title => {
      type => 'string',
      flag => 't'
    },
    #
    # represented in Getopt::Long as
    # content=s
    #
    # content is accessible as $self->opts->content
    #
    content => {
      type => 'string',
    },
    #
    # represented in Getopt::Long as
    # attach|a=s@
    #
    # attach is accessible as $self->opts->attach
    #
    attach => {
      flag => 'a',
      args => '@' # allow multiple options
    },
    #
    # represented in Getopt::Long as
    # publish|p
    #
    # publish is accessible as $self->opts->publish
    #
    publish => {
      flag => 'p',
      type => 'flag'
    },
    #
    # represented in Getopt::Long as
    # unpublish|u
    #
    # unpublish is accessible as $self->opts->unpublish
    #
    unpublish => {
      flag => 'u'
      # defaults to type: flag
    }
  }
}

my $todotask = run Todolist::Task;

# $todotask->spec

The subs method works in tandem with the "auto" method and is expected to be overridden by the subclass and should return a hashref where the keys represent a subcommand at $ARGV[0] and the value represents the description of the corresponding action (i.e. command).

subs(Any %args) : HashRef

=example-1 subs

package Todo::Admin;

use parent 'Data::Object::Cli';

our $name = 'todo <action>';

sub auto {
  {
    add_user => '_handle_add_user',
    del_user => '_handle_del_user'
  }
}

sub subs {
  {
    add_user => 'Add a new user to the system',
    del_user => 'Remove a user to the system'
  }
}

my $admin = run Todo::Admin;

__DATA__

Usage: {name}

Commands:

{commands}

Options:

{options}

cpanm Data::Object::Cli

perl -MCPAN -e shell
install Data::Object::Cli