-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathargv.html
473 lines (368 loc) · 14.2 KB
/
argv.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
<html>
<head>
<title>Argv - Not just another getopt.</title>
<style type="text/css">
dt { font-weight: bold; }
code {
background-color: #EEF;
}
pre.example {
padding: 0.5em;
border: 2px solid #80F;
background-color: #EDF;
}
pre.proto {
margin-left: 5%;
padding: 0.5em;
border: 2px solid #00F;
background-color: #EEF;
}
</style>
</head>
<body>
<h1>Argv - Not just another getopt.</h1>
<p>Okay, so it is just another <code>getopt</code>. One with
custom error callback functions, no global data, a useable API,
and a modern common-usage command-line syntax that's compatible
with <code>getopt</code>.</p>
<h2><a name="contents">Contents</a></h2>
<ul>
<li><a href="#syntax">Command-line Syntax</a>
<ul>
<li><a href="#matching">Option Matching</a></li>
<li><a href="#standards">Standards</a></li>
</ul>
</li>
<li><a href="#interface">Interface</a>
<ul>
<li><a href="#ARGVPARSER"><code>ARGVPARSER</code></a></li>
<li><a href="#ARGV"><code>ARGV</code></a></li>
<li><a href="#ARGV_LAST"><code>ARGV_LAST</code></a></li>
<li><a href="#ARGV_NOARG"><code>ARGV_NOARG</code></a></li>
<li><a href="#ARGV_ARG"><code>ARGV_ARG</code></a></li>
<li><a href="#ARGV_ARGA"><code>ARGV_ARGA</code></a></li>
<li><a href="#ARGV_REQ"><code>ARGV_REQ</code></a></li>
<li><a href="#ARGV_REQA"><code>ARGV_REQA</code></a></li>
<li><a href="#argv_init"><code>argv_init</code></a></li>
<li><a href="#argv_uninit"><code>argv_uninit</code></a></li>
<li><a href="#argv_set_args"><code>argv_set_args</code></a></li>
<li><a href="#argv_set_mixed"><code>argv_set_mixed</code></a></li>
<li><a href="#argv_set_errorf"><code>argv_set_errorf</code></a></li>
<li><a href="#argv_error_count"><code>argv_error_count</code></a></li>
<li><a href="#argv_set_progname"><code>argv_set_progname</code></a></li>
<li><a href="#argv_next"><code>argv_next</code></a></li>
</ul>
</li>
<li><a href="#example">Example Usage</a></li>
</ul>
<hr>
<h2><a name="syntax">Command-line Syntax</a></h2>
<p>The following argument syntaxes are recognized:</p>
<dl>
<dt>Short option</dt>
<dd>
<p>Short options consist of a single character, preceeded by a single
hyphen.</p>
<p>The argument may be separate, assigned (attached with an equals sign),
or attached directly.</p>
<p>The argument must immediately follow the option.</p>
<p>Multiple short options may be specified per hyphen. Only options
that have either no argument or a non-attached required argument are
allowed. Arguments to these options must not be assigned and must
be given in the same order as the options.</p>
<pre class="example">
program -o # no argument
program -o arg # separate argument
program -o=arg # assigned argument
program -oarg # attached argument
program -abc b_arg # multiple options
</pre>
</dd>
<dt>Long option</dt>
<dd>
<p>Long options consist of a string, preceeded by one or two hyphens.</p>
<p>The option name may be abbreviated to a unique prefix.</p>
<p>The argument may be separate or assigned.</p>
<p>The argument must immediately follow the option.</p>
<pre class="example">
program -opt --opt # no argument
program -opt arg --opt arg # separate argument
program -opt=arg --opt=arg # assigned argument
</pre>
</dd>
<dt>Parameter</dt>
<dd>
<p>A parameter is an argument without an option.</p>
<p>These may be mixed with options if
<a href="#argv_set_mixed"><code>argv_set_mixed</code></a> is called with
a non-zero value.</p>
<pre class="example">
program file1 -opt arg file2
</pre>
</dd>
<dt>Single Hyphen</dt>
<dd>
<p>A single hyphen by itself is treated as an argument or parameter.</p>
<pre class="example">
program - -o -
</pre>
</dd>
<dt>Double Hyphen</dt>
<dd>
<p>A doubled hyphen by itself is the end of options.
Everything after is treated as a parameter.</p>
<pre class="example">
program --opt arg -- -param1 param2
</pre>
</dd>
</dl>
<h3><a name="matching">Option Matching</a></h3>
<p>An option is matched as follows:</p>
<ol type="1">
<li>If the option is a single character and only one hyphen preceeds it,
then look for a match to a short option.</li>
<li>Look for an exact match to a long option.</li>
<li>Look for a match to a unique prefix of a long option.</li>
<li>If only one hyphen preceeds it, look for only those options
that may have an attached argument.</li>
<li>If only one hyphen preceeds it and the entire option string
consists of valid short options, begin matching its contents.</li>
<li>The option is unknown.</li>
</ol>
<p>Note that there are three ambiguous syntaxes:</p>
<ul>
<li>an attached argument</li>
<li>a long option with a single hyphen</li>
<li>multiple short options</li>
</ul>
<p>A multiple short option cannot be confused with an attached argument
because options with attached arguments are not allowed in a multiple
short option.</p>
<p>Incorrect matches may occur under the following circumstances:</p>
<ul>
<li>Options “<code>A</code>” and “<code>AB</code>”
are defined and “<code>A</code>” takes an attached argument
which may be “<code>B</code>”.</li>
<li>Options “<code>A</code>”, “<code>B</code>”,
and “<code>AB</code>” are defined, and
“<code>A</code>” and “<code>B</code>” are
specified as a multiple short option.</li>
</ul>
<h3><a name="standards">Standards</a></h3>
<p>This library can be used by programs that follow
Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10
in the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2,
Utility Syntax Guidelines. This is the same as <code>getopt</code>.</p>
<p>In other words: options may be a single alpha-numeric character (3),
options start with a hyphen (4), multiple short
options may be specified per hyphen (5), options and
arguments are separate unless otherwise specified (6), all arguments
may be non-optional (7), all options
can optionally preceed all parameters (9), and the
double-hyphen ends options (10).</p>
<p>Compliance with these guidelines, and avoiding our additional
features, is the program's responsibility.</p>
<p>Additional features include: optional arguments, assigned
arguments, mixed options and parameters, non-alpha-numeric options,
and long options.</p>
<hr>
<h2><a name="interface">Interface</a></h2>
<h3><a name="ARGVPARSER"><code>ARGVPARSER</code></a></h3>
<p>The parser's state object. The internals are private. It should
be declared directly, not as a pointer.</p>
<pre class="example">
ARGVPARSER apr;
</pre>
<h3><a name="ARGV"><code>ARGV</code></a></h3>
<p>A <code>struct</code> that contains information on an option.
These are declared as an array. The last entry in the array
must be <a href="#ARGV_LAST"><code>ARGV_LAST</code></a>.</p>
<p>The members are:</p>
<dl>
<dt><code>char optchar</code></dt>
<dd>
The short option character.
</dd>
<dt><code>char* optname</code></dt>
<dd>
The long option name.
</dd>
<dt><code>size_t optlen</code></dt>
<dd>
The long option name's length. If zero,
<a href="#argv_init"><code>argv_init</code></a> and
<a href="#argv_set_args"><code>argv_set_args</code></a> will
replace it with the result of <code>strlen(optname)</code>.
</dd>
<dt><code>int optarg</code></dt>
<dd>
Information on the option's argument.
</dd>
<dt><code>int optval</code></dt>
<dd>
Value to uniquely identify this option. Values zero and one are reserved.
This is the return value from <a href="#argv_next"><code>argv_next</code></a>
when this option is found.
</dd>
</dl>
<pre class="example">
ARGV args[] = {
{ 'a', NULL, 0, <a href="#ARGV_NOARG">ARGV_NOARG</a>, 'a' },
{ 'b', "bb", 2, <a href="#ARGV_NOARG">ARGV_NOARG</a>, 'b' },
<a href="#ARGV_LAST">ARGV_LAST</a>
};
</pre>
<h3><a name="ARGV_LAST"><code>ARGV_LAST</code></a></h3>
<p>A macro declaring a <code>struct</code> of type
<a href="#ARGV"><code>ARGV</code></a>
to be used as the last member of an options array.</p>
<h3><a name="ARGV_NOARG"><code>ARGV_NOARG</code></a></h3>
<p>An <a href="#ARGV"><code>optarg</code></a> value.
Declares the option to have no argument.</p>
<h3><a name="ARGV_ARG"><code>ARGV_ARG</code></a></h3>
<p>An <a href="#ARGV"><code>optarg</code></a> value.
Declares the option to have an optional argument.</p>
<h3><a name="ARGV_ARGA"><code>ARGV_ARGA</code></a></h3>
<p>An <a href="#ARGV"><code>optarg</code></a> value.
Declares the option to have an optional argument that may be attached.</p>
<h3><a name="ARGV_REQ"><code>ARGV_REQ</code></a></h3>
<p>An <a href="#ARGV"><code>optarg</code></a> value.
Declares the option to have a required argument.</p>
<h3><a name="ARGV_REQA"><code>ARGV_REQA</code></a></h3>
<p>An <a href="#ARGV"><code>optarg</code></a> value.
Declares the option to have a required argument that may be attached.</p>
<h3><a name="argv_init"><code>argv_init</code></a></h3>
<pre class="proto">
int argv_init(<a href="#ARGVPARSER">ARGVPARSER</a> * apr,
<a href="#ARGV">ARGV</a> * args,
int argc,
char ** argv);
</pre>
<p>Initializes a parser object.</p>
<p>Returns zero on success, negative on failure. (Don't worry. The
current implementation doesn't fail.)</p>
<h3><a name="argv_uninit"><code>argv_uninit</code></a></h3>
<pre class="proto">
void argv_uninit(<a href="#ARGVPARSER">ARGVPARSER</a> * apr);
</pre>
<p>Finalizes a parser object.</p>
<p>Does not return a value.</p>
<h3><a name="argv_set_args"><code>argv_set_args</code></a></h3>
<pre class="proto">
int argv_set_args(<a href="#ARGVPARSER">ARGVPARSER</a> * tk,
<a href="#ARGV">ARGV</a> * args);
</pre>
<p>Change the current option array. This is only good for
context-sensitive option parsing.</p>
<p>Returns zero on success, negative on failure. (Don't worry. The
current implementation doesn't fail.)</p>
<h3><a name="argv_set_mixed"><code>argv_set_mixed</code></a></h3>
<pre class="proto">
int argv_set_mixed(<a href="#ARGVPARSER">ARGVPARSER</a> * apr,
int mixed);
</pre>
<p>If <code>mixed</code> is non-zero, options and parameters can
be mixed. If zero, all options must preceed all parameters.</p>
<p>The command line will not be permuted to enforce this order. If
<code>mixed</code> is zero, any options after the first parameter
will be treated as parameters.</p>
<p>The default is to not allow mixed options and parameters.</p>
<p>Returns zero on success, negative on failure. (Don't worry. The
current implementation doesn't fail.)</p>
<h3><a name="argv_set_errorf"><code>argv_set_errorf</code></a></h3>
<pre class="proto">
int argv_set_errorf(<a href="#ARGVPARSER">ARGVPARSER</a> * apr,
int (*cb)(const char *));
</pre>
<p>Set the error message callback function for a parser object. The function
may be set to <code>NULL</code>.</p>
<p>The callback function should behave similarly to <code>yyerror</code>
from YACC.</p>
<p>The default callback function prints the message and a newline
to <code>stderr</code>.</p>
<p>Returns zero on success, negative on failure. (Don't worry. The
current implementation doesn't fail.)</p>
<h3><a name="argv_error_count"><code>argv_error_count</code></a></h3>
<pre class="proto">
int argv_error_count(<a href="#ARGVPARSER">ARGVPARSER</a> * apr);
</pre>
<p>Return the number of errors a parser object has encountered.</p>
<h3><a name="argv_set_progname"><code>argv_set_progname</code></a></h3>
<pre class="proto">
int argv_set_progname(<a href="#ARGVPARSER">ARGVPARSER</a> * apr,
const char * progname);
</pre>
<p>Set the name of the program used in error messages. By default,
<code>basename(argv[0])</code> will be used.</p>
<p>Returns zero on success, negative on failure. (Don't worry. The
current implementation doesn't fail.)</p>
<h3><a name="argv_next"><code>argv_next</code></a></h3>
<pre class="proto">
int argv_next(<a href="#ARGVPARSER">ARGVPARSER</a> * apr,
char ** arg,
size_t * arglen);
</pre>
<p>Return the next option and argument.</p>
<p>This function will not return when it encounters an error.
The function specified by
<a href="#argv_set_errorf"><code>argv_set_errorf</code></a>
will be called with an error message and parsing will continue.</p>
<p>The argument <code>arglen</code> may be <code>NULL</code>.</p>
<p>The return value is:</p>
<ul>
<li>0 for the end of input</li>
<li>1 for a parameter</li>
<li>the value of <a href="#ARGV"><code>optval</code></a> for an option</li>
</ul>
<p>If an argument is found, a pointer to it will be placed in
<code>*arg</code> and, if <code>arglen</code> is non-<code>NULL</code>,
the length of the argument will be placed in <code>*arglen</code>.</p>
<hr>
<h2><a name="example">Example Usage</a></h2>
<pre class="example">
int
main(int argc, char * argv[])
{
<a href="#ARGV">ARGV</a> args[] = {
{ 'D', NULL, 0, <a href="#ARGV_ARGA">ARGV_ARGA</a>, 'D' },
{ 0, "level", 5, <a href="#ARGV_ARG">ARGV_ARG</a>, 'L' },
{ 'v', "verbose", 0, <a href="#ARGV_NOARG">ARGV_NOARG</a>, 'v' },
<a href="#ARGV_LAST">ARGV_LAST</a>
};
<a href="#ARGVPARSER">ARGVPARSER</a> apr;
int o;
size_t n = 0;
char * s = NULL;
<a href="#argv_init">argv_init</a>(&apr, args, argc, argv);
<a href="#argv_set_mixed">argv_set_mixed</a>(&apr, 1);
while ((o = <a href="#argv_next">argv_next</a>(&apr, &s, &n))) {
switch (o) {
case 1:
if (!in_name) in_name = arg;
else if (!out_name) out_name = arg;
else {
fprintf(stderr, "too many files!\n");
exit(1);
}
break;
case 'D':
symbol_define(g_preproc, arg, arglen);
break;
case 'L':
if (arg) g_level = strtol(arg, NULL, 0);
break;
case 'v':
g_verbose++;
break;
default:
fprintf(stderr, "%c=%s,%d\n", o, s, (int)n);
break;
}
}
<a href="#argv_uninit">argv_uninit</a>(&apr);
return 0;
}
</pre>
<hr>
</body>
</html>