.\" 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::Command 3pm" .TH Commandable::Command 3pm "2023-10-01" "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::Command" \- represent metadata for an invokable command .SH "ACCESSORS" .IX Header "ACCESSORS" The following simple methods return metadata fields about the command .SS "name" .IX Subsection "name" .SS "description" .IX Subsection "description" .Vb 2 \& $name = $command\->name; \& $desc = $command\->description; .Ve .PP Strings giving the short name (to be used on a commandline), and descriptive text for the command. .SS "arguments" .IX Subsection "arguments" .Vb 1 \& @args = $command\->arguments; .Ve .PP A (possibly-empty) list of argument metadata structures. .SS "options" .IX Subsection "options" .Vb 1 \& %opts = $command\->options; .Ve .PP A (possibly-empty) kvlist of option metadata structures. .SS "package" .IX Subsection "package" .Vb 1 \& $pkg = $command\->packaage; .Ve .PP The package name as a plain string. .SS "code" .IX Subsection "code" .Vb 1 \& $sub = $command\->code; .Ve .PP A \s-1CODE\s0 reference to the code actually implementing the command. .SS "config" .IX Subsection "config" .Vb 1 \& $conf = $command\->config; .Ve .PP A \s-1HASH\s0 reference to the configuration of the command. .SH "METHODS" .IX Header "METHODS" .SS "parse_invocation" .IX Subsection "parse_invocation" .Vb 1 \& @vals = $command\->parse_invocation( $cinv ); .Ve .PP Parses values out of a Commandable::Invocation instance according to the specification for the command's arguments. Returns a list of perl values suitable to pass into the function implementing the command. .PP This method will throw an exception if mandatory arguments are missing. .SH "ARGUMENT SPECIFICATIONS" .IX Header "ARGUMENT SPECIFICATIONS" Each argument specification is given by an object having the following structure: .SS "name" .IX Subsection "name" .SS "description" .IX Subsection "description" .Vb 1 \& $name = $argspec\->name; \& \& $desc = $argspec\->description; .Ve .PP Text strings for the user, used to generate the help text. .SS "optional" .IX Subsection "optional" .Vb 1 \& $bool = $argspec\->optional; .Ve .PP If false, the option is mandatory and an error is raised if no value is provided for it. If true, it is optional and if absent an \f(CW\*(C`undef\*(C'\fR will passed instead. .SS "slurpy" .IX Subsection "slurpy" .Vb 1 \& $bool = $argspec\->slurpy; .Ve .PP If true, the argument will be passed as an \s-1ARRAY\s0 reference containing the entire remaining list of tokens provided by the user. .SH "OPTION SPECIFICATIONS" .IX Header "OPTION SPECIFICATIONS" Each option specification is given by an object having the following structure: .SS "name" .IX Subsection "name" .Vb 1 \& $name = $optspec\->name; .Ve .PP A string giving the name of the option. This is the name it will be given in the options hash provided to the command subroutine. .SS "names" .IX Subsection "names" .Vb 1 \& @names = $optspec\->names; .Ve .PP A list containing the name plus all the aliases this option is known by. .SS "description" .IX Subsection "description" .Vb 1 \& $desc = $optspec\->description; .Ve .PP A text string containing information for the user, used to generate the help text. .SS "mode" .IX Subsection "mode" .Vb 1 \& $mode = $optspec\->mode; .Ve .PP A string that describes the behaviour of the option. .PP \&\f(CW\*(C`set\*(C'\fR options do not expect a value to be suppled by the user, and will store a true value in the options hash if present. .PP \&\f(CW\*(C`value\*(C'\fR options take a value from the rest of the token, or the next token. .PP .Vb 2 \& \-\-opt=value \& \-\-opt value .Ve .PP \&\f(CW\*(C`multi_value\*(C'\fR options can be supplied more than once; values are pushed into an \s-1ARRAY\s0 reference which is passed in the options hash. .PP \&\f(CW\*(C`inc\*(C'\fR options may be supplied more than once; each occurance will increment the stored value by one. .SS "default" .IX Subsection "default" .Vb 1 \& $val = $optspec\->default; .Ve .PP A value to provide in the options hash if the user did not specify a different one. .SS "negatable" .IX Subsection "negatable" .Vb 1 \& $bool = $optspec\->negatable; .Ve .PP If true, also accept a \f(CW\*(C`\-\-no\-OPT\*(C'\fR option to reset the value of the option to \&\f(CW\*(C`undef\*(C'\fR. .SS "typespec" .IX Subsection "typespec" .Vb 1 \& $type = $optspec\->typespec; .Ve .PP If defined, gives a type specification that any user-supplied value must conform to. .PP The \f(CW\*(C`i\*(C'\fR type must be a string giving a (possibly-negative) decimal integer. .SH "AUTHOR" .IX Header "AUTHOR" Paul Evans