diff options
| author | Karen Arutyunov <karen@codesynthesis.com> | 2020-04-08 14:51:57 +0300 |
|---|---|---|
| committer | Karen Arutyunov <karen@codesynthesis.com> | 2020-04-27 11:38:53 +0300 |
| commit | 720c5a33b6a49cf328fdd7611f49153cf8f60247 (patch) | |
| tree | 9725f3d1f42ec90fde84520f49647edea013ce5e /doc | |
| parent | 3183f3bb927a90783ae0aeaf190a0919377aabe4 (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')
| -rw-r--r-- | doc/cli-epilogue.1 | 21 | ||||
| -rw-r--r-- | doc/cli-epilogue.xhtml | 24 | ||||
| -rw-r--r-- | doc/cli-prologue.1 | 59 | ||||
| -rw-r--r-- | doc/cli-prologue.xhtml | 72 | ||||
| -rw-r--r-- | doc/cli.1 | 412 | ||||
| -rw-r--r-- | doc/cli.xhtml | 568 | ||||
| -rw-r--r-- | doc/default.css | 322 | ||||
| -rwxr-xr-x | doc/doc.sh | 78 | ||||
| -rw-r--r-- | doc/guide/.gitignore | 2 | ||||
| -rw-r--r-- | doc/guide/guide.html2ps | 63 | ||||
| -rw-r--r-- | doc/guide/index.xhtml | 1336 | ||||
| -rw-r--r-- | doc/guide/makefile | 39 | ||||
| -rw-r--r-- | doc/language.txt | 128 | ||||
| -rw-r--r-- | doc/makefile | 44 |
14 files changed, 0 insertions, 3168 deletions
diff --git a/doc/cli-epilogue.1 b/doc/cli-epilogue.1 deleted file mode 100644 index 5e2ffae..0000000 --- a/doc/cli-epilogue.1 +++ /dev/null @@ -1,21 +0,0 @@ -.\" -.\" 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) $copyright$. - -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 diff --git a/doc/cli-epilogue.xhtml b/doc/cli-epilogue.xhtml deleted file mode 100644 index 8a70d81..0000000 --- a/doc/cli-epilogue.xhtml +++ /dev/null @@ -1,24 +0,0 @@ - <h1>DIAGNOSTICS</h1> - - <p>If the input file is not a valid CLI definition, <code><b>cli</b></code> - will issue diagnostic messages to STDERR and exit with non-zero exit - code.</p> - - <h1>BUGS</h1> - - <p>Send bug reports to the - <a href="mailto:cli-users@codesynthesis.com">cli-users@codesynthesis.com</a> mailing list.</p> - - </div> - <div id="footer"> - Copyright © $copyright$. - - <div id="terms"> - Permission is granted to copy, distribute and/or modify this - document under the terms of the - <a href="http://www.codesynthesis.com/licenses/mit.txt">MIT License</a>. - </div> - </div> -</div> -</body> -</html> diff --git a/doc/cli-prologue.1 b/doc/cli-prologue.1 deleted file mode 100644 index 165cd1a..0000000 --- a/doc/cli-prologue.1 +++ /dev/null @@ -1,59 +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 -.\"-------------------------------------------------------------------- diff --git a/doc/cli-prologue.xhtml b/doc/cli-prologue.xhtml deleted file mode 100644 index 9a57f0e..0000000 --- a/doc/cli-prologue.xhtml +++ /dev/null @@ -1,72 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> - -<head> - <title>CLI 1.2.0 Compiler Command Line Manual</title> - - <meta name="copyright" content="© $copyright$"/> - <meta name="keywords" content="cli,command,line,interface,compiler,c++"/> - <meta name="description" content="CLI Compiler Command Line Manual"/> - - <link rel="stylesheet" type="text/css" href="default.css" /> - -<style type="text/css"> - - #synopsis { - list-style-type: none; - } - - #synopsis li { - padding-top : 0.0em; - padding-bottom : 0.0em; - } - - .options { - margin: 1em 0 1em 0; - } - - .options dt { - margin: 1em 0 0 0; - } - - .options dd { - margin: .1em 0 0 4.5em; - } - -</style> -</head> - -<body> -<div id="container"> - <div id="content"> - - <h1>NAME</h1> - - <p>cli - command line interface compiler for C++</p> - - <h1>SYNOPSIS</h1> - - <dl id="synopsis"> - <dt><code><b>cli</b> [<i>options</i>] <i>file</i></code></dt> - </dl> - - <h1>DESCRIPTION</h1> - - <p><code><b>cli</b></code> 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 - <code><b>name.cli</b></code> the following is generated. By - default or if the <code><b>--generate-cxx</b></code> option is - specified, the following C++ files are generated: - <code><b>name.hxx</b></code> (header file), <code><b>name.ixx</b></code> - (inline file, generated unless the <code><b>--suppress-inline</b></code> - option is specified), and <code><b>name.cxx</b></code> (source file). - If the <code><b>--generate-html</b></code> option is specified, then - the <code><b>name.html</b></code> HTML documentation file is generated. - If the <code><b>--generate-man</b></code> option is specified, then - the <code><b>name.1</b></code> man page file is generated. When - <code><b>--generate-html</b></code> or <code><b>--generate-man</b></code> - is specified, the <code><b>--stdout</b></code> option can be used to - redirect the output to STDOUT instead of a file.</p> - - <h1>OPTIONS</h1> 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 diff --git a/doc/cli.xhtml b/doc/cli.xhtml deleted file mode 100644 index efd8337..0000000 --- a/doc/cli.xhtml +++ /dev/null @@ -1,568 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> - -<head> - <title>CLI 1.2.0 Compiler Command Line Manual</title> - - <meta name="copyright" content="© 2009-2020 Code Synthesis Tools CC"/> - <meta name="keywords" content="cli,command,line,interface,compiler,c++"/> - <meta name="description" content="CLI Compiler Command Line Manual"/> - - <link rel="stylesheet" type="text/css" href="default.css" /> - -<style type="text/css"> - - #synopsis { - list-style-type: none; - } - - #synopsis li { - padding-top : 0.0em; - padding-bottom : 0.0em; - } - - .options { - margin: 1em 0 1em 0; - } - - .options dt { - margin: 1em 0 0 0; - } - - .options dd { - margin: .1em 0 0 4.5em; - } - -</style> -</head> - -<body> -<div id="container"> - <div id="content"> - - <h1>NAME</h1> - - <p>cli - command line interface compiler for C++</p> - - <h1>SYNOPSIS</h1> - - <dl id="synopsis"> - <dt><code><b>cli</b> [<i>options</i>] <i>file</i></code></dt> - </dl> - - <h1>DESCRIPTION</h1> - - <p><code><b>cli</b></code> 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 - <code><b>name.cli</b></code> the following is generated. By - default or if the <code><b>--generate-cxx</b></code> option is - specified, the following C++ files are generated: - <code><b>name.hxx</b></code> (header file), <code><b>name.ixx</b></code> - (inline file, generated unless the <code><b>--suppress-inline</b></code> - option is specified), and <code><b>name.cxx</b></code> (source file). - If the <code><b>--generate-html</b></code> option is specified, then - the <code><b>name.html</b></code> HTML documentation file is generated. - If the <code><b>--generate-man</b></code> option is specified, then - the <code><b>name.1</b></code> man page file is generated. When - <code><b>--generate-html</b></code> or <code><b>--generate-man</b></code> - is specified, the <code><b>--stdout</b></code> option can be used to - redirect the output to STDOUT instead of a file.</p> - - <h1>OPTIONS</h1> - <dl class="options"> - <dt><code><b>--help</b></code></dt> - <dd>Print usage information and exit.</dd> - - <dt><code><b>--version</b></code></dt> - <dd>Print version and exit.</dd> - - <dt><code><b>--include-path</b></code>|<code><b>-I</b></code> <code><i>dir</i></code></dt> - <dd>Search <code><i>dir</i></code> for bracket-included - (<code><b><></b></code>) options files.</dd> - - <dt><code><b>--output-dir</b></code>|<code><b>-o</b></code> <code><i>dir</i></code></dt> - <dd>Write the generated files to <code><i>dir</i></code> instead of the - current directory.</dd> - - <dt><code><b>--std</b></code> <code><i>version</i></code></dt> - <dd>Specify the C++ standard that should be used during compilation. Valid - values are <code><b>c++98</b></code> (default), <code><b>c++11</b></code>, - and <code><b>c++14</b></code>.</dd> - - <dt><code><b>--generate-modifier</b></code></dt> - <dd>Generate option value modifiers in addition to accessors.</dd> - - <dt><code><b>--generate-specifier</b></code></dt> - <dd>Generate functions for determining whether the option was specified on - the command line.</dd> - - <dt><code><b>--generate-parse</b></code></dt> - <dd>Generate <code><b>parse()</b></code> 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.</dd> - - <dt><code><b>--generate-merge</b></code></dt> - <dd>Generate <code><b>merge()</b></code> 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 <code><b>--generate-specifier</b></code>.</dd> - - <dt><code><b>--generate-description</b></code></dt> - <dd>Generate the option description list that can be examined at - runtime.</dd> - - <dt><code><b>--generate-file-scanner</b></code></dt> - <dd>Generate the <code><b>argv_file_scanner</b></code> implementation. - This scanner is capable of reading command line arguments from the - <code><b>argv</b></code> array as well as files specified with command - line options.</dd> - - <dt><code><b>--generate-vector-scanner</b></code></dt> - <dd>Generate the <code><b>vector_scanner</b></code> implementation. This - scanner is capable of reading command line arguments from - <code><b>vector<string></b></code>.</dd> - - <dt><code><b>--generate-group-scanner</b></code></dt> - <dd>Generate the <code><b>group_scanner</b></code> implementation. This - scanner supports grouping of arguments (usually options) to apply only to - a certain argument. - - <p>Groups can be specified before (leading) and/or after (trailing) the - argument they apply to. A leading group starts with - '<code><b>{</b></code>' and ends with '<code><b>}+</b></code>' while a - trailing group starts with '<code><b>+{</b></code>' and ends with - '<code><b>}</b></code>'. For example:</p> - - <pre>{ --foo --bar }+ arg # 'arg' with '--foo' '--bar' -arg +{ fox=1 baz=2 } # 'arg' with 'fox=1' 'baz=2'</pre> - - <p>Multiple leading and/or trailing groups can be specified for the same - argument. For example:</p> - - <pre>{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'</pre> - - <p>Note that the group applies to a single argument only. For example:</p> - - <pre>{ --foo }+ arg1 arg2 +{ --bar } # 'arg1' with '--foo' and - # 'arg2' with '--bar'</pre> - - <p>The group separators ('<code><b>{</b></code>', - '<code><b>}+'</b></code>, 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:</p> - - <pre>{--foo}+ arg # '{--foo}+' ... -arg+{ --foo } # 'arg+{' ...</pre> - - <p>If one of the group separators needs to be specified as an argument - verbatim, then it must be escaped with '<code><b>\</b></code>'. For - example:</p> - - <pre>} # error: unexpected group separator -}x # '}x' -\} # '}' -{ \}+ }+ arg # 'arg' with '}+'</pre></dd> - - <dt><code><b>--suppress-inline</b></code></dt> - <dd>Generate all functions non-inline. By default simple functions are - made inline. This option suppresses creation of the inline file.</dd> - - <dt><code><b>--suppress-cli</b></code></dt> - <dd>Do not generate the CLI support types (scanners, parser, etc). - Normally, the support types are generated unless another - <code><b>.cli</b></code> was included, in which case the support types are - expected to be provided by its generated code.</dd> - - <dt><code><b>--cli-namespace</b></code> <code><i>ns</i></code></dt> - <dd>Generate the CLI support types in the <code><i>ns</i></code> namespace - (<code><b>cli</b></code> by default). The namespace can be nested, for - example <code><b>details::cli</b></code>. If the namespace is empty, then - the support types are generated in the global namespace.</dd> - - <dt><code><b>--ostream-type</b></code> <code><i>type</i></code></dt> - <dd>Output stream type instead of the default - <code><b>std::ostream</b></code> that should be used to print usage and - exception information.</dd> - - <dt><code><b>--generate-cxx</b></code></dt> - <dd>Generate C++ code. If neither <code><b>--generate-man</b></code>, - <code><b>--generate-html</b></code>, nor - <code><b>--generate-txt</b></code> is specified, this mode is assumed by - default.</dd> - - <dt><code><b>--generate-man</b></code></dt> - <dd>Generate documentation in the man page format.</dd> - - <dt><code><b>--generate-html</b></code></dt> - <dd>Generate documentation in the HTML format.</dd> - - <dt><code><b>--generate-txt</b></code></dt> - <dd>Generate documentation in the plain text format, similar to - usage.</dd> - - <dt><code><b>--stdout</b></code></dt> - <dd>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.</dd> - - <dt><code><b>--suppress-undocumented</b></code></dt> - <dd>Suppress the generation of documentation entries for undocumented - options.</dd> - - <dt><code><b>--suppress-usage</b></code></dt> - <dd>Suppress the generation of the usage printing code.</dd> - - <dt><code><b>--long-usage</b></code></dt> - <dd>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.</dd> - - <dt><code><b>--short-usage</b></code></dt> - <dd>If specified together with <code><b>--long-usage</b></code>, generate - both short and long usage versions. In this mode, the long usage printing - function is called <code><b>print_long_usage()</b></code> and in its - implementation the long documentation string is always used, even if the - short version is provided.</dd> - - <dt><code><b>--page-usage</b></code> <code><i>name</i></code></dt> - <dd>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). - - <p>The <code><i>name</i></code> 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:</p> - - <pre>--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</pre> - - <p>If both <code><b>--long-usage</b></code> and - <code><b>--short-usage</b></code> options are specified, then the long - usage function has the <code><b>*long_usage()</b></code> suffix.</p></dd> - - <dt><code><b>--option-length</b></code> <code><i>len</i></code></dt> - <dd>Indent option descriptions <code><i>len</i></code> 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.</dd> - - <dt><code><b>--ansi-color</b></code></dt> - <dd>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 - <code><b>less(1)</b></code>, it will display them correctly.</dd> - - <dt><code><b>--exclude-base</b></code></dt> - <dd>Exclude base class information from usage and documentation.</dd> - - <dt><code><b>--include-base-last</b></code></dt> - <dd>Include base class information after derived for usage and - documentation. By default, base classes are included first.</dd> - - <dt><code><b>--class-doc</b></code> <code><i>name</i></code>=<code><i>kind</i></code></dt> - <dd>Specify the documentation <code><i>kind</i></code> that should be used - for the options class <code><i>name</i></code>. The - <code><i>name</i></code> value should be a fully-qualified class name, for - example, <code><b>app::options</b></code>. The <code><i>kind</i></code> - value can be <code><b>short</b></code>, <code><b>long</b></code>, - <code><b>exclude</b></code>, or <code><b>exclude-base</b></code>. If the - value is <code><b>exclude</b></code>, then the class documentation is - excluded from usage and man/HTML/text output. If it is - <code><b>exclude-base</b></code>, then it is only excluded when used as a - base. For usage, the <code><b>short</b></code> and - <code><b>long</b></code> values determine which usage function will be - called when the class is used as base or as part of the page usage (see - <code><b>--page-usage</b></code>). For man/HTML/text, these values - determine which documentation strings are used in the output.</dd> - - <dt><code><b>--class</b></code> <code><i>name</i></code></dt> - <dd>Generate the man page, HTML, or text documentation only for the - options class <code><i>name</i></code>. The <code><i>name</i></code> value - should be a fully-qualified options class name, for example, - <code><b>app::options</b></code>. 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.</dd> - - <dt><code><b>--docvar</b></code>|<code><b>-v</b></code> <code><i>name</i></code>=<code><i>val</i></code></dt> - <dd>Set documentation variable <code><i>name</i></code> to the value - <code><i>val</i></code>. Documentation variables can be substituted in - prologues and epilogues (see <code><b>--*-prologue*</b></code> and - <code><b>--*-epilogue*</b></code> options) using the - <code><b>$</b></code><code><i>name</i></code><code><b>$</b></code> - expansion syntax (use <code><b>$$</b></code> to escape expansion). They - can also be defined in <code><b>.cli</b></code> files using the - <code>"\<code><i>name</i></code>=<code><i>val</i></code>"</code> - syntax.</dd> - - <dt><code><b>--link-regex</b></code> <code><i>regex</i></code></dt> - <dd>Add <code><i>regex</i></code> 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 - <code><b>/</b><i>pattern</i><b>/</b><i>replacement</i><b>/</b></code>. Any - character can be used as a delimiter instead of '<code><b>/</b></code>' - and the delimiter can be escaped inside <code><i>pattern</i></code> and - <code><i>replacement</i></code> with a backslash (<code><b>\</b></code>). - 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 - <code><b>--link-regex-trace</b></code> option to debug link - transformation.</dd> - - <dt><code><b>--link-regex-trace</b></code></dt> - <dd>Trace the process of applying regular expressions specified with the - <code><b>--link-regex</b></code> option. Use this option to find out why - your regular expressions don't do what you expected them to do.</dd> - - <dt><code><b>--html-heading-map</b></code> <code><i>c</i></code>=<code><i>h</i></code></dt> - <dd>Map CLI heading <code><i>c</i></code> (valid values: - '<code><b>H</b></code>', '<code><b>0</b></code>', '<code><b>1</b></code>', - '<code><b>h</b></code>', and '<code><b>2</b></code>') to HTML heading - <code><i>h</i></code> (for example, '<code><b>h1</b></code>', - '<code><b>h2</b></code>', etc).</dd> - - <dt><code><b>--omit-link-check</b></code></dt> - <dd>Don't check that local fragment link references (\l{#ref ...}) resolve - to ids.</dd> - - <dt><code><b>--hxx-prologue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the beginning of the generated C++ - header file.</dd> - - <dt><code><b>--ixx-prologue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the beginning of the generated C++ - inline file.</dd> - - <dt><code><b>--cxx-prologue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the beginning of the generated C++ - source file.</dd> - - <dt><code><b>--man-prologue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the beginning of the generated man - page file.</dd> - - <dt><code><b>--html-prologue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the beginning of the generated HTML - file.</dd> - - <dt><code><b>--txt-prologue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the beginning of the generated text - file.</dd> - - <dt><code><b>--hxx-epilogue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the end of the generated C++ header - file.</dd> - - <dt><code><b>--ixx-epilogue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the end of the generated C++ inline - file.</dd> - - <dt><code><b>--cxx-epilogue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the end of the generated C++ source - file.</dd> - - <dt><code><b>--man-epilogue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the end of the generated man page - file.</dd> - - <dt><code><b>--html-epilogue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the end of the generated HTML - file.</dd> - - <dt><code><b>--txt-epilogue</b></code> <code><i>text</i></code></dt> - <dd>Insert <code><i>text</i></code> at the end of the generated text - file.</dd> - - <dt><code><b>--hxx-prologue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the beginning of the - generated C++ header file.</dd> - - <dt><code><b>--ixx-prologue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the beginning of the - generated C++ inline file.</dd> - - <dt><code><b>--cxx-prologue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the beginning of the - generated C++ source file.</dd> - - <dt><code><b>--man-prologue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the beginning of the - generated man page file.</dd> - - <dt><code><b>--html-prologue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the beginning of the - generated HTML file.</dd> - - <dt><code><b>--txt-prologue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the beginning of the - generated text file.</dd> - - <dt><code><b>--hxx-epilogue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the end of the - generated C++ header file.</dd> - - <dt><code><b>--ixx-epilogue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the end of the - generated C++ inline file.</dd> - - <dt><code><b>--cxx-epilogue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the end of the - generated C++ source file.</dd> - - <dt><code><b>--man-epilogue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the end of the - generated man page file.</dd> - - <dt><code><b>--html-epilogue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the end of the - generated HTML file.</dd> - - <dt><code><b>--txt-epilogue-file</b></code> <code><i>file</i></code></dt> - <dd>Insert the content of <code><i>file</i></code> at the end of the - generated text file.</dd> - - <dt><code><b>--output-prefix</b></code> <code><i>prefix</i></code></dt> - <dd>Add <code><i>prefix</i></code> at the beginning of the generated - output file name(s).</dd> - - <dt><code><b>--output-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Add <code><i>suffix</i></code> at the end of the generated output file - name(s). Note that it is added before any file type-specific suffixes; see - <code><b>--*-suffix</b></code> below.</dd> - - <dt><code><b>--hxx-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Use <code><i>suffix</i></code> instead of the default - <code><b>.hxx</b></code> to construct the name of the generated header - file.</dd> - - <dt><code><b>--ixx-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Use <code><i>suffix</i></code> instead of the default - <code><b>.ixx</b></code> to construct the name of the generated inline - file.</dd> - - <dt><code><b>--cxx-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Use <code><i>suffix</i></code> instead of the default - <code><b>.cxx</b></code> to construct the name of the generated source - file.</dd> - - <dt><code><b>--man-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Use <code><i>suffix</i></code> instead of the default - <code><b>.1</b></code> to construct the name of the generated man page - file.</dd> - - <dt><code><b>--html-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Use <code><i>suffix</i></code> instead of the default - <code><b>.html</b></code> to construct the name of the generated HTML - file.</dd> - - <dt><code><b>--txt-suffix</b></code> <code><i>suffix</i></code></dt> - <dd>Use <code><i>suffix</i></code> instead of the default - <code><b>.txt</b></code> to construct the name of the generated text - file.</dd> - - <dt><code><b>--option-prefix</b></code> <code><i>prefix</i></code></dt> - <dd>Use <code><i>prefix</i></code> instead of the default - '<code><b>-</b></code>' 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.</dd> - - <dt><code><b>--option-separator</b></code> <code><i>sep</i></code></dt> - <dd>Use <code><i>sep</i></code> instead of the default - '<code><b>--</b></code>' 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.</dd> - - <dt><code><b>--keep-separator</b></code></dt> - <dd>Leave the option separator in the scanner. This is primarily useful - for incremental option parsing.</dd> - - <dt><code><b>--no-combined-flags</b></code></dt> - <dd>Disable support for combining multiple single-character flags into a - single argument (the <code><b>-xyz</b></code> form that is equivalent to - <code><b>-x</b></code> <code><b>-y</b></code> <code><b>-z</b></code>). An - argument is considered a combination of flags if it starts with a single - option prefix (<code><b>--option-prefix</b></code>) 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.</dd> - - <dt><code><b>--no-combined-values</b></code></dt> - <dd>Disable support for combining an option and its value into a single - argument with the assignment sign (the - <code><i>option</i><b>=</b><i>value</i></code> form). This functionality - requires a non-empty option prefix - (<code><b>--option-prefix</b></code>).</dd> - - <dt><code><b>--include-with-brackets</b></code></dt> - <dd>Use angle brackets (<code><b><></b></code>) instead of quotes - (<code><b>""</b></code>) in the generated <code><b>#include</b></code> - directives.</dd> - - <dt><code><b>--include-prefix</b></code> <code><i>prefix</i></code></dt> - <dd>Add <code><i>prefix</i></code> to the generated - <code><b>#include</b></code> directive paths.</dd> - - <dt><code><b>--guard-prefix</b></code> <code><i>prefix</i></code></dt> - <dd>Add <code><i>prefix</i></code> 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.</dd> - - <dt><code><b>--reserved-name</b></code> <code><i>name</i></code>=<code><i>rep</i></code></dt> - <dd>Add <code><i>name</i></code> with an optional <code><i>rep</i></code> - 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.</dd> - - <dt><code><b>--options-file</b></code> <code><i>file</i></code></dt> - <dd>Read additional options from <code><i>file</i></code>. Each option - should appear on a separate line optionally followed by space or equal - sign (<code><b>=</b></code>) and an option value. Empty lines and lines - starting with <code><b>#</b></code> are ignored. Option values can be - enclosed in double (<code><b>"</b></code>) or single - (<code><b>'</b></code>) 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 <code><b>'"x"'</b></code>. Non-leading and - non-trailing quotes are interpreted as being part of the option value. - - <p>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 <code><b>--options-file</b></code> option is specified except - that the shell escaping and quoting is not required. Repeat this option to - specify more than one options file.</p></dd> - </dl> - - <h1>DIAGNOSTICS</h1> - - <p>If the input file is not a valid CLI definition, <code><b>cli</b></code> - will issue diagnostic messages to STDERR and exit with non-zero exit - code.</p> - - <h1>BUGS</h1> - - <p>Send bug reports to the - <a href="mailto:cli-users@codesynthesis.com">cli-users@codesynthesis.com</a> mailing list.</p> - - </div> - <div id="footer"> - Copyright © 2009-2020 Code Synthesis Tools CC. - - <div id="terms"> - Permission is granted to copy, distribute and/or modify this - document under the terms of the - <a href="http://www.codesynthesis.com/licenses/mit.txt">MIT License</a>. - </div> - </div> -</div> -</body> -</html> diff --git a/doc/default.css b/doc/default.css deleted file mode 100644 index c73bb8d..0000000 --- a/doc/default.css +++ /dev/null @@ -1,322 +0,0 @@ -html { - margin : 0; - padding : 0; - background : white; -} - -body { - font-family : "Lucida Grande", Verdana, "Bitstream Vera Sans", sans-serif; - font-weight : normal; - font-size : 13px; - line-height : 19px; - - color : black; - - margin : 0 2em 0 2em; - padding : 0; -} - - -body { - min-width: 40em; -} - -#container { - max-width : 46em; - margin : 0 auto; - padding : 0 1em 0 1em; -} - - - -/* - * Footer - * - */ -#footer { - color : #3a84a7; - - padding : 1em 0 0.5em 0; - - font-size : 10px; - line-height : 15px; - - text-align: center; -} - -#footer a:link, #footer a:visited { - - color:#1d6699; - text-decoration: underline; -} - -#footer a { - margin-left: 0.7em; - margin-right: 0.7em; -} - -#footer p { - padding: 0; - margin: 0.3em 0 0 0; -} - -/* Distribution terms. */ -#footer #terms { - text-align: justify; - - font-size : 110%; - font-family : monospace; - - padding : 1em 0 0.5em 0; -} - - -/* - * Content - * - */ - -#content { - padding : 0em 0.1em 0 1.3em; - margin : 1.4em 0 0 0; -} - -#content p, -#content ol, -#content ul, -#content dl { - text-align: justify; -} - -#content h1 { - margin-left: -0.89em; -} - -a:link { - color:#0536d2; -} - - -/* - * Headings - * - */ - -h1, h2, h3, h4, h5, h6 { - font-weight : 500; -} - -h1 { font-size : 155%; } -h2 { font-size : 130%; } -h3 { font-size : 125%; } -h4 { font-size : 110%; } -h5 { font-size : 106%; } -h6 { font-size : 100%; } - -h1 { margin : 1.8em 0 0.8em 0;} -h2 { margin-top : 1.4em;} -h3 { margin-top : 1em;} - -p.indent { - margin-left : 1.5em; -} - - -/* - * Fix for IE 5.5 table font problem - * - */ - -table { - font-size : 13px; -} - - -/* - * table of content - * - */ - -ul.toc li { - padding : .4em 0em 0em 0em; -} - - -/* Toc links don't need to show when they are visited. */ -.toc a:visited { - color:#0536d2; -} - - -/* - * lists - * - */ - - -/* list of links */ -ul.menu { - list-style-type : none; -} - -ul.menu li { - padding-top : 0.3em; - padding-bottom : 0.3em; -} - - - -/* @@ I should probably use child selector here */ -/* list with multiline list-elements */ -ul.multiline li, ol.multiline li, dl.multiline dd { - padding-top : 0.16em; - padding-bottom : 0.16em; - - font-size : 11px; - line-height : 15px; -} - - -/* C++ code snippet */ -pre.cxx { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - -/* CLI code snippet */ -pre.cli { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - -/* make code snippet */ -pre.make { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - -/* terminal output */ -pre.term { - margin-top : 0em; - margin-bottom : 2em; - - margin-left : 1em; -} - - -/* Images */ -div.center { - text-align: center; -} - -/* Document info. */ -#docinfo { - margin-top: 4em; - border-top: 1px dashed #000000; - font-size: 70%; -} - - -/* Footnote */ - -#footnote { - margin-top : 2.5em; -} - -#footnote hr, hr.footnote { - margin-left: 0; - margin-bottom: 0.6em; - width: 8em; - border-top: 1px solid #000000; - border-right: none; - border-bottom: none; - border-left: none; - -} - -#footnote ol { - margin-left: 0; - padding-left: 1.45em; -} - -#footnote li { - text-align : left; - font-size : 11px; - line-height : 15px; - - padding : .4em 0 .4em 0; -} - - -/* Normal table with borders, etc. */ - -table.std { - margin: 2em 0 2em 0; - - border-collapse : collapse; - border : 1px solid; - border-color : #000000; - - font-size : 11px; - line-height : 14px; -} - -table.std th, table.std td { - border : 1px solid; - padding : 0.6em 0.8em 0.6em 0.8em; -} - -table.std th { - background : #cde8f6; -} - -table.std td { - text-align: left; -} - - -/* - * "item | description" table. - * - */ - -table.description { - border-style : none; - border-collapse : separate; - border-spacing : 0; - - font-size : 13px; - - margin : 0.6em 0 0.6em 0; - padding : 0 0 0 0; -} - -table.description tr { - padding : 0 0 0 0; - margin : 0 0 0 0; -} - -table.description * td, table.description * th { - border-style : none; - margin : 0 0 0 0; - vertical-align : top; -} - -table.description * th { - font-weight : normal; - padding : 0.4em 1em 0.4em 0; - text-align : left; - white-space : nowrap; - background : none; -} - -table.description * td { - padding : 0.4em 0 0.4em 1em; - text-align : justify; -} diff --git a/doc/doc.sh b/doc/doc.sh deleted file mode 100755 index df577cc..0000000 --- a/doc/doc.sh +++ /dev/null @@ -1,78 +0,0 @@ -#! /usr/bin/env bash - -version=1.2.0-b.6 - -trap 'exit 1' ERR -set -o errtrace # Trap in functions. - -function info () { echo "$*" 1>&2; } -function error () { info "$*"; exit 1; } - -date="$(date +"%B %Y")" -copyright="$(sed -n -re 's%^Copyright \(c\) (.+)\.$%\1%p' ../LICENSE)" - -while [ $# -gt 0 ]; do - case $1 in - --clean) - rm -f cli.xhtml cli.1 - rm -f guide/cli-guide.ps guide/cli-guide.pdf - exit 0 - ;; - *) - error "unexpected $1" - ;; - esac -done - -function compile () # <input-name> <output-name> -{ - local i=$1; shift - local o=$1; shift - - # Use a bash array to handle empty arguments. - # - local ops=() - while [ $# -gt 0 ]; do - ops=("${ops[@]}" "$1") - shift - done - - # --html-suffix .xhtml - cli -I .. \ --v project="cli" \ --v version="$version" \ --v date="$date" \ --v copyright="$copyright" \ -"${ops[@]}" --generate-html --stdout \ ---html-prologue-file cli-prologue.xhtml \ ---html-epilogue-file cli-epilogue.xhtml \ -"../cli/$i.cli" >"$o.xhtml" - - # --man-suffix .1 - cli -I .. \ --v project="cli" \ --v version="$version" \ --v date="$date" \ --v copyright="$copyright" \ -"${ops[@]}" --generate-man --stdout \ ---man-prologue-file cli-prologue.1 \ ---man-epilogue-file cli-epilogue.1 \ -"../cli/$i.cli" >"$o.1" -} - -compile options cli --suppress-undocumented - -# Manual. -# - -#function compile_doc () -#{ -# html2ps -f doc.html2ps:a4.html2ps -o "$n-a4.ps" "$n.xhtml" -# ps2pdf14 -sPAPERSIZE=a4 -dOptimize=true -dEmbedAllFonts=true "$n-a4.ps" "$n-a4.pdf" -# -# html2ps -f doc.html2ps:letter.html2ps -o "$n-letter.ps" "$n.xhtml" -# ps2pdf14 -sPAPERSIZE=letter -dOptimize=true -dEmbedAllFonts=true "$n-letter.ps" "$n-letter.pdf" -#} - -html2ps -f guide/guide.html2ps -o guide/cli-guide.ps guide/index.xhtml -ps2pdf14 -dOptimize=true -dEmbedAllFonts=true guide/cli-guide.ps guide/cli-guide.pdf diff --git a/doc/guide/.gitignore b/doc/guide/.gitignore deleted file mode 100644 index 239cc7f..0000000 --- a/doc/guide/.gitignore +++ /dev/null @@ -1,2 +0,0 @@ -*.ps -*.pdf diff --git a/doc/guide/guide.html2ps b/doc/guide/guide.html2ps deleted file mode 100644 index a691002..0000000 --- a/doc/guide/guide.html2ps +++ /dev/null @@ -1,63 +0,0 @@ -@html2ps { - option { - toc: hb; - colour: 1; - hyphenate: 1; - titlepage: 1; - } - - datefmt: "%B %Y"; - - titlepage { - content: " -<div align=center> - <h1><big>CLI Language</big></h1> - <h1><big>Getting Started Guide</big></h1> - <h1> </h1> - <h1> </h1> - <h1> </h1> - <h1> </h1> - <h1> </h1> - <h1> </h1> -</div> - <p>Copyright © 2009-2020 Code Synthesis Tools CC.</p> - - <p>Permission is granted to copy, distribute, and/or modify this document - under the terms of the - <a href='http://www.codesynthesis.com/licenses/mit.txt'>MIT License</a>. - </p> - - <p>This document is available in the following formats: - <a href='http://www.codesynthesis.com/projects/cli/doc/guide/index.xhtml'>XHTML</a>, - <a href='http://www.codesynthesis.com/projects/cli/doc/guide/cli-guide.pdf'>PDF</a>, and - <a href='http://www.codesynthesis.com/projects/cli/doc/guide/cli-guide.ps'>PostScript</a>.</p>"; - } - - toc { - indent: 2em; - } - - header { - odd-right: $H; - even-left: $H; - } - - footer { - odd-left: $D; - odd-center: $T; - odd-right: $N; - - even-left: $N; - even-center: $T; - even-right: $D; - } -} - -body { - font-size: 12pt; - text-align: justify; -} - -pre { - font-size: 10pt; -} diff --git a/doc/guide/index.xhtml b/doc/guide/index.xhtml deleted file mode 100644 index 675db03..0000000 --- a/doc/guide/index.xhtml +++ /dev/null @@ -1,1336 +0,0 @@ -<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> -<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"> - -<head> - <title>CLI Language Getting Started Guide</title> - - <meta name="copyright" content="© 2009-2020 Code Synthesis Tools CC"/> - <meta name="keywords" content="cli,command,line,interface,language,c++"/> - <meta name="description" content="CLI Language Getting Started Guide"/> - - <link rel="stylesheet" type="text/css" href="../default.css" /> - -<style type="text/css"> - pre { - padding : 0 0 0 0em; - margin : 0em 0em 0em 0; - - font-size : 102% - } - - body { - min-width: 48em; - } - - h1 { - font-weight: bold; - font-size: 200%; - line-height: 1.2em; - } - - h2 { - font-weight : bold; - font-size : 150%; - - padding-top : 0.8em; - } - - h3 { - font-size : 140%; - padding-top : 0.8em; - } - - /* Adjust indentation for three levels. */ - #container { - max-width: 48em; - } - - #content { - padding: 0 0.1em 0 4em; - /*background-color: red;*/ - } - - #content h1 { - margin-left: -2.06em; - } - - #content h2 { - margin-left: -1.33em; - } - - /* Title page */ - - #titlepage { - padding: 2em 0 1em 0; - border-bottom: 1px solid black; - } - - #titlepage .title { - font-weight: bold; - font-size: 200%; - text-align: center; - } - - #titlepage #first-title { - padding: 1em 0 0.4em 0; - } - - #titlepage #second-title { - padding: 0.4em 0 2em 0; - } - - /* Lists */ - ul.list li, ol.list li { - padding-top : 0.3em; - padding-bottom : 0.3em; - } - - dl dt { - padding : 0.8em 0 0 0; - } - - /* TOC */ - table.toc { - border-style : none; - border-collapse : separate; - border-spacing : 0; - - margin : 0.2em 0 0.2em 0; - padding : 0 0 0 0; - } - - table.toc tr { - padding : 0 0 0 0; - margin : 0 0 0 0; - } - - table.toc * td, table.toc * th { - border-style : none; - margin : 0 0 0 0; - vertical-align : top; - } - - table.toc * th { - font-weight : normal; - padding : 0em 0.1em 0em 0; - text-align : left; - white-space : nowrap; - } - - table.toc * table.toc th { - padding-left : 1em; - } - - table.toc * td { - padding : 0em 0 0em 0.7em; - text-align : left; - } - - /* Sample options documentation. */ - .options dt { - padding-top : 0.4em; - } - - .options dd { - padding-top : 0.1em; - padding-bottom : 0.4em; - padding-left : 1.4em; - } -</style> - - -</head> - -<body> -<div id="container"> - <div id="content"> - - <div class="noprint"> - - <div id="titlepage"> - <div class="title" id="first-title">CLI Language</div> - <div class="title" id="second-title">Getting Started Guide</div> - - <p>Copyright © 2009-2020 Code Synthesis Tools CC.</p> - - <p>Permission is granted to copy, distribute, and/or modify this document - under the terms of the - <a href="http://www.codesynthesis.com/licenses/mit.txt">MIT License</a>. - </p> - - <p>This document is available in the following formats: - <a href="http://www.codesynthesis.com/projects/cli/doc/guide/index.xhtml">XHTML</a>, - <a href="http://www.codesynthesis.com/projects/cli/doc/guide/cli-guide.pdf">PDF</a>, and - <a href="http://www.codesynthesis.com/projects/cli/doc/guide/cli-guide.ps">PostScript</a>.</p> - - </div> - -<h1>Table of Contents</h1> - - <table class="toc"> - <tr> - <th>1</th><td><a href="#1">Introduction</a></td> - </tr> - - <tr> - <th>2</th><td><a href="#2">Hello World Example</a> - <table class="toc"> - <tr><th>2.1</th><td><a href="#2.1">Defining Command Line Interface</a></td></tr> - <tr><th>2.2</th><td><a href="#2.2">Translating CLI Definitions to C++</a></td></tr> - <tr><th>2.3</th><td><a href="#2.3">Implementing Application Logic</a></td></tr> - <tr><th>2.4</th><td><a href="#2.4">Compiling and Running</a></td></tr> - <tr><th>2.5</th><td><a href="#2.5">Adding Documentation</a></td></tr> - </table> - </td> - </tr> - - <tr> - <th>3</th><td><a href="#3">CLI Language</a> - <table class="toc"> - <tr><th>3.1</th><td><a href="#3.1">Options Class Definition</a></td></tr> - <tr><th>3.2</th><td><a href="#3.2">Option Definition</a></td></tr> - <tr><th>3.3</th><td><a href="#3.3">Option Documentation</a></td></tr> - <tr><th>3.4</th><td><a href="#3.4">Include Directive</a></td></tr> - <tr><th>3.5</th><td><a href="#3.5">Namespace Definition</a></td></tr> - </table> - </td> - </tr> - </table> - </div> - - <!-- Introduction --> - - <h1><a name="1">1 Introduction</a></h1> - - <p>Command Line Interface (CLI) definition language is a domain-specific - language (DSL) for defining command line interfaces of C++ programs. - CLI definitions are automatically translated to C++ classes using the - CLI compiler. These classes implement parsing of the command - line arguments and provide a convenient and type-safe interface - for accessing the extracted data.</p> - - <p>Beyond this guide, you may also find the following sources of - information useful:</p> - - <ul class="list"> - <li><a href="http://www.codesynthesis.com/projects/cli/doc/cli.xhtml">CLI - Compiler Command Line Manual</a></li> - - <li>The <code>INSTALL</code> file in the CLI distribution provides build - instructions for various platforms.</li> - - <li>The <code>examples/</code> directory in the CLI distribution contains - a collection of examples and a README file with an overview of each - example.</li> - - <li>The <a href="http://www.codesynthesis.com/mailman/listinfo/cli-users">cli-users</a> - mailing list is the place to ask technical questions about the CLI language - and compiler. Furthermore, the - <a href="http://www.codesynthesis.com/pipermail/cli-users/">cli-users mailing - list archives</a> may already have answers to some of your questions.</li> - </ul> - - - <!-- Hello World Example --> - - - <h1><a name="2">2 Hello World Example</a></h1> - - <p>In this chapter we will examine how to define a very simple command - line interface in CLI, translate this interface to C++, and use the - result in an application. The code presented in this chapter is based - on the <code>hello</code> example which can be found in the - <code>examples/hello/</code> directory of the CLI distribution.</p> - - <h2><a name="2.1">2.1 Defining Command Line Interface</a></h2> - - <p>Our <code>hello</code> application is going to print a greeting - line for each name supplied on the command line. It will also - support two command line options, <code>--greeting</code> - and <code>--exclamations</code>, that can be used to - customize the greeting line. The <code>--greeting</code> - option allows us to specify the greeting phrase instead of the - default <code>"Hello"</code>. The <code>--exclamations</code> - option is used to specify how many exclamation marks should - be printed at the end of each greeting. We will also support - the <code>--help</code> option which triggers printing of the - usage information.</p> - - <p>We can now write a description of the above command line interface - in the CLI language and save it into <code>hello.cli</code>:</p> - - <pre class="cli"> -include <string>; - -class options -{ - bool --help; - std::string --greeting = "Hello"; - unsigned int --exclamations = 1; -}; - </pre> - - <p>While some details in the above code fragment might not be completely - clear (the CLI language is covered in greater detail in the next - chapter), it should be easy to connect declarations in - <code>hello.cli</code> to the command line interface described in - the preceding paragraphs. The next step is to translate this - interface specification to C++.</p> - - <h2><a name="2.2">2.2 Translating CLI Definitions to C++</a></h2> - - <p>Now we are ready to translate <code>hello.cli</code> to C++. - To do this we invoke the CLI compiler from a terminal (UNIX) or - a command prompt (Windows): - </p> - - <pre class="term"> -$ cli hello.cli - </pre> - - <p>This invocation of the CLI compiler produces three C++ files: - <code>hello.hxx</code> <code>hello.ixx</code>, and - <code>hello.cxx</code>. You can change the file name extensions - for these files with the compiler command line options. See the - <a href="http://www.codesynthesis.com/projects/cli/doc/cli.xhtml">CLI - Compiler Command Line Manual</a> for more information.</p> - - <p>The following code fragment is taken from <code>hello.hxx</code>; it - should give you an idea about what gets generated:</p> - - <pre class="cxx"> -#include <string> - -class options -{ -public: - options (int argc, char** argv); - options (int argc, char** argv, int& end); - - // Option accessors. - // -public: - bool - help () const; - - const std::string& - greeting () const; - - unsigned int - exclamations () const; - -private: - .. -}; - </pre> - - <p>The <code>options</code> C++ class corresponds to the <code>options</code> - CLI class. For each option in this CLI class an accessor function is - generated inside the C++ class. The <code>options</code> C++ class also - defines a number of overloaded constructs that we can use to parse the - <code>argc/argv</code> array. Let's now see how we can use this generated - class to implement option parsing in our <code>hello</code> application.</p> - - <h2><a name="2.3">2.3 Implementing Application Logic</a></h2> - - <p>At this point we have everything we need to implement our - application:</p> - - <pre class="cxx"> -#include <iostream> -#include "hello.hxx" - -using namespace std; - -void -usage (ostream& os) -{ - os << "usage: driver [options] <names>" << endl - << "options:" << endl; - options::print_usage (os); -} - -int -main (int argc, char* argv[]) -{ - try - { - int end; // End of options. - options o (argc, argv, end); - - if (o.help ()) - { - usage (cout); - return 0; - } - - if (end == argc) - { - cerr << "no names provided" << endl; - usage (cerr); - return 1; - } - - // Print the greetings. - // - for (int i = end; i < argc; i++) - { - cout << o.greeting () << ", " << argv[i]; - - for (unsigned int j = 0; j < o.exclamations (); j++) - cout << '!'; - - cout << endl; - } - } - catch (const cli::exception& e) - { - cerr << e << endl; - usage (cerr); - return 1; - } -} -</pre> - - <p>At the beginning of our application we create the <code>options</code> - object which parses the command line. The <code>end</code> variable - contains the index of the first non-option argument. We then access - the option values as needed during the application execution. We also - catch and print <code>cli::exception</code> in case something goes - wrong, for example, an unknown option is specified or an option value - is invalid. - </p> - - <h2><a name="2.4">2.4 Compiling and Running</a></h2> - - <p>After saving our application from the previous section in - <code>driver.cxx</code>, we are ready to build and run our program. - On UNIX this can be done with the following commands:</p> - - <pre class="term"> -$ c++ -o driver driver.cxx hello.cxx - -$ ./driver world -Hello, world! - -$ ./driver --greeting Hi --exclamations 3 John Jane -Hi, John!!! -Hi, Jane!!! - </pre> - - <p>We can also test the error handling:</p> - - <pre class="term"> -$ ./driver -n 3 Jane -unknown option '-n' -usage: driver [options] <names> -options: ---help ---greeting <arg> ---exclamations <arg> - -$ ./driver --exclamations abc Jane -invalid value 'abc' for option '--exclamations' -usage: driver [options] <names> -options: ---help ---greeting <arg> ---exclamations <arg> - </pre> - - <h2><a name="2.5">2.5 Adding Documentation</a></h2> - - <p>As we have seen in the previous sections, the <code>options</code> - C++ class provides the <code>print_usage()</code> function which we - can use to display the application usage information. Right now this - information is very basic and does not include any description of - the purpose of each option:</p> - - <pre class="term"> -$ ./driver --help -usage: driver [options] <names> -options: ---help ---greeting <arg> ---exclamations <arg> - </pre> - - <p>To make the usage information more descriptive we can document each - option in the command line interface definition. This information can - also be used to automatically generate program documentation in various - formats, such as HTML and man page. For example:</p> - - <pre class="cli"> -include <string>; - -class options -{ - bool --help {"Print usage information and exit."}; - - std::string --greeting = "Hello" - { - "<text>", - "Use <text> as a greeting phrase instead of the default \"Hello\"." - }; - - unsigned int --exclamations = 1 - { - "<num>", - "Print <num> exclamation marks instead of 1 by default." - }; -}; - </pre> - - <p>If we now save this updated command line interface to - <code>hello.cli</code> and recompile our application, the usage - information printed by the program will look like this:</p> - - <pre class="term"> -usage: driver [options] <names> -options: ---help Print usage information and exit. ---greeting <text> Use <text> as a greeting phrase instead of the - default "Hello". ---exclamations <num> Print <num> exclamation marks instead of 1 by - default. - </pre> - - <p>We can also generate the program documentation in the HTML - (<code>--generate-html</code> CLI option) and man page - (<code>--generate-man</code> CLI option) formats. For example:</p> - - <pre class="term"> -$ cli --generate-html hello.cli - </pre> - - <p>The resulting <code>hello.html</code> file contains the following - documentation:</p> - -<dl class="options"> - <dt><code><b>--help</b></code></dt> - <dd>Print usage information and exit.</dd> - - <dt><code><b>--greeting</b></code> <i>text</i></dt> - <dd>Use <i>text</i> as a greeting phrase instead of the default "Hello".</dd> - - <dt><code><b>--exclamations</b></code> <i>num</i></dt> - <dd>Print <i>num</i> exclamation marks instead of 1 by default.</dd> - -</dl> - - <p>This HTML fragment can be combined with custom prologue and epilogue - to create a complete program documentation - (<code>--html-prologue/--html-epilogue</code> options for the HTML - output, <code>--man-prologue/--man-epilogue</code> options for the - man page output). For an example of such complete documentation see - the <a href="http://www.codesynthesis.com/projects/cli/doc/cli.xhtml">CLI - Compiler Command Line Manual</a> and the <code>cli(1)</code> man - page. For more information on the option documentation syntax, - see <a href="#3.3">Section 3.3, Option Documentation</a>.</p> - - <!-- CLI Language --> - - - <h1><a name="3">3 CLI Language</a></h1> - - <p>This chapter describes the CLI language and its mapping to C++. - A CLI file consists of zero or more <a href="#3.4">Include - Directives</a> followed by one or more <a href="#3.5">Namespace Definitions</a> - or <a href="#3.1">Option Class Definitions</a>. C and C++-style comments - can be used anywhere in the CLI file except in character and - string literals.</p> - - <h2><a name="3.1">3.1 Option Class Definition</a></h2> - -<p>The central part of the CLI language is <em>option class</em>. An - option class contains one or more <em>option</em> definitions, for - example:</p> - - <pre class="cli"> -class options -{ - bool --help; - int --compression; -}; - </pre> - - <p>If we translate the above CLI fragment to C++, we will get a C++ - class with the following interface:</p> - - <pre class="cli"> -class options -{ -public: - options (int& argc, - char** argv, - bool erase = false, - cli::unknown_mode opt_mode = cli::unknown_mode::fail, - cli::unknown_mode arg_mode = cli::unknown_mode::stop); - - options (int start, - int& argc, - char** argv, - bool erase = false, - cli::unknown_mode opt_mode = cli::unknown_mode::fail, - cli::unknown_mode arg_mode = cli::unknown_mode::stop); - - options (int& argc, - char** argv, - int& end, - bool erase = false, - cli::unknown_mode opt_mode = cli::unknown_mode::fail, - cli::unknown_mode arg_mode = cli::unknown_mode::stop); - - options (int start, - int& argc, - char** argv, - int& end, - bool erase = false, - cli::unknown_mode opt_mode = cli::unknown_mode::fail, - cli::unknown_mode arg_mode = cli::unknown_mode::stop); - - options (cli::scanner&, - cli::unknown_mode opt_mode = cli::unknown_mode::fail, - cli::unknown_mode arg_mode = cli::unknown_mode::stop); - - options (const options&); - - options& - operator= (const options&); - -public: - static void - print_usage (std::ostream&); - -public: - bool - help () const; - - int - compression () const; -}; - </pre> - - - <p>An option class is mapped to a C++ class with the same name. The - C++ class defines a set of public overloaded constructors, a public - copy constructor and an assignment operator, as well as a set of public - accessor functions and, if the <code>--generate-modifier</code> CLI - compiler option is specified, modifier functions corresponding to option - definitions. It also defines a public static <code>print_usage()</code> - function that can be used to print the usage information for the options - defined by the class.</p> - - <p>The <code>argc/argv</code> arguments in the overloaded constructors - are used to pass the command line arguments array, normally as passed - to <code>main()</code>. The <code>start</code> argument is used to - specify the position in the arguments array from which the parsing - should start. The constructors that don't have this argument, start - from position 1, skipping the executable name in <code>argv[0]</code>. - The <code>end</code> argument is used to return the position in - the arguments array where the parsing of options stopped. This is the - position of the first program argument, if any. If the <code>erase</code> - argument is <code>true</code>, then the recognized options and their - values are removed from the <code>argv</code> array and the - <code>argc</code> count is updated accordingly.</p> - - <p>The <code>opt_mode</code> and <code>arg_mode</code> arguments - specify the parser behavior when it encounters an unknown option - and argument, respectively. The <code>unknown_mode</code> type - is part of the generated CLI runtime support code. It has the - following interface:</p> - - <pre class="cxx"> -namespace cli -{ - class unknown_mode - { - public: - enum value - { - skip, - stop, - fail - }; - - unknown_mode (value v); - operator value () const; - }; -} - </pre> - - <p>If the mode is <code>skip</code>, the parser skips an unknown - option or argument and continue parsing. If the mode is - <code>stop</code>, the parser stops the parsing process. The - position of the unknown entity is stored in the <code>end</code> - argument. If the mode is <code>fail</code>, the parser throws the - <code>cli::unknown_option</code> or <code>cli::unknown_argument</code> - exception (described blow) on encountering an unknown option or argument, - respectively.</p> - - <p>Instead of the <code>argc/argv</code> arguments, the last overloaded - constructor accepts the <code>cli::scanner</code> object. It is part - of the generated CLI runtime support code and has the following - abstract interface:</p> - - <pre class="cxx"> -namespace cli -{ - class scanner - { - public: - virtual bool - more () = 0; - - virtual const char* - peek () = 0; - - virtual const char* - next () = 0; - - virtual void - skip () = 0; - }; -} - </pre> - - <p>The CLI runtime also provides two implementations of this interface: - <code>cli::argv_scanner</code> and <code>cli::argv_file_scanner</code>. - The first implementation is a simple scanner for the <code>argv</code> - array (it is used internally by all the other constructors) and has the - following interface:</p> - - <pre class="cxx"> -namespace cli -{ - class argv_scanner - { - public: - argv_scanner (int& argc, char** argv, bool erase = false); - argv_scanner (int start, int& argc, char** argv, bool erase = false); - - int - end () const; - - ... - }; -} - </pre> - - <p>The <code>cli::argv_file_scanner</code> implementation provides - support for reading command line arguments from the <code>argv</code> - array as well as files specified with command line options. It is - generated only if explicitly requested with the - <code>--generate-file-scanner</code> CLI compiler option and has - the following interface:</p> - - <pre class="cxx"> -namespace cli -{ - class argv_file_scanner - { - public: - argv_file_scanner (int& argc, - char** argv, - const std::string& option, - bool erase = false); - - argv_file_scanner (int start, - int& argc, - char** argv, - const std::string& option, - bool erase = false); - - struct option_info - { - // If search_func is not NULL, it is called, with the arg - // value as the second argument, to locate the options file. - // If it returns an empty string, then the file is ignored. - // - const char* option; - std::string (*search_func) (const char*, void* arg); - void* arg; - }; - - argv_file_scanner (int& argc, - char** argv, - const option_info* options, - std::size_t options_count, - bool erase = false); - - argv_file_scanner (int start, - int& argc, - char** argv, - const option_info* options, - std::size_t options_count, - bool erase = false); - ... - }; -} - </pre> - - <p>The <code>option</code> argument in the first two constructors and - the <code>options</code> and <code>options_count</code> arguments - in the last two are used to pass the option name(s) that should be - recognized as specifying the file containing additional options. - Such a file contains a set of options, each appearing on a - separate line optionally followed by space and an option value. Empty lines - and lines starting with <code>#</code> are ignored. Option values can - be enclosed in double (<code>"</code>) or single (<code>'</code>) - 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 - <code>'"x"'</code>. Non-leading and non-trailing quotes are interpreted - as being part of the option value.</p> - - <p>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 is specified, except that the shell escaping - and quoting is not required. Multiple files can be specified by including - several file options on the command line or inside other files.</p> - - <p>The parsing constructor (those with the <code>argc/argv</code> or - <code>cli::scanner</code> arguments) can throw the following exceptions: <code>cli::unknown_option</code>, - <code>cli::unknown_argument</code>, <code>cli::missing_value</code>, and - <code>cli::invalid_value</code>. The first two exceptions are thrown - on encountering unknown options and arguments, respectively, as - described above. The <code>missing_value</code> exception is thrown when - an option value is missing. The <code>invalid_value</code> exception is - thrown when an option value is invalid, for example, a non-integer value - is specified for an option of type <code>int</code>.</p> - - <p>Furthermore, all scanners (and thus the parsing constructors that - call them) can throw the <code>cli::eos_reached</code> exception - which indicates that one of the <code>peek()</code>, <code>next()</code>, - or <code>skip()</code> functions were called while <code>more()</code> - returns <code>false</code>. Catching this exception normally indicates an - error in an option parser implementation. The <code>argv_file_scanner</code> - class can also throw the <code>cli::file_io_failure</code> exception - which indicates that a file could not be opened or there was a reading - error as well as the <code>cli::unmatched_quote</code> exception - which indicates that an unmatched leading or trailing quote was - found in an option value.</p> - - <p>All CLI exceptions are derived from the common <code>cli::exception</code> - class which implements the polymorphic <code>std::ostream</code> insertion. - For example, if you catch the <code>cli::unknown_option</code> - exception as <code>cli::exception</code> and print it to - <code>std::cerr</code>, you will get the error message corresponding - to the <code>unknown_option</code> exception.</p> - - <p>The exceptions described above are part of the generated CLI runtime - support code and have the following interfaces:</p> - - <pre class="cxx"> -#include <exception> - -namespace cli -{ - class exception: public std::exception - { - public: - virtual void - print (std::ostream&) const = 0; - }; - - inline std::ostream& - operator<< (std::ostream& os, const exception& e) - { - e.print (os); - return os; - } - - class unknown_option: public exception - { - public: - unknown_option (const std::string& option); - - const std::string& - option () const; - - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; - - class unknown_argument: public exception - { - public: - unknown_argument (const std::string& argument); - - const std::string& - argument () const; - - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; - - class missing_value: public exception - { - public: - missing_value (const std::string& option); - - const std::string& - option () const; - - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; - - class invalid_value: public exception - { - public: - invalid_value (const std::string& option, - const std::string& value); - - const std::string& - option () const; - - const std::string& - value () const; - - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; - - class eos_reached: public exception - { - public: - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; - - class file_io_failure: public exception - { - public: - file_io_failure (const std::string& file); - - const std::string& - file () const; - - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; - - class unmatched_quote: public exception - { - public: - unmatched_quote (const std::string& argument); - - const std::string& - argument () const; - - virtual void - print (std::ostream&) const; - - virtual const char* - what () const throw (); - }; -} - </pre> - - - <h2><a name="3.2">3.2 Option Definition</a></h2> - -<p>An option definition consists of four components: <em>type</em>, - <em>name</em>, <em>default value</em>, and <em>documentation</em>. - An option type can be any C++ type as long as its string representation - can be parsed using the <code>std::istream</code> interface. If the option - type is user-defined then you will need to include its declaration using - the <a href="#3.4">Include Directive</a>.</p> - -<p>An option of a type other than <code>bool</code> is expected to - have a value. An option of type <code>bool</code> is treated as - a flag and does not have a value. That is, a mere presence of such - an option on the command line sets this option's value to - <code>true</code>.</p> - -<p>The name component specifies the option name as it will be entered - in the command line. A name can contain any number of aliases separated - by <code>|</code>. The C++ accessor and modifier function names are - derived from the first name by removing any leading special characters, - such as <code>-</code>, <code>/</code>, etc., and replacing special - characters in other places with underscores. For example, the following - option definition:</p> - - <pre class="cli"> -class options -{ - int --compression-level | --comp | -c; -}; - </pre> - - <p>Will result in the following accessor function:</p> - - <pre class="cli"> -class options -{ - int - compression_level () const; -}; - </pre> - - <p>While any option alias can be used on the command line to specify - this option's value.</p> - - <p>If the option name conflicts with one of the CLI language keywords, - it can be specified as a string literal:</p> - - <pre class="cli"> -class options -{ - bool "int"; -}; - </pre> - - <p>The following component of the option definition is the optional default - value. If the default value is not specified, then the option is - initialized with the default constructor. In particular, this means - that a <code>bool</code> option will be initialized to <code>false</code>, - an <code>int</code> option will be initialized to <code>0</code>, etc.</p> - - <p>Similar to C++ variable initialization, the default option value - can be specified using two syntactic forms: an assignment initialization - and constructor initialization. The two forms are equivalent except - that the constructor initialization can be used with multiple arguments, - for example:</p> - - <pre class="cli"> -include <string>; - -class options -{ - int -i1 = 5; - int -i2 (5); - - std::string -s1 = "John"; - std::string -s2 ("Mr John Doe", 8, 3); -}; - </pre> - - <p>The assignment initialization supports character, string, boolean, and - simple integer literals (including negative integers) as well - as identifiers. For more complex expressions use the constructor - initialization or wrap the expressions in parenthesis, for example:</p> - - <pre class="cli"> -include "constants.hxx"; // Defines default_value. - -class options -{ - int -a = default_value; - int -b (25 * 4); - int -c = (25 / default_value + 3); -}; - </pre> - - <p>By default, when an option is specified two or more times on the command - line, the last value overrides all the previous ones. However, a number - of standard C++ containers are handled differently to allow collecting - multiple option values or building key-value maps. These - containers are <code>std::vector</code>, <code>std::set</code>, and - <code>std::map</code>.</p> - - <p>When <code>std::vector</code> or <code>std::set</code> is specified - as an option type, all the values for this option are inserted into the - container in the order they are encountered. As a result, - <code>std::vector</code> will contain all the values, including - duplicates while <code>std::set</code> will contain all the unique - values. For example:</p> - - <pre class="cli"> -include <set>; -include <vector>; - -class options -{ - std::vector<int> --vector | -v; - std::set<int> --set | -s; -}; - </pre> - - <p>If we have a command line like this: - <code>-v 1 -v 2 -v 1 -s 1 -s 2 -s 1</code>, then the vector returned - by the <code>vector()</code> accessor function will contain three - elements: <code>1</code>, <code>2</code>, and <code>1</code> while - the set returned by the <code>set()</code> accessor will contain - two elements: <code>1</code> and <code>2</code>.</p> - - <p>When <code>std::map</code> is specified as an option type, the option - value is expected to have two parts: the key and the value, separated - by <code>=</code>. All the option values are then parsed into key/value - pairs and inserted into the map. For example:</p> - - <pre class="cli"> -include <map>; -include <string>; - -class options -{ - std::map<std::string, std::string> --map | -m; -}; - </pre> - - <p>The possible option values for this interface are: <code>-m a=A</code>, - <code>-m =B</code> (key is an empty string), <code>-m c=</code> (value - is an empty string), or <code>-m d</code> (same as <code>-m d=</code>).</p> - - <p>The last component in the option definition is optional documentation. - It is discussed in the next section.</p> - - <h2><a name="3.3">3.3 Option Documentation</a></h2> - - <p>Option documentation mimics C++ string array initialization: - it is enclosed in <code>{}</code> and consists of one or more - documentation strings separated by a comma, for example:</p> - - <pre class="cli"> -class options -{ - int --compression = 5 - { - "<level>", - "Set compression to <level> instead of 5 by default. - - With the higher compression levels the program may produce a - smaller output but may also take longer and use more memory." - }; -}; - </pre> - - <p>The option documentation consists of a maximum of three documentation - strings. The first string is the value documentation string. - It describes the option value and is only applicable to options - with types other than <code>bool</code> (options of type - <code>bool</code> are flags and don't have an explicit value). - The second string (or the first string for options of type - <code>bool</code>) is the short documentation string. It - provides a brief description of the option. The last entry - in the option documentation is the long documentation string. - It provides a detailed description of the option. The short - documentation string is optional. If only two strings are - present in the option documentation (one string for options - of type <code>bool</code>), then the second (first) string is - assumed to be the long documentation string.</p> - - <p>Option documentation is used to print the usage information - as well as to generate program documentation in the HTML and - man page formats. For usage information the short documentation - string is used if provided. If only the long string is available, - then, by default, only the first sentence from the long string - is used. You can override this behavior and include the complete - long string in the usage information by specifying the - <code>--long-usage</code> CLI compiler option. When generating - the program documentation, the long documentation strings are - always used.</p> - - <p>The value documentation string can contain text enclosed in - <code><></code> which is automatically recognized by the CLI - compiler and typeset according to the selected output in all three - documentation strings. For example, in usage the <code>level</code> - value for the <code>--compression</code> option presented above - will be displayed as <code><level></code> while in the HTML and - man page output it will be typeset in italic as - <code><i>level</i></code>. Here is another example using the - <code>std::map</code> type:</p> - - <pre class="cli"> -include <map>; -include <string>; - -class options -{ - std::map<std::string, std::string> --map - { - "<key>=<value>", - "Add the <key>, <value> pair to the map." - }; -}; - </pre> - - <p>The resulting HTML output for this option would look like this:</p> - -<dl class="options"> - <dt><code><b>--map</b></code> <i>key</i>=<i>value</i></dt> - <dd>Add the <i>key</i>, <i>value</i> pair to the map.</dd> -</dl> - - <p>As you might have noticed from the examples presented so far, the - documentation strings can span multiple lines which is not possible - in C++. Also, all three documentation strings support the following - basic formatting mechanisms. The start of a new paragraph is indicated - by a blank line. A fragment of text can be typeset in monospace font - (normally used for code fragments) by enclosing it in the - <code>\c{}</code> block. Similarly, text can be typeset in bold or - italic fonts using the <code>\b{}</code> and <code>\i{}</code> blocks, - respectively. You can also combine several font properties in a single - block, for example, <code>\cb{bold code}</code>. If you need to include - literal <code>}</code> in a formatting block, you can use the - <code>\}</code> escape sequence, for example, - <code>\c{int a[] = {1, 2\}}</code>. The following example shows how we - can use these mechanisms:</p> - - <pre class="cli"> -class options -{ - int --compression = 5 - { - "<level>", - "Set compression to <level> instead of 5 by default. - - With the higher compression levels the program \i{may} - produce a smaller output but may also \b{take longer} - and \b{use more memory}." - }; -}; - </pre> - - <p>The resulting HTML output for this option would look like this:</p> - -<dl class="options"> - <dt><code><b>--compression</b></code> <i>level</i></dt> - <dd>Set compression to <i>level</i> instead of 5 by default. - - <p>With the higher compression levels the program <i>may</i> produce a - smaller output but may also <b>take longer</b> and <b>use more memory</b>.</p></dd> -</dl> - - <h2><a name="3.4">3.4 Include Directive</a></h2> - - <p>If you are using user-defined types in your option definitions, - you will need to include their declarations with the include - directive. Include directives can use <code>< ></code> or - <code>" "</code>-enclosed paths. The CLI compiler does not - actually open or read these files. Instead, the include directives - are translated to C++ preprocessor <code>#include</code> directives - in the generated C++ header file. For example, the following CLI - definition:</p> - - <pre class="cli"> -include <string>; -include "types.hxx"; // Defines the name_type class. - -class options -{ - std::string --string; - name_type --name; -}; - </pre> - - <p>Will result in the following C++ header file:</p> - - <pre class="cli"> -#include <string> -#include "types.hxx" - -class options -{ - ... - - const std::string& - string () const; - - const name_type& - name () const; - - ... -}; - </pre> - - <p>Without the <code>#include</code> directives the <code>std::string</code> - and <code>name_type</code> types in the <code>options</code> class would - be undeclared and result in compilation errors.</p> - - <h2><a name="3.5">3.5 Namespace Definition</a></h2> - - <p>Option classes can be placed into namespaces which are translated - directly to C++ namespaces. For example:</p> - - <pre class="cli"> -namespace compiler -{ - namespace lexer - { - class options - { - int --warning-level = 0; - }; - } - - namespace parser - { - class options - { - int --warning-level = 0; - }; - } - - namespace generator - { - class options - { - int --target-width = 32; - }; - } -} - </pre> - - <p>The above CLI namespace structure would result in the equivalent C++ - namespaces structure:</p> - - <pre class="cxx"> -namespace compiler -{ - namespace lexer - { - class options - { - int - warning_level () const; - }; - } - - namespace parser - { - class options - { - int - warning_level () const; - }; - } - - namespace generator - { - class options - { - int - target_width () const; - }; - } -} - </pre> - - - </div> -</div> - - -</body> -</html> diff --git a/doc/guide/makefile b/doc/guide/makefile deleted file mode 100644 index 40ed0f9..0000000 --- a/doc/guide/makefile +++ /dev/null @@ -1,39 +0,0 @@ -# file : doc/guide/makefile -# author : Boris Kolpackov <boris@codesynthesis.com> -# license : MIT; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../../build/bootstrap.make - -default := $(out_base)/ -install := $(out_base)/.install -cleandoc := $(out_base)/.cleandoc - -# Build. -# -$(default): $(out_base)/cli-guide.ps $(out_base)/cli-guide.pdf - - -$(out_base)/cli-guide.ps: $(src_base)/index.xhtml \ - $(src_base)/guide.html2ps \ - | $(out_base)/. - $(call message,html2ps $<,html2ps -f $(src_base)/guide.html2ps -o $@ $<) - -$(out_base)/cli-guide.pdf: $(out_base)/cli-guide.ps | $(out_base)/. - $(call message,ps2pdf $<,ps2pdf14 $< $@) - -# Install. -# -$(install): $(out_base)/cli-guide.ps $(out_base)/cli-guide.pdf - $(call install-data,$(src_base)/index.xhtml,$(install_doc_dir)/cli/guide/index.xhtml) - $(call install-data,$(src_base)/cli-guide.ps,$(install_doc_dir)/cli/guide/cli-guide.ps) - $(call install-data,$(src_base)/cli-guide.pdf,$(install_doc_dir)/cli/guide/cli-guide.pdf) - -# Clean. -# -$(cleandoc): - $(call message,rm $$1,rm -f $$1,$(out_base)/cli-guide.ps) - $(call message,rm $$1,rm -f $$1,$(out_base)/cli-guide.pdf) - -# How to. -# -$(call include,$(bld_root)/install.make) diff --git a/doc/language.txt b/doc/language.txt deleted file mode 100644 index e6c9161..0000000 --- a/doc/language.txt +++ /dev/null @@ -1,128 +0,0 @@ -Token types: - keyword - identifier - punctuation (";" "{" "}" "(" ")" "," "|" "=" ":") - cxx-path-literal ("c++:path", <c++:path>, "path", <path>) - cli-path-literal ("cli:path", <cli:path>, "path.cli", <path.cli>) - char-literal - string-literal - bool-literal - int-literal - float-literal - call-expr (e.g., (a, 2)) - template-expr (e.g., <a, 2>) - end-of-stream - -def-unit: - include-decl-seq(opt) decl-seq(opt) - -include-decl-seq: - source-decl - include-decl - include-decl-seq include-decl - -source-decl: - "source" cli-path-literal ";" - -include-decl: - "include" include-path ";" - -include-path: - cxx-path-literal - cli-path-literal - -decl-seq: - decl - decl-seq decl - -decl: - source-decl - scope-doc - namespace-def - class-def - -scope-doc: - string-literal - "{" doc-string-seq "}" - -namespace-def: - "namespace" identifier "{" namespace-body "}" - -namespace-body: - decl-seq(opt) - -class-def: - "class" identifier inheritance-spec(opt) abstract-spec(opt) "{" class-decl-seq(opt) "};" - -inheritance-spec: - ":" base-seq - -base-seq: - qualified-name - base-seq "," qualified-name - -abstract-spec: - "=" "0" - -class-decl-seq: - class-decl - class-decl-seq class-decl - -class-decl - scope-doc - option-def - -option-def: - type-spec option-name-seq initializer(opt) option-def-trailer - -type-spec: - fundamental-type-spec - qualified-name - -option-name-seq: - option-name - option-name-seq "|" option-name - -option-name: - option-identifier - string-literal - -initializer: - "=" initializer-expr - call-expr - -initializer-expr: - bool-literal - int-literal - float-literal - char-literal - string-literal - qualified-name - call-expr - -option-def-trailer: - ";" - option-doc - -option-doc: - "{" doc-string-seq "}" - -doc-string-seq: - string-literal - doc-string-seq "," string-literal - -qualified-name: - "::" qualified-name-trailer - qualified-name-trailer - -qualified-name-trailer: - template-id - qualified-name "::" template-id - -template-id: - identifier template-expr(opt) - -fundamental-type-spec: - "bool" - ... - "long double" diff --git a/doc/makefile b/doc/makefile deleted file mode 100644 index 6ec866e..0000000 --- a/doc/makefile +++ /dev/null @@ -1,44 +0,0 @@ -# file : doc/makefile -# author : Boris Kolpackov <boris@codesynthesis.com> -# license : MIT; see accompanying LICENSE file - -include $(dir $(lastword $(MAKEFILE_LIST)))../build/bootstrap.make - -default := $(out_base)/ -install := $(out_base)/.install -cleandoc := $(out_base)/.cleandoc - -$(default): $(out_base)/cli.xhtml $(out_base)/cli.1 $(out_base)/guide/ - -# Generated documentation. -# -$(out_base)/cli.xhtml: $(src_root)/cli/options.cli \ - $(src_base)/cli-prologue.xhtml \ - $(src_base)/cli-epilogue.xhtml - $(call message,cli-html $<,$(out_root)/cli/cli --generate-html \ ---output-dir $(out_base) --html-prologue-file $(src_base)/cli-prologue.xhtml \ ---html-epilogue-file $(src_base)/cli-epilogue.xhtml $<) - $(call message,,mv $(out_base)/options.html $(out_base)/cli.xhtml) - -$(out_base)/cli.1: $(src_root)/cli/options.cli \ - $(src_base)/cli-prologue.1 \ - $(src_base)/cli-epilogue.1 - $(call message,cli-man $<,$(out_root)/cli/cli --generate-man \ ---output-dir $(out_base) --man-prologue-file $(src_base)/cli-prologue.1 \ ---man-epilogue-file $(src_base)/cli-epilogue.1 $<) - $(call message,,mv $(out_base)/options.1 $(out_base)/cli.1) - -# Install. -# -$(install): $(out_base)/guide/.install $(out_base)/cli.xhtml $(out_base)/cli.1 - $(call install-data,$(src_base)/default.css,$(install_doc_dir)/cli/default.css) - $(call install-data,$(out_base)/cli.xhtml,$(install_doc_dir)/cli/cli.xhtml) - $(call install-data,$(out_base)/cli.1,$(install_man_dir)/man1/cli.1) - -# Clean. -# -$(cleandoc): $(out_base)/guide/.cleandoc - -$(call include,$(bld_root)/install.make) - -$(call import,$(src_base)/guide/makefile) |