view release on metacpan or  search on metacpan

lib/Getopt/Tree.pm  view on Meta::CPAN

 # 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',
     }, 
 ];
 
=head2 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"

=head1 USAGE

Two functions are exported by default: L<parse_command_line> and
L<print_usage>.

=head2 Functions

=head3 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 C<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.