+ +

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.

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

+ +