| 1 | # $Id: Regex.pm,v 1.2 2002/05/27 13:16:55 willijar Exp $ | ||
| 2 | |||
| 3 | require Exporter; | ||
| 4 | package Getopt::Regex; | ||
| 5 | @ISA=qw(Exporter); | ||
| 6 | @EXPORT_OK=qw(GetOptions); | ||
| 7 | use strict; | ||
| 8 | |||
| 9 | =head1 NAME | ||
| 10 | |||
| 11 | Getopt::Regex - handle command line options flexibly using regular expressions | ||
| 12 | |||
| 13 | =head1 SYNOPSIS | ||
| 14 | |||
| 15 | use Getopt::Regex; | ||
| 16 | GetOptions(\@ARGV,[$regex,$ref,$takesarg],...); | ||
| 17 | |||
| 18 | B<\@ARGV> - reference to array of command line arguments | ||
| 19 | B<$regex> - regular expression for identifying the option | ||
| 20 | B<$ref> - reference to a variable to be set or a function which is passed the argument if it exists. | ||
| 21 | B<$takesarg> - if 1 subsequent command line argument is taken as its argument | ||
| 22 | |||
| 23 | =head1 DESCRIPTION | ||
| 24 | |||
| 25 | This package provides a flexible yet simple method for handling | ||
| 26 | command line options. It does not stamp over the callers namespace or, | ||
| 27 | currently, inforce any particular standard for the options - the user | ||
| 28 | can do this if they want. By using anonymous closures sophisticated | ||
| 29 | option specifications can be constructed. | ||
| 30 | |||
| 31 | The function B<GetOptions>, exported from the package takes a | ||
| 32 | reference to the argument list followed by a set of option | ||
| 33 | specifications which are references to arrays containing at least a | ||
| 34 | regular expression to match for the option and a reference to a | ||
| 35 | variable to be set or a function to be called. A third optional | ||
| 36 | argument for each option, if set to 1, pulles off the following | ||
| 37 | command line argument as an argument for that option. | ||
| 38 | |||
| 39 | The simplest use is to set a boolean variable if an argument is set | ||
| 40 | |||
| 41 | GetOptions(\@ARGV,['-[v|V]',\$bool,0]); | ||
| 42 | |||
| 43 | If the option C<'-v'> or C<'-V'> occurs $bool will be set to 1, otherwise | ||
| 44 | it is left unchanged. | ||
| 45 | |||
| 46 | A subsequent command line argument may be used as as an option argument | ||
| 47 | as follows | ||
| 48 | |||
| 49 | GetOptions(\@ARGV,['-f',\$fname,1]); | ||
| 50 | |||
| 51 | will set $fname to fname if '-f fname' is specified on the command line. | ||
| 52 | |||
| 53 | Processed arguments are removed from the argument list. | ||
| 54 | Only the first occurance of an argument is processed, if a | ||
| 55 | variable is being set as in the above examples | ||
| 56 | |||
| 57 | More complex argument specifications are possible using anonymous | ||
| 58 | functions as arguments. If the option takes an argument, the argument | ||
| 59 | is passed to the function. Parts of the regular expression may also | ||
| 60 | be used in the anonymous closure being executed. e.g. | ||
| 61 | |||
| 62 | GetOptions(\@ARGV, | ||
| 63 | ['-D(.+)=(.+)',sub { diagnostic $1,$2; } ,0], | ||
| 64 | ['-D(.+)', sub { diagnostic $1; $_[0]; },1]); | ||
| 65 | |||
| 66 | The first option specification will match options in the format | ||
| 67 | '-DDIAGNOSTIC=VALUE',the second will match occurances of the format | ||
| 68 | '-DDIAGNOSTIC VALUE'. As can be seen use of the regex matching | ||
| 69 | variables can be made in handling the options. | ||
| 70 | |||
| 71 | When B<GetOptions> is called with a function reference the function is | ||
| 72 | called for all matching occurances of the regular expression, and the | ||
| 73 | proceesed options are removed from the argument list. | ||
| 74 | |||
| 75 | Another useful example is | ||
| 76 | |||
| 77 | GetOptions(\@ARGV,['-(no-)*optimization',0,sub { $optimization=!$1; }]); | ||
| 78 | |||
| 79 | which identifies the option statements '-optimization' or | ||
| 80 | '-no-optimization' setting $optimization true or false approptiately. | ||
| 81 | |||
| 82 | The option '--' ends the search for matching options - further | ||
| 83 | arguments are not searched. | ||
| 84 | |||
| 85 | =head1 NOTE | ||
| 86 | |||
| 87 | Requires at least Perl 5.000 or Perl 5.001m if anonymous closures are | ||
| 88 | used. | ||
| 89 | |||
| 90 | =head1 HISTORY | ||
| 91 | |||
| 92 | $Log: Regex.pm,v $ | ||
| 93 | Revision 1.2 2002/05/27 13:16:55 willijar | ||
| 94 | Added in bug fix given be Edmond Abrahamian <edmond@tripos.com> which | ||
| 95 | permits it to work if an argument is zero (but not ""). | ||
| 96 | |||
| 97 | Revision 1.1 2002/05/27 13:14:53 willijar | ||
| 98 | Initial revision | ||
| 99 | |||
| 100 | Revision 1.3 1995/12/16 09:48:28 willijar | ||
| 101 | Rename package to be more consistant with guidlines | ||
| 102 | |||
| 103 | Revision 1.2 1995/12/12 22:01:35 willijar | ||
| 104 | Removed unnecessary default argument. Extended pod documentation. | ||
| 105 | |||
| 106 | Revision 1.1 1995/12/10 15:57:06 willijar | ||
| 107 | Initial revision | ||
| 108 | |||
| 109 | =head1 BUGS | ||
| 110 | |||
| 111 | Please let me know. | ||
| 112 | |||
| 113 | =head1 TODO | ||
| 114 | |||
| 115 | Possibly integrate default behaviour of other option functions in this | ||
| 116 | package. | ||
| 117 | |||
| 118 | =head1 AUTHOR | ||
| 119 | |||
| 120 | John A.R. Williams, <J.A.R.Williams@aston.ac.uk> | ||
| 121 | |||
| 122 | =cut | ||
| 123 | |||
| 124 | sub GetOptions { | ||
| 125 | my ($argv,@options)=@_; | ||
| 126 | foreach (@options) { | ||
| 127 | my ($regex,$ref,$takesarg)=@{$_}; | ||
| 128 | my @args=@{$argv}; | ||
| 129 | @{$argv}=(); | ||
| 130 | my $arg; | ||
| 131 | argloop: | ||
| 132 | while (($arg=shift @args) ne "") { | ||
| 133 | if ($arg=~/$regex/) { | ||
| 134 | my $val=1; | ||
| 135 | if ($takesarg) { $val=shift @args; } | ||
| 136 | if (ref($ref) eq 'CODE') { &$ref($val); } | ||
| 137 | else { ${$ref}=$val; last argloop;} | ||
| 138 | } | ||
| 139 | else { | ||
| 140 | push @{$argv},$arg; | ||
| 141 | if ($arg eq '--') { last argloop; } | ||
| 142 | } | ||
| 143 | } | ||
| 144 | push @{$argv},@args; | ||
| 145 | } | ||
| 146 | } | ||
| 147 | |||
| 148 | 1; |