bpkg-argument-grouping(1)   General Commands Manual  bpkg-argument-grouping(1)

NAME
       bpkg-argument-grouping - argument grouping facility

SYNOPSIS
       bpkg { options }+ argument +{ options }

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 '{' and ends with
       '}+' while a trailing group starts with '+{' and ends with '}'. 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 '{' and '}'. 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 ('{', '}+', 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 '\'. For example:

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

BUGS
       Send bug reports to the users@build2.org mailing list.

COPYRIGHT
       Copyright (c) 2014-2024 the build2 authors.

       Permission is granted to copy, distribute and/or modify this document
       under the terms of the MIT License.

bpkg 0.17.0                        June 2024         bpkg-argument-grouping(1)