NAME

Filter::Arguments - Configure and read your command line arguments from @ARGV.

SYNOPSIS

            

              
              
use Filter::Arguments;
@ARGV = qw( --drink Jolt --sandwhich BLT );
my $beverage = Argument( alias => 'drink', default => 'tea' );
my $food     = Argument( sandwich => 'ham & cheese' );
Arguments::verify_usage();
# prints "I'll have a BLT and a Jolt please."
print "I'll have a $food and a $beverage please.\n";
            
          

DESCRIPTION

Here is a simple way to configure and parse your command line arguments from @ARGV.

FEATURES

• Automatic enforcement of required values

• Automatic generation of usage text

• Automatic detection of alias

• Automatic construction of hash, array, scalar, hash ref, or array ref results

EXAMPLES

a required command line option

            

              
              
my $beverage = Argument;
Arguments::verify_usage();
            
          

If the --beverage option is not found in @ARGV then the verify_usage function will die with the appropriate usage instructions.

an optional command line option

            

              
              
my $beverage = Argument( default => 'Milk' );
Arguments::verify_usage();
            
          

If no --beverage option is found then the value 'Milk' is provided.

an aliased option populates a variable of a different name

            

              
              
my $beverage = Argument( alias => 'drink' );
Arguments::verify_usage();
            
          

The value of $beverage will be whatever is found to follow --drink in @ARGV.

an implied alias and default

            

              
              
my $beverage = Argument( drink => 'Milk' );
Arguments::verify_usage();
            
          

The value of $beverage will be whatever is found to follow --drink in @ARGV, or it will default to 'Milk'.

populate an array

            

              
              
my @drinks = Argument( default => [qw( Water OJ Jolt )] );
            
          

The @drinks array will contain whatever values follow --drinks in @ARGV, or it will contain the given defaults.

populate a list of scalars

            

              
              
my ($a,$b,$c) = Arguments;
            
          

This will populate $a, $b, and $c with 1 if --a, --b, and --c are all found in @ARGV.

Note, it sure would confuse matters if these variables are not booleans, or single value options.

slurp up everything in @ARGV as a hash

            

              
              
my %args = Arguments;
            
          

Um, what exactly does that do?

            

              
              
@ARGV = qw( --a --b --c --drink Jolt --eat Rice Beans --numbers 3 2 1 );
            
          

Translates to:

            

              
              
%args = (
   a       => 1,
   b       => 1,
   c       => 1,
   drink   => 'Jolt',
   eat     => [ 'Rice', 'Beans' ],
   numbers => [ 3, 2, 1 ],
)
            
          

Note, it wouldn't make much sense to use the verify_usage fuction in this case.

populate an array ref

            

              
              
my $drinks_ra = Argument( default => [qw( Water OJ Jolt )] );
            
          

In this case the '_ra' naming convention for "reference to array" is noticed and the behavior is otherwise the same as the @drinks example above.

Note, the same example like this:

            

              
              
my $drinks = Argument( default => [qw( Water OJ Jolt )] );
            
          

Now drinks is not recognized as a reference to array type of scalar, and instead it will be populated with 'Water'.

populate a hash ref

            

              
              
my $args_rh = Arguments;
            
          

Same as the above example, where the '_rh' suffix is recognized as a special reference to hash and populated as such.

DEPENDENCIES

Filter::Simple

TODO

Regex or list based validation of given values.

For example:

            

              
              
my $x = Argument( valid => qr{\A \d+ \z}xms );
my $y = Argument( valid => [qw( 1 3 5 7 11 12 )] );
            
          

Usage validation without the need for a special function call.

LIMITATIONS

Suppose you want to support the option --alias with a default value of 'default'.

            

              
              
my $option = Argument( alias => 'default' );
            
          

This will be correctly interpreted as option --default and no default value.

This is a special case limitation because 'alias' is a reserved key.

In this one wierd particular situation you'll need to do:

            

              
              
my $option = Argument( alias => 'alias', default => 'default' );
            
          

Or:

            

              
              
my $alias = Argument( default => 'default' );
            
          

BUGS

Version 0.10 is a complete rewrite from 0.07. Despite big improvements, this revision doesn't quite acheive the elegance I have always dreamed of. I'm ready for anything.

AUTHOR

Dylan Doxey <dylan.doxey@gmail.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Dylan Doxey

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of Perl 5 you may have available.