aboutsummaryrefslogtreecommitdiff
path: root/bpkg/argument-grouping.cli
blob: ccb92897eeccf889b477da580fac2148e43a667f (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
// file      : bpkg/argument-grouping.cli
// copyright : Copyright (c) 2014-2019 Code Synthesis Ltd
// 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 was copied from CLI.
//
"
\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'
\

Note that the group applies to a single argument only. For example:

\
{ --foo }+ arg1  arg2 +{ --bar }  # 'arg1' with '--foo' and
                                  # 'arg2' with '--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 '}+'
\

"