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
|
GETARG(3) BSD Library Functions Manual GETARG(3)
NNAAMMEE
ggeettaarrgg, aarrgg__pprriinnttuussaaggee -- collect command line options
SSYYNNOOPPSSIISS
##iinncclluuddee <<ggeettaarrgg..hh>>
_i_n_t
ggeettaarrgg(_s_t_r_u_c_t _g_e_t_a_r_g_s _*_a_r_g_s, _s_i_z_e___t _n_u_m___a_r_g_s, _i_n_t _a_r_g_c, _c_h_a_r _*_*_a_r_g_v,
_i_n_t _*_o_p_t_i_n_d);
_v_o_i_d
aarrgg__pprriinnttuussaaggee(_s_t_r_u_c_t _g_e_t_a_r_g_s _*_a_r_g_s, _s_i_z_e___t _n_u_m___a_r_g_s,
_c_o_n_s_t _c_h_a_r _*_p_r_o_g_n_a_m_e, _c_o_n_s_t _c_h_a_r _*_e_x_t_r_a___s_t_r_i_n_g);
DDEESSCCRRIIPPTTIIOONN
ggeettaarrgg() collects any command line options given to a program in an eas-
ily used way. aarrgg__pprriinnttuussaaggee() pretty-prints the available options, with
a short help text.
_a_r_g_s is the option specification to use, and it's an array of _s_t_r_u_c_t
_g_e_t_a_r_g_s elements. _n_u_m___a_r_g_s is the size of _a_r_g_s (in elements). _a_r_g_c and
_a_r_g_v are the argument count and argument vector to extract option from.
_o_p_t_i_n_d is a pointer to an integer where the index to the last processed
argument is stored, it must be initialised to the first index (minus one)
to process (normally 0) before the first call.
_a_r_g___p_r_i_n_t_u_s_a_g_e take the same _a_r_g_s and _n_u_m___a_r_g_s as getarg; _p_r_o_g_n_a_m_e is the
name of the program (to be used in the help text), and _e_x_t_r_a___s_t_r_i_n_g is a
string to print after the actual options to indicate more arguments. The
usefulness of this function is realised only be people who has used pro-
grams that has help strings that doesn't match what the code does.
The _g_e_t_a_r_g_s struct has the following elements.
struct getargs{
const char *long_name;
char short_name;
enum { arg_integer,
arg_string,
arg_flag,
arg_negative_flag,
arg_strings,
arg_double,
arg_collect
} type;
void *value;
const char *help;
const char *arg_help;
};
_l_o_n_g___n_a_m_e is the long name of the option, it can be NULL, if you don't
want a long name. _s_h_o_r_t___n_a_m_e is the characted to use as short option, it
can be zero. If the option has a value the _v_a_l_u_e field gets filled in
with that value interpreted as specified by the _t_y_p_e field. _h_e_l_p is a
longer help string for the option as a whole, if it's NULL the help text
for the option is omitted (but it's still displayed in the synopsis).
_a_r_g___h_e_l_p is a description of the argument, if NULL a default value will
be used, depending on the type of the option:
arg_integer the argument is a signed integer, and _v_a_l_u_e should
point to an _i_n_t.
_a_r_g___s_t_r_i_n_g the argument is a string, and _v_a_l_u_e should point to a
_c_h_a_r_*.
_a_r_g___f_l_a_g the argument is a flag, and _v_a_l_u_e should point to a
_i_n_t. It gets filled in with either zero or one,
depending on how the option is given, the normal case
being one. Note that if the option isn't given, the
value isn't altered, so it should be initialised to
some useful default.
_a_r_g___n_e_g_a_t_i_v_e___f_l_a_g this is the same as _a_r_g___f_l_a_g but it reverses the mean-
ing of the flag (a given short option clears the
flag), and the synopsis of a long option is negated.
_a_r_g___s_t_r_i_n_g_s the argument can be given multiple times, and the val-
ues are collected in an array; _v_a_l_u_e should be a
pointer to a _s_t_r_u_c_t _g_e_t_a_r_g___s_t_r_i_n_g_s structure, which
holds a length and a string pointer.
_a_r_g___d_o_u_b_l_e argument is a double precision floating point value,
and _v_a_l_u_e should point to a _d_o_u_b_l_e.
_a_r_g___c_o_l_l_e_c_t allows more fine-grained control of the option parsing
process. _v_a_l_u_e should be a pointer to a
_g_e_t_a_r_g___c_o_l_l_e_c_t___i_n_f_o structure:
typedef int (*getarg_collect_func)(int short_opt,
int argc,
char **argv,
int *optind,
int *optarg,
void *data);
typedef struct getarg_collect_info {
getarg_collect_func func;
void *data;
} getarg_collect_info;
With the _f_u_n_c member set to a function to call, and
_d_a_t_a to some application specific data. The parameters
to the collect function are:
_s_h_o_r_t___f_l_a_g non-zero if this call is via a short option
flag, zero otherwise
_a_r_g_c, _a_r_g_v the whole argument list
_o_p_t_i_n_d pointer to the index in argv where the flag is
_o_p_t_a_r_g pointer to the index in argv[*optind] where the
flag name starts
_d_a_t_a application specific data
You can modify _*_o_p_t_i_n_d, and _*_o_p_t_a_r_g, but to do this
correct you (more or less) have to know about the
inner workings of getarg.
You can skip parts of arguments by increasing _*_o_p_t_a_r_g
(you could implement the --zz_3 set of flags from ggzziipp
with this), or whole argument strings by increasing
_*_o_p_t_i_n_d (let's say you want a flag --cc _x _y _z to specify
a coordinate); if you also have to set _*_o_p_t_a_r_g to a
sane value.
The collect function should return one of
ARG_ERR_NO_MATCH, ARG_ERR_BAD_ARG, ARG_ERR_NO_ARG,
ENOMEM on error, zero otherwise.
For your convenience there is a function,
ggeettaarrgg__ooppttaarrgg(), that returns the traditional argument
string, and you pass it all arguments, sans data, that
where given to the collection function.
Don't use this more this unless you absolutely have
to.
Option parsing is similar to what getopt uses. Short options without
arguments can be compressed (--xxyyzz is the same as --xx --yy --zz), and short
options with arguments take these as either the rest of the argv-string
or as the next option (--oo_f_o_o, or --oo _f_o_o).
Long option names are prefixed with -- (double dash), and the value with
a = (equal), ----ffoooo==_b_a_r. Long option flags can either be specified as
they are (----hheellpp), or with an (boolean parsable) option (----hheellpp==_y_e_s,
----hheellpp==_t_r_u_e, or similar), or they can also be negated (----nnoo--hheellpp is the
same as ----hheellpp==no), and if you're really confused you can do it multiple
times (----nnoo--nnoo--hheellpp==_f_a_l_s_e, or even ----nnoo--nnoo--hheellpp==_m_a_y_b_e).
EEXXAAMMPPLLEE
#include <stdio.h>
#include <string.h>
#include <getarg.h>
char *source = "Ouagadougou";
char *destination;
int weight;
int include_catalog = 1;
int help_flag;
struct getargs args[] = {
{ "source", 's', arg_string, &source,
"source of shippment", "city" },
{ "destination", 'd', arg_string, &destination,
"destination of shippment", "city" },
{ "weight", 'w', arg_integer, &weight,
"weight of shippment", "tons" },
{ "catalog", 'c', arg_negative_flag, &include_catalog,
"include product catalog" },
{ "help", 'h', arg_flag, &help_flag }
};
int num_args = sizeof(args) / sizeof(args[0]); /* number of elements in args */
const char *progname = "ship++";
int
main(int argc, char **argv)
{
int optind = 0;
if (getarg(args, num_args, argc, argv, &optind)) {
arg_printusage(args, num_args, progname, "stuff...");
exit (1);
}
if (help_flag) {
arg_printusage(args, num_args, progname, "stuff...");
exit (0);
}
if (destination == NULL) {
fprintf(stderr, "%s: must specify destination\n", progname);
exit(1);
}
if (strcmp(source, destination) == 0) {
fprintf(stderr, "%s: destination must be different from source\n");
exit(1);
}
/* include more stuff here ... */
exit(2);
}
The output help output from this program looks like this:
$ ship++ --help
Usage: ship++ [--source=city] [-s city] [--destination=city] [-d city]
[--weight=tons] [-w tons] [--no-catalog] [-c] [--help] [-h] stuff...
-s city, --source=city source of shippment
-d city, --destination=city destination of shippment
-w tons, --weight=tons weight of shippment
-c, --no-catalog include product catalog
BBUUGGSS
It should be more flexible, so it would be possible to use other more
complicated option syntaxes, such as what ps(1), and tar(1), uses, or the
AFS model where you can skip the flag names as long as the options come
in the correct order.
Options with multiple arguments should be handled better.
Should be integreated with SL.
It's very confusing that the struct you pass in is called getargS.
SSEEEE AALLSSOO
getopt(3)
ROKEN September 24, 1999 ROKEN
|
