Getargs::Long 0.1 Copyright (c) 2000-2001, Raphael Manfredi ------------------------------------------------------------------------ This program is free software; you can redistribute it and/or modify it under the terms of the Artistic License, a copy of which can be found with perl. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the Artistic License for more details. ------------------------------------------------------------------------ ======================================================================== This module is known to exercise a bug in perl 5.6.0. Don't use that version of perl: use 5.005_03, or try 5.6.1. The interface of this module changed between 0.1.2 and 0.1.3, and is NOT backward compatible. That's why it's still called alpha software. ======================================================================== *** This is alpha software -- use at your own risks *** Name DSLI Description Info ----------- ---- -------------------------------------------- ----- Getargs:: ::Long adpf Parses long function args f(-arg => value) RAM SYNOPSIS use Getargs::Long; # case sensitive use Getargs::Long qw(ignorecase); # case insensitive # Simple, args mandatory my ($val, $other) = getargs(@_, qw(val other)); # Simple, args optional (in [] means optional) my ($val, $other) = getargs(@_, [qw(val other)]); # Simple with typechecking, args mandatory my ($val, $other) = getargs(@_, qw(val=Class::X other=ARRAY)); # Simple with typechecking, args optional my ($val, $other) = getargs(@_, [qw(val=Class::X other=ARRAY)]); # Faster version, building dedicated argument parsing routine my ($val, $other) = cgetargs(@_, qw(val other)); # Other cases, use full specs: my ($x, $y, $z, $a, $b, $c) = xgetargs(@_, # Non-mandatory, defaults to undef unless specified otherwise 'x' => ['i'], # integer, no default 'y' => ['ARRAY', ['a', 'b']], # Has a default 'z' => [], # No typecheck, can be anything # Mandatory arguments 'a' => 'i', # integer (scalar) 'b' => 'TYPE', # TYPE or any heir of TYPE 'c' => undef, # unspecified type but mandatory ); # Extract remaining unparsed args in @extra my ($val, $other, @extra) = getargs(@_, { -strict => 0 }, qw(val other)); # Alter behaviour of the getargs() routines via switches in hashref my ($val, $other) = getargs(@_, { -strict => 1, # unknown switches are fatal -ignorecase => 1, # override package's global -inplace => 1, # edit @_ inplace: remove parsed args -extra => 0, # suppress return of extra arguments }, qw(val other) ); DESCRIPTION Instead of duplicating the manual page, and because examples are better than a long explaination, here are examples for common cases, showing the routine argument sepecification and how various calling sequences are interpreted by those specifications. Example 1 -- All mandatory: sub f { my ($port, $server) = getargs(@_, qw(port=i server=HTTP::Server)); } f(-server => $server, port => 80); # or -port, since - is optional f(port => 80, server => $server); f(server => $server); # WRONG: missing mandatory -port f(server => 80, port => 80); # WRONG: -server not an HTTP::Server f(server => undef, port => 80); # WRONG: -server cannot be undef Example 2 -- All optional sub cmd { my ($a, $o) = getargs(@_, [qw(a o=s)]); } cmd(); # OK cmd(-a => undef); # OK -a accepts anything, even undef cmd(-a => 1, -o => ".."); # OK cmd(-a => 1, -o => undef); # WRONG: -o does not accept undef cmd(-x => 1); # WRONG: -x is not a known argument name Example 3 -- Mixed optional / mandatory sub f { my ($x, $z) = xgetargs(@_, -x => 'i', # -x mandatory integer -z => ['n', -20.4], # -z optional, defaults to -20.4 ); } f(x => 1, z => {}); # WRONG: z is not a numerical value f(z => 1, x => -2); # OK f(-z => 1); # WRONG: mandatory x is missing f(-z => undef); # WRONG: z cannot be undef Example 4 -- Parsing options sub f { my ($x, $z) = xgetargs(@_, { -strict => 0, -ignorecase => 1 }, -x => 'i', # -x mandatory integer -z => ['n', -20.4], # -z optional, defaults to -20.4 ); } f(x => 1, foo => {}); # OK, -foo ignored since not strict f(-X => 1); # OK, -X actually specifies -x with ignorecase -- Raphael Manfredi