// -*- 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.

