1 .TH lopsub-suite 5 "DATE()" GIT_VERSION()
3 lopsub-suite \- lopsub suite syntax
7 describes the options to a command line utility with zero or more
8 related subcommands. The
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:
22 [supercommand sup_cmd]
23 command directives for sup_cmd
28 command directives for sub1
29 [option opt_1_to_sub1]
30 option directives for opt_1
33 ... (further subcommands)
36 ... (optional extra section for man page)
38 ... (further extra sections)
43 line which declares the name of the suite. The
45 all subsequent lines up to the first
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.
57 lines indicate the beginning of a command of the suite. The part between this
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
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
81 line starts an option to the current command. It is followed by
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
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
100 Most directives of this section are only relevant for man page output (with
102 being the exception), they are ignored for C output.
105 The optional text for an unnumbered section heading at the beginning of the
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.
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.
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.
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
131 Centered in the header line. Defaults to "User commands".
136 The text enclosed between
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
146 Both texts will become part of the manual page, but are not not part
147 of the short or long help.
150 This text is shown at the bottom of each command before the value of the
151 aux_info directive. If no
153 is specified for a command, the prefix is omitted as well. If
155 is not given, the empty string is assumed.
158 This text is only used for header output. The argument for the generated macro
159 call is set to this value for all commands for which no
161 directive is given. If no
163 directive is given, the value 0 is used as the argument for the macro.
164 .SH COMMAND DIRECTIVES
167 A single line containing the purpose of the command. This text is printed in
168 the short and long help, and is also included in the man page.
173 Arbitrary plain text enclosed between
177 The text may be split over multiple lines and paragraphs. The
178 description of the supercommand (if any) becomes the description of
179 the manual page, which is shown after the command summary and before
180 the list of options. The descriptions of all commands are included
181 in the manual page and in the long help text but not in the short help.
183 Closing remarks for the command can be added in a similar way by enclosing
188 This text will be positioned after the option list.
191 Custom synopsis of the command. If this is not given, the synopsis text will be
192 auto-generated from the options and the value of the
197 Name of the command line arguments which are not related to any option,
198 for example file names. This text will be included in the automatically
199 generated synopsis text.
201 If this is not given, the command is assumed to take no arguments other than
202 the specified options and their arguments. For such commands the attempt to
203 parse an argv[] vector fails if it contains further non-option arguments.
206 This directive is special because its value is not included in the generated .c
207 file but in the header file. More precisely, the preprocessor macro
208 .B \%LSG_SUITENAME_AUX_INFOS
209 will be defined which expands to a series of macro calls to
210 .B \%LSG_SUITENAME_AUX_INFO(val_n),
211 one for each command of the suite, where
213 is the (unquoted) value of the
215 directive of the nth command. Commands for which no
217 directive was specified receive a value of zero. The
218 .B \%LSG_SUITENAME_AUX_INFO
219 macro is supposed to be defined by the application.
220 Hence it is up to the application to make the expansion of
221 .B \%LSG_SUITENAME_AUX_INFOS
224 The value, if specified, is also copied to the man page at the end of the
225 section for the command.
227 .SH OPTION DIRECTIVES
230 The optional single-letter equivalent for the option. If this is
231 specified, the option may be given either in the GNU-style long
232 option format with two leading dashes or in the short form with a
233 single dash. Otherwise only the long form will be accepted. As usual,
234 multiple short option flags may be combined.
237 A single line which summarizes the option. This text is included in
238 both the short and the long help and in the man page. Defaults to
242 A description for the type of the values for the option. The given text
243 is printed in the synopsis of the command, which is part of the short
244 and the long help and the man page. It defaults to the string "val".
246 This directive is ignored for flag options (options without an argument).
249 This directive determines whether the option takes an argument. The
251 .B no_arg, required_arg
254 which indicate, respectively, that the option takes no argument at all,
255 an argument which is mandatory, or an argument which may be omitted. The
258 Hence an option works as a flag if the
260 directive is not given.
262 Note that arguments to options which take an optional argument must
263 be given as --foo=bar rather than --foo bar because the latter form
267 For flag options this directive should be set to
269 or not set at all. For options which take an argument, the value of the directive
270 determines the type of the argument.
273 for options which take a string argument, and
278 for options which take a numeric argument.
281 Lopsub maintains for each option a bitmask which contains the value
282 of each possible flag for this option. Flags may be accumulated by
283 defining multiple flag directives in the suite. Note there is no
284 equal sign between the
286 directive and its value.
288 The following flags are defined.
292 This flag instructs the lopsub library to keep track of all given
293 arguments to an option, not just one as for ordinary options. This
294 is only relevant for options which take an (optional or required)
298 Instruct the parser to fail if this option is not given in the
299 argument vector. If an option may be given at the command line or
300 in the config file, this flag should be avoided because the command
301 line argv vector will not be parsed successfully if the option is
302 only given in the config file. The recommended way to deal with
303 this situation is to parse command line and config file separately,
304 then merge the two parse results and check in the application if the
305 option is given in the merged parse result.
307 There is another disadvantage of this flag: if the parser fails due
308 to a missing option that was declared required, it is not possible to
309 detect if other options were given. For example, if the suite defines
310 the --help option, and the application is executed with this option
311 only, the parser will still return a parse error.
314 This flag indicates that the current option is in fact not a real option.
319 are both ignored. The purpose of this flag is to add additional
320 information for the help output and the man page.
324 Create an enumerable option.
326 Enumerable options take one out of a fixed set of possible values
327 which are predefined in the suite. Such options are always of type
328 string. It is an error if a different argument type was specified or
329 if the option was defined to not take an argument.
331 The syntax for the array of values is
334 values = {ID_0 = "string_0", ..., ID_N = "string_N"}
337 For each option for which the
339 directive was specified, the lopsubgen command generates a C
340 enumeration which contains the given identifiers. This allows
341 referring to each possible value through a numeric constant.
344 This directive makes only sense for options which take an argument. For
345 such options it defines the value the option parser provides
346 automatically if the option is not given in the argument vector.
350 is specified in the suite, and the option is not given in the argument
351 vector either, the implied value depends on the argument type. For
352 numeric options, a value of zero is assumed. For options which take
353 a string argument, a NULL pointer is returned. For enum options,
354 the first possible value (index zero) is taken as the default.
357 The detailed, multi-line help text for the current option. Included
358 in the man page and the long help.
360 A minimal suite and the corresponding "application".
368 purpose = hello world
370 summary = add "world"
377 #include <stdio.h> /* printf(3) */
378 #include <stdlib.h> /* exit(3) */
380 #include "hello.lsg.h"
382 int main(int argc, char **argv)
384 struct lls_parse_result *lpr;
385 const struct lls_opt_result *result;
386 const struct lls_command *cmd = lls_cmd(0, hello_suite);
389 ret = lls_parse(argc, argv, cmd, &lpr, NULL);
391 fprintf(stderr, "%s\\n", lls_strerror(-ret));
395 result = lls_opt_result(LSG_HELLO_HELLO_OPT_WORLD, lpr);
396 if (lls_opt_given(result))
409 $ lopsubgen --gen-c --gen-h < hello.suite
421 $ cc hello.c hello.lsg.c -o hello -llopsub
432 option not recognized
434 invalid number of arguments
437 Generate and examine the manual page:
440 $ lopsubgen --gen-man < hello.suite
441 $ man -l ./hello.lsg.man