sys/man/8/getflags

   1 .TH GETFLAGS 8
   2 .SH NAME
   3 getflags, usage \- command-line parsing for shell scripts
   4 .SH SYNOPSIS
   5 .B aux/getflags $*
   6 .PP
   7 .B aux/usage
   8 .SH DESCRIPTION
   9 .I Getflags
  10 parses the flags in its command-line arguments
  11 according to the environment variable
  12 .BR $flagfmt .
  13 This variable should be a comma-separated list of flag specifiers.
  14 Each flag is a single letter, optionally followed by a
  15 colon and a name. It may be followed by a space-separated
  16 list of argument names.
  17
  18 .PP
  19 .I Getflags
  20 prints an
  21 .IR rc (1)
  22 script to be evaluated by the calling program.
  23 For every flag specified in
  24 .BR $flagfmt ,
  25 the generated script sets a corresponding environment variable.
  26 If the flag specifier contains
  27 .BR :name ,
  28 the corresponding variable  is named
  29 .BR $name .
  30 Otherwise, it is named
  31 .BI $flag x.
  32
  33 .PP
  34 After evaluating the script, the environment variables will
  35 be set as follows:
  36 If a flag is not present in the argument list, the environment
  37 variable will default to the empty list.
  38 If the flag is present and takes no arguments, the environment
  39 variable will be initialized with the string
  40 .BR '1' .
  41 If the flag takes arguments, the flag's variable will be initialized
  42 with a list of those argument values.
  43 The script then sets the variable
  44 .B $*
  45 to the list of remaining non-flag arguments.
  46 .PP
  47 The
  48 .B $status
  49 is variable to the empty string on success, or
  50 .B 'usage'
  51 when there is an error parsing the command line.
  52 .PP
  53 .I Usage
  54 prints a usage message to standard error.
  55 The message is constructed using
  56 .BR $0 ,
  57 .BR $flagfmt ,
  58 and
  59 .BR $args .
  60 The program name is taken from
  61 .BR $0 ,
  62 as set by
  63 .IR rc (1)
  64 The list of flags is extracted from
  65 .BR $flagfmt .
  66 The description of positional argument list is taken from
  67 .BR  $args .
  68
  69 .SH EXAMPLE
  70 .PP
  71 An example of the script generated:
  72 .IP
  73 .EX
  74 % flagfmt='e:example, x, a:arg with args'
  75 % aux/getflags -exa arg list positional stuff
  76 example=()
  77 flagx=()
  78 arg=()
  79 example=1
  80 flagx=1
  81 arg=(arg list)
  82 *=(positional stuff)
  83 status=''
  84 .EE
  85 .PP
  86 Parse the arguments for
  87 .IR leak (1):
  88 .IP
  89 .EX
  90 flagfmt='b:showbmp, s:acidfmt, f binary, r res, x width'
  91 args='name | pid list'
  92 if(! ifs=() eval `{aux/getflags $*} || ~ $#* 0){
  93         aux/usage
  94         exit usage
  95 }
  96 if(~ $#showbmp 0)
  97         echo '-b flag not set'
  98 echo $showbmp   # named
  99 echo $acidfmt   # also named
 100 echo $flagf     # default name
 101 echo $flagr     # default name
 102 .EE
 103 .SH SOURCE
 104 .B /sys/src/cmd/aux/getflags.c
 105 .br
 106 .B /sys/src/cmd/aux/usage.c
 107 .SH SEE ALSO
 108 .IR arg (2)