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_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>