NAME Easy::Options

Easy::Options - Easy to use, feature rich general purpose option processing using Getopt::Long as the underlying options processing package. Contrary to the Getopt::Long package, and despite the fact that this refers to "options", it will also process required arguments. This is distinct from the '=' options specifier in Getopt::Long, which states that __IF__ the option is listed on the command line, then it must have a value. With Easy::Options you may specify also that a program requires the argument to have a value even if it isn't specified on the command line.

Please don't flame me for the lame documentation here. I banged out this little bit of documentation just so there would be __something__. I intend to add more for later releases.

Also, please don't flame me about the tests. I have partially completed tham, and I am working on finishing. Right now, there are no real tests run. =head1 SYNOPSIS

  use Easy::Options;
  my @mama_is = qw( sweet );
  my %optargs = (
                 'mama|mom|mother' => [ ':=s@',
                                        \@mama_is,
                                        "Characteristics of 'mama'. Default value is qw(" . join(' ', @mama_is ) . ")"
                                      ],
                );

  my %options_target = ();
  my %options = easy_options( optargs => \%optargs, target => \%options_target )

NOTABLE

If you do not specify a 'usage' or 'help' options in your %optargs, then one will be inserted for you. When invoked, the usage() routine will print out a usage message(somewhat verbose) which includes information about the available options, listing REQUIRED options first followed by OPTIONAL options (alphabetically within their respective groups). For each option, the options type is listed along with its current value, followed by the <DOC_STRING> (see below).

OPTARGS

The %optargs are a modified form of the options processing arguments to GetOpt::Long, and are converted to GetOpt::Long argument form. There are two additions to the

  The %optargs from above take the following form:

  '<OPTION_NAME>' => [ '<OPTION_SPEC>', <DEFAULT_VALUE>, "<DOC_STRING>" ]

'OPTION_NAME' may ba a pipe delimited list of alternate names for an option. The first alernate listed becomes the canonical name for the option.

'OPTIONS_SPEC' is essentially the Getopt::Long form of option specification with one addition in terms of required vs optional parameters. You may add an additinoal options/required specifier character at the beginning of the options spec to indicate whether this option (or argument if you prefer) is required/optional for the program itself.

An example would help:

  'this|that:s=@'

This is a standard Getopt::Long options specifier that says I am expecting string values if values are provided, but values need not be privided. The option may be repeated on the command line and the results will be put into an array.

You would specify this like so for Easy::Options:

       ( 'this|that' => [ ':s=@', [], "--this <XX> is the same as --that <XX>" )

Supposing you program REQUIRED that --this be set. You would add a n equal sign to the options spec:

       ( 'this|that' => [ '=:s=@', [], "--this <XX> is the same as --that <XX>" )

Which would indicate that the program required the array (or string or int, as the case may be) to be non-empty, yet you wouldn't necessarily need to list it on the command line if there were defaults already set.

These are all the possibilities include: '==', ':=', '=:', '::'

If there is only a single optional/required specifier it is used for BOTH purposes. That is to say a single '=' would make the parameter value necessary if indeed the option were specified on the command line, and it would make the parameter values required to be defined for the program to continue. Like wise, a single ':' would make the parameter optional on all accounts.

'DEFAULT_VALUE' Can be 0) undef 1) scalar literal 2) SCALAR reference - in which case the variable referred to will be set to the value of the option as given on the command line 3) CODE reference - treated the same way Getopt::Long treats CODE references 4) ARRAY reference - treated the same way Getopt::Long treats ARRAY references 5) HASH reference - treated the same way Getopt::Long treats HASH references

'DOC_STRING' Is a brief description of the purpose of the option. This is ised in a --help printout.

TODO

  Add more docs to cover topics about: 
      overriding the help/usage builtin
      avoiding triggering the help/usage on failure
      providing a brief_usage argument
      using passthroughs to do partial option processing
      additional arguments that can be passed to easy_options():
        configuration parameters for Getopt::Long
        configuration parameters for Easy::Options;
        `target' parameter
        etc ..

I would like to have the options be returned as a tied hash. In this way, one could step through the keys of the hash and be certain only to get the canonical names for options. Currently, alternate names are inserted into the %options alongside the canonical names. With a tied hash, one could obscure the fact that there are alternate names, but could make the tied hash return the appropriate value when an alternate name is used to retrieve a value from the %options hash, and possiblly issue a warning about the alternate name being depricated.

BUGS

Because the alternate names are inserted into the %options alongside the canonical names, the values can get out of sync if you change a value in the %options hash which has alternative names (because the alternate names duplicate the values in the %options hash)

AUTHOR

Theo Lengyel, <dirt@cpan.org<gt>

SEE ALSO Getopt::Long perl.

cpanm Easy::Options

perl -MCPAN -e shell
install Easy::Options