1\function{cmdopt_new} 2\synopsis{Create a cmdopt object for parsing command-line options} 3\usage{obj = cmdopt_new (Ref_Type error_routine)} 4\description 5 This function creates an returns an object that may be used by the 6 \sfun{cmdopt_process} function to parse command line arguments. The 7 \sfun{cmdopt_new} function takes a reference to an error handling 8 function that will get called upon error. In most cases, this 9 function should print out the error message, display a usage 10 message, and then call \ifun{exit}. If the error handler is \NULL, 11 or it returns instead of calling exit, then an exception will be thrown. 12 13 The error handler must be defined to take a single string argument 14 (the error message) and must return nothing. 15\example 16#v+ 17 require ("cmdopt"); 18 private define help_callback () 19 { 20 () = fputs ("Usage: pgm [options] infile\n", stderr); 21 () = fputs ("Options:\n", stderr); 22 () = fputs (" -h|--help Show this help\n", stderr); 23 () = fputs (" -v|--verbose Increase verbosity level\n", stderr); 24 () = fputs (" -o|--output Output filename [stdout]\n", stderr); 25 exit (1); 26 } 27 private define error_handler (text) 28 { 29 () = fprintf (stderr, "%s\n", text); 30 help_callback (); 31 } 32 define slsh_main () 33 { 34 variable verbose = 0; 35 outfile = "-"; % stdout 36 variable c = cmdopt_new (&error_handler); 37 cmdopt_add (c, "v|verbose", &verbose; inc); 38 cmdopt_add (c, "h|help", &help_callback); 39 cmdopt_add (c, "s:o|output", &outfile; type="str"); 40 variable iend = cmdopt_process (c, __argv, 1); 41 42 if (verbose) message ("some informative message"); 43 variable fp = stdout; 44 if (outfile != "-") fp = fopen (outfile, "w"); 45 . 46 . 47 } 48#v- 49\seealso{cmdopt_add, cmdopt_process} 50\done 51 52\function{cmdopt_process} 53\synopsis{Process the command-line options} 54\usage{Int_Type cmdopt_process (optobj, argv, istart)} 55#v+ 56 Struct_Type optobj; 57 Array_Type argv; 58 Int_Type istart 59#v- 60\description 61 This function parses the command line arguments in the string array 62 \exmp{argv} according to the rules specified by the \exmp{optobj} 63 object, previously allocated by \sfun{cmdopt_new}. The array of 64 strings is processed starting at the index specified by 65 \exmp{istart}. The function returns the index of the array element 66 where parsing stopped. Upon error, the function will call the error 67 handler established by the prior call to \exmp{cmdopt_new}. 68\example 69#v+ 70 define slsh_main () 71 { 72 . 73 . 74 optobj = cmdopt_new (...); 75 cmdopt_add (optobj, ...); 76 . 77 . 78 variable iend = cmdopt_process (optobj, __argv, 1); 79 . 80 . 81 } 82#v- 83\notes 84 This function may also be called in an object-oriented style using the 85 \exmp{process} method: 86#v+ 87 optobj = cmdopt_new (...); 88 optobj.add (...) 89 iend = optobj.process (__argv, 1); 90#v- 91\seealso{cmdopt_add, cmdopt_new} 92\done 93 94\function{cmdopt_add} 95\synopsis{Add support for a command-line option} 96\usage{cmdopt_add (optobj, optname, addr [,...] [;qualifiers])} 97#v+ 98 Struct_Type optobj; 99 String_Type optname; 100 Ref_Type addr; 101#v- 102\description 103 This function adds support for a command-line option to 104 \exmp{optobj} and specifies how that option should be handled. 105 Handling an option involves setting the value of a variable 106 associated with the option, or by calling a function upon its 107 behalf. 108 109 For clarity, assume a command-line option can be specified using the 110 single character \exmp{f} or by the longer name \exmp{foo}. Then the 111 rules for calling \sfun{cmdopt_add} for the various flavors options 112 supported by this interface and how the option may be specified on 113 the command line are as follows: 114 115 Options that set a variable \exmp{v} to a value \exmp{val}: 116#v+ 117 cmdopt_add (optobj, "f|foo", &v; default=val); 118 cmdline: pgm -f ... 119 cmdline: pgm --foo ... 120#v- 121 122 Options that increment an integer variable \exmp{v}: 123#v+ 124 cmdopt_add (optobj, "f|foo", &v; inc); 125 cmdline: pgm -f -f ... % In these examples, v 126 cmdline: pgm --foo --foo ... % gets incremented twice 127#v- 128 129 Options that bitwise-or an integer variable \exmp{v} with \exmp{FLAG}: 130#v+ 131 cmdopt_add (optobj, "f|foo", &v; bor=FLAG); 132 cmdline: pgm -f ... % v = v | FLAG 133 cmdline: pgm --foo ... % v = v | FLAG 134#v- 135 Options that bitwise-and an integer variable \exmp{v} with \exmp{MASK}: 136#v+ 137 cmdopt_add (optobj, "f|foo", &v; band=MASK); 138 cmdline: pgm -f ... % v = v & MASK; 139 cmdline: pgm --foo ... % v = v & MASK; 140#v- 141 The above two options may be combined: 142#v+ 143 cmdopt_add (optobj, "f|foo", &v; bor=FLAG1, band=~FLAG2); 144 cmdline: pgm -f ... % v &= ~FLAG2; v |= FLAG1; 145#v- 146 147 Options that require a value and set \exmp{v} to the value VAL. 148#v+ 149 cmdopt_add (optobj, "f|foo", &v; type="int"); 150 cmdline: pgm -f VAL ... 151 cmdline: pgm -fVAL ... 152 cmdline: pgm --foo VAL ... 153 cmdline: pgm --foo=VAL ... 154#v- 155 156 Options whose value is optional: 157#v+ 158 cmdopt_add (optobj, "f|foo", &v; type="string", optional=DFLT); 159 cmdline: pgm -f ... % set v to DFLT 160 cmdline: pgm -fVAL ... % set v to VAL 161 cmdline: pgm --foo ... % set v to DFLT 162 cmdline: pgm --foo=VAL ... % set v to VAL 163#v- 164 165 For the latter two cases, if the \exmp{append} qualifier is used, 166 then instead of assigning the value to the specified variable, the 167 value will be appended to a list assigned to the variable, e.g., 168#v+ 169 cmdopt_add (optobj, "f|foo", &v; type="float", append); 170#v- 171 Then the command line \exmp{pgm --foo=VAL1 -fVAL2 -f VAL3 ...} will 172 result in the assignment to \exmp{v} or the 3 element list 173 \exmp{\{VAL1, VAL2, VAL3\}}. 174 175 An option can also be associated with a callback function that get 176 called when the option is handled. 177 178 Options that cause a function to be called with arguments 179 \exmp{a0,...}: 180#v+ 181 cmdopt_add (optobj, "f|foo", &func, a0...); 182 cmdline: pgm --foo 183 cmdline: pgm -f 184#v- 185 Here \exmp{func} should be written with the signature: 186#v+ 187 define func (a0, ...) {...} 188#v- 189 Options that take a value and cause a function to be called with 190 additional arguments \exmp{a0,...}: 191#v+ 192 cmdopt_add (optobj, "f|foo", &func, a0,...; type="int"); 193 cmdline: pgm --foo=VAL 194 cmdline: pgm -f VAL 195 cmdline: pgm -fVAL 196#v- 197 In this case, \exmp{func} should be written as 198#v+ 199 define func (value, a0, ...) {...} 200#v- 201 202 As the above examples illustrate, the data-type of the value assigned 203 to a variable must be specified using the \exmp{type} qualifier. 204 Currently the \exmp{type} must be set to one of the following values: 205#v+ 206 "str" (String_Type) 207 "int" (Int_Type) 208 "float" (Double_Type) 209#v- 210\notes 211 This function may also be called in an object-oriented style using the 212 \exmp{add} method: 213#v+ 214 optobj = cmdopt_new (...); 215 optobj.add ("f|foo", &func, a0,...; type="int"); 216#v- 217\seealso{cmdopt_new, cmdopt_process} 218\done 219