// file      : bpkg/argument-grouping.cli
// license   : MIT; see accompanying LICENSE file

include <bpkg/common-options.hxx>;

"\section=1"
"\name=bpkg-argument-grouping"
"\summary=argument grouping facility"

// NOTE: the grouping documentation (indented part) was copied verbatim from
//       CLI's --generate-group-scanner documentation.
//
"
\h|SYNOPSIS|

\c{\b{bpkg} \b{{} \i{options} \b{\}+} \i{argument} \b{+{} \i{options} \b{\}}}

\h|DESCRIPTION|

For certain commands certain options and command line variables can be grouped
to only apply to specific arguments. This help topic describes the argument
grouping facility used for this purpose.

     Groups can be specified before (leading) and/or after (trailing) the
     argument they apply to. A leading group starts with '\cb{{}' and ends
     with '\cb{\}+}' while a trailing group starts with '\cb{+{}' and ends
     with '\cb{\}}'. For example:

     \
     { --foo --bar }+ arg   # 'arg' with '--foo' '--bar'
     arg +{ fox=1 baz=2 }   # 'arg' with 'fox=1' 'baz=2'
     \

     Multiple leading and/or trailing groups can be specified for the
     same argument. For example:

     \
     { -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'
     \

     The group applies to a single argument only unless multiple arguments
     are themselves grouped with '\cb{{}' and '\cb{\}}'. For example:

     \
     { --foo }+ arg1  arg2 +{ --bar }      # 'arg1' with '--foo'
                                           # 'arg2' with '--bar'

     { --foo }+ { arg1  arg2 } +{ --bar }  # 'arg1' with '--foo' '--bar'
                                           # 'arg2' with '--foo' '--bar'
     \

     The group separators ('\cb{{}', '\cb{\}+'}, 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:

     \
     {--foo}+ arg   # '{--foo}+' ...
     arg+{ --foo }  # 'arg+{' ...
     \

     If one of the group separators needs to be specified as an argument
     verbatim, then it must be escaped with '\cb{\\}'. For example:

     \
     }             # error: unexpected group separator
     }x            # '}x'
     \}            # '}'
     { \}+ }+ arg  # 'arg' with '}+'
     \
"
