=head1 NAME

Getopt::Tiny - yet another command line argument parsing module

=head1 SYNOPSIS

	use Getopt::Tiny;

	my $arg = 'default value';
	my @list;
	my %hash;
	my $flag;
	my %set;

	# begin usage info
	my (%flags) = (
		'argx' => \$arg,	# set a parameter
		'listx' => \@list,	# fill in a list
		'hashx' => \%hash,	# set key/value pairs
	);
	my (%switches) = (
		'flagx' => \$flag,	# on or off
	}
	# end usage info

	getopt(\@ARGV, \%flags, \%switches, $what_comes_after);
	Getopt::Tiny::usage(__FILE__, \%flags, \%switches, 'files');

B<or>

	use Getopt::Tiny;
	%flags = ...
	%switches = ...
	getopt()
	Getopt::Tiny::usage();


=head1 DESCRIPTION

Getopt::Tiny is yet another argument parsing module.  The results of 
the argument parsing are stored by using references that were provided 
to getopt().  Usage information is automatically generated.  Getopt::Tiny
expects all arguments to be switches -- no trailing list of files.

Getopt::Tiny can either call an existing usage() function or it can
use it's own builtin one.   It trys to use the existing one by default.
If that fails, it will use its own.  It figures out how to
describe things by reading the file where call to getopt() originated.
In the file where getopt is called, the following two lines must
appear exactly as written here:

	# begin usage info
	# end usage info

Between these two lines, lines that match the pattern of:

	'someflag' => ...  # a description

will be noticed and used to document each flag individually.

The usage() function of Getopt::Tiny can be called on it's own.
It can either have it's arguments given to it explicitly or it
can default them like getopt().

If a usage function is provided, it will be called with one parameter:
the argument that didn't parse.

Getopt::Tiny can be used in situation where it is expected to parse
the entire command line and in situations where there will be command
line args left over.  When Getopt::Tiny is expected to parse the
whole command line, do not include a forth argument to getopt().  When
it is expected that there will be stuff left over, pass a description
of what should be left over as the forth argument to getopt().

=head1 ARGUMENT TYPES

There are four types of arguments that Getopt::Tiny supports.  

=over 32

=item switches

Switches are either on or off. In the
example in the synopsis, the variable $flag will be respectively set 
to C<1> or C<0> if C<-flagx> or C<-noflagx> appears in the argument list .

=item parameter

Parameters have values.  In the example above, the $arg variable
will be set to whatever follows C<-argx> in the argument list.

=item list

List flags can have multiple values.  If present, they will have
at least one value.  In the example above, if the argument list
containted C<qw(-listx a b c -listx -d e -argx foo)>, the array @list 
would end up with a value of C<qw(a b c -d e)>.

=item hash

Hashes have multiple key-value pairs.  If present they will have
at least one value.  In the exmaple above, if the argument list
containted C<qw(-hashx a=b c=d -hashx -e=f -argx bar)>, the hash %hash
would end up with a value of C<(a =E<gt> b, c =E<gt> d, -e =E<gt> f)>.

=back

=head1 DEFAULT PARAMETERS

If no arguments are given to getopt() then it assumes that 
the argument list to parse is C<\@ARGV> and that the flags and switch
references are C<\%::flags> and C<\%::switches> respectively.

Likewise, if no arguments are given to usage() then it assumes
that filename to look for information in is C<(caller(0))[1]> and
that the flags and switches are as above.

=head1 COPYRIGHT

Copyright (C) 1998, 2002, David Muir Sharnoff.   This modules
licensed under the terms of The Artistic License as found at
http://www.opensource.org/licenses/artistic-license.php.  The
optional aggregation clause is in effect.