/ 
Filter-Arguments-0.14
River stage zero No dependents
/ Filter::Arguments

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.