The long option parser for subcommands (lopsub).
[lopsub.git] / lopsub-suite.5.m4
1 .TH lopsub-suite 5 "DATE()" GIT_VERSION()
2 .SH NAME
3 lopsub-suite \- lopsub suite syntax
4 .SH DESCRIPTION
5 A
6 .B lopsub suite
7 describes the options to a command line utility with zero or more
8 related subcommands. The
9 .BR lopsubgen (1)
10 utility translates a lopsub suite into either C source code or a manual
11 page. The generated C code can be compiled and linked against the
12 lopsub library to produce command line parsers for the main command
13 and all subcommands defined in the suite.
14
15 This document explains the format of a lopsub suite. The overall
16 structure is as follows:
17
18 .EX
19 [suite mysuite]
20 suite directives
21
22 [supercommand sup_cmd]
23 command directives for sup_cmd
24 [option opt1]
25 ... (further options)
26
27 [subcommand sub1]
28 command directives for sub1
29 [option opt_1_to_sub1]
30 option directives for opt_1
31 ... (further options)
32
33 ... (further subcommands)
34
35 [section see also]
36 ... (optional extra section for man page)
37
38 ... (further extra sections)
39 .EE
40
41 A suite begins with a
42 .B [suite]
43 line which declares the name of the suite. The
44 .B suite directives,
45 all subsequent lines up to the first
46 .B [supercommand]
47 or
48 .B [subcommand]
49 line, state further properties of the suite which are unrelated to
50 any particular command, for example the version number. All available
51 suite directives are summarized below.
52
53 The
54 .B [supercommand]
55 and
56 .B [subcommand]
57 lines indicate the beginning of a command of the suite. The part between this
58 line and the first
59 .B [option]
60 line contains the
61 .B command directives,
62 for example the purpose and the description of the named command.
63 See the section on command directives below.
64
65 Supercommands and subcommands share the same set of possible command
66 directives. They differ mainly in the way the documentation is
67 formated. There can only be one supercommand but arbitrary many
68 subcommands. For example, the supercommand could be the name of
69 the application, and the subcommands could be "load", "save" "info"
70 and "quit". The subcommand would be passed as the first non-option
71 argument to the supercommand, followed by options specific to that
72 subcommand.
73
74 Of course it is possible to define no subcommands at all. Conversely,
75 one can define only subcommands but no supercommand. This makes
76 sense if the commands are run by some other means, for example in an
77 interactive session from a command prompt.
78
79 Within the command section, an
80 .B [option]
81 line starts an option to the current command. It is followed by
82 .B option directives,
83 which specify, for example, whether or not the option takes
84 an argument. All supported option directives are listed in the
85 corresponding section below.
86
87 Further material for man output can be included between the
88 .B [section]
89 and
90 .B [/section]
91 markers.
92 This text will not be included in the generated .c and .h files and
93 is thus also not part of the short and long help available at run
94 time. The text is not interpreted except that leading whitespace is
95 stripped from each line. Arbitrary roff source can be included here.
96
97 Empty lines and lines starting with a hash character (#) are
98 ignored.
99 .SH SUITE DIRECTIVES
100 Most directives of this section are only relevant for man page output (with
101 .B aux_info_default
102 being the exception), they are ignored for C output.
103 .TP
104 .B caption
105 The optional text for an unnumbered section heading at the beginning of the
106 manual page.
107 .TP
108 .B title
109 Sets the title of the man page. Defaults to the name of the
110 supercommand. If this is not given and the suite has no supercommand,
111 the .TH macro to set the title of the man page is omitted.
112 .TP
113 .B mansect
114 Sets the man page section. Defaults to 1 (user commands). Both title
115 and section are positioned at the left and right in the header line.
116 .TP
117 .B date
118 This text is positioned in the middle of the footer line of the man page. It is
119 common to set this to the date of the last nontrivial change that was made to
120 the man page. Defaults to the current date.
121 .TP
122 .B version-string
123 Positioned at the left in the footer line. Defaults to the empty string. The
124 value of this directive is ignored if a version string is explicitly requested
125 by passing
126 .B --version-string
127 to
128 .BR losubgen .
129 .TP
130 .B manual_title
131 Centered in the header line. Defaults to "User commands".
132 .TP
133 .B introduction
134 .TQ
135 .B conclusion
136 The text enclosed between
137 .B [introduction]
138 and
139 .B [/introduction]
140 is shown between the supercommand (if any) and the subcommand list.
141 Concluding remarks after the subcommand list may be added in the same
142 way with
143 .B [conclusion]
144 and
145 .BR [/conclusion] .
146 Both texts will become part of the manual page, but are not not part
147 of the short or long help. Like for the
148 .B section
149 directive, arbitrary roff source may be included here.
150 .TP
151 .B aux_info_prefix
152 This text is shown at the bottom of each command before the value of the
153 aux_info directive. If no
154 .B aux_info
155 is specified for a command, the prefix is omitted as well. If
156 .B aux_info_prefix
157 is not given, the empty string is assumed.
158 .TP
159 .B aux_info_default
160 This text is only used for header output. The argument for the generated macro
161 call is set to this value for all commands for which no
162 .B aux_info
163 directive is given. If no
164 .B aux_info_default
165 directive is given, the value 0 is used as the argument for the macro.
166 .SH COMMAND DIRECTIVES
167 .TP
168 .B purpose
169 A single line containing the purpose of the command. This text is printed in
170 the short and long help, and is also included in the man page.
171 .TP
172 .B description
173 .TQ
174 .B closing
175 Arbitrary plain text enclosed between
176 .B [description]
177 and
178 .BR [/description] .
179 The text may be split over multiple lines and paragraphs. The
180 description of the supercommand (if any) becomes the description of
181 the manual page, which is shown after the command summary and before
182 the list of options. The descriptions of all commands are included
183 in the manual page and in the long help text but not in the short help.
184
185 Closing remarks for the command can be added in a similar way by enclosing
186 plain text between
187 .B [closing]
188 and
189 .BR [/closing] .
190 This text will be positioned after the option list.
191 .TP
192 .B synopsis
193 Custom synopsis of the command. If this is not given, the synopsis text will be
194 auto-generated from the options and the value of the
195 .B non-opts-name
196 directive.
197 .TP
198 .B non-opts-name
199 Name of the command line arguments which are not related to any option,
200 for example file names. This text will be included in the automatically
201 generated synopsis text.
202
203 If this is not given, the command is assumed to take no arguments other than
204 the specified options and their arguments. For such commands the attempt to
205 parse an argv[] vector fails if it contains further non-option arguments.
206 .TP
207 .B aux_info
208 This directive is special because its value is not included in the generated .c
209 file but in the header file. More precisely, the preprocessor macro
210 .B \%LSG_SUITENAME_AUX_INFOS
211 will be defined which expands to a series of macro calls to
212 .B \%LSG_SUITENAME_AUX_INFO(val_n),
213 one for each command of the suite, where
214 .B val_n
215 is the (unquoted) value of the
216 .B aux_info
217 directive of the nth command. Commands for which no
218 .B aux_info
219 directive was specified receive a value of zero. The
220 .B \%LSG_SUITENAME_AUX_INFO
221 macro is supposed to be defined by the application.
222 Hence it is up to the application to make the expansion of
223 .B \%LSG_SUITENAME_AUX_INFOS
224 a valid C construct.
225
226 The value, if specified, is also copied to the man page at the end of the
227 section for the command.
228
229 .SH OPTION DIRECTIVES
230 .TP
231 .B short_opt
232 The optional single-letter equivalent for the option. If this is
233 specified, the option may be given either in the GNU-style long
234 option format with two leading dashes or in the short form with a
235 single dash. Otherwise only the long form will be accepted. As usual,
236 multiple short option flags may be combined.
237 .TP
238 .B summary
239 A single line which summarizes the option. This text is included in
240 both the short and the long help and in the man page. Defaults to
241 the empty string.
242 .TP
243 .B typestr
244 A description for the type of the values for the option. The given text
245 is printed in the synopsis of the command, which is part of the short
246 and the long help and the man page. It defaults to the string "val".
247
248 This directive is ignored for flag options (options without an argument).
249 .TP
250 .B arg_info
251 This directive determines whether the option takes an argument. The
252 possible values are
253 .B no_arg, required_arg
254 and
255 .B optional_arg
256 which indicate, respectively, that the option takes no argument at all,
257 an argument which is mandatory, or an argument which may be omitted. The
258 default value is
259 .B no_arg.
260 Hence an option works as a flag if the
261 .B arg_info
262 directive is not given.
263
264 Note that arguments to options which take an optional argument must
265 be given as --foo=bar rather than --foo bar because the latter form
266 would be ambiguous.
267 .TP
268 .B arg_type
269 For flag options this directive should be set to
270 .B none,
271 or not set at all. For options which take an argument, the value of the directive
272 determines the type of the argument.
273 Possible values are
274 .B string
275 for options which take a string argument, and
276 .B int32,
277 .B uint32.
278 .B int64,
279 .B uint64,
280 for options which take a numeric argument.
281 .TP
282 .B flag
283 Lopsub maintains for each option a bitmask which contains the value
284 of each possible flag for this option. Flags may be accumulated by
285 defining multiple flag directives in the suite. Note there is no
286 equal sign between the
287 .B flag
288 directive and its value.
289
290 The following flags are defined.
291 .RS
292 .B
293 .IP multiple
294 This flag instructs the lopsub library to keep track of all given
295 arguments to an option, not just one as for ordinary options. This
296 is only relevant for options which take an (optional or required)
297 argument.
298 .B
299 .IP required
300 Instruct the parser to fail if this option is not given in the
301 argument vector. If an option may be given at the command line or
302 in the config file, this flag should be avoided because the command
303 line argv vector will not be parsed successfully if the option is
304 only given in the config file. The recommended way to deal with
305 this situation is to parse command line and config file separately,
306 then merge the two parse results and check in the application if the
307 option is given in the merged parse result.
308 .B
309 .IP ignored
310 This flag indicates that the current option is in fact not a real option.
311 In particular,
312 .B name
313 and
314 .B short_opt
315 are both ignored. The purpose of this flag is to add additional
316 information for the help output and the man page.
317 .RE
318 .TP
319 .B values
320 Create an enumerable option.
321
322 Enumerable options take one out of a fixed set of possible values
323 which are predefined in the suite. Such options are always of type
324 string. It is an error if a different argument type was specified or
325 if the option was defined to not take an argument.
326
327 The syntax for the array of values is
328
329 .EX
330 values = {ID_0 = "string_0", ..., ID_N = "string_N"}
331 .EE
332
333 For each option for which the
334 .B values
335 directive was specified, the lopsubgen command generates a C
336 enumeration which contains the given identifiers. This allows to
337 refer to each possible value through a numeric constant.
338 .TP
339 .B default_val
340 This directive makes only sense for options which take an argument. For
341 such options it defines the value the option parser provides
342 automatically if the option is not given in the argument vector.
343
344 If no
345 .B default_val
346 is specified in the suite, and the option is not given in the argument
347 vector either, the implied value depends on the argument type. For
348 numeric options, a value of zero is assumed. For options which take
349 a string argument, a NULL pointer is returned. For enum options,
350 the first possible value (index zero) is taken as the default.
351 .TP
352 .B help
353 The detailed, multi-line help text for the current option. Included
354 in the man page and the long help.
355 .SH EXAMPLE
356 A minimal suite and the corresponding "application".
357
358 The suite file
359 .IR hello.suite :
360
361 .EX
362 [suite hello]
363 [supercommand hello]
364 purpose = hello world
365 [option world]
366 summary = add "world"
367 .EE
368
369 The "application"
370 .IR hello.c :
371
372 .EX
373 #include <stdio.h> /* printf(3) */
374 #include <stdlib.h> /* exit(3) */
375 #include <lopsub.h>
376 #include "hello.lsg.h"
377
378 int main(int argc, char **argv)
379 {
380 struct lls_parse_result *lpr;
381 const struct lls_opt_result *result;
382 const struct lls_command *cmd = lls_cmd(0, hello_suite);
383 int ret;
384
385 ret = lls_parse(argc, argv, cmd, &lpr, NULL);
386 if (ret < 0) {
387 fprintf(stderr, "%s\\n", lls_strerror(-ret));
388 exit(1);
389 }
390 printf("hello");
391 result = lls_opt_result(LSG_HELLO_HELLO_OPT_WORLD, lpr);
392 if (lls_opt_given(result))
393 printf(" world");
394 printf("\\n");
395 exit(0);
396 }
397 .EE
398
399 Generate
400 .I hello.lsg.c
401 and
402 .IR hello.lsg.h :
403
404 .EX
405 $ lopsubgen --gen-c --gen-h < hello.suite
406 .EE
407
408 Compile
409 .I hello.c
410 and
411 .I hello.lsg.c
412 to produce the
413 .I hello
414 executable:
415
416 .EX
417 $ cc hello.c hello.lsg.c -o hello -llopsub
418 .EE
419
420 Run it:
421
422 .EX
423 $ ./hello
424 hello
425 $ ./hello --world
426 hello world
427 $ ./hello -w
428 option not recognized
429 $ ./hello 42
430 invalid number of arguments
431 .EE
432
433 Generate and examine the manual page:
434
435 .EX
436 $ lopsubgen --gen-man < hello.suite
437 $ man -l ./hello.lsg.man
438 .EE
439
440 .SH SEE ALSO
441 .BR lopsubgen (1),
442 .BR lopsub (7),
443 .BR lopsubex (1),
444 .BR gengetopt (1),
445 .BR getopt (1),
446 .BR getopt (3)