1 files changed, 84 insertions, 0 deletions
diff --git a/bpkg/argument-grouping.cxx b/bpkg/argument-grouping.cxx
new file mode 100644
index 0000000..998b7ea
--- /dev/null
+++ b/bpkg/argument-grouping.cxx
@@ -0,0 +1,84 @@
+// -*- C++ -*-
+//
+// This file was generated by CLI, a command line interface
+// compiler for C++.
+//
+
+// Begin prologue.
+//
+#include <bpkg/types-parsers.hxx>
+//
+// End prologue.
+
+#include <bpkg/argument-grouping.hxx>
+
+#include <map>
+
+namespace bpkg
+{
+  ::bpkg::cli::usage_para
+  print_bpkg_argument_grouping_usage (::std::ostream& os, ::bpkg::cli::usage_para p)
+  {
+    CLI_POTENTIALLY_UNUSED (os);
+
+    if (p != ::bpkg::cli::usage_para::none)
+      os << ::std::endl;
+
+    os << "\033[1mSYNOPSIS\033[0m" << ::std::endl
+       << ::std::endl
+       << "\033[1mbpkg\033[0m \033[1m{\033[0m \033[4moptions\033[0m \033[1m}+\033[0m \033[4margument\033[0m \033[1m+{\033[0m \033[4moptions\033[0m \033[1m}\033[0m\033[0m" << ::std::endl
+       << ::std::endl
+       << "\033[1mDESCRIPTION\033[0m" << ::std::endl
+       << ::std::endl
+       << "For certain commands certain options and command line variables can be grouped" << ::std::endl
+       << "to only apply to specific arguments. This help topic describes the argument" << ::std::endl
+       << "grouping facility used for this purpose." << ::std::endl
+       << ::std::endl
+       << "Groups can be specified before (leading) and/or after (trailing) the argument" << ::std::endl
+       << "they apply to. A leading group starts with '\033[1m{\033[0m' and ends with '\033[1m}+\033[0m' while a" << ::std::endl
+       << "trailing group starts with '\033[1m+{\033[0m' and ends with '\033[1m}\033[0m'. For example:" << ::std::endl
+       << ::std::endl
+       << "{ --foo --bar }+ arg   # 'arg' with '--foo' '--bar'" << ::std::endl
+       << "arg +{ fox=1 baz=2 }   # 'arg' with 'fox=1' 'baz=2'" << ::std::endl
+       << ::std::endl
+       << "Multiple leading and/or trailing groups can be specified for the same argument." << ::std::endl
+       << "For example:" << ::std::endl
+       << ::std::endl
+       << "{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'" << ::std::endl
+       << ::std::endl
+       << "The group applies to a single argument only unless multiple arguments are" << ::std::endl
+       << "themselves grouped with '\033[1m{\033[0m' and '\033[1m}\033[0m'. For example:" << ::std::endl
+       << ::std::endl
+       << "{ --foo }+ arg1  arg2 +{ --bar }      # 'arg1' with '--foo'" << ::std::endl
+       << "                                      # 'arg2' with '--bar'" << ::std::endl
+       << ::std::endl
+       << "{ --foo }+ { arg1  arg2 } +{ --bar }  # 'arg1' with '--foo' '--bar'" << ::std::endl
+       << "                                      # 'arg2' with '--foo' '--bar'" << ::std::endl
+       << ::std::endl
+       << "The group separators ('\033[1m{\033[0m', '\033[1m}+'\033[0m, etc) must be separate command line arguments." << ::std::endl
+       << "In particular, they must not be adjacent either to the arguments inside the" << ::std::endl
+       << "group nor to the argument they apply to. All such cases will be treated as" << ::std::endl
+       << "ordinary arguments. For example:" << ::std::endl
+       << ::std::endl
+       << "{--foo}+ arg   # '{--foo}+' ..." << ::std::endl
+       << "arg+{ --foo }  # 'arg+{' ..." << ::std::endl
+       << ::std::endl
+       << "If one of the group separators needs to be specified as an argument verbatim," << ::std::endl
+       << "then it must be escaped with '\033[1m\\\033[0m'. For example:" << ::std::endl
+       << ::std::endl
+       << "}             # error: unexpected group separator" << ::std::endl
+       << "}x            # '}x'" << ::std::endl
+       << "\\}            # '}'" << ::std::endl
+       << "{ \\}+ }+ arg  # 'arg' with '}+'" << ::std::endl;
+
+    p = ::bpkg::cli::usage_para::text;
+
+    return p;
+  }
+}
+
+// Begin epilogue.
+//
+//
+// End epilogue.
+