path: root/lopsubex.suite

# Written 2016 by Andre Noll <maan@tuebingen.mpg.de>
#
# 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 = [<subcommand>] [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 = [<subcommand>]
	[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 = <file>
	[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 <maan@tuebingen.mpg.de>
	Andre Noll
	.ME
[/section]