NAME
Getopt::Tree - Get tree-like options (like the route command).
ABSTRACT
Getopt::Tree is a module to help parse and validate command line parameters built on top of Getopt::Long. Getopt::Tree allows the developer to specify an array parameters, including the name, abbreviation, type, description, and any parameters that are applicable to and/or dependent on that parameter.
EXAMPLE
Simple "route" example
# Accept the commands add, remove, print, and their associated dependent
# options.
my $p = [
{
name => 'add',
exists => 1,
descr => 'Add a new route',
params => [
{
name => 'gateway',
abbr => 'gw',
descr => 'Remote gateway for this network',
},
{
name => 'network',
abbr => 'net',
descr => 'Network address to add route for',
},
{
name => 'subnet',
abbr => 'mask',
descr => 'Subnet mask for the given network',
},
],
},
{
name => 'remove',
abbr => 'delete',
exists => 1,
descr => 'Delete a route',
params => [
{
name => 'network',
abbr => 'net',
descr => 'Network address to delete',
},
{
name => 'subnet',
abbr => 'mask',
descr => 'Subnet mask for the given network',
},
],
},
{
name => 'print',
exists => 1,
descr => 'Display routing table',
},
];Complex example
my $p = [
# Required global parameter.
{ name => 'user', leaf => 1, eval => sub { my ( $p ) = @_; return 1 if $p =~ /^[a-z]+$/i; },
# Optional global parameter.
{
name => 'no-cache',
abbr => 'nc',
exists => 1,
optional => 1,
descr => 'Don\'t cache your credentials in /tmp/.'
},
# Start of a branch. If one or more branches exist, at least one must be
# followed.
{
name => 'search',
abbr => 's',
descr => 'Search for ticket, list tickets in queue, or print contents of a ticket.',
params => [
{
name => 'ticket', # field name
abbr => 't', # alternate name
re => TICKET_REGEX, # field must match re
descr => 'The ticket number to search for.', # auto-doc
params => [
{ # fields that are allowed if this field is set
name => 'show-all-worklog-fields',
exists => 1, # I just want a 1 or a 0 if set
optional => 1,
descr => 'Show all worklog fields.'
},
{
name => 'show-all-fields',
multi => 1, # can be set multiple times, returns arrayref
exists => 1, # unless exists is set too, then you just get the count
descr => 'Show all ticket fields.'
},
],
},
],
}
];
my ( $operation, $params ) = parse_command_line( $p );
if ( !$operation ) { print_usage( $p ); die; }
print "Performing $operation!\n"USAGE
Two functions are exported by default: parse_command_line and print_usage.
Functions
parse_command_line
Parses the command line (@ARGV) based on the specified data structure.
Accepts two parameters. The first is a required array reference describing the possible command line parameters. It returns three values, the "top level" option, a hashref of the other specified options, and an arrayref of any remaining unparsed options (similar to Getopt::Long).
The second parameter is an optional array reference or string from which the parameters are to be read, rather than reading them from @ARGV. If a string is passed, it will be converted to an array via Text::ParseWords::shellwords.
If the command line was unable to be parsed (the passed data structure was inconsistent, etc), parse_command_line will die with an appropriate error message. If the command line was invalid (the user entered something that did not meet the given requirements, etc) a warning will be printed and undef will be returned.
print_usage
Prints usage information based on the specified data structure.
Takes two parameters, the first is a required array reference describing the possible command line parameters, and the second is an optional file handle to which the usage information will be printed. Alternately, in place of a filehandle, a hashref of options can be passed. Valid options are:
- fh
-
The filehandle to print to. If not set, no output is printed.
- return
-
A boolean value that determines whether or not the usage should be returned as a string.
- wrap_at
-
Number of characters to wrap the output at. Will be auto-detected from $ENV{COLUMNS} if not set, defaults to 80 if auto-detection fails.
- hide_top_line
-
Hides the top line of output which contains the program name how to pass switches.
Usage information is generated mostly from the "descr" fields in the data structure, indentation is based on parameter dependence, parameters that accept values are noted, and optional parameters are presented inside of brackets.
Configuration
The "expected command line configuration data structure" will be referred to as "the data structure" because I can't think of a better name for it.
Concepts
The design is similar to the Unix "route" command, in which a "top level" command (such as "add" or "delete") will have zero or more dependent parameters (such as the "gateway" or "subnet"). Getopt::Tree uses Getopt::Long to actually parse the command line, but adds a layer of logic on top to discover which top level command and dependent options the user specified. Conflicting options, parameter types, and usage document generation are all handled by Getopt::Tree based on the data structure supplied by the developer.
Commands are separated into two types, top level and dependent. At least on top level command is required. Once Getopt::Tree identifies the proper top level command, it will look for the dependent commands that apply to the specified top level command. Since each dependent command can also have dependent commands, the process is repeated until no more commands are found.
Each set of dependents in the tree is considered a "level", with the top level being the first set of entries in the structure, and each successive level being composed of the dependents of the prior level. Note that a level could simply be described as the distance to the top of a tree, where as a "branch" would be the specific set of dependents for a given command, irrespective of dependents of commands on the same level.
Data Structure
The data structure is composed of an array of hashrefs. Each hashref describes a single parameter. Each hashref in the array contains various options describing the parameter. Valid options are as follows:
name
Full parameter name. Required. Must not contain the characters "@", "|", or "=" and must not conflict with other names or abbreviations in the same branch. This is the name that will be returned, if the parameter is set, by parse_command_line.
abbr
Parameter abbreviation. Will be accepted on the command line in place of the proper name, but must obey the same rules as the proper name.
optional
Defines whether this parameter is optional. Boolean. Defaults to false, ie, the parameter is required.
exists
Defines whether or not the parameter has a value or whether it should simply be checked for existence. Boolean. Defaults to false, ie, the parameter must have a value.
leaf
Defines whether or not the parameter should be considered a "leaf" on the current branch or not. A leaf is a required parameter at the current level and has no dependents. Useful to place a required parameter that applies to multiple branches without specifying the required parameter in each branch. Conflicts with "optional" and "params". Defaults to false, ie, this parameter is not a leaf.
params
An optional arrayref of hashrefs representing parameters dependent on this parameter. Format is exactly the same as for the primary data structure.
descr
Textural description of what the parameter is and does. Used as part of the usage information. If not set, a placeholder is supplied.
multi
Defines whether or not this parameter can be specified multiple times or not. Boolean. Defaults to false.
re
Defines a regular expression to match values against. The result of the first capture of this expression will be treated as the value in place of the user-specified value. If no capture is found or the match fails, the parameter will be treated as invalid. Conflicts with "exists". If both "re" and "eval" are specified, "re" will be processed first and the result passed to "eval".
eval
Defines a subroutine to be called to validate the value passed for this parameter. The returned value from the subroutine will be used in place of the user-specified value. If undef is returned, the parameter is treated as invalid. Conflicts with "exists". If both "re" and "eval" are specified, "re" will be processed first and the result passed to "eval".
VARIABLES
$Getopt::Tree::USAGE_HEADER
Text to be printed near the top of the "usage" output.
$Getopt::Tree::USAGE_HEADER
Text to be printed at the end of the "usage" output.
$Getopt::Tree::SWITCH_PREFIX_STR
Characters to prefix a switch. Defaults to a single hyphen ('-'). Can be set to an empty string to use switchless options (Note: This option is not well tested!).
NOTES
You can't have a dependent parameter of the same name as a non-optional parameter higher in the tree. If the parser sees a two instances of the same parameter it will bail, so you have to make sure that there are no identically named parameters in one part of the tree as in another part of the tree that the parser passes through. Example:
{ name => 'bad' },
{ name => 'normal', params => [ { name => 'bad' }, { name => 'bad2' } ] }
{ name => 'normal2', params => [ { name => 'bad2' } ] }Both of the 'bad' entries will collide when the user specifies 'normal', since the parser passes through the top level and the normal->params level. However, bad2 will never collide because the parser will never pass through both levels.
Also, identical abbreviations are not checked for or corrected. They will probably cause problems.
CHANGES
Version 1.12, 20100411, jeagle
Add ability to return usage as a string.
Add ability to set the prefix character via $Getopt::Tree::SWITCH_PREFIX_STR
Remove automatic -help flag.
Fix a silly bug causing parameter values that evaluate to false to fail.
Version 1.11, 20100917, jeagle
Appease older versions of Perl in print_usage's usage of square brackets in a string.
Version 1.10, 20100709, jeagle
Correct handling of eval flags mixed with other flags.
Add optional destination filehandle to print_usage.
Clean up for export to CPAN.
Version 1.9, 20100428, jeagle
Show usage if no parameters are passed.
Version 1.8, 20100427, jeagle
Add $Version variable.
Give a better error message for parameters passed without a leading '-'.
Version 1.4, 20100427, jeagle
Add automatic -help flag parsing. This feature may cause problems if users wanted to override '-help', so this may change in the future.
Show required leaf parmeters at the top usage line, reformat usage a little.