- -

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'

- -

Note that the group applies to a single argument only. For example:

- -

{ --foo }+ arg1  arg2 +{ --bar }  # 'arg1' with '--foo' and
-                                  # 'arg2' with '--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.

- -