9base

revived minimalist port of Plan 9 userland to Unix
git clone git://git.suckless.org/9base
Log | Files | Refs | README | LICENSE

getflags.1 (1817B)


      1 .TH GETFLAGS 8
      2 .SH NAME
      3 getflags, usage \- command-line parsing for shell scripts
      4 .SH SYNOPSIS
      5 .B getflags $*
      6 .PP
      7 .B usage [ progname ]
      8 .SH DESCRIPTION
      9 .I Getflags
     10 parses the options in its command-line arguments
     11 according to the environment variable
     12 .BR $flagfmt .
     13 This variable should be a list of comma-separated options.
     14 Each option can be a single letter, indicating that it does
     15 not take arguments, or a letter followed by the space-separated
     16 names of its arguments.
     17 .I Getflags 
     18 prints an 
     19 .IR rc (1)
     20 script on standard output which initializes the
     21 environment variable
     22 .BI $flag x
     23 for every option mentioned in 
     24 .BR $flagfmt .
     25 If the option is not present on the command-line, the script
     26 sets that option's flag variable to an empty list.
     27 Otherwise, the script sets that option's flag variable with
     28 a list containing the option's arguments or, 
     29 if the option takes no arguments,
     30 with the string
     31 .BR 1 .
     32 The script also sets the variable
     33 .B $*
     34 to the list of arguments following the options.
     35 The final line in the script sets the
     36 .B $status
     37 variable, to the empty string on success
     38 and to the string
     39 .B usage
     40 when there is an error parsing the command line.
     41 .PP
     42 .I Usage
     43 prints a usage message to standard error.
     44 It creates the message using
     45 .BR $flagfmt ,
     46 as described above,
     47 .BR $args ,
     48 which should contain the string to be printed explaining
     49 non-option arguments,
     50 and
     51 .BR $0 ,
     52 the program name
     53 (see
     54 .IR rc (1)).
     55 If run under 
     56 .IR sh (1),
     57 which does not set
     58 .BR $0 ,
     59 the program name must be given explicitly on the command line.
     60 .SH EXAMPLE
     61 Parse the arguments for
     62 .IR leak (1):
     63 .IP
     64 .EX
     65 flagfmt='b,s,f binary,r res,x width'
     66 args='name | pid list'
     67 if(! ifs=() eval `{getflags $*} || ~ $#* 0){
     68 	usage
     69 	exit usage
     70 }
     71 .EE
     72 .SH SOURCE
     73 .B \*9/src/cmd/getflags.c
     74 .br
     75 .B \*9/src/cmd/usage.c
     76 .SH SEE ALSO
     77 .IR arg (3)