NAME¶
cli-generate - Generate source and documentation from CLI descriptions
SYNOPSIS¶
cli-generate [
-c |
-h |
-m |
-w ]
FILENAME.cli
DESCRIPTION¶
Operation¶
cli-generate reads in a CLI (command line interface) description file,
parses it into its various sections, and prints out one of a set of output
files. In typical usage, that output would be directed to a file and later
compiled or included in other sources.
The CLI file (named
PROGRAM.cli) is divided into two parts, a
header (formatted much like a standard mail header) and a series of sections.
Headers and sections other than those specified below are ignored. All headers
and sections are optional.
file = header "\n" *section
header = *(header-line "\n")
header-line = header-field ":" whitespace value
whitespace = *(SPACE / TAB)
section = "[" name "]" "\n" lines
lines = *( line "\n" )
- Description:
- A one-line description of what the program does.
- Include:
- Add C statements to #include the given source file. Must be formatted as
either <file> or file
- Min:
- The minimum number of allowed non-option arguments. Defaults to 0.
- Max:
- The maximum number of allowed non-option arguments. Negative values mean
unlimited. Defaults to -1.
- Show-Pid:
- Set to non-zero if the resulting program is to show its PID with every
output message. Defaults to 0.
- Usage:
- A one-line description of the intended usage. Defaults to empty.
Section Names¶
- [prefix]
- The text in this section is shown in the command usage before the options
description.
- [options]
- The list of options this program accepts. See below for their format.
- [suffix]
- The text in this section is shown in the command usage after the options
description.
- [description]
- [return value]
- [errors]
- [examples]
- [environment]
- [files]
- [see also]
- [notes]
- [caveats]
- [diagnostics]
- [bugs]
- [restrictions]
- [author]
- [history]
- These sections are formatted and copied into the man page in the standard
order.
options = *(option / separator)
option = option1 "\n" option2 "\n" *(line "\n")
option1 = [shortopt] [longopt] type ["=" flag-value] variable ["=" init]
option2 = helpstr ["=" default]
separator = "-- " text "\n"
shortopt = "-" character
longopt = "--" word
type = "FLAG" / "COUNTER" / "INTEGER" / "UINTEGER" / "STRING" / "STRINGLIST" / "FUNCTION"
If not specified,
flag-value and
init are
0, and
default is empty.
Except for
[prefix],
[options], and
[suffix], all of the
sections support formatting instructions similar to that of TeXinfo (but
greatly simplified).
- @strong{text}
- Use "strong" (bold) text.
- @command{text}
- Indicate the name of a command.
- @option{text}
- Indicate a command-line option.
- @emph{text}
- Use "emphatic" (italicized) text.
- @var{text}
- Indicate a metasyntactic variable.
- @env{text}
- Indicate an environment variable.
- @file{text}
- Indicate the name of a file.
- @code{text}
- Indicate text that is a literal example of a piece of a program.
- @samp{text}
- Indicate text that is a literal example of a sequence of characters.
- @example
- @end example
- The text between these two tags is indented.
- @verbatim
- @end verbatim
- Everything between these two tags is passed as-is (verbatim) to the
output.
- @table @format
- @end table
- Mark up a two-column table, or "definition list".
- @item paragraph
- Add an item to a table. The @item starts a paragraph that will be
the actual list entry. Any subsequent paragraphs will be typeset
seperately.
OPTIONS¶
- -c
- Output C source code.
- -h
- Output C header file.
- -m
- Output a UNIX man page.
- -w
- Output HTML (web) markup.
EXAMPLES¶
Here is a sample CLI file, containing many of the described elements.
Min: 1
Max: 1
Usage: PATH
Description: Create a file.
Show-Pid: 0
Include: <stdio.h>
[prefix]
If the given PATH is a directory, it is suffixed with another name.
[description]
@program generates a new random file from a variety of sources including
@command{ls} and @command{ps} output.
If the given @option{PATH} is a directory, it is suffixed with another
name of my choosing.
[options]
-v --verbose FLAG=1 opt_verbose
-t --type STRING opt_type = "type1"
The type of the file to generate. = type1
Possible types for this include @option{type1} and @option{base64}.
AUTHOR¶
Bruce Guenter <bruce@untroubled.org>
