aboutsummaryrefslogtreecommitdiffstats
path: root/man0/libsimple-arg.h.0
blob: abc8619f89d3ee283c59ff65967c715f54639b5d (plain) (blame)
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
474
475
476
477
478
479
480
481
482
483
484
485
486
.TH LIBSIMPLE\-ARG.H 0 libsimple
.SH NAME
libsimple\-arg.h \- command line argument parsing header for libsimple

.SH SYNOPSIS
.nf
#include <libsimple\-arg.h>

extern char *\fIargv0\fP;

struct longopt {
	const char *long_flag;
	char short_flag;
	int with_arg;
};

#define ARGBEGIN                             ARGBEGIN2(1, 0)
#define SUBARGBEGIN                          ARGBEGIN2(0, 0)
#define ARGBEGIN2(\fIWITH_ARGV0\fP, \fIKEEP_DASHDASH\fP) /* implementation omitted */
#define ARGMAPLONG(\fILONGOPTS\fP)                 /* implementation omitted */
#define ARGALT(\fISYMBOL\fP)                       /* implementation omitted */
#define ARGEND                               /* implementation omitted */
#define ARGNUM                               /* implementation omitted */
#define FLAG()                               /* implementation omitted */
#define LFLAG()                              /* implementation omitted */
#define ARG()                                /* implementation omitted */
#define ARGHERE()                            /* implementation omitted */
#define NOFLAGS(...)                         /* implementation omitted */
#define TESTLONG(\fIFLG\fP, \fIWARG\fP)                  /* implementation omitted */
#define USAGE(\fISYNOPSIS\fP)                      /* implementation omitted */
#define NUSAGE(\fISTATUS\fP, \fISYNOPSIS\fP)             /* implementation omitted */
.fi

.SH DESCRIPTION
The
.I <libsimple\-arg.h>
header define a collection of macros for parsing the
command line arguments, thatis, the data in the
two first parameters of the
.IR main ()
function, according to the default behaviour specified
by POSIX (extensions of the specification is available).
It also includes the three headers the macros need:
.IR <stdio.h> ,
.IR <stdlib.h> ,
and
.IR <string.h> ,
additionally in defines the variable
.I argv0
which the macros set to the command line argument with
index zero which is the process was invoked with, normally,
but not always, this the filename of or the path to the
binary the process runs; one common exception to this is
for login shells: when a user logs in, the shell that is
started is started with the filename of the shell's binary
prefix with a dash
.RB ( \- )
as the zeroth command line argument. Assuming the second
argument in the
.IR main ()
function is named
.IR argv ,
the program should set
.I argv0
to
.I argv[0]
if the process may call a either of the
.BR libsimple_eprintf (3),
.BR libsimple_enprintf (3),
.BR libsimple_weprintf (3),
.BR libsimple_veprintf (3),
.BR libsimple_venprintf (3),
and
.BR libsimple_vweprintf (3)
functions before the either of the
.B ARGBEGIN
macro is used, and must do so if the function
.BR usage (),
defined by the
.B USAGE
and
.B NUSAGE
macros, is called before the
.B ARGBEGIN
macro is used.
.PP
Applications should normally parse or validate the command
line arguments and print usage information on usage error.
The macros
.BI USAGE( SYNOPSIS )
and
.BI NUSAGE( STATUS ,\  SYNOPSIS )
define a
.RI ( static )
function, name
.IR usage (),
that print the usage information and terminate the process,
the also declare the variable
.IR argv0 .
.IR usage ()
does take any arguments.
.IR usage ()
defined by
.B USAGE
terminate the process with exit value 1.
.IR usage ()
defined by
.B NUSAGE
terminate the process with exit value
.IR STATUS.
Both print the an error message to the standard error
in the following format:
.nf

	\fB\(dqusage: %s %s\en\(dq,\fP \fIargv0\fP\fB, \fP\fISYNOPSIS\fP

.fi
However, if
.I SYNOPSIS
is
.B NULL
or the empty string, the error message printed in the
following format.
.nf

	\fB\(dqusage: %s\en\(dq,\fP \fIargv0\fP
.fi
.PP
The macros
.B ARGBEGIN
and
.B ARGEND
are used to parse command line arguments, they use the variable
named
.I argc
(number of command line arguments)
and
.I argv
(command line arguments) and set
.I argv0
to
.IR argv[0] ,
.I argv[argc]
must be
.BR NULL ,
which is the case for the
.IR main ()
function. The
value that should be stored to
.I argv0
is not available at
.IR argv[0] ,
the macro
.B SUBARGBEGIN
should be used instead of
.BR ARGBEGIN .
These macros work similar to a switch statement in a loop:
.nf

	ARGBEGIN {
	case 'a':
		/* handle \-a */
		break;
	case 'b':
		/* handle \-b */
		break;
	case ARGNUM:
		/* handle \-0, \-1, \-2, ..., \-9 */
		break;
	default:
		/* print usage information for other flags */
		usage();
	} ARGEND;

.fi
After
.BR ARGEND ,
.I argc
and
.I argv
are set to only contain the remaining, unparsed, arguments.
.PP
The
.BR ARGBEGIN2 ()
macro can be used instead of the
.B ARGBEGIN
and
.B SUBARGBEGIN
macros for greater flexibility. If
.I WITH_ARGV0
is non-zero, it behaves like the
.B ARGBEGIN
macro, otherwise it behaves like the
.B SUBARGBEGIN
macro. If
.I KEEP_DASHDASH
is zero,
.B --
is removed from
.I argv
and
.I argc
decreased by one
before the parsing is stopped when
.B --
is encounted, this is normal behaviour,
the application code not need to handle
.B --
especially; on the other hand if
.I KEEP_DASHDASH
is non-zero
.B --
is not removed before parsing is stopped when
.B --
is encounted, and it becomes visible to the application
code, implement GNU behaviour by running the parsing
in a loop and stop when the application code sees
.BR -- .
.PP
If the application should support flags starting with
another symbol than a dash
.RB ( \- ),
the macro
.BR ARGALT ()
can be used. Its argument, 
.IR SYMBOL ,
should be
.B char
and it is used thusly:
.nf

	ARGBEGIN {
	case 'a':
		/* handle \-a */
		break;
	default:
		usage();
	} ARGALT('+') {
	case 'a':
		/* handle +a */
		break;
	default:
		usage();
	} ARGALT('/') {
	case 'a':
		/* handle /a */
		break;
	default:
		usage();
	} ARGEND;
.fi
.PP
In multicase statement (any case statement actually), the
.BR FLAG ()
macro can be used to identify which flag is being parsed.
For example, in
.I case 'a'
.BR FLAG ()
returns
.IR 'a' .
The
.BR LFLAG ()
macro returns the entire element in
.IR argv .
Note that one such element can contain multiple flags,
and the it can contain the flags argument, but the
argument can also be in the next element.
.PP
The macros
.BR ARG (),
.BR ARGNULL (),
and
.BR ARGHERE ()
are used the get the value provided with an option, one
of the must be used to let the parse know that the option
should have a value.
.BR ARG ()
returns the current option's value, or terminates the
by calling
.IR usage ()
if the option does not have a value.
.BR ARGNULL ()
returns the current option's value, or returns
.B NULL
if the option does not have a value.
.BR ARGHERE ()
Remaining part of the current argument in the command
line, including the character the specifies the flag.
It can be used together with
.B ARGNUM
to parse numerical options (a dash followed by a
multidigit number). It can also be used to parse
options where the value is optional be must appear
in the same argument, for example, if the current
argument is
.BR \-n1000 ,
.BR ARGHERE ()
will return
.B \(dqn1000\(dq
when the
.B \-n
option is parsed, but if the argument is just
.BR \-n ,
.BR ARGHERE ()
will return
.BR \(dqn\(dq ,
even if the next argument is
.BR 1000 .
.PP
The
.BR TESTLONG ()
macro can be used to implement support for long
options (for example
.B \-\-long
or
.BR \-long ).
.I FLG
shall be the full string of the flag, and
.I WARG
shall be non-zero if and only if the option should
have a value. If the value must be specified in the
same argument (that is for example
.B \-\-long=value
rather than
.BR \-\-long\ value ),
.I FLG
must end with an equals sign
.RB ( = )
in addition to a non-zero value on
.IR WARG .
Example:
.nf

	ARGBEGIN {
	case 'x':
	handle_dash_x:
		/* handle \-x */
		break;
	case '\-':
		if (TESTLONG(\(dq\-\-xdev\(dq, 0))
			goto handle_dash_x;
		else
			usage();
		break;
	default:
		usage();
	} ARGEND;

.fi
.I FLG
must not have side-effects,
.I WARG
should not have side-effects.
.PP
If your application have many long options with short
option aliases, the
.BR ARGMAPLONG ()
macro can be used.
.I LONGOPTS
shall be a
.B struct longopt *
with multiple
.BR "struct longopt" s,
the end of the last shall be marked with a
.B struct longopt
where
.I long_flag
is
.BR NULL .
The
.BR ARGMAPLONG ()
macro will test each entry, in order, using the
.BR TESTLONG ()
macro with
.I long_flag
as
.I FLG
and with
.I with_arg
as
.IR WARG .
If the test passes, the keyword
.B break
is used to break the
.B case
(so the
.BR ARGMAPLONG ()
macro shall be used directly in a
.B case
(or
.BR default )
for
.BR ARGBEGIN ,
.BR SUBARGBEGIN ,
or
.BR ARGBEGIN2 ,
and not inside a loop or inner
.BR switch ),
and in the next iteration of the argument parsing loop,
the flag will be the short flag consisting of the two
characters
.I long_flag[0]
and
.I short_flag
(in that order). Example:
.nf

	struct longopt map[] = {
		{\(dq--long-a\(dq, 'a', 0},
		{\(dq--long-b\(dq, 'b', 0},
		{NULL, 0, 0}
	}
	ARGBEGIN {
	case 'a':
		/* handle \-a and \-\-long\-a */
		break;
	case 'b':
		/* handle \-b and \-\-long\-b */
		break;
	case '\-':
		ARGMAPLONG(map);
		usage();
	default:
		usage();
	} ARGEND;
.fi
.PP
NB! Long options with optional arguments should                                                                                      
have to map entries, one where
.I long_flag
ends with
.RB ' = '
and
.I with_arg
is non-zero, and one where
.I long_flag
does not end with
.RB ' = '
and
.I with_arg
is zero. These
.I cannot
have the same
.IR short_flag .
.PP
If your application, does not recognise any options,
but should still have like normal programs and support
.BR \-\- ,
the macro
.BR NOFLAGS ()
can be used instead of the
.B ARGBEGIN
and
.B ARGEND
macros. It behaves just like
.nf

	ARGBEGIN {
	default:
		usage();
	} ARGEND;

.fi
but is optimised. Additionally, if the last argument
is non-zero, the
.IR usage ()
function is called. All arguments evaluated exactly
once, or if flags are used, never. So if your application
should not have any options or operands,
.I NOFLAGS(argc)
can be used.

.SH APPLICATION USAGE
None.

.SH RATIONALE
None.

.SH FUTURE DIRECTIONS
None.

.SH NOTES
None.

.SH SEE ALSO
.BR libsimple.h (0)