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]