File Coverage

lib/AppConfig/Args.pm
Criterion Covered Total %
statement 36 43 83.7
branch 11 20 55.0
condition 5 5 100.0
subroutine 6 6 100.0
pod 0 2 0.0
total 58 76 76.3


line stmt bran cond sub pod time code
1             package AppConfig::Args;
2              
3             #============================================================================
4             #
5             # AppConfig::Args.pm
6             #
7             # Perl5 module to read command line argument and update the variable
8             # values in an AppConfig::State object accordingly.
9             #
10             # Written by Andy Wardley <abw@wardley.org>
11             #
12             # Copyright (C) 1997-2003 Andy Wardley. All Rights Reserved.
13             # Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
14             #
15             # $Id: Args.pm,v 1.60 2003/04/29 10:42:39 abw Exp $
16             #
17             #============================================================================
18              
19             require 5.004;
20              
21 1     1   17 use strict;
  1         15  
  1         14  
22              
23 1     1   42 use AppConfig::State;
  1         9  
  1         23  
24              
25 1     1   16 use vars qw( $VERSION );
  1         9  
  1         16  
26             BEGIN {
27 1     1   14 $VERSION = '1.64';
28             }
29              
30              
31             #------------------------------------------------------------------------
32             # new($state, \@args)
33             #
34             # Module constructor. The first, mandatory parameter should be a
35             # reference to an AppConfig::State object to which all actions should
36             # be applied. The second parameter may be a reference to a list of
37             # command line arguments. This list reference is passed to args() for
38             # processing.
39             #
40             # Returns a reference to a newly created AppConfig::Args object.
41             #------------------------------------------------------------------------
42              
43             sub new {
44 1     1 0 11     my $class = shift;
45 1         9     my $state = shift;
46                 
47              
48 1         16     my $self = {
49                     STATE => $state, # AppConfig::State ref
50             DEBUG    => $state->_debug(), # store local copy of debug
51             PEDANTIC => $state->_pedantic, # and pedantic flags
52                 };
53              
54 1         10     bless $self, $class;
55            
56             # call parse() to parse any arg list passed
57 1 50       12     $self->parse(shift)
58             if @_;
59              
60 1         12     return $self;
61             }
62              
63              
64             #------------------------------------------------------------------------
65             # parse(\@args)
66             #
67             # Examines the argument list and updates the contents of the
68             # AppConfig::State referenced by $self->{ STATE } accordingly. If
69             # no argument list is provided then the method defaults to examining
70             # @ARGV. The method reports any warning conditions (such as undefined
71             # variables) by calling $self->{ STATE }->_error() and then continues to
72             # examine the rest of the list. If the PEDANTIC option is set in the
73             # AppConfig::State object, this behaviour is overridden and the method
74             # returns 0 immediately on any parsing error.
75             #
76             # Returns 1 on success or 0 if one or more warnings were raised.
77             #------------------------------------------------------------------------
78              
79             sub parse {
80 4     4 0 37     my $self = shift;
81 4   100     94     my $argv = shift || \@ARGV;
82 4         36     my $warnings = 0;
83 4         32     my ($arg, $nargs, $variable, $value);
84              
85              
86             # take a local copy of the state to avoid much hash dereferencing
87 4         45     my ($state, $debug, $pedantic) = @$self{ qw( STATE DEBUG PEDANTIC ) };
88              
89              
90              
91             # loop around arguments
92 4   100     63     ARG: while (@$argv && $argv->[0] =~ /^-/) {
93 8         70 $arg = shift(@$argv);
94              
95             # '--' indicates the end of the options
96 8 50       79 last if $arg eq '--';
97              
98             # strip leading '-';
99 8         88 ($variable = $arg) =~ s/^-(-)?//;
100              
101             # test for '--' prefix and push back any '=value' item
102 8 100       90 if (defined $1) {
103 5         73 ($variable, $value) = split(/=/, $variable);
104 5 100       54 unshift(@$argv, $value) if defined $value;
105             }
106              
107             # check the variable exists
108 8 50       86 if ($state->_exists($variable)) {
109              
110             # see if it expects any mandatory arguments
111 8         115 $nargs = $state->_argcount($variable);
112 8 100       75 if ($nargs) {
113             # check there's another arg and it's not another '-opt'
114 7 50       123 if(defined($argv->[0])) {
115 7         64 $value = shift(@$argv);
116             }
117             else {
118 0         0 $state->_error("$arg expects an argument");
119 0         0 $warnings++;
120 0 0       0 last ARG if $pedantic;
121 0         0 next;
122             }
123             }
124             else {
125             # set a value of 1 if option doesn't expect an argument
126 1         37 $value = 1;
127             }
128              
129             # set the variable with the new value
130 8         87 $state->set($variable, $value);
131             }
132             else {
133 0         0 $state->_error("$arg: invalid option");
134 0         0 $warnings++;
135 0 0       0 last ARG if $pedantic;
136             }
137                 }
138              
139             # return status
140 4 50       109     return $warnings ? 0 : 1;
141             }
142              
143              
144              
145             1;
146              
147             __END__
148            
149             =head1 NAME
150            
151             AppConfig::Args - Perl5 module for reading command line arguments.
152            
153             =head1 SYNOPSIS
154            
155             use AppConfig::Args;
156            
157             my $state = AppConfig::State->new(\%cfg);
158             my $cfgargs = AppConfig::Args->new($state);
159            
160             $cfgargs->parse(\@args); # read args
161            
162             =head1 OVERVIEW
163            
164             AppConfig::Args is a Perl5 module which reads command line arguments and
165             uses the options therein to update variable values in an AppConfig::State
166             object.
167            
168             AppConfig::File is distributed as part of the AppConfig bundle.
169            
170             =head1 DESCRIPTION
171            
172             =head2 USING THE AppConfig::Args MODULE
173            
174             To import and use the AppConfig::Args module the following line should appear
175             in your Perl script:
176            
177             use AppConfig::Args;
178            
179             AppConfig::Args is used automatically if you use the AppConfig module
180             and create an AppConfig::Args object through the parse() method.
181            
182             AppConfig::File is implemented using object-oriented methods. A new
183             AppConfig::Args object is created and initialised using the new() method.
184             This returns a reference to a new AppConfig::File object. A reference to
185             an AppConfig::State object should be passed in as the first parameter:
186            
187             my $state = AppConfig::State->new();
188             my $cfgargs = AppConfig::Args->new($state);
189            
190             This will create and return a reference to a new AppConfig::Args object.
191            
192             =head2 PARSING COMMAND LINE ARGUMENTS
193            
194             The C<parse()> method is used to read a list of command line arguments and
195             update the STATE accordingly. A reference to the list of arguments should
196             be passed in.
197            
198             $cfgargs->parse(\@ARGV);
199            
200             If the method is called without a reference to an argument list then it
201             will examine and manipulate @ARGV.
202            
203             If the PEDANTIC option is turned off in the AppConfig::State object, any
204             parsing errors (invalid variables, unvalidated values, etc) will generate
205             warnings, but not cause the method to return. Having processed all
206             arguments, the method will return 1 if processed without warning or 0 if
207             one or more warnings were raised. When the PEDANTIC option is turned on,
208             the method generates a warning and immediately returns a value of 0 as soon
209             as it encounters any parsing error.
210            
211             The method continues parsing arguments until it detects the first one that
212             does not start with a leading dash, '-'. Arguments that constitute values
213             for other options are not examined in this way.
214            
215             =head1 FUTURE DEVELOPMENT
216            
217             This module was developed to provide backwards compatibility (to some
218             degree) with the preceeding App::Config module. The argument parsing
219             it provides is basic but offers a quick and efficient solution for those
220             times when simple option handling is all that is required.
221            
222             If you require more flexibility in parsing command line arguments, then
223             you should consider using the AppConfig::Getopt module. This is loaded
224             and used automatically by calling the AppConfig getopt() method.
225            
226             The AppConfig::Getopt module provides considerably extended functionality
227             over the AppConfig::Args module by delegating out the task of argument
228             parsing to Johan Vromans' Getopt::Long module. For advanced command-line
229             parsing, this module (either Getopt::Long by itself, or in conjunction with
230             AppConfig::Getopt) is highly recommended.
231            
232             =head1 AUTHOR
233            
234             Andy Wardley, E<lt>abw@wardley.orgE<gt>
235            
236             =head1 REVISION
237            
238             $Revision: 1.60 $
239            
240             =head1 COPYRIGHT
241            
242             Copyright (C) 1997-2003 Andy Wardley. All Rights Reserved.
243            
244             Copyright (C) 1997,1998 Canon Research Centre Europe Ltd.
245            
246             This module is free software; you can redistribute it and/or modify it
247             under the same terms as Perl itself.
248            
249             =head1 SEE ALSO
250            
251             AppConfig, AppConfig::State, AppConfig::Getopt, Getopt::Long
252            
253             =cut
254