summaryrefslogtreecommitdiff
path: root/doc/cli.1
diff options
context:
space:
mode:
authorKaren Arutyunov <karen@codesynthesis.com>2020-04-08 14:51:57 +0300
committerKaren Arutyunov <karen@codesynthesis.com>2020-04-27 11:38:53 +0300
commit720c5a33b6a49cf328fdd7611f49153cf8f60247 (patch)
tree9725f3d1f42ec90fde84520f49647edea013ce5e /doc/cli.1
parent3183f3bb927a90783ae0aeaf190a0919377aabe4 (diff)
Separate tests and examples into individual packages
Also make cli module to be explicitly enabled via the config.cli configuration variable.
Diffstat (limited to 'doc/cli.1')
-rw-r--r--doc/cli.1412
1 files changed, 0 insertions, 412 deletions
diff --git a/doc/cli.1 b/doc/cli.1
deleted file mode 100644
index 6b64f9e..0000000
--- a/doc/cli.1
+++ /dev/null
@@ -1,412 +0,0 @@
-.\" Process this file with
-.\" groff -man -Tascii cli.1
-.\"
-.TH CLI 1 "December 2009" "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
-
-Note that the group applies to a single argument only\. For example:
-
-.nf
-{ --foo }+ arg1 arg2 +{ --bar } # 'arg1' with '--foo' and
- # 'arg2' with '--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--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--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--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--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-2020 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