/ 
Do-1.88
River stage zero No dependents
/ Data::Object::Cli

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, +319

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 terms of the The Apache License, Version 2.0, as elucidated here, https://github.com/iamalnewkirk/do/blob/master/LICENSE.

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