1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
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 <Raphael_Manfredi@pobox.com>
|