Merge branch 't/build-improvements'
[lopsub.git] / lopsub-suite.5.m4
1 .TH lopsub-suite 5 "DATE()" GIT_VERSION()
3 lopsub-suite \- lopsub suite syntax
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.
15 This document explains the format of a lopsub suite. The overall
16 structure is as follows:
18 .EX
19 [suite mysuite]
20 suite directives
22 [supercommand sup_cmd]
23 command directives for sup_cmd
24 [option opt1]
25 ... (further options)
27 [subcommand sub1]
28 command directives for sub1
29 [option opt_1_to_sub1]
30 option directives for opt_1
31 ... (further options)
33 ... (further subcommands)
35 [section see also]
36 ... (optional extra section for man page)
38 ... (further extra sections)
39 .EE
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.
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.
65 Supercommands and subcommands share the same set of possible command
66 directives. They differ mainly in the way the documentation is
67 formatted. 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.
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.
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.
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.
97 Empty lines and lines starting with a hash character (#) are
98 ignored.
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.
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.
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.
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
211 will be defined which expands to a series of macro calls to
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
221 macro is supposed to be defined by the application.
222 Hence it is up to the application to make the expansion of
224 a valid C construct.
226 The value, if specified, is also copied to the man page at the end of the
227 section for the command.
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".
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.
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.
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.
309 There is another disadvantage of this flag: if the parser fails due
310 to a missing option that was declared required, it is not possible to
311 detect if other options were given. For example, if the suite defines
312 the --help option, and the application is executed with this option
313 only, the parser will still return a parse error.
314 .B
315 .IP ignored
316 This flag indicates that the current option is in fact not a real option.
317 In particular,
318 .B name
319 and
320 .B short_opt
321 are both ignored. The purpose of this flag is to add additional
322 information for the help output and the man page.
323 .RE
324 .TP
325 .B values
326 Create an enumerable option.
328 Enumerable options take one out of a fixed set of possible values
329 which are predefined in the suite. Such options are always of type
330 string. It is an error if a different argument type was specified or
331 if the option was defined to not take an argument.
333 The syntax for the array of values is
335 .EX
336 values = {ID_0 = "string_0", ..., ID_N = "string_N"}
337 .EE
339 For each option for which the
340 .B values
341 directive was specified, the lopsubgen command generates a C
342 enumeration which contains the given identifiers. This allows
343 referring to each possible value through a numeric constant.
344 .TP
345 .B default_val
346 This directive makes only sense for options which take an argument. For
347 such options it defines the value the option parser provides
348 automatically if the option is not given in the argument vector.
350 If no
351 .B default_val
352 is specified in the suite, and the option is not given in the argument
353 vector either, the implied value depends on the argument type. For
354 numeric options, a value of zero is assumed. For options which take
355 a string argument, a NULL pointer is returned. For enum options,
356 the first possible value (index zero) is taken as the default.
357 .TP
358 .B help
359 The detailed, multi-line help text for the current option. Included
360 in the man page and the long help.
362 A minimal suite and the corresponding "application".
364 The suite file
365 .IR hello.suite :
367 .EX
368 [suite hello]
369 [supercommand hello]
370 purpose = hello world
371 [option world]
372 summary = add "world"
373 .EE
375 The "application"
376 .IR hello.c :
378 .EX
379 #include <stdio.h> /* printf(3) */
380 #include <stdlib.h> /* exit(3) */
381 #include <lopsub.h>
382 #include "hello.lsg.h"
384 int main(int argc, char **argv)
385 {
386 struct lls_parse_result *lpr;
387 const struct lls_opt_result *result;
388 const struct lls_command *cmd = lls_cmd(0, hello_suite);
389 int ret;
391 ret = lls_parse(argc, argv, cmd, &lpr, NULL);
392 if (ret < 0) {
393 fprintf(stderr, "%s\\n", lls_strerror(-ret));
394 exit(1);
395 }
396 printf("hello");
397 result = lls_opt_result(LSG_HELLO_HELLO_OPT_WORLD, lpr);
398 if (lls_opt_given(result))
399 printf(" world");
400 printf("\\n");
401 exit(0);
402 }
403 .EE
405 Generate
406 .I hello.lsg.c
407 and
408 .IR hello.lsg.h :
410 .EX
411 $ lopsubgen --gen-c --gen-h < hello.suite
412 .EE
414 Compile
415 .I hello.c
416 and
417 .I hello.lsg.c
418 to produce the
419 .I hello
420 executable:
422 .EX
423 $ cc hello.c hello.lsg.c -o hello -llopsub
424 .EE
426 Run it:
428 .EX
429 $ ./hello
430 hello
431 $ ./hello --world
432 hello world
433 $ ./hello -w
434 option not recognized
435 $ ./hello 42
436 invalid number of arguments
437 .EE
439 Generate and examine the manual page:
441 .EX
442 $ lopsubgen --gen-man < hello.suite
443 $ man -l ./
444 .EE
447 .BR lopsubgen (1),
448 .BR lopsub (7),
449 .BR lopsubex (1),
450 .BR gengetopt (1),
451 .BR getopt (1),
452 .BR getopt (3)