NAME

Data::Object::Cli

ABSTRACT

Data-Object CLI Base Class

SYNOPSIS

  package Command;

  use Data::Object 'Class';

  extends 'Data::Object::Cli';

  method main() {
    say $self->help->list;
  }

  run Command;

  __DATA__

  =pod help

  Do something!

  =pod sign

  {command}

  =pod spec

  action=s, verbose|v

  =cut

DESCRIPTION

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.

ATTRIBUTES

This package has the following attributes.

args

  args(ArgsObject)

The attribute is read-only, accepts (ArgsObject) values, and is optional.

data

  data(DataObject)

The attribute is read-only, accepts (DataObject) values, and is optional.

opts

  opts(OptsObject)

The attribute is read-only, accepts (OptsObject) values, and is optional.

vars

  vars(VarsObject)

The attribute is read-only, accepts (VarsObject) values, and is optional.

METHODS

This package implements the following methods.

exit

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

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 example

  $self->exit(0);
  $self->exit(1);

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

fail

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

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 example

  $self->fail;

  $self->fail($method_name, %args);
  $self->fail($method_name);

handle

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

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 example

  $self->handle($method_name, %args);
  $self->handle($method_name);

help

  help() : ArrayRef[Str]

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

help example

  =pod help

  ...

  =cut

  my $help = $self->help

main

  main(Any %args) : Any

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 example

  # $args{args} = $self->args; # represents @ARGV
  # $args{data} = $self->data; # represents __DATA__
  # $args{opts} = $self->opts; # represents Getopt::Long
  # $args{vars} = $self->vars; # represents %ENV

  $self->main(%args)

okay

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

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 example

  $self->okay;

  $self->okay($method_name, %args);
  $self->okay($method_name);

run

  run() : Any

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 example

  run __PACKAGE__;

sign

  sign() : HashRef[Int]

The sign method returns an hashref of named @ARGV positional arguments. These named arguments are accessible as methods on the Data::Object::Args object through the args attribute.

sign example

  =pod sign

  {command} {action}

  =cut

  $self->sign;

  # using the arguments

  $self->args->command; # $ARGV[0]
  $self->args->action; # $ARGV[1]

  $self->args->command($new_command);
  $self->args->action($new_action);

spec

  spec() : ArrayRef[Str]

The spec method returns an arrayref of Getopt::Long option specs. By default, this package look for those specs as a comma-separated list in the POD section named "spec", short for "options specifications". These options are accessible as methods on the Data::Object::Opts object through the opts attribute.

spec example

  =pod spec

  resource|r=s, verbose|v, help|h

  =cut

  $self->spec;

  # using the options

  $self->opts->resource;
  $self->opts->verbose;

  $self->opts->resource($new_resource);
  $self->opts->verbose(0);

CREDITS

Al Newkirk, +309

Anthony Brummett, +10

Adam Hopkins, +2

José Joaquín Atria, +1

AUTHOR

Al Newkirk, awncorp@cpan.org

LICENSE

Copyright (C) 2011-2019, Al Newkirk, et al.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

PROJECT

Wiki

Project

Initiatives

Milestones

Contributing

Issues

SEE ALSO

To get the most out of this distribution, consider reading the following:

Do

Data::Object

Data::Object::Class

Data::Object::ClassHas

Data::Object::Role

Data::Object::RoleHas

Data::Object::Library

cpanm Do

perl -MCPAN -e shell
install Do