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.
--std version
Specify the C++ standard that should be used during compilation. Valid values are c++98 (default), c++11, and c++14.
--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 option appending/overriding.
--generate-merge
Generate merge() functions. This is primarily useful for being able to merge several already parsed options class instances, for example, to implement option appending/overriding. Note that this option forces --generate-specifier.
--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.
--generate-vector-scanner
Generate the vector_scanner implementation. This scanner is capable of reading command line arguments from vector<string>.
--generate-group-scanner
Generate the group_scanner implementation. This scanner supports grouping of arguments (usually options) to apply only to a certain argument.

Groups can be specified before (leading) and/or after (trailing) the argument they apply to. A leading group starts with '{' and ends with '}+' while a trailing group starts with '+{' and ends with '}'. For example:

{ --foo --bar }+ arg   # 'arg' with '--foo' '--bar'
arg +{ fox=1 baz=2 }   # 'arg' with 'fox=1' 'baz=2'

Multiple leading and/or trailing groups can be specified for the same argument. For example:

{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'

The group applies to a single argument only unless multiple arguments are themselves grouped with '{' and '}'. For example:

{ --foo }+ arg1  arg2 +{ --bar }      # 'arg1' with '--foo'
                                      # 'arg2' with '--bar'

{ --foo }+ { arg1  arg2 } +{ --bar }  # 'arg1' with '--foo' '--bar'
                                      # 'arg2' with '--foo' '--bar'

The group separators ('{', '}+', etc) must be separate command line arguments. In particular, they must not be adjacent either to the arguments inside the group nor to the argument they apply to. All such cases will be treated as ordinary arguments. For example:

{--foo}+ arg   # '{--foo}+' ...
arg+{ --foo }  # 'arg+{' ...

If one of the group separators needs to be specified as an argument verbatim, then it must be escaped with '\'. For example:

}             # error: unexpected group separator
}x            # '}x'
\}            # '}'
{ \}+ }+ arg  # 'arg' with '}+'
--suppress-inline
Generate all functions non-inline. By default simple functions are made inline. This option suppresses creation of the inline file.
--suppress-cli
Do not generate the CLI support types (scanners, parser, etc). Normally, the support types are generated unless another .cli was included, in which case the support types are expected to be provided by its generated code.
--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, --generate-html, nor --generate-txt 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.
--generate-txt
Generate documentation in the plain text format, similar to usage.
--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 long usage printing function is called print_long_usage() and in its implementation 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 the long usage function has the *long_usage() suffix.

--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.
--ascii-tree
Convert UTF-8 tree(1) output to ASCII. Specifically, box-drawing characters used in the --charset=UTF-8 output are replaced with ASCII characters used in the --charset=ASCII output.
--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.
--include-base-last
Include base class information after derived for usage and documentation. By default, base classes are included first.
--class-doc name=kind
Specify the documentation kind that should be used for the options class name. The name value should be a fully-qualified class name, for example, app::options. The kind value can be short, long, exclude, or exclude-base. If the value is exclude, then the class documentation is excluded from usage and man/HTML/text output. If it is exclude-base, then it is only excluded when used as a base. For usage, the short and long values determine which usage function will be called when the class is used as base or as part of the page usage (see --page-usage). For man/HTML/text, these values determine which documentation strings are used in the output.
--class name
Generate the man page, HTML, or text documentation only for the options class name. The name value 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.
--link-regex regex
Add regex to the list of regular expressions used to transform link targets in the generated documentation. The argument to this option is a Perl-like regular expression in the form /pattern/replacement/. Any character can be used as a delimiter instead of '/' and the delimiter can be escaped inside pattern and replacement with a backslash (\). You can specify multiple regular expressions by repeating this option. All the regular expressions are tried in the order specified and the first expression that matches is used. Use the --link-regex-trace option to debug link transformation.
--link-regex-trace
Trace the process of applying regular expressions specified with the --link-regex option. Use this option to find out why your regular expressions don't do what you expected them to do.
--html-heading-map c=h
Map CLI heading c (valid values: 'H', '0', '1', 'h', and '2') to HTML heading h (for example, 'h1', 'h2', etc).
--omit-link-check
Don't check that local fragment link references (\l{#ref ...}) resolve to ids.
--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.
--txt-prologue text
Insert text at the beginning of the generated text 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 file.
--html-epilogue text
Insert text at the end of the generated HTML file.
--txt-epilogue text
Insert text at the end of the generated text file.
--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.
--txt-prologue-file file
Insert the content of file at the beginning of the generated text 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.
--txt-epilogue-file file
Insert the content of file at the end of the generated text file.
--output-prefix prefix
Add prefix at the beginning of the generated output file name(s).
--output-suffix suffix
Add suffix at the end of the generated output file name(s). Note that it is added before any file type-specific suffixes; see --*-suffix below.
--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.
--txt-suffix suffix
Use suffix instead of the default .txt to construct the name of the generated text 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.
--keep-separator
Leave the option separator in the scanner. This is primarily useful for incremental option parsing.
--no-combined-flags
Disable support for combining multiple single-character flags into a single argument (the -xyz form that is equivalent to -x -y -z). An argument is considered a combination of flags if it starts with a single option prefix (--option-prefix) and only contains letters and digits. Note that an option with a value may not be part of such a combination, not even if it is specified last.
--no-combined-values
Disable support for combining an option and its value into a single argument with the assignment sign (the option=value form). This functionality requires a non-empty option prefix (--option-prefix).
--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. Each option should appear on a separate line optionally followed by space or equal sign (=) 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.