From 720c5a33b6a49cf328fdd7611f49153cf8f60247 Mon Sep 17 00:00:00 2001 From: Karen Arutyunov Date: Wed, 8 Apr 2020 14:51:57 +0300 Subject: Separate tests and examples into individual packages Also make cli module to be explicitly enabled via the config.cli configuration variable. --- doc/cli.1 | 412 -------------------------------------------------------------- 1 file changed, 412 deletions(-) delete mode 100644 doc/cli.1 (limited to 'doc/cli.1') 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\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 -- cgit v1.1