bpkg-argument-grouping(1)

💅 bpkg-argument-grouping — the argument grouping facility, bestie

okay so this is a page from the bpkg manual (General Commands Manual section, for the record), and it's all about argument grouping. it's not a command you run, it's a help topic — like, it explains the vibe of how grouping works before you go use it. 🦋

---

✨ NAME ✨

bpkg-argument-grouping — the argument grouping facility. that's it, that's the name. 🎀

---

✨ SYNOPSIS ✨

bpkg { options }+ argument +{ options }

like. that's the shape of it. you got your options in a little group before, your argument in the middle (main character 💅), and your options in a group after. periodt.

---

✨ DESCRIPTION ✨

so for certain commands, some options and command line variables can get grouped so they only apply to specific arguments. this help topic is the whole rundown of the argument grouping facility used for exactly that. 🫶

groups can be specified before (leading) and/or after (trailing) the argument they apply to. here's the tea:

• a leading group starts with { and ends with }+
• 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'

ok and you're not limited to one group either. multiple leading and/or trailing groups can be specified for the same argument. obsessed. 💖

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

ngl the group applies to a single argument only — unless multiple arguments are themselves grouped with { and }. then they share. iconic.

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

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

🚨 IMPORTANT VIBE CHECK 🚨 the group separators ({, }+, etc) must be separate command line arguments. like, they must NOT be adjacent either to the arguments inside the group or to the argument they apply to. all such cases get treated as ordinary arguments. no cap. 😭

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

and if one of the group separators needs to be specified as an argument verbatim? you gotta escape it with \. yes bestie, backslash. ✨

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

note that last one — { \}+ }+ arg gives you 'arg' with '}+'. the escaped one is literal, the unescaped one is doing group separator business. iykyk. 🧚

---

🐛 BUGS 🐛

found a bug? don't just suffer in silence, send bug reports to the users@build2.org mailing list. fr fr, they wanna know. 💀

---

©️ 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.

---

and that's the whole page, bestie 💜 this was bpkg 0.17.0, dated June 2024 — go forth and group your arguments responsibly, you absolute 👑