/ 
EasyArgs-0.01
/ EasyArgs

NAME

EasyArgs - Perl module for easily handling command line arguments.

SYNOPSIS

use EasyArgs('EzArgs');

my %args = EzArgs;

if(exists($args{'-l'}))
	{
	print "-l log file value is ". ($args{'-l'}) ."\n";
	}

DESCRIPTION

EasyArgs is Yet Another module for parsing command line arguments. (The first being Getopt::Declare by Damian Conway, available on CPAN)

EasyArgs was designed to be easy to use for basic argument handling.

In its simplest form, you can use the module and import the one exportable subroutine called EzArgs.

use EasyArgs('EzArgs');

This will set up the module to parse the command line arguments in its basic, default configuration.

The "EzArgs" subroutine is exported into the namespace where "use" was called. EzArgs is a subroutine that provides a simple interface to most argument parsing needs.

GET ALL ARGUMENT/VALUE PAIRS:

Calling EzArgs with no parameters will return a hash containing all the Argument/Value pairs on the command line. You can then use that hash to test for the existence of an argument and for that argument's value.

my %arg_hash = EzArgs;

if(exists($args{'-l'}))
	{
	print "-l log file value is ". ($args{'-l'}) ."\n";
	}

%> script.pl -l=output.txt
-l log file is output.txt

TEST FOR EXISTENCE OF AN ARGUMENT:

Passing an argument into EzArgs will return a boolean indicating whether or not that argument exists on the command line or not. This avoids the need of making a hash.

print "verbose mode on\n" if(EzArgs('-v'));

GET THE VALUE FOR AN ARGUMENT:

You can pass EzArgs the string 'Value' and the name of the argument, and the subroutine will return the value associated with that argument.

my $log=EzArgs('Value', '-l');
open(my $fh, '>'.$log) or die;

OPTIONS AVALAILABLE WHEN USING EASYARGS

When you use EasyArgs, you can pass it additional information that tells it how to parse the command line arguments. This is in the form of Method/Parameter pairs that are included on the use EasyArgs line. The parameters are passed as an array ref so that any number of parameters can be passed to the method call.

use EasyArgs
	(
	MethodName => [ parm1, parm2 ],
	);

VALUE ASSOCIATION

By default, any command line argument that contains an equal sign ('=') will be split into an argument=value pair. You can further specify that certain arguments will use the next argument to contain its value. A common example is the -l argument for a logfile or -f for a input file.

%> script.pl -l output.log -f input.txt

By default, EasyArgs will parse this as four arguments, "-l", "output.log", "-f", and "input.txt"

You can tell EasyArgs that the value associated with "-l" and "-f" is specified in the argument that follows it.

use EasyArgs
	(
	'EzArgs',
	ArgumentsThatConsumeNextArgument => ['-l', '-f'],
	);

ARGUMENT ATOMIZATION

Some programs allow the user to specify multiple single-character switches at the same time. The Unix "ls" command allows this:

%> ls -alt

The ls program interprets this as three arguments, '-a', '-l', '-t'. Other programs might wish to interpret this as a single argument '-alt'.

%> aircraft.pl -alt=30000

EasyArgs refers to the "ls" approach to arguments as "atomization". A molecule of arguments, "-alt", are atomized into individual switches.

ATOMIZE SINGLE DASH ARGUMENTS

You can specify to EasyArgs to atomize all single dash arguments (/\-\w/) and leave all other arguments alone.

use EasyArgs
	(
	'EzArgs',
	AtomizeSingleDashArguments=>[],
	);
print "-v verbose mode on\n" if (EzArgs('-v'));

%> aircraft.pl -vt --alt=30000
-v verbose mode on

ATOMIZE ARBITRARY ARGUMENTS

If single dash atomizing isn't quite it for you, you can specify your own method for argument atomization when you use EasyArgs.

use EasyArgs
	(
	SetAtomizer=>
		[
		sub { return $_[0]; }
		],
	);

The subroutine receives the full argument, ("-alt=3"), and must return a list of argument/value pairs (-a,3,-l,3,-t,3). Use this with caution.

ARGUMENT LEVELS

EasyArgs allows you to parse arguments differently based on what "level" they are contained in. Levels are separated by some argument on the command line which matches some regular expression. The most common level separator is "--".

You could write a perl script that interfaces between the user and some other program. The interface script might take its own arguments which get parsed one way, but then the user may need to pass in other argumetns which get passed directly to the second program.

For example, a script that interfaces between a user and the Unix "ls" command might be executed by the user like this:

%> ls_interface.pl -verbose -all -- -alt

Another example of argument "levels" is the "cvs" command, which has global arguments and command specific arguments. The arguments before the "command" are one level, the arguments after the "command" are another level. (examples of cvs commands are "tag", "edit", "lock", etc)

%> cvs -v tag -c yada

LEVEL EXAMPLES

The method to split the arguments into levels is 'DecomposeLevel'. You can then move from one level to the next with 'GoNextLevel' and 'GoPrevLevel'.

The "ls" interface script could use EasyArgs like this:

use EasyArgs 
( 
	'EzArgs',
	DecomposeLevel => [],		# split on "--"
	GoNextLevel => [],		# go to arguments after "--"
	AtomizeSingleDashArguments=>[], # atomize args after "--"
);

my %args = EzArgs;

print join("\n", keys(%args));

%> example.pl -abc -- -xyz
-y
-z
-x

LEVEL PROGRAMMING

A cvs interface script could parse the first level of arguments. And then based on the command, parse the second level of arguments in a manner specific to that command.

# split the first level, looking for the cvs command.
use EasyArgs 
( 
	'EzArgs',
	DecomposeLevel => ['^(tag|edit|lock|unlock)$'],
	ParseIfNeeded=>[],
);

my %hash1 = EzArgs;
print join("\n", keys(%hash1)) . "\n";


# get the cvs command that actually occurred on the command line
my $command = EzArgs('SeparatorValue');
print "command is $command\n";

# move to the next level of arguments 
EzArgs('GoNextLevel');

# each cvs command can parse the arguments differently.
if($command eq 'tag')
	{
	EzArgs('ArgumentsThatConsumeNextArgument',"-l");
	}
elsif($command eq 'edit')
	{
	EzArgs('AtomizeSingleDashArguments');
	}


my %hash2 = EzArgs;
print join("\n", keys(%hash2)) . "\n";

%> example.pl -abc edit -xyz
-abc
command is edit
-y
-z
-x

EXPORT

None by default.

sub EzArgs can be exported by the "use" statement. You must pass the string 'EzArgs' to the use EasyArgs statement as the first parameter.

use EasyArgs('EzArgs');

AUTHOR

Greg London, email@greglondon.com

SEE ALSO

Getopt::Declare is a much more advanced command line argument parser. If EasyArgs doesn't do the job, take a look at Getopt::Declare.