/ 
Commandable-0.14
River stage one • 4 direct dependents • 7 total dependents
/ Commandable::Finder::SubAttributes

NAME

Commandable::Finder::SubAttributes - find commands stored as subs with attributes

SYNOPSIS

use Commandable::Finder::SubAttributes;

my $finder = Commandable::Finder::SubAttributes->new(
   package => "MyApp::Commands",
);

my $help_command = $finder->find_command( "help" );

foreach my $command ( $finder->find_commands ) {
   ...
}

DESCRIPTION

This implementation of Commandable::Finder looks for functions that define commands, where each command is provided by an individual sub in a given package.

ATTRIBUTES

use Commandable::Finder::SubAttributes ':attrs';

sub command_example
   :Command_description("An example of a command")
{
   ...
}

Properties about each command are stored as attributes on the named function, using Attribute::Storage.

The following attributes are available on the calling package when imported with the :attrs symbol:

Command_description

:Command_description("description text")

Gives a plain string description text for the command.

Command_arg

:Command_arg("argname", "description")

Gives a named argument for the command and its description.

If the name is suffixed by a ?, this argument is optional. (The ? itself will be removed from the name).

If the name is suffixed by ..., this argument is slurpy. (The ... itself will be removed from the name).

Command_opt

:Command_opt("optname", "description")

:Command_opt("optname", "description", "default")

Gives a named option for the command and its description.

If the name contains | characters it provides multiple name aliases for the same option.

If the name field ends in a = character, a value is expected for the option. It can either be parsed from the next input token, or after an = sign of the same token:

--optname VALUE
--optname=VALUE

If the name field ends in a @ character, a value is expected for the option and can be specified multiple times. All the values will be collected into an ARRAY reference.

If the name field ends in a + character, the option can be specified multiple times and the total count will be used as the value.

If the name field ends in a ! character, the option is negatable. An option name of --no-OPTNAME is recognised and will reset the value to undef. By setting a default of some true value (e.g. 1) you can detect if this has happened.

An optional third argument may be present to specify a default value, if not provided by the invocation.

GLOBAL OPTION ATTRIBUTES

Since version 0.14 this module also allows attaching attributes to package variables in the package that stores the subroutines (often main), which will then be handled automatically as global options by the finder.

Remember that these have to be package variables (i.e. declared with our); lexical variables (declared with my) will not work.

our $VERBOSE
   :GlobalOption("verbose|v+", "Increase the verbosity of status output");

This often serves as a convenient alternative to modules like Getopt::Long, because it integrates with the help command automatically.

GlobalOption

:GlobalOption("optname", "description")

Gives the name for this global option and its description. These are handled in the same way as for "Command_opt" given above, except that no default is handled here. Instead, if the variable already has a value that will be taken as its default.

CONSTRUCTOR

new

$finder = Commandable::Finder::SubAttributes->new( %args )

Constructs a new instance of Commandable::Finder::SubAttributes.

Takes the following named arguments:

package => STR

The name of the package to look in for command subs.

name_prefix => STR

Optional. Gives the name prefix to use to filter for subs that actually provide a command, and to strip off to find the name of the command. Default command_.

underscore_to_hyphen => BOOL

Optional. If true, sub names that contain underscores will be converted into hyphens. This is often useful in CLI systems, allowing commands to be typed with hyphenated names (e.g. "get-thing") while the Perl sub that implements it is named with an underscores (e.g. "command_get_thing"). Defaults true, but can be disabled by passing a defined-but-false value such as 0 or ''.

Any additional arguments are passed to the configure method to be used as configuration options.

new_for_caller

new_for_main

$finder = Commandable::Finder::SubAttributes->new_for_caller( %args )
$finder = Commandable::Finder::SubAttributes->new_for_main( %args )

Convenient wrapper constructors that pass either the caller's package name or main as the package name. Combined with the find_and_invoke_ARGV method these are particularly convenient for wrapper scripts:

#!/usr/bin/perl

use v5.14;
use warnings;

use Commandable::Finder::SubAttributes ':attrs';

exit Commandable::Finder::SubAttributes->new_for_main
   ->find_and_invoke_ARGV;

# command subs go here...

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>