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 the argv 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 example details::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 called print_short_usage() and print_long_usage() and for the long usage the long documentation string is always used, even if the short version is provided.

--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.

--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.