.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Commandable::Finder::Packages 3pm"
.TH Commandable::Finder::Packages 3pm "2023-01-08" "perl v5.36.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
"Commandable::Finder::Packages" \- find commands stored per package
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Commandable::Finder::Packages;
\&
\&   my $finder = Commandable::Finder::Packages\->new(
\&      base => "MyApp::Command",
\&   );
\&
\&   my $help_command = $finder\->find_command( "help" );
\&
\&   foreach my $command ( $finder\->find_commands ) {
\&      ...
\&   }
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This implementation of Commandable::Finder looks for implementations of
commands, where each command is implemented by a different package somewhere
in the symbol table.
.PP
This class uses Module::Pluggable to load packages from the filesystem.
As commands are located per package (and not per file), the application can
provide special-purpose internal commands by implementing more packages in the
given namespace, regardless of which files they come from.
.SH "CONSTANTS"
.IX Header "CONSTANTS"
.Vb 1
\&   package My::App::Commands::example;
\&
\&   use constant COMMAND_NAME => "example";
\&   use constant COMMAND_DESC => "an example of a command";
\&
\&   ...
.Ve
.PP
Properties about each command are stored as methods (usually constant methods)
within each package. Often the constant pragma module is used to create
them.
.PP
The following constant names are used by default:
.SS "\s-1COMMAND_NAME\s0"
.IX Subsection "COMMAND_NAME"
.Vb 1
\&   use constant COMMAND_NAME => "name";
.Ve
.PP
Gives a string name for the command.
.SS "\s-1COMMAND_DESC\s0"
.IX Subsection "COMMAND_DESC"
.Vb 1
\&   use constant COMMAND_DESC => "description";
.Ve
.PP
Gives a string description for the command.
.SS "\s-1COMMAND_ARGS\s0"
.IX Subsection "COMMAND_ARGS"
.Vb 3
\&   use constant COMMAND_ARGS => (
\&      { name => "argname", description => "description" },
\&   );
.Ve
.PP
Gives a list of command argument specifications. Each specification is a \s-1HASH\s0
reference corresponding to one positional argument, and should contain keys
named \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`description\*(C'\fR, and optionally \f(CW\*(C`optional\*(C'\fR.
.SS "\s-1COMMAND_OPTS\s0"
.IX Subsection "COMMAND_OPTS"
.Vb 3
\&   use constant COMMAND_OPTS => (
\&      { name => "optname", description => "description" },
\&   );
.Ve
.PP
Gives a list of command option specifications. Each specification is a \s-1HASH\s0
reference giving one named option, in no particular order, and should contain
keys named \f(CW\*(C`name\*(C'\fR, \f(CW\*(C`description\*(C'\fR and optionally \f(CW\*(C`mode\*(C'\fR and \f(CW\*(C`default\*(C'\fR.
.SH "CONSTRUCTOR"
.IX Header "CONSTRUCTOR"
.SS "new"
.IX Subsection "new"
.Vb 1
\&   $finder = Commandable::Finder::Packages\->new( %args )
.Ve
.PP
Constructs a new instance of \f(CW\*(C`Commandable::Finder::Packages\*(C'\fR.
.PP
Takes the following named arguments:
.IP "base => \s-1STR\s0" 4
.IX Item "base => STR"
The base of the package namespace to look inside for packages that implement
commands.
.IP "name_method => \s-1STR\s0" 4
.IX Item "name_method => STR"
Optional. Gives the name of the method inside each command package to invoke
to generate the name of the command. Default \f(CW\*(C`COMMAND_NAME\*(C'\fR.
.IP "description_method => \s-1STR\s0" 4
.IX Item "description_method => STR"
Optional. Gives the name of the method inside each command package to invoke
to generate the description text of the command. Default \f(CW\*(C`COMMAND_DESC\*(C'\fR.
.IP "arguments_method => \s-1STR\s0" 4
.IX Item "arguments_method => STR"
Optional. Gives the name of the method inside each command package to invoke
to generate a list of argument specifications. Default \f(CW\*(C`COMMAND_ARGS\*(C'\fR.
.IP "options_method => \s-1STR\s0" 4
.IX Item "options_method => STR"
Optional. Gives the name of the method inside each command package to invoke
to generate a list of option specifications. Default \f(CW\*(C`COMMAND_OPTS\*(C'\fR.
.IP "code_method => \s-1STR\s0" 4
.IX Item "code_method => STR"
Optional. Gives the name of the method inside each command package which
implements the actual command behaviour. Default \f(CW\*(C`run\*(C'\fR.
.IP "named_by_package => \s-1BOOL\s0" 4
.IX Item "named_by_package => BOOL"
Optional. If true, the name of each command will be taken from its package
name. with the leading \f(CW\*(C`base\*(C'\fR string removed. If absent or false, the
\&\f(CW\*(C`name_method\*(C'\fR will be used instead.
.PP
If either name or description method are missing from a package, that package
is silently ignored.
.PP
Any additional arguments are passed to the \f(CW\*(C`configure\*(C'\fR method to be used as
configuration options.
.SH "AUTHOR"
.IX Header "AUTHOR"
Paul Evans <leonerd@leonerd.org.uk>