home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1993 #3 / NN_1993_3.iso / spool / comp / lang / perl / 8009 < prev    next >
Encoding:
Text File  |  1993-01-28  |  27.2 KB  |  1,046 lines
  1. Newsgroups: comp.lang.perl
  2. Path: sparky!uunet!charon.amdahl.com!pacbell.com!ames!saimiri.primate.wisc.edu!zaphod.mps.ohio-state.edu!caen!uvaarpa!mmdf
  3. From: Alan Stebbens <aks%anywhere@hub.ucsb.edu>
  4. Subject: ParseArgs options parser w/bells & whistles
  5. Message-ID: <1993Jan26.194814.919@uvaarpa.Virginia.EDU>
  6. Sender: mmdf@uvaarpa.Virginia.EDU (Mail System)
  7. Reply-To: Alan Stebbens <aks@hub.ucsb.edu>
  8. Organization: The Internet
  9. Date: Tue, 26 Jan 1993 19:48:14 GMT
  10. Lines: 1034
  11.  
  12. The code in the archive below is yet another options parser, but this
  13. one takes care of any requirement I have ever used in any program, C,
  14. Perl, or whatever.
  15.  
  16. I've been using it for a while, but hadn't taken the time to
  17. write the man page.  Well, using "wrapman", it now has an embedded man
  18. page, and a Makefile to install it in your favorite place.
  19.  
  20. Below, is the first page of the man page, so you can see if you care to
  21. even unpack the "sh" archive which follows it.
  22.  
  23. Feel free to submit bug fixes, or suggest improvements.
  24.  
  25. Enjoy.
  26.  
  27. -- Alan Stebbens, UCSB, Santa Barbara <aks@hub.ucsb.edu>
  28. "If all you have is a hammer, then everything looks like a nail."
  29.  
  30. ============================= cut here ===================================
  31.  
  32.      PARSEARGS(3)            (January 14, 1993)           PARSEARGS(3)
  33.  
  34.      NAME
  35.           parseargs.pl - Parse the argument vector
  36.  
  37.      SYNOPSIS
  38.           require 'parseargs.pl'
  39.  
  40.           &ParseOpts('FLAG1 FLAG2 ... FLAGn');
  41.  
  42.           &ParseArgs('FLAG1', 'ACTION1', 'FLAG2', 'ACTION2', ...);
  43.  
  44.           &ParseArgs(<<'EOF');
  45.              FLAG1   ACTION1
  46.              FLAG2   ACTION2
  47.              ...
  48.              FLAGn   ACTIONn
  49.           EOF
  50.  
  51.      DESCRIPTION
  52.           These subroutines parse the current command argument vector,
  53.           @ARGV,  for  switches  which match defined FLAG expressions,
  54.           evaluating associated ACTION expressions.
  55.  
  56.           The argument parsing stops on the first  unhandled  non-flag
  57.           argument.   An  error  is  reported  on  any  unhandled flag
  58.           arguments (-flag).
  59.  
  60.           There are two subroutines: ParseArgs,  and  ParseOpts.   The
  61.           former  is more general and allows complete control over the
  62.           flag strings and  the  associated  actions.   The  ParseOpts
  63.           routine has a simpler interface, with useful default actions
  64.           for the specified flag strings.
  65.  
  66.           In both routines, each FLAG is matched against  the  current
  67.           argument,  and,  if  successful, the corresponding ACTION is
  68.           evaluated, followed by a next.  FLAG can be a  general  Perl
  69.           expression,  or  it  can be one of a special syntax (defined
  70.           below), which is  used  to  create  a  Perl  expression  for
  71.           testing.
  72.  
  73.           Any argument not matching any of the test expressions causes
  74.           an  error.   When  an  error occurs, if the string $Usage is
  75.           defined, it will be printed after the error message.
  76.  
  77.           ACTION can be a general  Perl  expression,  except  that  no
  78.           embedded newlines are permitted.  An empty string, or action
  79.           of `#' is considered to be a null action, for  which  useful
  80.           defaults are supplied.
  81.  
  82.           Within ACTION, the string `ARG' will be substituted with the
  83.           appropriate  Perl expression which evaluates to the argument
  84.           of the switch which selected the action.
  85.  
  86.      Page 1                                          (printed 1/26/93)
  87.  
  88. ============================= cut here ===================================
  89.  
  90. parseargs.shar
  91. ============================= cut here ===================================
  92. #!/bin/sh
  93. # This is a shell archive (produced by shar 3.49)
  94. # To extract the files from this archive, save it to a file, remove
  95. # everything above the "!/bin/sh" line above, and type "sh file_name".
  96. #
  97. # made 01/26/1993 19:43 UTC by aks@anywhere
  98. # Source directory /fs.real/anywhere/home/aks/src/Lang/perl/Lib/parseargs
  99. #
  100. # existing files will NOT be overwritten unless -c is specified
  101. #
  102. #                                                                          
  103. #                                                                          
  104. #
  105. # This shar contains:
  106. # length  mode       name
  107. # ------ ---------- ------------------------------------------
  108. #  19844 -r--r--r-- parseargs.pl
  109. #    534 -r--r--r-- Makefile
  110. #    723 -rwxr-xr-x test.pl
  111. #    113 -rwxr-xr-x test1
  112. #
  113. if test -r _shar_seq_.tmp; then
  114.     echo 'Must unpack archives in sequence!'
  115.     echo Please unpack part `cat _shar_seq_.tmp` next
  116.     exit 1
  117. fi
  118. # ============= parseargs.pl ==============
  119. if test -f 'parseargs.pl' -a X"$1" != X"-c"; then
  120.     echo 'x - skipping parseargs.pl (File already exists)'
  121.     rm -f _shar_wnt_.tmp
  122. else
  123. | _shar_wnt_.tmp
  124. echo 'x - extracting parseargs.pl (Text)'
  125. sed 's/^X//' << 'SHAR_EOF' > 'parseargs.pl' &&
  126. # ParseArgs.pl script for perl
  127. 'di';
  128. 'ig00';
  129. #
  130. # Author: Alan K. Stebbens <aks@hub.ucsb.edu>
  131. # $Id: parseargs.pl,v 1.5 1993/01/26 19:43:43 aks Exp $
  132. # See bottom of file for documentation.
  133. X
  134. $InitParseProgram = '
  135. X Arg:while (@ARGV && ($_ = shift @ARGV)) {
  136. X       $arg = s/=(.*)// ? $1 : undef;
  137. X       while (/^-./) {        # parse clustered switches
  138. X ';
  139. X
  140. $FinishParseProgram = '
  141. X           last;
  142. X       }
  143. X       if (!index(\'-debug\',$_)) {
  144. X       $Debug = $arg || 1; next;
  145. X       }
  146. X       if (!index(\'-verbose\',$_)) {
  147. X       $Verbose = $arg || 1; next;
  148. X       }
  149. X       next if /^-$/;
  150. X       last unless /^-/;
  151. X       die "Bad arg: $_\n", $Usage;
  152. X    }
  153. X    unshift(@ARGV, $_) if length;
  154. X ';
  155. X
  156. sub ParseOpts {
  157. X    local($i);
  158. X    local(@opts) = split(' ',shift);
  159. X    for ($i = $#opts + 1; $i > $[; $i--) {
  160. X        splice(@opts, $i, 0, ''); # insert null actions
  161. X    }
  162. X    &ParseArgs(@opts);
  163. }
  164. X
  165. %ParseArgFlags =   ( '<', 'ParseArgInFile',
  166. X             '>', 'ParseArgOutFile',
  167. X             '/', 'ParseArgDirectory',
  168. X             '.', 'ParseArgPlainFile',
  169. X             '!', 'ParseArgNewFile',
  170. X             '@', 'ParseArgsFromFile',
  171. X             '#', 'ParseNumberArgs',
  172. X             '~', 'ParseUserLogin',
  173. X             '(', 'ParseGroupName',
  174. X             '=', '',
  175. X             ':', '',
  176. X             '+', '',
  177. X             '*', '',
  178. X           );
  179. X
  180. $ParseArgFlags = join('',keys(%ParseArgFlags));
  181. X
  182. sub ParseArgs {
  183. X    local(@arglist) = @_;    # argument list
  184. X    local($_);
  185. X    local($NoArg) = "Missing argument for option: ";
  186. X    if ($#arglist == $[) {    # a single string?
  187. X    local(@lines) = split(/\n/,$arglist[0]);
  188. X    @arglist = ();
  189. X    foreach (@lines) {    # parse strings into FLAG, ACTION pairs
  190. X        if (/^\s*(\S+)\s+(\S.*)$/) {
  191. X        push(@arglist,$1,$2);
  192. X        } elsif (/^\s*(\S+)/) {
  193. X        push(@arglist,$1,''); # default ACTION
  194. X        }
  195. X    }
  196. X    }
  197. X    local($parser,$x,$option,$flag,$action,$expr,$arg,$interp);
  198. X    $parser = $InitParseProgram;
  199. X    for ($x = 0; $x <= $#arglist; $x += 2) {
  200. X    $option = $arglist[$x];
  201. X    $action = $arglist[$x+1];
  202. X    length($option) || next;    # ignore null options
  203. X    $action =~ s/\s*\#\s*$//; # remove any comments
  204. X    $action =~ s/\bARG\b/\$arg/; # substitute
  205. X    # check for --word, -word, +word, or _word w or w/o =
  206. X    if ($option =~ /^(--|-|\+|_)(\w+)(\W|)/) {
  207. X        die "$0: Unknown option flag: $flag\n" 
  208. X        if !defined($ParseArgFlags{$flag = $3});
  209. X        $expr = "\t    if (!index('$1$2',\$_)) {\n";
  210. X        $interp = $ParseArgFlags{$flag};
  211. X        if ($flag) {
  212. X        $arg = "\$arg = defined(\$arg) ? \$arg : shift \@ARGV";
  213. X        $arg .= " || die \"$NoArg $2\\n\", \$Usage" if $flag eq '=';
  214. X        $expr .= "\t\t".$arg.";\n";
  215. X        $expr .= "\t\t\$arg = \&".$interp."(\$2,\$arg);\n" if $interp;
  216. X        $action = "\$opt_$2 = \$arg" unless $action;
  217. X        $expr .= "\t\t".$action.";\n";
  218. X        } else {        # no flag char: -xyz
  219. X        $arg = $1 eq '--' ? 1 : $1 eq '-' ? 2 : $1 eq '+' ? 4 : 8;
  220. X        $action = "\$opt_$2 = $arg" unless $action;
  221. X        $expr .= "\t\t".$action.";\n";
  222. X        }
  223. X        $expr .= "\t\tnext Arg;\n";
  224. X    } elsif ($option =~ /^(\w)(\W)?/) { # how about single character option?
  225. X        $interp = ($flag = $2) && $ParseArgFlags{$flag};
  226. X        die "$0: Unknown option flag: $flag on option $option\n"
  227. X        if index($ParseArgFlags,$flag = $2) < $[;
  228. X        $expr = "\t    if (s/^-$1/-/) {\n";
  229. X        $interp = $ParseArgFlags{$flag};
  230. X        if ($flag) {    # assignment option?
  231. X        $arg = "\$arg = ";
  232. X        if ($flag eq '+' || $flag eq '*') { # sticky args?
  233. X            $expr = "\t    if (s/^-$1(.*)//) {\n";
  234. X            $arg .= "length(\$1) ? \$1 : ";
  235. X        }
  236. X        $arg .= "defined(\$arg) ? \$arg : shift \@ARGV";
  237. X        $arg .= " || die \"$NoArg $1\\n\", \$Usage" 
  238. X            if $flag eq '=' || $flag eq '+';
  239. X        $expr .= "\t\t".$arg.";\n";
  240. X        $expr .= "\t\t\$arg = \&".$interp."(\$2,\$arg);" if $interp;
  241. X        $action = "\$opt_$1 = \$arg" unless $action;
  242. X        $expr .= "\t\t".$action.";\n" if $action;
  243. X        $expr .= "\t\tundef \$arg;\n";
  244. X        } else {
  245. X        $expr .= "\t\t\$opt_$1++;\n" unless $action;
  246. X        $expr .= "\t\t".$action.";\n" if $action;
  247. X        }
  248. X        $expr .= "\t\tnext;\n";
  249. X    } else {        # use option as expr
  250. X        $expr = "\t    if ($option) {\n";
  251. X        $expr .= "\t\t".$action.";\n" if $action;
  252. X        $expr .= "\t\tnext Arg;\n" unless $action !~ /\bnext\b/;
  253. X    }
  254. X    $parser .= $expr;
  255. X    $parser .= "\t    }\n";
  256. X    }
  257. X    $parser .= $FinishParseProgram;
  258. X    print STDERR $parser 
  259. X    if @ARGV && $ARGV[0] eq '-DEBUG_PARSER' && shift @ARGV;
  260. X    eval $parser;
  261. X    die $@ if $@;
  262. }
  263. X    
  264. # Reference this routine in an action if you want an option to 
  265. # insert arguments acquired by reading a file.
  266. X
  267. sub ParseArgsFromFile {
  268. X    local($file) = shift;
  269. X    open(FEXP,$file) || die "Can't open input: $file: $!\n";
  270. X    unshift(@ARGV, grep((chop, s/\s*\#.*$//, length > 0),<FEXP>));
  271. X    close FEXP;
  272. }
  273. X
  274. sub ParseArgInFile {
  275. X    local($opt,$_) = @_;
  276. X    die "$0: File $_ cannot be read!\n" unless -r;
  277. X    open("FH_$opt","<$_") || die "$O: Cannot open $_ for input: $!\n";
  278. X    $_;
  279. }
  280. X
  281. sub ParseArgOutFile {
  282. X    local($opt,$_) = @_;
  283. X    -e && ( -w || die "$0: File $_ cannot be written!\n" );
  284. X    open("FH_$opt",">$_") || die "$0: Cannot open $_ for output: $!\n";
  285. X    $_;
  286. }
  287. X
  288. sub ParseArgDirectory {
  289. X    local($opt,$_) = @_;
  290. X    -e || die "$0: Directory $_ does not exist!\n";
  291. X    -d || die "$0: $_ is not a directory!\n";
  292. X    $_;
  293. }
  294. X
  295. sub ParseArgPlainFile {
  296. X    local($opt,$_) = @_;
  297. X    -e || die "$0: File $_ does not exist!\n";
  298. X    -f || die "$0: File $_ is not a plain file!\n";
  299. X    $_;
  300. }
  301. X
  302. sub ParseArgNewFile {
  303. X    local($opt,$_) = @_;
  304. X    ! -e || die "$0: File $_ already exists!\n";
  305. X    $_;
  306. }
  307. X
  308. sub ParseNumberArgs {
  309. X    local($opt,$_) = @_;
  310. X    /^\d+$/ || die "$0: Option $opt $_ is not a number!\n";
  311. X    $_;
  312. }
  313. X
  314. sub ParseUserLogin {
  315. X    local($opt,$_) = @_;
  316. X    /^\d+$/ ? 
  317. X    $_ == (getpwuid($_))[$[+2] || die "$0: $_ is not a valid user id!\n"
  318. X        : $_ eq (getpwnam($_))[$[] || die "$0: $_ is not a valid login name!\n";
  319. X    $_;
  320. }
  321. X
  322. sub ParseGroupName {
  323. X    local($opt,$_) = @_;
  324. X    /^\d+$/ ?
  325. X    $_ == (getgrgid($_))[$[+2] || die "$0: $_ is not a valid group id!\n"
  326. X        : $_ eq (getgrnam($_))[$[] || die "$0: $_ is not a valid group name!\n";
  327. X    $_;
  328. }
  329. X
  330. 1;
  331. __END__
  332. ###############################################################
  333. X    # These next few lines are legal in both Perl and nroff.
  334. X
  335. .00;                       # finish .ig
  336. X 
  337. 'di           \" finish diversion--previous line must be blank
  338. .nr nl 0-1    \" fake up transition to first page again
  339. .nr % 0         \" start at page 1
  340. .rm ';
  341. .\" Bullet Item
  342. .de Bi
  343. .TP 1i
  344. .B \\h'.5i'\\$1
  345. ..
  346. .TH PARSEARGS 3 "January 14, 1993"
  347. .AT 3
  348. .SH NAME
  349. parseargs.pl - Parse the argument vector
  350. .SH SYNOPSIS
  351. .B require 'parseargs.pl'
  352. .sp
  353. .B &ParseOpts('FLAG1 FLAG2 ... FLAGn');
  354. .sp
  355. .B &ParseArgs('FLAG1', 'ACTION1', 'FLAG2', 'ACTION2', ...);
  356. .sp
  357. .nf
  358. .na
  359. .ft B
  360. &ParseArgs(<<'EOF');
  361. X   FLAG1   ACTION1
  362. X   FLAG2   ACTION2
  363. X   ...
  364. X   FLAGn   ACTIONn
  365. EOF
  366. .ft R
  367. .ad
  368. .fi
  369. .SH DESCRIPTION
  370. These subroutines parse the current command argument vector, 
  371. .BR @ARGV ,
  372. for switches which match defined 
  373. .B FLAG
  374. expressions, evaluating associated 
  375. .B ACTION
  376. expressions.
  377. .sp
  378. The argument parsing stops on the first unhandled non-flag argument.
  379. An error is reported on any unhandled flag arguments (\c
  380. .BI -flag ).
  381. .sp
  382. There are two subroutines: 
  383. .BR ParseArgs ,
  384. and 
  385. .BR ParseOpts .
  386. The former is
  387. more general and allows complete control over the flag strings and the
  388. associated actions.  The 
  389. .B ParseOpts
  390. routine has a simpler interface,
  391. with useful default actions for the specified flag strings.
  392. .sp
  393. In both routines, each 
  394. .B FLAG
  395. is matched against the current argument,
  396. and, if successful, the corresponding 
  397. .B ACTION 
  398. is evaluated, followed by
  399. a 
  400. .BR next .
  401. .B FLAG
  402. can be a general Perl expression, or it can be one of
  403. a special syntax (defined below), which is used to create a Perl
  404. expression for testing.
  405. .sp
  406. Any argument not matching any of the test expressions causes an error.
  407. When an error occurs, if the string 
  408. .B $Usage
  409. is defined, it will be
  410. printed after the error message.
  411. .sp
  412. .B ACTION
  413. can be a general Perl expression, except that no embedded
  414. newlines are permitted.  An empty string, or action of 
  415. .B `#'
  416. is considered to be a null action, for which useful defaults are
  417. supplied.
  418. .sp
  419. Within 
  420. .BR ACTION ,
  421. the string 
  422. .I `ARG'
  423. will be substituted with the
  424. appropriate Perl expression which evaluates to the argument of the switch
  425. which selected the action. 
  426. .sp
  427. In the case of 
  428. .BR ParseOpts ,
  429. all actions are provided by default.
  430. .sp
  431. As a convenience for Perl script writers (that is, myself :^), the
  432. following flags and actions are supplied, after all other flags have
  433. been tested: 
  434. .sp
  435. .nf
  436. .B \t-debug\t$DEBUG++
  437. .B \t-verbose\t$VERBOSE++
  438. .fi
  439. .sp
  440. Also, for the case of when arguments may be obtained by reading a file
  441. passed as an argument itself, the user may reference the subroutine
  442. .B &ParseArgsFromFile(\c
  443. .IB ARG )
  444. as an action, where 
  445. .I ARG
  446. is the special
  447. string recognized and substituted with an appropriate expression.
  448. .sp
  449. The syntax of 
  450. .B FLAG
  451. is:
  452. .TP .5i
  453. (a) \fB(--|-|+|_)\fIWORD\fB[\fIF\fB]\fR
  454. .sp
  455. This syntax allows the various methods of setting switches to be
  456. recognized, with an optional trailing flag character
  457. .IR `F' ,
  458. indicating how to handle the
  459. argument, if any.
  460. If there is no graphic character suffixed to the
  461. .IR WORD ,
  462. then the option accepts no arguments, and is set to 1 when supplied on
  463. the command line.
  464. .sp
  465. The following graphic flag characters are recognized and provide for
  466. interpretation of the arguments, when given.  When an explicit user
  467. action is given in conjunction with one of these flag characters, the
  468. interpretation action is accomplished before the user action.  When no
  469. user action is given, the default variable,
  470. .BI `$opt_ WORD' ,
  471. is assigned the value of the argument.
  472. .Bi `='
  473. this flag accepts a required argument, either in the same word following an
  474. equal sign (\c
  475. .BR `=' ),
  476. or in the next word of the argument vector.  That is, both of these
  477. argument types are valid:
  478. .sp
  479. .B \t-WORD=VALUE\t
  480. and
  481. .B \t-WORD VALUE
  482. .sp
  483. An omitted argument is an error with the \fB`='\fP flag character.
  484. .Bi `:'
  485. this flag character causes the option to take an 
  486. optional argument, not causing an error should it be omitted.
  487. .Bi `<'
  488. treat the argument as an input file,
  489. causing an error if the file is non-existent or unreadable.  The file is
  490. opened for reading under the file handle 
  491. .BI FH_ WORD.
  492. .Bi `>'
  493. treat the argument as an output file,
  494. causing an error if the file is not writable.  The file is opened for
  495. writing under the file handle
  496. .BI FH_ WORD.
  497. .Bi `/'
  498. treat the argument as a directory, which must exist.
  499. .Bi "`.'" "(a period)"
  500. treat the argument as a plain file which must exist; if the file is a
  501. directory, or a special file, then an error occurs.  Symbolic links are
  502. ok, if they point to a plain file.
  503. .Bi `!'
  504. treat the argument as a new, nonexistent file name.  An error occurs if
  505. the file already exists, in any form.
  506. .Bi `#'
  507. treat the argument as an integer, causing an error for any non-digits
  508. found.
  509. .Bi `~'
  510. verify the argument as a valid user login name or numerical user id.
  511. .Bi `('
  512. treat the argument as a valid group name, or numerical group id.
  513. .Bi `@'
  514. treat the argument as a readable file, read the files contents, and
  515. split the lines into the argument vector, 
  516. .BR @ARGV .
  517. .IP "" .5i
  518. The switches recognized by 
  519. .I (a)
  520. may all be minimally abbreviated, as
  521. the test expression used to recognize the switch is
  522. .B `!index(FLAG,$_)'.
  523. Thus, for the flag 
  524. .BR `-edit' , 
  525. the options 
  526. .BR `-edit' ,
  527. .BR `-edi' ,
  528. .BR `-ed',
  529. and
  530. .B `-e'
  531. will be recognized.
  532. .sp
  533. When designing switch names with abbreviation, care must be taken to
  534. specify the longer abbreviations first, so they will not be masked
  535. by shorter ones.
  536. .sp
  537. The default 
  538. .B ACTION
  539. performed by a switch matching this style 
  540. .BR FLAG ,
  541. is to set a Perl variable,
  542. .BI $opt_ WORD,
  543. to a `1', if no value was given, or to the argument supplied.
  544. .sp
  545. X  The following are all examples of this syntax:
  546. .sp
  547. .B  --list-all -edit +help -verbose _broadcast= _netmask=
  548. .B  -input< -output> -dir/ --user~ -file@ -count#
  549. .sp
  550. .TP .5i
  551. (b) \fIC\fB[=:<>/.!#~(+*]\fR
  552. .sp
  553. In this syntax, 
  554. .B C
  555. is a single character switch, which may be followed by one of the
  556. previously documented flag characters, or one of the following two 
  557. additional ones:
  558. .Bi `+'
  559. This flag character causes the option to require an argument, which may
  560. be given either juxtaposed with the option word itself, or on the
  561. subsequent argument vector word.
  562. .Bi `*'
  563. This flag character causes the option to attempt to obtain an argument,
  564. and failing that, cause no error.
  565. .IP "" .5i
  566. Single character switches may be given separately, or may be clustered into
  567. a single switch word.  For example, the options
  568. .B -l
  569. and
  570. .BR -t ,
  571. may be given as:
  572. .B -lt
  573. or
  574. .BR -tl .
  575. .sp
  576. The single character assignable options may require arguments, or
  577. they may be optional.  The argument syntax may be one of:
  578. .sp
  579. .nf
  580. .B \t\fR(1)\fB `-O=arg'
  581. .B \t\fR(2)\fB `-Oarg'
  582. .B \t\fR(3)\fB `-O arg'
  583. .fi
  584. .sp
  585. where 
  586. .B `-O'
  587. is your favorite option.  The argument flags 
  588. .B `=' 
  589. and 
  590. .B `:'
  591. indicate required or optional arguments which can only be assigned
  592. via styles 
  593. .I (1) 
  594. and 
  595. .IR (3) .
  596. The argument flags 
  597. .B `+' 
  598. and 
  599. .B `*'
  600. also mean required and optional, but indicate that style 
  601. .I (2)
  602. is permissible, which disallows option clustering.
  603. .sp
  604. The following table should make this a little clearer:
  605. .sp
  606. .ta .5i +.5i +1i +1i +1i
  607. .nf
  608. .ft B
  609. X    Flag    Argument?    -O=arg    -Oarg    -O arg
  610. .ft R
  611. X    ----    ---------    ------    -----    ------
  612. X     \fB=\fP    required      ok      no      ok      
  613. X     \fB:\fP    optional      ok      no      ok
  614. X     \fB+\fP    required      ok      ok      ok
  615. X     \fB*\fP    optional      ok      ok      ok
  616. .fi
  617. .ta 0.5i
  618. .sp
  619. If a switch defined with an argument is given in a cluster, its
  620. argument may come from:
  621. .sp 
  622. .IP \\h'.5i'1. 1i
  623. the immediately following characters, if the 
  624. .I FLAG
  625. is defined as 
  626. .B `C+' 
  627. or 
  628. .BR `C*' .
  629. This behavior is similar to how 
  630. .I lpr
  631. parses its printer switch: 
  632. .BR `-Pprinter' .
  633. In this case, the flag would be given as
  634. .BR `P+' .
  635. If the flag is defined as 
  636. .BR `P=' ,
  637. then either an equal sign must be used, or the subsequent word will be
  638. used as the argument.
  639. .sp
  640. .IP \\h'.5i'2. 1i
  641. the string followed by the equal sign (\fB`='\fP)
  642. in the same word as the switch.  This allows single character switches
  643. to be given similar to longer switches:
  644. .B `-l=999'
  645. or 
  646. .BR `-length=999' .
  647. .IP \\h'.5i'3. 1i
  648. the subsequent word in the argument vector, if there are no
  649. strings resulting from cases 
  650. .I (1)
  651. or 
  652. .I (2)
  653. above.
  654. .sp 
  655. The default action for this style flag is to increment a Perl
  656. variable, 
  657. .BI $opt_ C, 
  658. where 
  659. .B `C' 
  660. is the single character switch name, or to set its value to the argument
  661. if defined to accept arguments. 
  662. For example, if the flags 
  663. .B `l'
  664. and 
  665. .B `t'
  666. were defined, then the switch 
  667. .B `-lt'
  668. would cause the variables
  669. .B $opt_l
  670. and
  671. .B $opt_t
  672. to both be incremented.
  673. .TP .5i
  674. (c) \fBexpr\fR
  675. This syntax is the usual Perl expression.  It is tested
  676. directly, and no default action is assumed; actions must be
  677. specified by the user.
  678. .PP
  679. Since the order of the flags is the order in which the tests will be
  680. performed, if the user mixes flag styles, and there are overlaps between
  681. single character options and word options, the word options should
  682. be specified first, otherwise the single character parsing will cause
  683. the word argument to get broken into characters.
  684. .PP
  685. In order to facilitate debugging the options specifications and the 
  686. resulting parser, if the first argument is
  687. .BR `-DEBUG_PARSER' ,
  688. then the parser code will be printed to 
  689. .B STDERR
  690. before being eval'ed.
  691. .SH EXAMPLES
  692. .sp
  693. .nf
  694. .ft B
  695. &ParseArgs(<<'EOF')            \fR# NOTE: single quotes!\fB
  696. X    t     $tbl++
  697. X    l     $lst++
  698. EOF
  699. .ft R
  700. .fi
  701. .IP
  702. This example recognizes the 
  703. .B `-t'
  704. and 
  705. .B `-l'
  706. switches, which may be
  707. given separately or combined as 
  708. .B `-lt' 
  709. or 
  710. .BR `-tl' ,
  711. and sets the associated variables accordingly.  In this case, the
  712. default variable assignments (\c
  713. .B $opt_t
  714. and 
  715. .BR $opt_l )
  716. are NOT done.
  717. .PP
  718. .nf
  719. .ft B
  720. &ParseArgs('t', '$tbl++', 'l', '$lst++');
  721. .ft R
  722. .fi
  723. .IP
  724. This is equivalent to the previous example.
  725. .PP
  726. .ft B
  727. &ParseOpts('t l');
  728. .ft R
  729. .IP
  730. This is essentially equivalent to the first two examples, except
  731. that the variables set for 
  732. .B `-t'
  733. and 
  734. .B `-l'
  735. are 
  736. .B $opt_t
  737. and 
  738. .BR $opt_l ,
  739. respectively.
  740. .PP
  741. .nf
  742. .ft B
  743. &ParseOpts('-file= -list: -edit -optimize');
  744. .ft R
  745. .fi
  746. .IP
  747. In this example, the variables set would be: 
  748. .BR $opt_file ,
  749. .BR $opt_list ,
  750. .BR $opt_edit ,
  751. and 
  752. .BR $opt_optimize .
  753. The 
  754. .B `-list'
  755. option has an optional argument, while 
  756. .B `-file'
  757. must be supplied with an argument or an error will result.
  758. .PP
  759. .nf
  760. .ft B
  761. &ParseArgs(<<'EOF");
  762. X     -file=   &ParseArgsFromFile(ARG);
  763. X     b        $Brief++
  764. X     v        $Verbose++
  765. X     l*       $Len = ARG || 80
  766. X     -edit
  767. X     -arch=   $Arch = ARG
  768. X     -os=     $OS = ARG
  769. EOF
  770. .fi
  771. .ft R
  772. .IP
  773. This example illustrates the combination of the various types,
  774. including a default action.  
  775. .sp
  776. The 
  777. .B `-file'
  778. switch, which may be abbreviated as 
  779. .B `-f'
  780. causes the routine,
  781. .I &ParseArgsFromFile
  782. to be invoked with computed argument 
  783. .B (ARG)
  784. of the 
  785. .B `-file'
  786. switch.  The arguments read from the file argument are then placed on
  787. the argument stack as if they had been typed by the user.  These new
  788. arguments are parsed along with any remaining, original arguments.
  789. .sp
  790. The 
  791. .B $Brief
  792. and
  793. .B $Verbose
  794. variables will be set if their respective, clusterable option flags are
  795. given. 
  796. .sp
  797. The 
  798. .B `-l'
  799. option may be optionally given an argument, either as
  800. .B `-lXYZ' or 
  801. .BR `-l\ XYZ' ;
  802. it is assigned to 
  803. .BR $Len .
  804. .sp
  805. The variable
  806. .B $opt_edit 
  807. will be set (to 1).
  808. .sp
  809. The 
  810. .B $Arch
  811. variable will be set to the argument supplied to the
  812. .B `-arch'
  813. switch; similarly, the
  814. .B $OS 
  815. variable will be set by the 
  816. .B `-os'
  817. switch, both of which may be abbreviated.
  818. .sp
  819. .PP
  820. .ft B
  821. &ParseOpts('-in< -out> -directory/ -file. -user~ -group( -num# -new!');
  822. .ft R
  823. .PP
  824. This is a rather baroque example illustrating the features of useful
  825. default actions.  The following variables will be set as follows.
  826. .TP 1i
  827. .B $opt_in
  828. is set to the name of a file which is opened for input, using the
  829. filehandle of
  830. .BR `FH_in' .
  831. The variable and filehandle names are always 
  832. .BI `$opt_ OPTION'
  833. and
  834. .BI `FH_ OPTION'.
  835. If the file could not be opened for input, an error would have occurred.
  836. .TP
  837. .B $opt_out
  838. is set to the name of a file opened for writing, using the filehandle of
  839. .BR `FH_out' .
  840. .TP
  841. .B $opt_directory
  842. is set to the name of an existing directory; an error will occur if the
  843. directory doesn't exist.
  844. .TP
  845. .B $opt_file
  846. is set to the name of an existing file; no other tests are made, just
  847. existence.  If the file given as an argument doesn't exist, an error
  848. occurs.
  849. .TP
  850. .B $opt_user
  851. is set to the name of a valid user login name or numeric user id.
  852. .TP
  853. .B $opt_group
  854. is set to the name of a valid group name or numeric group id.
  855. .TP
  856. .B $opt_num
  857. is set to a number given as the argument; anything other than a number
  858. causes an error.
  859. .IP
  860. .B $opt_new
  861. is set to the name of a non-existent file; an error occurs if the file
  862. already exists.
  863. .sp
  864. .SH ENVIRONMENT
  865. .B
  866. .IP @ARGV
  867. The argument vector is implicitly parsed.
  868. .SH FILES
  869. None.
  870. .SH AUTHOR
  871. Alan Stebbens <aks@hub.ucsb.edu>
  872. .SH "SEE ALSO"
  873. .IR getopts.pl (3),
  874. .IR perl (1)
  875. .SH DIAGNOSTICS
  876. .PP
  877. When an error occurs, one of the following error messages is generated,
  878. followed by the value of 
  879. .I $Usage
  880. if it is defined.
  881. .sp
  882. Unknown option flag: $flag
  883. .sp
  884. Can't open input: $file: $!
  885. .sp
  886. Unknown option flag: $flag on option $option
  887. .sp
  888. File $_ cannot be read!
  889. .sp
  890. File $_ cannot be written
  891. .sp
  892. Cannot open $_ for output: $!
  893. .sp
  894. Directory $_ does not exist!
  895. .sp
  896. $_ is not a directory!
  897. .sp
  898. File $_ does not exist!
  899. .sp
  900. File $_ is not a plain file!
  901. .sp
  902. File $_ already exists!
  903. .sp
  904. Option $opt: $_ is not a number!
  905. .sp
  906. $_ is not a valid user id!
  907. .sp
  908. $_ is not a valid login name!
  909. .sp
  910. $_ is not a valid group id!
  911. .sp
  912. $_ is not a valid group name!
  913. .sp
  914. Missing argument for option: $option
  915. .sp
  916. Bad option: $option
  917. .SH BUGS
  918. Probably.
  919. .\" Emacs Local Variables:
  920. .\" Emacs mode: perl
  921. .\" Emacs End:
  922. SHAR_EOF
  923. chmod 0444 parseargs.pl ||
  924. echo 'restore of parseargs.pl failed'
  925. Wc_c="`wc -c < 'parseargs.pl'`"
  926. test 19844 -eq "$Wc_c" ||
  927.     echo 'parseargs.pl: original size 19844, current size' "$Wc_c"
  928. rm -f _shar_wnt_.tmp
  929. fi
  930. # ============= Makefile ==============
  931. if test -f 'Makefile' -a X"$1" != X"-c"; then
  932.     echo 'x - skipping Makefile (File already exists)'
  933.     rm -f _shar_wnt_.tmp
  934. else
  935. | _shar_wnt_.tmp
  936. echo 'x - extracting Makefile (Text)'
  937. sed 's/^X//' << 'SHAR_EOF' > 'Makefile' &&
  938. # Makefile to install parseargs
  939. X
  940. X    ROOT = /eci/share
  941. X PERLLIB = $(ROOT)/lib/perl
  942. X  MANDIR = $(ROOT)/man/man3
  943. X
  944. X INSTALL = /usr/ucb/install
  945. X
  946. I    = ( set -x ; $(INSTALL) -c -m 444 $? $@ )
  947. L    = ( set -x ; ln -s $? $@ )
  948. R    = if [ -f $@ ]; then rm -f $@ ; fi
  949. X
  950. default:
  951. X    @( set -x ; $(MAKE) -n install )
  952. X
  953. install: $(PERLLIB)/parseargs.pl $(MANDIR)/parseargs.3
  954. X
  955. $(PERLLIB)/parseargs.pl:    parseargs.pl ;            @$R ; $I
  956. $(MANDIR)/parseargs.3:        $(PERLLIB)/parseargs.pl ;    @$R ; $L
  957. X
  958. shar:
  959. X    shar -L50 -o parseargs.shar parseargs.pl Makefile test.pl test1
  960. SHAR_EOF
  961. chmod 0444 Makefile ||
  962. echo 'restore of Makefile failed'
  963. Wc_c="`wc -c < 'Makefile'`"
  964. test 534 -eq "$Wc_c" ||
  965.     echo 'Makefile: original size 534, current size' "$Wc_c"
  966. rm -f _shar_wnt_.tmp
  967. fi
  968. # ============= test.pl ==============
  969. if test -f 'test.pl' -a X"$1" != X"-c"; then
  970.     echo 'x - skipping test.pl (File already exists)'
  971.     rm -f _shar_wnt_.tmp
  972. else
  973. | _shar_wnt_.tmp
  974. echo 'x - extracting test.pl (Text)'
  975. sed 's/^X//' << 'SHAR_EOF' > 'test.pl' &&
  976. #!/bin/perl
  977. X
  978. require 'parseargs.pl';
  979. X
  980. $Usage = <<EOF;
  981. usage: $0 -input INPUT -output OUTPUT -new NEW -exists OLD
  982. X      -login LOGIN -group GROUP -number NUM
  983. EOF
  984. X    
  985. &ParseArgs(<<'EOF');
  986. X    -input<
  987. X    -dir/
  988. X    -output>
  989. X    -new!
  990. X    -exists.
  991. X    -login~
  992. X    -group(
  993. X    -number#
  994. EOF
  995. X
  996. format STDOUT =
  997. X input = @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  998. X     $opt_input
  999. X   dir = @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  1000. X     $opt_dir
  1001. output = @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  1002. X     $opt_output
  1003. X   new = @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  1004. X     $opt_new
  1005. exists = @<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  1006. X     $opt_exists
  1007. X login = @<<<<<<<<<<<<<<
  1008. X     $opt_login
  1009. X group = @<<<<<<<<<<<<<<<
  1010. X     $opt_group
  1011. number = @<<<<<<<<<<<<<<
  1012. X     $opt_number
  1013. .
  1014. X
  1015. write;
  1016. X
  1017. exit;
  1018. SHAR_EOF
  1019. chmod 0755 test.pl ||
  1020. echo 'restore of test.pl failed'
  1021. Wc_c="`wc -c < 'test.pl'`"
  1022. test 723 -eq "$Wc_c" ||
  1023.     echo 'test.pl: original size 723, current size' "$Wc_c"
  1024. rm -f _shar_wnt_.tmp
  1025. fi
  1026. # ============= test1 ==============
  1027. if test -f 'test1' -a X"$1" != X"-c"; then
  1028.     echo 'x - skipping test1 (File already exists)'
  1029.     rm -f _shar_wnt_.tmp
  1030. else
  1031. | _shar_wnt_.tmp
  1032. echo 'x - extracting test1 (Text)'
  1033. sed 's/^X//' << 'SHAR_EOF' > 'test1' &&
  1034. #!/bin/sh
  1035. set -x
  1036. ./test.pl -input=test.pl -dir . -output=xyz -new=qrz -exists=test1 -login bin -group bin -num 1
  1037. SHAR_EOF
  1038. chmod 0755 test1 ||
  1039. echo 'restore of test1 failed'
  1040. Wc_c="`wc -c < 'test1'`"
  1041. test 113 -eq "$Wc_c" ||
  1042.     echo 'test1: original size 113, current size' "$Wc_c"
  1043. rm -f _shar_wnt_.tmp
  1044. fi
  1045. exit 0
  1046.