1 #============================================================================
5 # Perl5 module to interface AppConfig::* to Johan Vromans' Getopt::Long
6 # module. Getopt::Long implements the POSIX standard for command line
7 # options, with GNU extensions, and also traditional one-letter options.
8 # AppConfig::Getopt constructs the necessary Getopt:::Long configuration
9 # from the internal AppConfig::State and delegates the parsing of command
10 # line arguments to it. Internal variable values are updated by callback
13 # Written by Andy Wardley <abw@wardley.org>
15 # Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.
16 # Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
18 #============================================================================
20 package AppConfig::Getopt;
24 use Getopt::Long 2.17;
25 our $VERSION = '1.65';
28 #------------------------------------------------------------------------
31 # Module constructor. The first, mandatory parameter should be a
32 # reference to an AppConfig::State object to which all actions should
33 # be applied. The second parameter may be a reference to a list of
34 # command line arguments. This list reference is passed to parse() for
37 # Returns a reference to a newly created AppConfig::Getopt object.
38 #------------------------------------------------------------------------
49 # call parse() to parse any arg list passed
57 #------------------------------------------------------------------------
58 # parse(@$config, \@args)
60 # Constructs the appropriate configuration information and then delegates
61 # the task of processing command line options to Getopt::Long.
63 # Returns 1 on success or 0 if one or more warnings were raised.
64 #------------------------------------------------------------------------
68 my $state = $self->{ STATE };
69 my (@config, $args, $getopt);
73 # we trap $SIG{__WARN__} errors and patch them into AppConfig::State
74 local $SIG{__WARN__} = sub {
77 # AppConfig::State doesn't expect CR terminated error messages
78 # and it uses printf, so we protect any embedded '%' chars
80 $state->_error("%s", $msg);
83 # slurp all config items into @config
84 push(@config, shift) while defined $_[0] && ! ref($_[0]);
86 # add debug status if appropriate (hmm...can't decide about this)
87 # push(@config, 'debug') if $state->_debug();
89 # next parameter may be a reference to a list of args
92 # copy any args explicitly specified into @ARGV
93 @ARGV = @$args if defined $args;
95 # we enclose in an eval block because constructor may die()
97 # configure Getopt::Long
98 Getopt::Long::Configure(@config);
100 # construct options list from AppConfig::State variables
101 my @opts = $self->{ STATE }->_getopt_state();
104 if ($state->_debug()) {
105 print STDERR "Calling GetOptions(@opts)\n";
106 print STDERR "\@ARGV = (@ARGV)\n";
109 # call GetOptions() with specifications constructed from the state
110 $getopt = GetOptions(@opts);
114 $state->_error("%s", $@);
118 # udpdate any args reference passed to include only that which is left
120 @$args = @ARGV if defined $args;
126 #========================================================================
128 #========================================================================
130 package AppConfig::State;
132 #------------------------------------------------------------------------
135 # Constructs option specs in the Getopt::Long format for each variable
138 # Returns a list of specification strings.
139 #------------------------------------------------------------------------
143 my ($var, $spec, $args, $argcount, @specs);
145 my $linkage = sub { $self->set(@_) };
147 foreach $var (keys %{ $self->{ VARIABLE } }) {
148 $spec = join('|', $var, @{ $self->{ ALIASES }->{ $var } || [ ] });
150 # an ARGS value is used, if specified
151 unless (defined ($args = $self->{ ARGS }->{ $var })) {
152 # otherwise, construct a basic one from ARGCOUNT
155 defined ($argcount = $self->{ ARGCOUNT }->{ $var });
157 $args = "=s", last ARGCOUNT if $argcount eq ARGCOUNT_ONE;
158 $args = "=s@", last ARGCOUNT if $argcount eq ARGCOUNT_LIST;
159 $args = "=s%", last ARGCOUNT if $argcount eq ARGCOUNT_HASH;
163 $spec .= $args if defined $args;
165 push(@specs, $spec, $linkage);
179 AppConfig::Getopt - Perl5 module for processing command line arguments via delegation to Getopt::Long.
183 use AppConfig::Getopt;
185 my $state = AppConfig::State->new(\%cfg);
186 my $getopt = AppConfig::Getopt->new($state);
188 $getopt->parse(\@args); # read args
192 AppConfig::Getopt is a Perl5 module which delegates to Johan Vroman's
193 Getopt::Long module to parse command line arguments and update values
194 in an AppConfig::State object accordingly.
196 AppConfig::Getopt is distributed as part of the AppConfig bundle.
200 =head2 USING THE AppConfig::Getopt MODULE
202 To import and use the AppConfig::Getopt module the following line should appear
205 use AppConfig::Getopt;
207 AppConfig::Getopt is used automatically if you use the AppConfig module
208 and create an AppConfig::Getopt object through the getopt() method.
210 AppConfig::Getopt is implemented using object-oriented methods. A new
211 AppConfig::Getopt object is created and initialised using the new() method.
212 This returns a reference to a new AppConfig::Getopt object. A reference to
213 an AppConfig::State object should be passed in as the first parameter:
215 my $state = AppConfig::State->new();
216 my $getopt = AppConfig::Getopt->new($state);
218 This will create and return a reference to a new AppConfig::Getopt object.
220 =head2 PARSING COMMAND LINE ARGUMENTS
222 The C<parse()> method is used to read a list of command line arguments and
223 update the state accordingly.
225 The first (non-list reference) parameters may contain a number of
226 configuration strings to pass to Getopt::Long::Configure. A reference
227 to a list of arguments may additionally be passed or @ARGV is used by
230 $getopt->parse(); # uses @ARGV
231 $getopt->parse(\@myargs);
232 $getopt->parse(qw(auto_abbrev debug)); # uses @ARGV
233 $getopt->parse(qw(debug), \@myargs);
235 See Getopt::Long for details of the configuartion options available.
237 A Getopt::Long specification string is constructed for each variable
238 defined in the AppConfig::State. This consists of the name, any aliases
239 and the ARGS value for the variable.
241 These specification string are then passed to Getopt::Long, the arguments
242 are parsed and the values in the AppConfig::State updated.
244 See AppConfig for information about using the AppConfig::Getopt
245 module via the getopt() method.
249 Andy Wardley, E<lt>abw@wardley.orgE<gt>
253 Copyright (C) 1997-2007 Andy Wardley. All Rights Reserved.
255 Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
257 This module is free software; you can redistribute it and/or modify it
258 under the same terms as Perl itself.
260 =head1 ACKNOWLEDGMENTS
262 Many thanks are due to Johan Vromans for the Getopt::Long module. He was
263 kind enough to offer assistance and access to early releases of his code to
264 enable this module to be written.
268 AppConfig, AppConfig::State, AppConfig::Args, Getopt::Long