diff options
Diffstat (limited to 'cli/doc/pregenerated/cli.1')
| -rw-r--r-- | cli/doc/pregenerated/cli.1 | 438 |
1 files changed, 438 insertions, 0 deletions
diff --git a/cli/doc/pregenerated/cli.1 b/cli/doc/pregenerated/cli.1 new file mode 100644 index 0000000..d452ca4 --- /dev/null +++ b/cli/doc/pregenerated/cli.1 @@ -0,0 +1,438 @@ +.\" Process this file with +.\" groff -man -Tascii cli.1 +.\" +.TH CLI 1 "January 2023" "CLI 1.2.0" +.SH NAME +cli \- command line interface compiler for C++ +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH SYNOPSIS +.\"-------------------------------------------------------------------- +.B cli +.B [ +.I options +.B ] +.I file +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH DESCRIPTION +.\"-------------------------------------------------------------------- +.B 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 +.B name.cli +the following is generated. By default or if the +.B --generate-cxx +option is specified, the following C++ files are generated: +.B name.hxx +(header file), +.B name.ixx +(inline file, generated unless the +.B --suppress-inline +option is specified), and +.B name.cxx (source file). +If the +.B --generate-html +option is specified, then the +.B name.html +HTML documentation file is generated. If the +.B --generate-man +option is specified, then the +.B name.1 +man page file is generated. When +.B --generate-html +or +.B --generate-man +is specified, the +.B --stdout +option can be used to redirect the output to STDOUT instead of a file. +.\" +.\" +.\" +.\"-------------------------------------------------------------------- +.SH OPTIONS +.\"-------------------------------------------------------------------- +.IP "\fB--help\fR" +Print usage information and exit\. +.IP "\fB--version\fR" +Print version and exit\. +.IP "\fB--include-path\fR|\fB-I\fR \fIdir\fR" +Search \fIdir\fR for bracket-included (\fB<>\fR) options files\. +.IP "\fB--output-dir\fR|\fB-o\fR \fIdir\fR" +Write the generated files to \fIdir\fR instead of the current directory\. +.IP "\fB--std\fR \fIversion\fR" +Specify the C++ standard that should be used during compilation\. Valid values +are \fBc++98\fR (default), \fBc++11\fR, and \fBc++14\fR\. +.IP "\fB--generate-modifier\fR" +Generate option value modifiers in addition to accessors\. +.IP "\fB--generate-specifier\fR" +Generate functions for determining whether the option was specified on the +command line\. +.IP "\fB--generate-parse\fR" +Generate \fBparse()\fR 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\. +.IP "\fB--generate-merge\fR" +Generate \fBmerge()\fR 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 +\fB--generate-specifier\fR\. +.IP "\fB--generate-description\fR" +Generate the option description list that can be examined at runtime\. +.IP "\fB--generate-file-scanner\fR" +Generate the \fBargv_file_scanner\fR implementation\. This scanner is capable +of reading command line arguments from the \fBargv\fR array as well as files +specified with command line options\. +.IP "\fB--generate-vector-scanner\fR" +Generate the \fBvector_scanner\fR implementation\. This scanner is capable of +reading command line arguments from \fBvector<string>\fR\. +.IP "\fB--generate-group-scanner\fR" +Generate the \fBgroup_scanner\fR 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 '\fB{\fR' and ends with '\fB}+\fR' +while a trailing group starts with '\fB+{\fR' and ends with '\fB}\fR'\. For +example: + +.nf +{ --foo --bar }+ arg # 'arg' with '--foo' '--bar' +arg +{ fox=1 baz=2 } # 'arg' with 'fox=1' 'baz=2' +.fi + +Multiple leading and/or trailing groups can be specified for the same +argument\. For example: + +.nf +{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2' +.fi + +The group applies to a single argument only unless multiple arguments are +themselves grouped with '\fB{\fR' and '\fB}\fR'\. For example: + +.nf +{ --foo }+ arg1 arg2 +{ --bar } # 'arg1' with '--foo' + # 'arg2' with '--bar' + +{ --foo }+ { arg1 arg2 } +{ --bar } # 'arg1' with '--foo' '--bar' + # 'arg2' with '--foo' '--bar' +.fi + +The group separators ('\fB{\fR', '\fB}+'\fR, 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: + +.nf +{--foo}+ arg # '{--foo}+' \.\.\. +arg+{ --foo } # 'arg+{' \.\.\. +.fi + +If one of the group separators needs to be specified as an argument verbatim, +then it must be escaped with '\fB\e\fR'\. For example: + +.nf +} # error: unexpected group separator +}x # '}x' +\\} # '}' +{ \\}+ }+ arg # 'arg' with '}+' +.fi +.IP "\fB--suppress-inline\fR" +Generate all functions non-inline\. By default simple functions are made +inline\. This option suppresses creation of the inline file\. +.IP "\fB--suppress-cli\fR" +Do not generate the CLI support types (scanners, parser, etc)\. Normally, the +support types are generated unless another \fB\.cli\fR was included, in which +case the support types are expected to be provided by its generated code\. +.IP "\fB--cli-namespace\fR \fIns\fR" +Generate the CLI support types in the \fIns\fR namespace (\fBcli\fR by +default)\. The namespace can be nested, for example \fBdetails::cli\fR\. If +the namespace is empty, then the support types are generated in the global +namespace\. +.IP "\fB--ostream-type\fR \fItype\fR" +Output stream type instead of the default \fBstd::ostream\fR that should be +used to print usage and exception information\. +.IP "\fB--export-symbol\fR \fIsymbol\fR" +Insert \fIsymbol\fR in places where DLL export/import control statements +(\fB__declspec(dllexport/dllimport)\fR) are necessary\. +.IP "\fB--generate-cxx\fR" +Generate C++ code\. If neither \fB--generate-man\fR, \fB--generate-html\fR, +nor \fB--generate-txt\fR is specified, this mode is assumed by default\. +.IP "\fB--generate-man\fR" +Generate documentation in the man page format\. +.IP "\fB--generate-html\fR" +Generate documentation in the HTML format\. +.IP "\fB--generate-txt\fR" +Generate documentation in the plain text format, similar to usage\. +.IP "\fB--generate-dep\fR" +Generate \fBmake\fR dependency information\. This option triggers the creation +of the \fB\.d\fR file containing the dependencies of the generated files on +the main \fB\.cli\fR file as well as all the \fB\.cli\fR files that it +includes or sources, transitively\. Paths specified with the +\fB--*-prologue-file\fR and \fB--*-epilogue-file\fR options are also added as +dependencies\. Note, however, that paths specified with the +\fB--options-file\fR option are not added (since they may or may not contain +options that affect the output)\. +.IP "\fB--stdout\fR" +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\. +.IP "\fB--suppress-undocumented\fR" +Suppress the generation of documentation entries for undocumented options\. +.IP "\fB--suppress-usage\fR" +Suppress the generation of the usage printing code\. +.IP "\fB--long-usage\fR" +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\. +.IP "\fB--short-usage\fR" +If specified together with \fB--long-usage\fR, generate both short and long +usage versions\. In this mode, the long usage printing function is called +\fBprint_long_usage()\fR and in its implementation the long documentation +string is always used, even if the short version is provided\. +.IP "\fB--page-usage\fR \fIname\fR" +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 \fIname\fR 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: + +.nf +--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 +.fi + +If both \fB--long-usage\fR and \fB--short-usage\fR options are specified, then +the long usage function has the \fB*long_usage()\fR suffix\. +.IP "\fB--option-length\fR \fIlen\fR" +Indent option descriptions \fIlen\fR 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\. +.IP "\fB--ascii-tree\fR" +Convert UTF-8 \fBtree(1)\fR output to ASCII\. Specifically, box-drawing +characters used in the \fB--charset=UTF-8\fR output are replaced with ASCII +characters used in the \fB--charset=ASCII\fR output\. +.IP "\fB--ansi-color\fR" +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 \fBless(1)\fR, it will display them +correctly\. +.IP "\fB--exclude-base\fR" +Exclude base class information from usage and documentation\. +.IP "\fB--include-base-last\fR" +Include base class information after derived for usage and documentation\. By +default, base classes are included first\. +.IP "\fB--class-doc\fR \fIname\fR=\fIkind\fR" +Specify the documentation \fIkind\fR that should be used for the options class +\fIname\fR\. The \fIname\fR value should be a fully-qualified class name, for +example, \fBapp::options\fR\. The \fIkind\fR value can be \fBshort\fR, +\fBlong\fR, \fBexclude\fR, or \fBexclude-base\fR\. If the value is +\fBexclude\fR, then the class documentation is excluded from usage and +man/HTML/text output\. If it is \fBexclude-base\fR, then it is only excluded +when used as a base\. For usage, the \fBshort\fR and \fBlong\fR values +determine which usage function will be called when the class is used as base +or as part of the page usage (see \fB--page-usage\fR)\. For man/HTML/text, +these values determine which documentation strings are used in the output\. +.IP "\fB--class\fR \fIname\fR" +Generate the man page, HTML, or text documentation only for the options class +\fIname\fR\. The \fIname\fR value should be a fully-qualified options class +name, for example, \fBapp::options\fR\. 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\. +.IP "\fB--docvar\fR|\fB-v\fR \fIname\fR=\fIval\fR" +Set documentation variable \fIname\fR to the value \fIval\fR\. Documentation +variables can be substituted in prologues and epilogues (see +\fB--*-prologue*\fR and \fB--*-epilogue*\fR options) using the +\fB$\fR\fIname\fR\fB$\fR expansion syntax (use \fB$$\fR to escape expansion)\. +They can also be defined in \fB\.cli\fR files using the +\&"\e\fIname\fR=\fIval\fR"\fR syntax\. +.IP "\fB--link-regex\fR \fIregex\fR" +Add \fIregex\fR 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 +\fB/\fR\fIpattern\fR\fB/\fR\fIreplacement\fR\fB/\fR\fR\. Any character can be +used as a delimiter instead of '\fB/\fR' and the delimiter can be escaped +inside \fIpattern\fR and \fIreplacement\fR with a backslash (\fB\e\fR)\. 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 \fB--link-regex-trace\fR option to debug link +transformation\. +.IP "\fB--link-regex-trace\fR" +Trace the process of applying regular expressions specified with the +\fB--link-regex\fR option\. Use this option to find out why your regular +expressions don't do what you expected them to do\. +.IP "\fB--html-heading-map\fR \fIc\fR=\fIh\fR" +Map CLI heading \fIc\fR (valid values: '\fBH\fR', '\fB0\fR', '\fB1\fR', +\&'\fBh\fR', and '\fB2\fR') to HTML heading \fIh\fR (for example, '\fBh1\fR', +\&'\fBh2\fR', etc)\. +.IP "\fB--omit-link-check\fR" +Don't check that local fragment link references (\el{#ref \.\.\.}) resolve to +ids\. +.IP "\fB--hxx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ header file\. +.IP "\fB--ixx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ inline file\. +.IP "\fB--cxx-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated C++ source file\. +.IP "\fB--man-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated man page file\. +.IP "\fB--html-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated HTML file\. +.IP "\fB--txt-prologue\fR \fItext\fR" +Insert \fItext\fR at the beginning of the generated text file\. +.IP "\fB--hxx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ header file\. +.IP "\fB--ixx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ inline file\. +.IP "\fB--cxx-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated C++ source file\. +.IP "\fB--man-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated man page file\. +.IP "\fB--html-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated HTML file\. +.IP "\fB--txt-epilogue\fR \fItext\fR" +Insert \fItext\fR at the end of the generated text file\. +.IP "\fB--hxx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ header +file\. +.IP "\fB--ixx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ inline +file\. +.IP "\fB--cxx-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated C++ source +file\. +.IP "\fB--man-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated man page +file\. +.IP "\fB--html-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated HTML file\. +.IP "\fB--txt-prologue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the beginning of the generated text file\. +.IP "\fB--hxx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ header file\. +.IP "\fB--ixx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ inline file\. +.IP "\fB--cxx-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated C++ source file\. +.IP "\fB--man-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated man page file\. +.IP "\fB--html-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated HTML file\. +.IP "\fB--txt-epilogue-file\fR \fIfile\fR" +Insert the content of \fIfile\fR at the end of the generated text file\. +.IP "\fB--output-prefix\fR \fIprefix\fR" +Add \fIprefix\fR at the beginning of the generated output file name(s)\. +.IP "\fB--output-suffix\fR \fIsuffix\fR" +Add \fIsuffix\fR at the end of the generated output file name(s)\. Note that +it is added before any file type-specific suffixes; see \fB--*-suffix\fR +below\. +.IP "\fB--hxx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.hxx\fR to construct the name of +the generated header file\. +.IP "\fB--ixx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.ixx\fR to construct the name of +the generated inline file\. +.IP "\fB--cxx-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.cxx\fR to construct the name of +the generated source file\. +.IP "\fB--man-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.1\fR to construct the name of the +generated man page file\. +.IP "\fB--html-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.html\fR to construct the name of +the generated HTML file\. +.IP "\fB--txt-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.txt\fR to construct the name of +the generated text file\. +.IP "\fB--dep-suffix\fR \fIsuffix\fR" +Use \fIsuffix\fR instead of the default \fB\.d\fR to construct the name of the +generated dependency file\. See also \fB--dep-file\fR\. +.IP "\fB--dep-file\fR \fIpath\fR" +Use \fIpath\fR as the generated dependency file path instead of deriving it +from the input file name\. +.IP "\fB--option-prefix\fR \fIprefix\fR" +Use \fIprefix\fR instead of the default '\fB-\fR' 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\. +.IP "\fB--option-separator\fR \fIsep\fR" +Use \fIsep\fR instead of the default '\fB--\fR' 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\. +.IP "\fB--keep-separator\fR" +Leave the option separator in the scanner\. This is primarily useful for +incremental option parsing\. +.IP "\fB--no-combined-flags\fR" +Disable support for combining multiple single-character flags into a single +argument (the \fB-xyz\fR form that is equivalent to \fB-x\fR \fB-y\fR +\fB-z\fR)\. An argument is considered a combination of flags if it starts with +a single option prefix (\fB--option-prefix\fR) 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\. +.IP "\fB--no-combined-values\fR" +Disable support for combining an option and its value into a single argument +with the assignment sign (the \fIoption\fR\fB=\fR\fIvalue\fR\fR form)\. This +functionality requires a non-empty option prefix (\fB--option-prefix\fR)\. +.IP "\fB--include-with-brackets\fR" +Use angle brackets (\fB<>\fR) instead of quotes (\fB""\fR) in the generated +\fB#include\fR directives\. +.IP "\fB--include-prefix\fR \fIprefix\fR" +Add \fIprefix\fR to the generated \fB#include\fR directive paths\. +.IP "\fB--guard-prefix\fR \fIprefix\fR" +Add \fIprefix\fR 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\. +.IP "\fB--reserved-name\fR \fIname\fR=\fIrep\fR" +Add \fIname\fR with an optional \fIrep\fR 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\. +.IP "\fB--options-file\fR \fIfile\fR" +Read additional options from \fIfile\fR\. Each option should appear on a +separate line optionally followed by space or equal sign (\fB=\fR) and an +option value\. Empty lines and lines starting with \fB#\fR are ignored\. +Option values can be enclosed in double (\fB"\fR) or single (\fB'\fR) 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 \fB'"x"'\fR\. 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 \fB--options-file\fR option is specified except that the shell escaping +and quoting is not required\. Repeat this option to specify more than one +options file\. +.\" +.\" DIAGNOSTICS +.\" +.SH DIAGNOSTICS +If the input file is not a valid CLI definition, +.B cli +will issue diagnostic messages to STDERR and exit with non-zero exit code. +.\" +.\" BUGS +.\" +.SH BUGS +Send bug reports to the cli-users@codesynthesis.com mailing list. +.\" +.\" COPYRIGHT +.\" +.SH COPYRIGHT +Copyright (c) 2009-2023 Code Synthesis Tools CC. + +Permission is granted to copy, distribute and/or modify this document under +the terms of the MIT License. Copy of this license can be obtained from +http://www.codesynthesis.com/licenses/mit.txt |