diff options
-rw-r--r-- | doc/cli.1 | 233 | ||||
-rw-r--r-- | doc/cli.xhtml | 264 |
2 files changed, 497 insertions, 0 deletions
diff --git a/doc/cli.1 b/doc/cli.1 new file mode 100644 index 0000000..3c4e64c --- /dev/null +++ b/doc/cli.1 @@ -0,0 +1,233 @@ +.\" Process this file with +.\" groff -man -Tascii cli.1 +.\" +.TH CLI 1 "December 2009" "CLI 1.1.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 +.\"-------------------------------------------------------------------- +.\" +.\" The following documentation was generated by CLI, a command +.\" line interface compiler for C++. +.\" +.IP "\fB--help\fP" +Print usage information and exit\. + +.IP "\fB--version\fP" +Print version and exit\. + +.IP "\fB--output-dir\fP|\fB-o\fP \fIdir\fP" +Write the generated files to \fIdir\fP instead of the current directory\. + +.IP "\fB--generate-modifier\fP" +Generate option value modifiers in addition to accessors\. + +.IP "\fB--generate-specifier\fP" +Generate functions for determining whether the option was specified on the +command line\. + +.IP "\fB--generate-description\fP" +Generate the option description list that can be examined at runtime\. + +.IP "\fB--generate-file-scanner\fP" +Generate the argv_file_scanner implementation\. This scanner is capable of +reading command line arguments from the argv array as well as files +specified with command line options\. + +.IP "\fB--suppress-inline\fP" +Generate all functions non-inline\. By default simple functions are made +inline\. This option suppresses creation of the inline file\. + +.IP "\fB--suppress-undocumented\fP" +Suppress the generation of documentation entries for undocumented options\. + +.IP "\fB--suppress-usage\fP" +Suppress the generation of the usage printing code\. + +.IP "\fB--long-usage\fP" +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--option-length\fP \fIlen\fP" +Indent option descriptions \fIlen\fP 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--cli-namespace\fP \fIns\fP" +Generate the CLI support types in the \fIns\fP namespace (\fBcli\fP by +default)\. The namespace can be nested, for example \fBdetails::cli\fP\. If +the namespace is empty, then the support types are generated in the global +namespace\. + +.IP "\fB--generate-cxx\fP" +Generate C++ code\. If neither \fB--generate-man\fP nor +\fB--generate-html\fP is specified, this mode is assumed by default\. + +.IP "\fB--generate-man\fP" +Generate documentation in the man page format\. + +.IP "\fB--generate-html\fP" +Generate documentation in the HTML format\. + +.IP "\fB--man-prologue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the beginning of the man page file\. + +.IP "\fB--man-epilogue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the end of the man page file\. + +.IP "\fB--html-prologue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the beginning of the HTML file\. + +.IP "\fB--html-epilogue\fP \fIfile\fP" +Insert the content of \fIfile\fP at the end of the HTML file\. + +.IP "\fB--class\fP \fIfq-name\fP" +Generate the man page or HTML documentation only for the \fIfq-name\fP +options class\. The \fIfq-name\fP name should be a fully-qualified options +class name, for example, \fBapp::options\fP\. This functionality is useful +if you need to insert custom documentation between options belonging to +different classes\. + +.IP "\fB--stdout\fP" +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--hxx-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.hxx\fP to construct the name of +the generated header file\. + +.IP "\fB--ixx-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.ixx\fP to construct the name of +the generated inline file\. + +.IP "\fB--cxx-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.cxx\fP to construct the name of +the generated source file\. + +.IP "\fB--man-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.1\fP to construct the name of +the generated man page file\. + +.IP "\fB--html-suffix\fP \fIsuffix\fP" +Use \fIsuffix\fP instead of the default \fB\.html\fP to construct the name +of the generated HTML file\. + +.IP "\fB--option-prefix\fP \fIprefix\fP" +Use \fIprefix\fP instead of the default \fB-\fP 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\fP \fIsep\fP" +Use \fIsep\fP instead of the default \fB--\fP 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--include-with-brackets\fP" +Use angle brackets (<>) instead of quotes ("") in the generated +\fB#include\fP directives\. + +.IP "\fB--include-prefix\fP \fIprefix\fP" +Add \fIprefix\fP to the generated \fB#include\fP directive paths\. + +.IP "\fB--guard-prefix\fP \fIprefix\fP" +Add \fIprefix\fP 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\fP \fIname\fP=\fIrep\fP" +Add \fIname\fP with an optional \fIrep\fP 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\fP \fIfile\fP" +Read additional options from \fIfile\fP with each option appearing on a +separate line optionally followed by space and an option value\. Empty lines +and lines starting with \fB#\fP are ignored\. Option values can be enclosed +in double (\fB"\fP) or single (\fB'\fP) 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"'\fP\. 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\fP 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-2011 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 new file mode 100644 index 0000000..58ff1f2 --- /dev/null +++ b/doc/cli.xhtml @@ -0,0 +1,264 @@ +<!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.1.0 Compiler Command Line Manual</title> + + <meta name="copyright" content="© 2009-2011 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; + } + + #commands dt { + padding-top : 0.4em; + } + + #commands dd { + padding-bottom : 0.4em; + padding-left : 2em; + } + + .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"> + + <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> + +<!-- + The following documentation was generated by CLI, a command + line interface compiler for C++. +--> + +<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>--output-dir</b></code>|<code><b>-o</b></code> <i>dir</i></dt> + <dd>Write the generated files to <i>dir</i> instead of the current directory.</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-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>argv_file_scanner</code> implementation. This scanner is + capable of reading command line arguments from the <code>argv</code> array + as well as files specified with command line options.</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-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>--option-length</b></code> <i>len</i></dt> + <dd>Indent option descriptions <i>len</i> 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>--cli-namespace</b></code> <i>ns</i></dt> + <dd>Generate the CLI support types in the <i>ns</i> 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>--generate-cxx</b></code></dt> + <dd>Generate C++ code. If neither <code><b>--generate-man</b></code> nor + <code><b>--generate-html</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>--man-prologue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the man page file.</dd> + + <dt><code><b>--man-epilogue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the man page file.</dd> + + <dt><code><b>--html-prologue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the beginning of the HTML file.</dd> + + <dt><code><b>--html-epilogue</b></code> <i>file</i></dt> + <dd>Insert the content of <i>file</i> at the end of the HTML file.</dd> + + <dt><code><b>--class</b></code> <i>fq-name</i></dt> + <dd>Generate the man page or HTML documentation only for the <i>fq-name</i> + options class. The <i>fq-name</i> name should be a fully-qualified options + class name, for example, <code><b>app::options</b></code>. This + functionality is useful if you need to insert custom documentation between + options belonging to different classes.</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>--hxx-suffix</b></code> <i>suffix</i></dt> + <dd>Use <i>suffix</i> 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> <i>suffix</i></dt> + <dd>Use <i>suffix</i> 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> <i>suffix</i></dt> + <dd>Use <i>suffix</i> 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> <i>suffix</i></dt> + <dd>Use <i>suffix</i> 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> <i>suffix</i></dt> + <dd>Use <i>suffix</i> instead of the default <code><b>.html</b></code> to + construct the name of the generated HTML file.</dd> + + <dt><code><b>--option-prefix</b></code> <i>prefix</i></dt> + <dd>Use <i>prefix</i> 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> <i>sep</i></dt> + <dd>Use <i>sep</i> 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>--include-with-brackets</b></code></dt> + <dd>Use angle brackets (<>) instead of quotes ("") in the generated + <code><b>#include</b></code> directives.</dd> + + <dt><code><b>--include-prefix</b></code> <i>prefix</i></dt> + <dd>Add <i>prefix</i> to the generated <code><b>#include</b></code> directive + paths.</dd> + + <dt><code><b>--guard-prefix</b></code> <i>prefix</i></dt> + <dd>Add <i>prefix</i> 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> <i>name</i>=<i>rep</i></dt> + <dd>Add <i>name</i> with an optional <i>rep</i> 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> <i>file</i></dt> + <dd>Read additional options from <i>file</i> with each option appearing on a + separate line optionally followed by space 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"> + © 2009-2011 <a href="http://www.codesynthesis.com">Code Synthesis Tools CC</a> + + <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> |