# Written 2016 by Andre Noll # # Public domain, no copyright claims. [suite lopsubex] aux_info_prefix = further information: aux_info_default = (unknown), S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH caption = lopsubex subcommands # This will be printed before the list of subcommands [supercommand lopsubex] purpose = illustrate lopsub features non-opts-name = [] [options] [description] This program illustrates the various features of the lopsub option parser. Consult the lopsubex.suite file and the source in lopsubex.c to see how the subcommands described in this document are implemented. [/description] [closing] When executed with no argument, the program lists the available subcommands. Otherwise the first argument must be a subcommand from the list below. [/closing] [introduction] Each subcommand of lopsubex illustrates a different feature of the lopsub library. [/introduction] [subcommand flag] purpose = options with no arguments [description] Flags are the simplest type of options as they take no argument. To create a flag option, simply omit arg_type, arg_info, and typestr in the suite file. [/description] [option simple] summary = simplest option on the planet [option sqrt4] short_opt = 2 summary = Flag option with a short option equivalent. [closing] Lopsub counts the number of times an option was given. This can be used, for example, to set the verbosity level of the application. Decimal digits are allowed as short option equivalent for a long option. [/closing] [subcommand int-param] purpose = options which take an integer argument [description] Options may be specified to take an integer argument. This subcommand provides a simple example. [/description] [option rotate] short_opt = r summary = example option which takes a required integer argument arg_info = required_arg arg_type = int32 typestr = degrees [help] Integers may be specified as a C99 decimal, hexadecimal or octal constant. The type of the argument for this option is a signed 32 bit integer, so negative values are allowed. [/help] [subcommand multiple] purpose = options that can be specified more than once [description] The multiple flag indicates that an option may be given more than once. This instructs the parser to make all given arguments available to the application via the parse_result structure which is returned from lls_parse(). [/description] [option verbose] short_opt = v summary = may be given multiple times, takes no argument [help] For flag options (options which do not take an argument), the number of times the flag was given is stored in the parse result, regardless of whether the multiple flag was set in the suite file. To specify the option twice, one may write either -v -v or -vv. [/help] [option input-file] short_opt = i summary = multiple string values may be given [help] The subcommand will print all given values. [/help] arg_info = required_arg arg_type = string typestr = path flag multiple [option output-file] short_opt = o summary = only one value is stored in the parse result. [help] Since this option is not declared as multiple, only one value is stored in the parse result. If the option was given more than once, the last given value wins. [/help] arg_info = required_arg arg_type = string typestr = path default_val = /dev/null [closing] Run this command and specify each option more than once to see the effect. [/closing] [subcommand custom-synopsis] purpose = overwrite the default usage string synopsis = [file...] [description] If a synopsis text is specified, this text is shown as the usage string in the help output. Otherwise, lopsub creates a suitable string on its own. In this example, the synopsis text is set to "[file...]". [/description] [subcommand enum] purpose = enumerable options [description] In this command, --color is an enum option, which takes the name of a color as its argument. Only a pre-defined set of colors are accepted, as defined in the suite file. The last value (black) shows how to specify values with embedded spaces and quotes. [/description] [option color] summary = name of a color short_opt = c arg_info = required_arg arg_type = string typestr = color values = { COLOR_RED = "red", COLOR_GREEN = "green", COLOR_BLUE = "blue", COLOR_YELLOW = "yellow", COLOR_BLACK = "black (that's not really a \"color\")" } default_val = green [subcommand serialize] purpose = write a parse result into a buffer [description] The lopsub library provides a function to serialize the result of a successful call to lls_parse(). This subcommand illustrates this feature. First it parses the given arguments to produce a parse result. Next it serializes the parse result into a buffer and de-serializes this buffer into a second parse result. A text which refers to the parsed values is printed twice, first with the original parse result, then with the de-serialized version. The two texts should be identical. [/description] [option fruit] short_opt = f arg_info = required_arg arg_type = string typestr = fruit flag multiple default_val = apples [option amount] short_opt = a arg_info = required_arg arg_type = uint32 typestr = g default_val = 100 [option sugar] short_opt = s [option container] short_opt = c arg_type = string arg_info = optional_arg default_val = bowl [subcommand non-ascii] purpose = use of non-ASCII characters (e.g., umlauts like 'ä') [description] Non-ASCII characters are not allowed for command and option names. They may appear, however, in the purpose text of a command (see above), in the type string and the description of an option (see below), and also in a help text like this: öäüß. Of course, non-ASCII characters are also allowed in the argument to a string option. The help text generated by the lopsub library functions should just work on any system where UTF-8 is the default character encoding. For generating man pages, however, UTF-8 will not do, because groff interprets input character codes between 127 and 255 as the corresponding characters in the latin1 (ISO-8859-1) code set. Hence, it is necessary to format the generated with the command preconv -e UTF-8. The man(1) command of the man-db package (default on most Linux distributions) does this automatically, so man pages should render correctly on those systems. On other systems it might help to convert the suite file to ISO-8859-1 before feeding it to lopsubgen: iconv -t ISO_8859-1 app.suite | ./lopsubgen --gen-man [/description] [option city] summary = name of a big city (Großstadt) [help] The command prints a more or less interesting sentence about the given city. At the moment, only Göttingen is supported. [/help] short_opt = c arg_info = required_arg arg_type = string typestr = Großstadt default_val = Göttingen [subcommand quotes] purpose = embedded quotes (") and backslashes (\). [description] In the C language a double quote (") denotes the beginning or the end of a string literal. Embedded double quotes must be prefixed with a backslash (\), and embedded backslashes need to be doubled. Lopsubgen handles these issues internally. Hence all help texts, purpose and description strings and default values may contain single (') or double quotes ("), balanced or unbalanced. Man output has similar issues. For example, if the first word of a line starts with a dot or a single quote, lopsubgen prevents roff from interpreting the word. Examples: .SH This is the path to a hidden version of /bin/sh. It should not be mistaken as a roff man macro for an unnumbered section heading. 'In the roff type-setting system, a single quote at the beginning of a line indicates a non-breaking control character. Lopsubgen will escape such lines automatically. [/description] [option chars] summary = specify problematic characters (e.g., "'`$\.) [help] Single (') and double quotes (") are also allowed in the type string and the default value of an option. [/help] short_opt = s arg_info = required_arg arg_type = string typestr = "set" default_val = .$`"'%#?*!/\ [subcommand help] purpose = automatically generated help texts non-opts-name = [] [description] The lopsub library provides functions which format the options and the help text of a command. Short and long help texts are available. [/description] [option long] summary = print the long help text short_opt = l [help] The short help omits the text of the suite file enclosed between the [help] and [/help] markers while the long version includes this text. [/help] [subcommand aux_info] purpose = stash additional per-command information into a suite file [description] The aux_info feature of lopsub allows adding of additional information to the subcommands of a suite without the need to maintain another per-command array, which would be error-prone. To illustrate the feature, the command section for this subcommand contains an author name and a (fictitious) permission value, realized as the OR of the usual file mode bits. When the subcommand is executed, it prints this information for each subcommand. Note that the man page contains the symbolic names of the permission bits while the code in the aux_info command handler of lopsubex.c gets the numeric value. [/description] aux_info = Random J. Hacker, S_IRWXU [subcommand default-val] purpose = how default values are handled [description] Run this subcommand with no arguments to see how default values apply, depending on the type of the argument and whether a default value is specified in the suite file. [/description] [option width] summary = numeric argument with default value short_opt = w arg_info = required_arg arg_type = uint32 typestr = pixels default_val = 42 [option height] summary = numeric argument without default value short_opt = h arg_info = required_arg arg_type = uint32 typestr = pixels [option town] short_opt = t summary = string argument with default value arg_info = required_arg arg_type = string typestr = name default_val = Berlin [option street] short_opt = s summary = string argument without default value arg_info = required_arg arg_type = string typestr = streetname [option time] summary = enum option with default value short_opt = T arg_info = required_arg arg_type = string typestr = daytime values = { DT_MORNING = "morning", DT_AFTERNOON = "afternoon", DT_EVENING = "evening", DT_NIGHT = "night" } default_val = night [option weekday] summary = enum option without default value short_opt = w arg_info = required_arg arg_type = string typestr = dayofweek values = { DOW_MONDAY = "Monday", DOW_TUESDAY = "Tuesday", DOW_WEDNESDAY = "Wednesday", DOW_THURSDAY = "Thursday", DOW_FRIDAY = "Friday", DOW_SATURDAY = "Saturday", DOW_SUNDAY = "Sunday" } [subcommand optional-arg] purpose = options with optional argument non-opts-name = [description] Options which take an optional argument behave much like like options with required argument. If the option is not given, or is given with no argument supplied, the default value is substituted, with the semantics illustrated in the default-val subcommand. Note that the optional argument must be specified as in --opt=arg rather than --opt arg because the latter form is ambiguous (arg could also be a non-option argument). Run this subcommand with -w=1, then with -w 1 to see the difference. Also note the difference between -w 1 and -h 1. [/description] [option width] summary = option with optional uint32 argument short_opt = w arg_info = optional_arg arg_type = uint32 typestr = pixels default_val = 42 [option height] summary = option with required uint32 argument short_opt = h arg_info = required_arg arg_type = uint32 typestr = pixels [conclusion] This concludes the description of the subcommands of lopsubex. For further information, consult the source code. [/conclusion] [section copyright] Written by Andre Noll .br Public domain, no copyright claims. .br Report bugs to .MT Andre Noll .ME [/section]