diff options
| -rw-r--r-- | bpkg/.gitignore | 1 | ||||
| -rw-r--r-- | bpkg/argument-grouping.cli | 68 | ||||
| -rw-r--r-- | bpkg/bpkg.cli | 5 | ||||
| -rw-r--r-- | bpkg/buildfile | 9 | ||||
| -rw-r--r-- | bpkg/help.cxx | 3 | ||||
| -rw-r--r-- | bpkg/pkg-build.cli | 2 | ||||
| -rwxr-xr-x | doc/cli.sh | 3 |
7 files changed, 85 insertions, 6 deletions
diff --git a/bpkg/.gitignore b/bpkg/.gitignore index 007b999..ebdc8f6 100644 --- a/bpkg/.gitignore +++ b/bpkg/.gitignore @@ -3,4 +3,5 @@ bpkg *-odb.?xx repository-signing.?xx repository-types.?xx +argument-grouping.?xx version.hxx diff --git a/bpkg/argument-grouping.cli b/bpkg/argument-grouping.cli new file mode 100644 index 0000000..459f320 --- /dev/null +++ b/bpkg/argument-grouping.cli @@ -0,0 +1,68 @@ +// file : bpkg/argument-grouping.cli +// copyright : Copyright (c) 2014-2018 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 '}+' +\ + +" diff --git a/bpkg/bpkg.cli b/bpkg/bpkg.cli index ed8ed0d..22898c1 100644 --- a/bpkg/bpkg.cli +++ b/bpkg/bpkg.cli @@ -295,6 +295,11 @@ namespace bpkg { "\l{bpkg-repository-signing(1)} \- how to sign repository" } + + bool argument-grouping + { + "\l{bpkg-argument-grouping(1)} \- argument grouping facility" + } }; class options: common_options diff --git a/bpkg/buildfile b/bpkg/buildfile index 8355f49..5c3ba35 100644 --- a/bpkg/buildfile +++ b/bpkg/buildfile @@ -42,7 +42,7 @@ rep-info-options \ rep-list-options \ rep-remove-options -help_topics = repository-signing repository-types +help_topics = repository-signing repository-types argument-grouping exe{bpkg}: \ {hxx ixx txx cxx}{** -{$options_topics} -{$help_topics} -*-odb -version} \ @@ -112,7 +112,8 @@ if $cli.configured # Help topics. # cli.cxx{repository-signing}: cli{repository-signing} - cli.cxx{repository-types}: cli{repository-types} + cli.cxx{repository-types}: cli{repository-types} + cli.cxx{argument-grouping}: cli{argument-grouping} # Option length must be the same to get commands/topics/options aligned. # @@ -133,8 +134,8 @@ bpkg::pkg_build_pkg_options=exclude-base --generate-modifier # Avoid generating CLI runtime and empty inline file for help topics. # - cli.cxx{repository-signing repository-types}: cli.options += --suppress-cli \ ---suppress-inline + cli.cxx{repository-signing repository-types argument-grouping}: \ + cli.options += --suppress-cli --suppress-inline # Include the generated cli files into the distribution and don't remove # them when cleaning in src (so that clean results in a state identical to diff --git a/bpkg/help.cxx b/bpkg/help.cxx index 2584f16..a5b6414 100644 --- a/bpkg/help.cxx +++ b/bpkg/help.cxx @@ -13,6 +13,7 @@ // #include <bpkg/repository-signing.hxx> #include <bpkg/repository-types.hxx> +#include <bpkg/argument-grouping.hxx> using namespace std; using namespace butl; @@ -35,6 +36,8 @@ namespace bpkg usage = &print_bpkg_repository_signing_usage; else if (t == "repository-types") usage = &print_bpkg_repository_types_usage; + else if (t == "argument-grouping") + usage = &print_bpkg_argument_grouping_usage; else fail << "unknown bpkg command/help topic '" << t << "'" << info << "run 'bpkg help' for more information"; diff --git a/bpkg/pkg-build.cli b/bpkg/pkg-build.cli index 6bb4ce2..a1a79de 100644 --- a/bpkg/pkg-build.cli +++ b/bpkg/pkg-build.cli @@ -147,7 +147,7 @@ namespace bpkg The following options can be grouped to apply to a specific \ci{pkg-spec} as well as specified globally, in which case they apply to all the - specified packages." + specified packages (see \l{bpkg-argument-grouping(1)} for details)." // NOTE: if adding a new option here, don't forget to also update // {validate,merge,compare,print}_options() in pkg-build.cxx! @@ -64,7 +64,8 @@ compile "pkg-build" $o --class-doc bpkg::pkg_build_pkg_options=exclude-base pages="cfg-create help pkg-clean pkg-configure pkg-disfigure \ pkg-drop pkg-fetch pkg-checkout pkg-install pkg-purge pkg-status pkg-test \ pkg-uninstall pkg-unpack pkg-update pkg-verify rep-add rep-remove rep-list \ -rep-create rep-fetch rep-info repository-signing repository-types" +rep-create rep-fetch rep-info repository-signing repository-types \ +argument-grouping" for p in $pages; do compile $p $o |