/ 
Commandable-0.06
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 ? character, this argument is optional. (The ? character itself will be removed from the name).

Command_opt

:Command_opt("optname", "description")

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

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

:Command_opt("optname", "description", "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_.

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>