diff options
Diffstat (limited to 'doc/cli.xhtml')
| -rw-r--r-- | doc/cli.xhtml | 103 |
1 files changed, 87 insertions, 16 deletions
diff --git a/doc/cli.xhtml b/doc/cli.xhtml index 3bc4e57..bc3aa5e 100644 --- a/doc/cli.xhtml +++ b/doc/cli.xhtml @@ -101,23 +101,71 @@ <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 - merging/overriding.</dd> + 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>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> + <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>vector_scanner</code> implementation. This scanner - is capable of reading command line arguments from + <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> @@ -224,10 +272,12 @@ 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>, or - <code><b>exclude</b></code>. If the value is <code><b>exclude</b></code>, - then the class documentation is excluded from usage and man/HTML/text - output. For usage, the <code><b>short</b></code> and + 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 @@ -433,6 +483,26 @@ 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> @@ -454,11 +524,12 @@ 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> 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 + <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 |