NAME
cli - command line interface compiler for C++
SYNOPSIS
cli [options] file
DESCRIPTION
cli
generates C++ implementation and
documentation in various formats for a command line interface
defined in the CLI language. For an input file in the form
name.cli
the following is generated. By
default or if the --generate-cxx
option is
specified, the following C++ files are generated:
name.hxx
(header file), name.ixx
(inline file, generated unless the --suppress-inline
option is specified), and name.cxx
(source file).
If the --generate-html
option is specified, then
the name.html
HTML documentation file is generated.
If the --generate-man
option is specified, then
the name.1
man page file is generated. When
--generate-html
or --generate-man
is specified, the --stdout
option can be used to
redirect the output to STDOUT instead of a file.
OPTIONS
--help
- Print usage information and exit.
--version
- Print version and exit.
--include-path
|-I
dir- Search dir for bracket-included (
<>
) options files. --output-dir
|-o
dir- Write the generated files to dir instead of the current directory.
--generate-modifier
- Generate option value modifiers in addition to accessors.
--generate-specifier
- Generate functions for determining whether the option was specified on the command line.
--generate-parse
- Generate
parse()
functions instead of parsing constructors. This is primarily useful for being able to parse into an already initialized options class instance, for example, to implement merging/overriding. --generate-description
- Generate the option description list that can be examined at runtime.
--generate-file-scanner
- Generate the
argv_file_scanner
implementation. This scanner is capable of reading command line arguments from theargv
array as well as files specified with command line options. --suppress-inline
- Generate all functions non-inline. By default simple functions are made inline. This option suppresses creation of the inline file.
--cli-namespace
ns- Generate the CLI support types in the ns namespace
(
cli
by default). The namespace can be nested, for exampledetails::cli
. If the namespace is empty, then the support types are generated in the global namespace. --ostream-type
type- Output stream type instead of the default
std::ostream
that should be used to print usage and exception information. --generate-cxx
- Generate C++ code. If neither
--generate-man
nor--generate-html
is specified, this mode is assumed by default. --generate-man
- Generate documentation in the man page format.
--generate-html
- Generate documentation in the HTML format.
--stdout
- Write output to STDOUT instead of a file. This option is not valid when generating C++ code and is normally used to combine generated documentation for several option classes in a single file.
--suppress-undocumented
- Suppress the generation of documentation entries for undocumented options.
--suppress-usage
- Suppress the generation of the usage printing code.
--long-usage
- If no short documentation string is provided, use the complete long documentation string in usage. By default, in this situation only the first sentence from the long string is used.
--short-usage
- If specified together with
--long-usage
, generate both short and long usage versions. In this mode, the usage printing functions are calledprint_short_usage()
andprint_long_usage()
and for the long usage the long documentation string is always used, even if the short version is provided. --page-usage
name- Generate the combined usage printing code for the entire page.
Specifically, this will include all the namespace-level documentation as
well as usage for all the options classes printed in the order they are
defined in the main translation unit (documentation/classes from included
units are ignored except for base classes).
The name argument is used as a prefix to form the name of the usage printing function. It can include the namespace qualification as well as documentation variable expansion, for example:
--page-usage print_ # print_usage() in global namespace --page-usage app::print_ # print_usage() in app namespace --page-usage print_$name$_ # print_foo_usage() if name is foo
If both
--long-usage
and--short-usage
options are specified, then two functions are generated with the*short_usage()
and*long_usage()
suffixes. --option-length
len- Indent option descriptions len characters when printing usage. This is useful when you have multiple options classes, potentially in separate files, and would like their usage to have the same indentation level.
--ansi-color
- Use ANSI color escape sequences when printing usage. By "color" we
really only mean the bold and underline modifiers. Note that Windows
console does not recognize ANSI escape sequences and will display them as
garbage. However, if you pipe such output through
less(1)
, it will display them correctly. --exclude-base
- Exclude base class information from usage and documentation.
--class
fq-name- Generate the man page or HTML documentation only for the
fq-name options class. The fq-name name should be a
fully-qualified options class name, for example,
app::options
. To generate documentation for multiple classes, repeat this option and the documentation will be produced in the order specified. This functionality is useful if you need to assemble documentation from multiple classes in a specific order or to insert custom documentation between options belonging to different classes. --docvar
|-v
name=val- Set documentation variable name to the value val.
Documentation variables can be substituted in prologues and epilogues (see
--*-prologue*
and--*-epilogue*
options) using the$
name$
expansion syntax (use$$
to escape expansion). They can also be defined in.cli
files using the"\name=val"
syntax. --hxx-prologue
text- Insert text at the beginning of the generated C++ header file.
--ixx-prologue
text- Insert text at the beginning of the generated C++ inline file.
--cxx-prologue
text- Insert text at the beginning of the generated C++ source file.
--man-prologue
text- Insert text at the beginning of the generated man page file.
--html-prologue
text- Insert text at the beginning of the generated HTML file.
--hxx-epilogue
text- Insert text at the end of the generated C++ header file.
--ixx-epilogue
text- Insert text at the end of the generated C++ inline file.
--cxx-epilogue
text- Insert text at the end of the generated C++ source file.
--man-epilogue
text- Insert text at the end of the generated man page text.
--html-epilogue
text- Insert text at the end of the generated HTML text.
--hxx-prologue-file
file- Insert the content of file at the beginning of the generated C++ header file.
--ixx-prologue-file
file- Insert the content of file at the beginning of the generated C++ inline file.
--cxx-prologue-file
file- Insert the content of file at the beginning of the generated C++ source file.
--man-prologue-file
file- Insert the content of file at the beginning of the generated man page file.
--html-prologue-file
file- Insert the content of file at the beginning of the generated HTML file.
--hxx-epilogue-file
file- Insert the content of file at the end of the generated C++ header file.
--ixx-epilogue-file
file- Insert the content of file at the end of the generated C++ inline file.
--cxx-epilogue-file
file- Insert the content of file at the end of the generated C++ source file.
--man-epilogue-file
file- Insert the content of file at the end of the generated man page file.
--html-epilogue-file
file- Insert the content of file at the end of the generated HTML file.
--hxx-suffix
suffix- Use suffix instead of the default
.hxx
to construct the name of the generated header file. --ixx-suffix
suffix- Use suffix instead of the default
.ixx
to construct the name of the generated inline file. --cxx-suffix
suffix- Use suffix instead of the default
.cxx
to construct the name of the generated source file. --man-suffix
suffix- Use suffix instead of the default
.1
to construct the name of the generated man page file. --html-suffix
suffix- Use suffix instead of the default
.html
to construct the name of the generated HTML file. --option-prefix
prefix- Use prefix instead of the default
-
as an option prefix. Unknown command line arguments that start with this prefix are treated as unknown options. If you set the option prefix to the empty value, then all the unknown command line arguments will be treated as program arguments. --option-separator
sep- Use sep instead of the default
--
as an optional separator between options and arguments. All the command line arguments that are parsed after this separator are treated as program arguments. Set the option separator to the empty value if you don't want this functionality. --include-with-brackets
- Use angle brackets (<>) instead of quotes ("") in the generated
#include
directives. --include-prefix
prefix- Add prefix to the generated
#include
directive paths. --guard-prefix
prefix- Add prefix to the generated header inclusion guards. The prefix is transformed to upper case and characters that are illegal in a preprocessor macro name are replaced with underscores.
--reserved-name
name=rep- Add name with an optional rep replacement to the list of names that should not be used as identifiers. If provided, the replacement name is used instead. All C++ keywords are already in this list.
--options-file
file- Read additional options from file with each option appearing on
a separate line optionally followed by space and an option value. Empty
lines and lines starting with
#
are ignored. Option values can be enclosed in double ("
) or single ('
) quotes to preserve leading and trailing whitespaces as well as to specify empty values. If the value itself contains trailing or leading quotes, enclose it with an extra pair of quotes, for example'"x"'
. Non-leading and non-trailing quotes are interpreted as being part of the option value.The semantics of providing options in a file is equivalent to providing the same set of options in the same order on the command line at the point where the
--options-file
option is specified except that the shell escaping and quoting is not required. Repeat this option to specify more than one options file.
DIAGNOSTICS
If the input file is not a valid CLI definition, cli
will issue diagnostic messages to STDERR and exit with non-zero exit
code.
BUGS
Send bug reports to the cli-users@codesynthesis.com mailing list.