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.

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>

perl v5.36.0                                       2023-10-01             Commandable::Fi...::SubAttributes(3pm)