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.