Provided by: libparanoid-perl_0.34-1_all bug

NAME

       Paranoid::Args - Command-linne argument parsing functions

VERSION

       $Id: Args.pm,v 0.22 2010/04/15 23:23:28 acorliss Exp $

SYNOPSIS

         use Paranoid::Args;

         $rv = parseArgs(\@templates, \%opts);
         $rv = parseArgs(\@templates, \%opts, \@args);

         @errors = Paranoid::Args::listErrors();
         Paranoid::Args::clearMemory();

DESCRIPTION

       The purpose of this module is to provide simplified but validated parsing and extraction
       of command-line arguments (otherwise known as the contents of @ARGV).  It is meant to be
       used in lieu of modules like Getopt::Std and Getopt::Long, but that does not mean that
       this module is functionally equivalent -- it isn't.  There are things that those modules
       do that this doesn't, but that's primarily by design.  My priorities are a bit different
       when it comes to this particular task.

       The primary focus of this module is validation, with the secondary focus being
       preservation of context.

   VALIDATION
       When validating the use of options and arguments we concern ourselves primarily the
       following things:

       1)  Is the option accompanied by the requisite arguments?

       2)  Was the option called with the other requisite options?

       3)  Was the option called without options meant only for mutually exclusive use?

       4)  Were any unrecognized options used?

       This module also does basic sanity validation of all option templates to ensure correct
       usage of this module.

   PRESERVATION OF CONTEXT
       Simply put, preservation of context means remembering the order and grouping of associated
       arguments.  A demonstrative example would perhaps serve better than one of my poor
       explanations.

       Take the hypothetical case of "tagging" files.  The traditional approach is to define an
       option that takes a single string argument and apply them to the remaining contents of
       @ARGV:

         ./foo.pl -t "tag1" file1 file2

       This module supports that model, with the option argument template being '$' for that
       single string.  But what if you wanted to apply different tags to different files with one
       command execution?

         ./foo.pl -t "tag1" file1 file2 -t "tag2" file3

       In this case it is important to keep each group of payloads that you want to operate on
       separate.  With this module you could instead use an argument template of '$@', which
       would return each set independently:

         %opt = (
           't' => [
                   [ "tag1", [ "file1", "file2" ] ],
                   [ "tag2", [ "file3" ] ],
                  ],
                 );

       Notice that we also preserve the context between the '$' and the '@' by putting the '@'
       arguments in a sublist.  With this example that could possible be considered pointless,
       but we also support templates like '$$@$' which makes this very useful.  Now, instead of
       having to shift or pop off the encapsulating arguments they now have one permanent ordinal
       index.  You also can now just grab the array reference for the '@' portion and iterate
       over a complete and separate list rather than having to take a splice of the complete
       argument array.

       It's probably just me, but I find that a little easier to track.

   SUPPORTED COMMAND-LINE SYNTAX
       In keeping with my established tradition of discarding everything I have no use for this
       module does not support the same range of expressiveness that the Getopt::* modules do.
       Nor do we support "flexible" modes of differing modes of expressiveness.  What we do
       support we support unconditionally.

       The following list of syntactical options are supported:

       o   Short option bundling (i.e., "rm -rf")

       o   Short option counting (i.e., "ssh -vvv")

       o   Short option argument concatenation (i.e., "cut -d' '")

       o   Long option "equals" argument concatenation (i.e., "./configure --prefix=/usr")

       o   The use of '--' to designate all following arguments are strictly that, even if they
           look like options.

       We don't support the hash key/value pairs (i.e., -s foo=one bar=two) or argument type
       validation (Getopt::* can validate string, integer, and floating point argument types).
       And while we support a short & long option we don't support innumerable aliases in
       addition.  In short, if it isn't explicitly documented it isn't supported, though it
       probably is in Getopt::*.

       There are a few restrictions meant to eliminate confusion:

       1)  Long and short argument concatenation is only allowed if the argument template is '$'
           (expecting a single argument, only).

       2)  Short argument concatenation is furthermore only allowed on arguments that aren't
           allowed to be bundled with other short options.

       3)  Short options supporting bundling can require associate arguments as long as '@' is
           not part of the argument template.

SUBROUTINES/METHODS

   parseArgs
         $rv = parseArgs(\@templates, \%opts);
         $rv = parseArgs(\@templates, \%opts, \@args);

       Using the option templates passed as the first reference this function populates the
       options hash with all of the parsed options found in the passed arguments.  The args list
       reference can be omitted if you wish the function to work off of @ARGV.  Please note that
       this function makes a working copy of the array, so no alterations will be made to it.

       If any options and/or arguments fail to match the option template, or if an option is
       found with no template, a text message is pushed into an errors array and the function
       will return a boolean false.

       When the options hash is populated extracted arguments to the options are stored in both
       long and short form as the keys, assuming they were defined in the template.  Otherwise it
       will use whatever form of option was defined.

       Any arguments not associated with an option are stored in the options hash in a list
       associated with the key PAYLOAD.

   Paranoid::Args::listErrors
         @errors = Paranoid::Args::listErrors();

       If you need a list of everything that was found wrong during a parseArgs run, from
       template errors to command-line argument validation failures, you can get all of the
       messages form listErrors.  Please note that we show it fully qualified about because it is
       not exported under any circumstances.  If you need these extended diagnostics, you'll need
       to call it as shown.

       Each time parseArgs is invoked this array is reset.

   Paranoid::Args::clearMemory
         Paranoid::Args::clearMemory();

       If the existance of a (most likely) lightly populated array bothers you, you may use this
       function to empty all internal data structures of their contents.  Like listErrors this
       function is not exported under any circumstances.

OPTION TEMPLATES

       The function provided by this module depends on templates to extract and validate the
       options and arguments.  Each option template looks similar to the following:

         {
           Short         => 'v',
           Long          => 'verbose',
           Template      => '$',
           CountShort    => 1,
           Multiple      => 1,
           CanBundle     => 1,
           ExclusiveOf   => [],
           AccompaniedBy => [],
         }

       This template provides extraction of verbose options in the following (and similar) forms:

         -vvvvv
         --verbose 5
         --verbose=5

       If CountShort was instead false you'd have to say '-v5' or '-v 5' instead of '-vvvvv'.

       When the parseArgs function is called the options hash passed to it would be populated
       with:

         %opts = (
           'v'        => 5,
           'verbose'  => 5,
           );

       The redundancy is intentional.  Regardless of whether you look up the short or the long
       name you will be able to retrieve the cummulative value.

       The particulars of all key/value pairs in a template are documented below.

   Short
       Short refers to the form of the short option style (minus the normal preceding '-').  If
       this is left undefined then no short option is supported.

       This parameter is set to undef by default.

       NOTE:  All short option names must be only one character in length and consisting only of
       alphanumeric characters.

   Long
       Long refers to the from of the long option style (minus the normal preceding '--').  If
       this is left undefined then no long option is supported.

       This parameter is set to undef by default.

       NOTE: All long option names must be more than one character in length and consisting only
       of alphanumeric characters and hyphens.

   Template
       Template refers to the argument template which informs us how many, if any, arguments are
       required for this option.  A template can consist of zero or more of the following
       characters:

         Char  Description
         ========================================================
         $     The option will be followed by a mandatory argument
         @     The option will be followed by one or more arguments
         ''    No additional arguments are expected

       For simple boolean options (like '-f') you'd use a zero-length string as the template.
       The associated value of the option will be either a scalar or a list reference, depending
       on various parameters in the option template.

       If the option has a template of '' then it is assumed that it is a boolean option.  The
       associated value in the options hash would then be a scalar:

         # Template: ''
         # @ARGV:  -vvv
         'v' => 3

       with the scalar denoting the number of times it was used in the arguments.  It is the same
       if the template is '$' but CountShort is true.  In that case, the template really only
       applies to the long option (whose argument would set the initial scalar value), while the
       short options operate purely as an incrementer.  However, since everything is processed
       serially, you get the following results:

         # Template '$', CountShort is true
         # @ARGV: -vvv --verbose=7 -v --verbose=1 -v
         'v' => 2

       If the template is '$', but Multiple is false (mandating that the option be used only
       once) the associated value is again scalar:

         # Template: '$'
         # @ARGV: -v3
         'v' => 3

       If the template is '$' and Multiple is true then the associated value is an array
       reference, with the contents of the array being every argument associated with each option
       invocation:

         # Template: '$'
         # @ARGV:  --file foo  --file bar
         'file' => [ 'foo', 'bar' ]

       If the template is two or more '$' or contains '@' anywhere in the template then the
       associated value is an array reference.  The element where '@' would occur would be an
       array reference to the list containing everything globbed up by the '@':

         # Template:  '$@'
         # @ARGV: --chmod 0755 foo bar
         'chmod'   => [ '0755', [ 'foo', 'bar' ] ]

       If Multiple is true, each element would be a reference to each invocation of the option,
       with the element organized internally as in the previous example:

         # Template: '@'
         # @ARGV:  --add 5 7 2 --add 4 9
         'add'   => [ [ 5, 7, 2 ], [ 4, 9 ] ]

         # Template: '$@$'
         # @ARGV: --perform one two three four --perform five six seven
         'perform' => [ [ 'one', [ 'two', 'three' ], 'four'],
                        [ 'five', [ 'six' ], 'seven' ] ]

       NOTE: You cannot use the '@' character if the short option is allowed to be bundled with
       other options.

       This parameter defaults to '' (boolean options).

   Multiple
       Multiple is a boolean parameter which, if set, allows an option to be used more than once
       on the command-line.

       This parameter defaults to false.

   ExclusiveOf
       ExclusiveOf is an array of options that this option cannot be used in conjunction with.
       If the options in this list contain both short and long names you do not have to list them
       both.  Listing only one of the names will suffice.

       This parameter defaults to an empty list.

   AccompaniedBy
       AccompaniedBy is array of options that this option must be accompanied by.  If the options
       in this list contain both short and long names you do not have to list them both.  Listing
       only one of the names will suffice.

       This parameter defaults to an empty list.

   CanBundle
       CanBundle is a boolean parameter which, if set, allows short options to be bundled as part
       of a single argument (i.e., combining '-r' and '-f' as '-rf').

       This parameter defaults to false.

       NOTE: if you wish to be able to concatenate a short option and its requisite argument then
       CanBundle must be set to false.

       NOTE: if CanBundle is true and each short option requires a mandatory argument those
       arguments will be associated with each option in the order in which the options were
       specified.  For example, if 'v' and 'S' each expected a mandatory single argument:

         -vuS foo bar

       v would be associated with foo, and S with bar.  Bundling of short options that use '@' as
       part of their template is not allowed due to the obvious guaranteed problems which will
       result.

DEPENDENCIES

       o   Paranoid

       o   Paranoid::Debug

EXAMPLE

         @otemplates = (
             {
               Short       => 'v',
               Long        => 'verbose',
               Multiple    => 1,
               CountShort  => 1,
               CanBundle   => 1,
               Template    => '$',
             },
             {
               Short       => 'f',
               Long        => 'force',
               CanBundle   => 1,
               Template    => '',
             },
             {
               Short       => 'h',
               Long        => 'host',
               Multiple    => 1,
               CanBundle   => 1,
               Template    => '$',
             },
           );

         # Process @ARGV:  -vvvfh host1 file1 file2 file3
         if (parseArgs(\@otemplates, \%opts, \@errors)) {
           setVerbosity($opts{'verbose'});

           if ($opts{'force'}) {
             foreach (@{ $opts{'host'} }) {
               if (connectToHost($_)) {
                 transferFiles(@{ $opts{'PAYLOAD'} });
               }
             }
           }
         } else {
           foreach (@errors) { warn "$_\n" };
         }

BUGS AND LIMITATIONS

       It is not advisable for you to call parseArgs multiple times in a program to process a
       list of arguments in sections.  parseArgs uses an internal flag to note whether or not its
       seen the '--' argument, which disables all further recognition of arguments as options.
       That flag is set to false with every invocation, possibly causing problems for later
       sections if that flag had been used in a prior section.

       This doesn't offer the same range of functionality or flexibility of Getopt::Long.

AUTHOR

       Arthur Corliss (corliss@digitalmages.com)

LICENSE AND COPYRIGHT

       This software is licensed under the same terms as Perl, itself.  Please see
       http://dev.perl.org/licenses/ for more information.

       (c) 2005, Arthur Corliss (corliss@digitalmages.com)