local-lib5/lib/perl5/AppConfig/Args.pm

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