/ 
Args-Simple-1.0
/ Args

NAME

Args::Simple - quick, dirty, and convenient command-line argument parser

VERSION

Version 1.0

SYNOPSIS

use Args::Simple;
use Args::Simple @args;

if (defined $Args::arg{$key}) {
  print "You specified the argument 
}

DESCRIPTION

Populates the %Args::arg table with values from @ARGV (command-line arguments) that match "--<key>", "--<key>=<value>", "-<k>", or "-<k><value>" where key and value are arbitary strings of code, and k is an arbitrary one character string. Consumes these arguments from @ARGV and returns the arguments that were not consumed.

Unlike some other command-line processing modules in CPAN, Args::Simple does not require any pre-specification of the options that the script will accept, and it makes it convenient to make quick changes like this:

# old version
$n = 15;
$result = doSomething($n);
print "The results of something were $result\n";

# new version
#   1. lets user override default $n value with  -n<x> or --n=<x>  options
#   2. suppresses output if  --quiet  argument is supplied
$n = $Args::arg{"n"} || 15;
$result = doSomething();
print "The results of something were $result\n" unless $Args::arg{"quiet"};

without needing to specify ahead of time that the program will accept the "n" and "quiet" arguments.

The fact that command-line options are consumed makes it convenient to add option handling to your program at any time. For example, suppose you have a script that expects 2 or 3 arguments. But then you decide it would be convenient to do some additional configuration of the script using some command-line switches. Your script may still continue to use code like:

($input,$output,$n) = @ARGV;
if (!defined $n) {
    warn "Third argument not provided. Assuming 15.\n";
    $n = 15;
}

while handling any command-line options that you specify and without needing to check if the items in @ARGV are regular arguments or command-line switches.

AN EXAMPLE

Let's look at this simple script to see how the Args::Simple module handles different command-line arguments:

# demo-Args.pl: print out how the Args module handles @ARGV
use Args::Simple;
foreach $arg (sort keys %Args::arg) {
    print "Command-line argument: $arg = $Args::arg{$arg}\n";
}
print "\@ARGV is [\"", join '","', @ARGV, "\"]\n";

Running the script:

perl demo-Args.pl file1 --key=value --arg -b -n40 -stop file2

will produce the output:

Command-line argument: arg = 1E0
Command-line argument: b = 1E0
Command-line argument: key = value
Command-line argument: n = 40
Command-line argument: s = top
@ARGV is ["file1","file2"]

EXPLANATION OF EXAMPLE

All the command-line arguments that began with a - (dash) were used to populate %Args::arg and were removed from @ARGV. Any arguments that did not begin with a dash were returned in @ARGV. There were four different styles of command line arguments that were handled by this example:

--<key>

For command-line arguments that begin with -- and do not contain an = (equals) character, a value of $Args::default_arg is assigned to $Args::arg{key}. $Args::default_arg is a special value that evaluates to 1 in a numeric context but not to 1 in a string context. See the section on $Args::default_arg below. Thus the arguments

--no-print --verbose

will populate %Args::arg with the values

"no-print" => "1E0"
"verbose"  => "1E0"
-<k>

For command-line arguments that consist of a single dash followed by a single character, the value of $Args::default_arg is assigned to $Args::arg{k}. So the arguments

-b -c -d

will populate %Args::arg with the values

"b" => "1E0"
"c" => "1E0"
"d" => "1E0"

Note: If the single character is a digit (0-9), then the argument is not treated like a command-line switch and it will propagate to @ARGV. There are plenty of scripts that want to be able to take a negative number as an argument, so for this module to consume those arguments would probably be the wrong thing to do. If you do wish to use a single digit as a switch, you can always specify the option with a double-dash, i.e.

--4

instead of

-4 .
--<key>=<value>

Command-line arguments that begin with -- and contain an = (equals) character are parsed as a key-value pair. The value will be assigned to $Args::arg{key}. For example the arguments

--water=wet --fire=hot --one=1 --5=five

will populate %Args::arg with the values

"water" => "wet"
"fire"  => "hot"
"one"   => "1"
"5"     => "five"
-<k><value>

For command-line arguments that begin with a single - (dash) followed by more than one character, the first character after the dash is interpreted as the key, and the remaining characters are used as the value for populating %Args::arg. The arguments

-n30 -f/dev/null -quiet

will populate %Args::arg with the values

"n" => "30"
"f" => "/dev/null"
"q" => "uiet"

Note that some command-line processing schemes allow for bundling of simple switches, that is, to say -rst to mean -r -s -t. This type of bundling is not supported by this module.

Also note that if the key character would be a digit (0-9), then the argument will not treated like a command-line switch and it will propagate to @ARGV. There are plenty of scripts that want to be able to take a negative number as an argument, so for this module to consume those arguments would probably be the wrong thing to do. If you do wish to use a single digit as a switch, you can always specify the option with a double-dash, i.e.

--2=.71828182845905

instead of

-2.71828182845905

ADDITIONAL INFORMATION

The Args::Simple module populates a few other variables of interest in the Args:: namespace.

$Args::default_arg

$Args::default_arg is a special argument that evaluates to 1 in a numeric context but not to 1 in a string context. This distinction allows you to determine whether an argument was invoked as

--key

or as

--key=1 ,

should that distinction be important to you.

# if program invoked with arguments:  --abc --def=1
$Args::arg{"abc"}==1;     # true
$Args::arg{"abc"} eq "1"; # false
$Args::arg{"def"}==1;     # true
$Args::arg{"def"} eq "1"; # true

@Args::ARGS and $Args::ARGS

The Args::Simple module may consume the arguments that are originally passed to the program. The list variable @Args::ARGS stores a copy of the original arguments in the original order. The scalar variable $Args::ARGS stores the original set of command-line arguments in a scalar variable.

if ($Args::ARGS =~ /john/i) {
    print "We mentioned John somewhere in the original command line\n";
}

Special cases

Some other information about how the module handles interesting sets of arguments.

Repeated arguments

If the same argument key is specified more than once, only the last value will be used to populate %Args::arg. The complete set of arguments will still be available in @Args::ARGS (see the above section).

# invoke with --c=cookie -c6
use Args::Simple;
print $Args::arg{"c"};     #  will print "6"
Multiple equals signs

In an argument of the form --key=value1=value2, only the first equals sign is significant. The whole string value1=value2 will become the value assigned to the key in %Args::arg.

Argument is a single dash

The argument - is not processed by the Args::Simple module and is returned in @ARGV.

Argument is a double dash

The argument -- is processed by the Args::Simple module. It assigns the default value ($Args::default_arg) to a key of the empty string in the %Args::arg table.

Argument has a trailing equals sign

For an argument of the form --key=, with no more characters after the equals sign, a value of an empty string is assigned to the key in the %Args::arg table.

COPYRIGHT & LICENSE

Copyright 2007-2009 Marty O'Brien, all rights reserved

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.