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