1 # Written 2016 by Andre Noll <maan@tuebingen.mpg.de>
3 # Public domain, no copyright claims.
6 aux_info_prefix = further information:
7 aux_info_default = (unknown), S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH
8 caption = lopsubex subcommands
9 # This will be printed before the list of subcommands
10 [supercommand lopsubex]
11 purpose = illustrate lopsub features
12 non-opts-name = [<subcommand>] [options]
14 This program illustrates the various features of the lopsub option
15 parser. Consult the lopsubex.suite file and the source in lopsubex.c
16 to see how the subcommands described in this document are implemented.
19 When executed with no argument, the program lists the available
20 subcommands. Otherwise the first argument must be a subcommand from
25 Each subcommand of lopsubex illustrates a different feature of the
30 purpose = options with no arguments
32 Flags are the simplest type of options as they take no argument.
33 To create a flag option, simply omit arg_type, arg_info, and typestr
37 summary = simplest option on the planet
40 summary = Flag option with a short option equivalent.
42 Lopsub counts the number of times an option was given. This can be
43 used, for example, to set the verbosity level of the application.
45 Decimal digits are allowed as short option equivalent for a long
49 [subcommand int-param]
50 purpose = options which take an integer argument
52 Options may be specified to take an integer argument. This subcommand
53 provides a simple example.
57 summary = example option which takes a required integer argument
58 arg_info = required_arg
62 Integers may be specified as a C99 decimal, hexadecimal or octal
65 The type of the argument for this option is a signed 32 bit integer,
66 so negative values are allowed.
70 purpose = options that can be specified more than once
72 The multiple flag indicates that an option may be given more than
73 once. This instructs the parser to make all given arguments available
74 to the application via the parse_result structure which is returned
79 summary = may be given multiple times, takes no argument
81 For flag options (options which do not take an argument), the number
82 of times the flag was given is stored in the parse result, regardless
83 of whether the multiple flag was set in the suite file.
85 To specify the option twice, one may write either -v -v or -vv.
89 summary = multiple string values may be given
91 The subcommand will print all given values.
93 arg_info = required_arg
99 summary = only one value is stored in the parse result.
101 Since this option is not declared as multiple, only one value is
102 stored in the parse result. If the option was given more than once,
103 the last given value wins.
105 arg_info = required_arg
108 default_val = /dev/null
110 Run this command and specify each option more than once to see
114 [subcommand custom-synopsis]
115 purpose = overwrite the default usage string
118 If a synopsis text is specified, this text is shown
119 as the usage string in the help output. Otherwise,
120 lopsub creates a suitable string on its own.
122 In this example, the synopsis text is set to "[file...]".
126 purpose = enumerable options
128 In this command, --color is an enum option, which takes the name of a
129 color as its argument. Only a pre-defined set of colors are accepted,
130 as defined in the suite file.
132 The last value (black) shows how to specify values with embedded
136 summary = name of a color
138 arg_info = required_arg
143 COLOR_GREEN = "green",
145 COLOR_YELLOW = "yellow",
146 COLOR_BLACK = "black (that's not really a \"color\")"
150 [subcommand serialize]
151 purpose = write a parse result into a buffer
153 The lopsub library provides a function to serialize the result
154 of a successful call to lls_parse(). This subcommand illustrates
155 this feature. First it parses the given arguments to produce a
156 parse result. Next it serializes the parse result into a buffer
157 and de-serializes this buffer into a second parse result. A text
158 which refers to the parsed values is printed twice, first with the
159 original parse result, then with the de-serialized version. The two
160 texts should be identical.
164 arg_info = required_arg
171 arg_info = required_arg
180 arg_info = optional_arg
183 [subcommand non-ascii]
184 purpose = use of non-ASCII characters (e.g., umlauts like 'ä')
186 Non-ASCII characters are not allowed for command and option names. They
187 may appear, however, in the purpose text of a command (see above),
188 in the type string and the description of an option (see below),
189 and also in a help text like this: öäüß. Of course, non-ASCII
190 characters are also allowed in the argument to a string option.
192 The help text generated by the lopsub library functions should just
193 work on any system where UTF-8 is the default character encoding.
195 For generating man pages, however, UTF-8 will not do, because
196 groff interprets input character codes between 127 and 255 as the
197 corresponding characters in the latin1 (ISO-8859-1) code set. Hence,
198 it is necessary to format the generated with the command preconv -e
199 UTF-8. The man(1) command of the man-db package (default on most
200 Linux distributions) does this automatically, so man pages should
201 render correctly on those systems. On other systems it might help to
202 convert the suite file to ISO-8859-1 before feeding it to lopsubgen:
204 iconv -t ISO_8859-1 app.suite | ./lopsubgen --gen-man
208 summary = name of a big city (Großstadt)
210 The command prints a more or less interesting sentence about the
211 given city. At the moment, only Göttingen is supported.
214 arg_info = required_arg
217 default_val = Göttingen
220 purpose = embedded quotes (") and backslashes (\).
222 In the C language a double quote (") denotes the beginning or the end
223 of a string literal. Embedded double quotes must be prefixed with a
224 backslash (\), and embedded backslashes need to be doubled.
226 Lopsubgen handles these issues internally. Hence all help texts,
227 purpose and description strings and default values may contain single
228 (') or double quotes ("), balanced or unbalanced.
230 Man output has similar issues. For example, if the first word of a
231 line starts with a dot or a single quote, lopsubgen prevents roff
232 from interpreting the word. Examples:
234 .SH This is the path to a hidden version of /bin/sh. It should not
235 be mistaken as a roff man macro for an unnumbered section heading.
237 'In the roff type-setting system, a single quote at the beginning
238 of a line indicates a non-breaking control character. Lopsubgen will
239 escape such lines automatically.
243 summary = specify problematic characters (e.g., "'`$\.)
245 Single (') and double quotes (") are also allowed in the type string
246 and the default value of an option.
249 arg_info = required_arg
252 default_val = .$`"'%#?*!/\
255 purpose = automatically generated help texts
256 non-opts-name = [<subcommand>]
258 The lopsub library provides functions which format the options and
259 the help text of a command. Short and long help texts are available.
262 summary = print the long help text
265 The short help omits the text of the suite file enclosed between the
266 [help] and [/help] markers while the long version includes this text.
269 [subcommand aux_info]
270 purpose = stash additional per-command information into a suite file
272 The aux_info feature of lopsub allows adding of additional information
273 to the subcommands of a suite without the need to maintain another
274 per-command array, which would be error-prone.
276 To illustrate the feature, the command section for this subcommand
277 contains an author name and a (fictitious) permission value,
278 realized as the OR of the usual file mode bits. When the subcommand
279 is executed, it prints this information for each subcommand.
281 Note that the man page contains the symbolic names of the permission
282 bits while the code in the aux_info command handler of lopsubex.c
283 gets the numeric value.
285 aux_info = Random J. Hacker, S_IRWXU
287 [subcommand default-val]
288 purpose = how default values are handled
290 Run this subcommand with no arguments to see how default values apply,
291 depending on the type of the argument and whether a default value is
292 specified in the suite file.
295 summary = numeric argument with default value
297 arg_info = required_arg
302 summary = numeric argument without default value
304 arg_info = required_arg
309 summary = string argument with default value
310 arg_info = required_arg
316 summary = string argument without default value
317 arg_info = required_arg
321 summary = enum option with default value
323 arg_info = required_arg
327 DT_MORNING = "morning",
328 DT_AFTERNOON = "afternoon",
329 DT_EVENING = "evening",
334 summary = enum option without default value
336 arg_info = required_arg
340 DOW_MONDAY = "Monday",
341 DOW_TUESDAY = "Tuesday",
342 DOW_WEDNESDAY = "Wednesday",
343 DOW_THURSDAY = "Thursday",
344 DOW_FRIDAY = "Friday",
345 DOW_SATURDAY = "Saturday",
346 DOW_SUNDAY = "Sunday"
349 [subcommand optional-arg]
350 purpose = options with optional argument
351 non-opts-name = <file>
353 Options which take an optional argument behave much like like options
354 with required argument. If the option is not given, or is given with
355 no argument supplied, the default value is substituted, with the
356 semantics illustrated in the default-val subcommand.
358 Note that the optional argument must be specified as in --opt=arg
359 rather than --opt arg because the latter form is ambiguous (arg could
360 also be a non-option argument).
362 Run this subcommand with -w=1, then with -w 1 to see the
363 difference. Also note the difference between -w 1 and -h 1.
366 summary = option with optional uint32 argument
368 arg_info = optional_arg
373 summary = option with required uint32 argument
375 arg_info = required_arg
380 This concludes the description of the subcommands of lopsubex. For
381 further information, consult the source code.
384 Written by Andre Noll
386 Public domain, no copyright claims.
389 .MT <maan@tuebingen.mpg.de>