config_file.l: Instruct flex to create a reentrant scanner.
[lopsub.git] / lopsubex.suite
1 # Written 2016 by Andre Noll <maan@tuebingen.mpg.de>
2 #
3 # Public domain, no copyright claims.
4
5 [suite lopsubex]
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]
13 [description]
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.
17 [/description]
18 [closing]
19 When executed with no argument, the program lists the available
20 subcommands. Otherwise the first argument must be a subcommand from
21 the list below.
22 [/closing]
23
24 [introduction]
25 Each subcommand of lopsubex illustrates a different feature of the
26 lopsub library.
27 [/introduction]
28
29 [subcommand flag]
30 purpose = options with no arguments
31 [description]
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
34 in the suite file.
35 [/description]
36 [option simple]
37 summary = simplest option on the planet
38 [option sqrt4]
39 short_opt = 2
40 summary = Flag option with a short option equivalent.
41 [closing]
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.
44
45 Decimal digits are allowed as short option equivalent for a long
46 option.
47 [/closing]
48
49 [subcommand int-param]
50 purpose = options which take an integer argument
51 [description]
52 Options may be specified to take an integer argument. This subcommand
53 provides a simple example.
54 [/description]
55 [option rotate]
56 short_opt = r
57 summary = example option which takes a required integer argument
58 arg_info = required_arg
59 arg_type = int32
60 typestr = degrees
61 [help]
62 Integers may be specified as a C99 decimal, hexadecimal or octal
63 constant.
64
65 The type of the argument for this option is a signed 32 bit integer,
66 so negative values are allowed.
67 [/help]
68
69 [subcommand multiple]
70 purpose = options that can be specified more than once
71 [description]
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
75 from lls_parse().
76 [/description]
77 [option verbose]
78 short_opt = v
79 summary = may be given multiple times, takes no argument
80 [help]
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.
84
85 To specify the option twice, one may write either -v -v or -vv.
86 [/help]
87 [option input-file]
88 short_opt = i
89 summary = multiple string values may be given
90 [help]
91 The subcommand will print all given values.
92 [/help]
93 arg_info = required_arg
94 arg_type = string
95 typestr = path
96 flag multiple
97 [option output-file]
98 short_opt = o
99 summary = only one value is stored in the parse result.
100 [help]
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.
104 [/help]
105 arg_info = required_arg
106 arg_type = string
107 typestr = path
108 default_val = /dev/null
109 [closing]
110 Run this command and specify each option more than once to see
111 the effect.
112 [/closing]
113
114 [subcommand custom-synopsis]
115 purpose = overwrite the default usage string
116 synopsis = [file...]
117 [description]
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.
121
122 In this example, the synopsis text is set to "[file...]".
123 [/description]
124
125 [subcommand enum]
126 purpose = enumerable options
127 [description]
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.
131
132 The last value (black) shows how to specify values with embedded
133 spaces and quotes.
134 [/description]
135 [option color]
136 summary = name of a color
137 short_opt = c
138 arg_info = required_arg
139 arg_type = string
140 typestr = color
141 values = {
142 COLOR_RED = "red",
143 COLOR_GREEN = "green",
144 COLOR_BLUE = "blue",
145 COLOR_YELLOW = "yellow",
146 COLOR_BLACK = "black (that's not really a \"color\")"
147 }
148 default_val = green
149
150 [subcommand serialize]
151 purpose = write a parse result into a buffer
152 [description]
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.
161 [/description]
162 [option fruit]
163 short_opt = f
164 arg_info = required_arg
165 arg_type = string
166 typestr = fruit
167 flag multiple
168 default_val = apples
169 [option amount]
170 short_opt = a
171 arg_info = required_arg
172 arg_type = uint32
173 typestr = g
174 default_val = 100
175 [option sugar]
176 short_opt = s
177 [option container]
178 short_opt = c
179 arg_type = string
180 arg_info = optional_arg
181 default_val = bowl
182
183 [subcommand non-ascii]
184 purpose = use of non-ASCII characters (e.g., umlauts like 'ä')
185 [description]
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.
191
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.
194
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:
203
204 iconv -t ISO_8859-1 app.suite | ./lopsubgen --gen-man
205
206 [/description]
207 [option city]
208 summary = name of a big city (Großstadt)
209 [help]
210 The command prints a more or less interesting sentence about the
211 given city. At the moment, only Göttingen is supported.
212 [/help]
213 short_opt = c
214 arg_info = required_arg
215 arg_type = string
216 typestr = Großstadt
217 default_val = Göttingen
218
219 [subcommand quotes]
220 purpose = embedded quotes (") and backslashes (\).
221 [description]
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.
225
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.
229
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:
233
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.
236
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.
240
241 [/description]
242 [option chars]
243 summary = specify problematic characters (e.g., "'`$\.)
244 [help]
245 Single (') and double quotes (") are also allowed in the type string
246 and the default value of an option.
247 [/help]
248 short_opt = s
249 arg_info = required_arg
250 arg_type = string
251 typestr = "set"
252 default_val = .$`"'%#?*!/\
253
254 [subcommand help]
255 purpose = automatically generated help texts
256 non-opts-name = [<subcommand>]
257 [description]
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.
260 [/description]
261 [option long]
262 summary = print the long help text
263 short_opt = l
264 [help]
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.
267 [/help]
268
269 [subcommand aux_info]
270 purpose = stash additional per-command information into a suite file
271 [description]
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.
275
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.
280
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.
284 [/description]
285 aux_info = Random J. Hacker, S_IRWXU
286
287 [subcommand default-val]
288 purpose = how default values are handled
289 [description]
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.
293 [/description]
294 [option width]
295 summary = numeric argument with default value
296 short_opt = w
297 arg_info = required_arg
298 arg_type = uint32
299 typestr = pixels
300 default_val = 42
301 [option height]
302 summary = numeric argument without default value
303 short_opt = h
304 arg_info = required_arg
305 arg_type = uint32
306 typestr = pixels
307 [option town]
308 short_opt = t
309 summary = string argument with default value
310 arg_info = required_arg
311 arg_type = string
312 typestr = name
313 default_val = Berlin
314 [option street]
315 short_opt = s
316 summary = string argument without default value
317 arg_info = required_arg
318 arg_type = string
319 typestr = streetname
320 [option time]
321 summary = enum option with default value
322 short_opt = T
323 arg_info = required_arg
324 arg_type = string
325 typestr = daytime
326 values = {
327 DT_MORNING = "morning",
328 DT_AFTERNOON = "afternoon",
329 DT_EVENING = "evening",
330 DT_NIGHT = "night"
331 }
332 default_val = night
333 [option weekday]
334 summary = enum option without default value
335 short_opt = w
336 arg_info = required_arg
337 arg_type = string
338 typestr = dayofweek
339 values = {
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"
347 }
348
349 [subcommand optional-arg]
350 purpose = options with optional argument
351 non-opts-name = <file>
352 [description]
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.
357
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).
361
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.
364 [/description]
365 [option width]
366 summary = option with optional uint32 argument
367 short_opt = w
368 arg_info = optional_arg
369 arg_type = uint32
370 typestr = pixels
371 default_val = 42
372 [option height]
373 summary = option with required uint32 argument
374 short_opt = h
375 arg_info = required_arg
376 arg_type = uint32
377 typestr = pixels
378
379 [conclusion]
380 This concludes the description of the subcommands of lopsubex. For
381 further information, consult the source code.
382 [/conclusion]
383 [section copyright]
384 Written by Andre Noll
385 .br
386 Public domain, no copyright claims.
387 .br
388 Report bugs to
389 .MT <maan@tuebingen.mpg.de>
390 Andre Noll
391 .ME
392 [/section]