Add support for option merging (--generate-merge)

2 files changed, 175 insertions, 37 deletions

diff --git a/doc/cli.1 b/doc/cli.1
index 94456d7..ab46e49 100644
--- a/doc/cli.1
+++ b/doc/cli.1
@@ -76,16 +76,68 @@ 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 merging/overriding\.
+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 argv_file_scanner\fR implementation\. This scanner is capable of
-reading command line arguments from the argv\fR array as well as files
+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 vector_scanner\fR implementation\. This scanner is capable of
+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\.
@@ -165,12 +217,13 @@ default, base classes are included first\.
 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, or \fBexclude\fR\. If the value is \fBexclude\fR, then the class
-documentation is excluded from usage and man/HTML/text output\. 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\.
+\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
@@ -185,7 +238,7 @@ 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\.
+\&"\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
@@ -203,8 +256,8 @@ Trace the process of applying regular expressions specified with the
 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)\.
+\&'\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\.
@@ -294,6 +347,20 @@ 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\.
@@ -308,14 +375,14 @@ 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 with each option appearing on a
-separate line optionally followed by space 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\.
+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
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&lt;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>&lt;></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