aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorBoris Kolpackov <boris@codesynthesis.com>2018-05-26 15:25:09 +0200
committerBoris Kolpackov <boris@codesynthesis.com>2018-05-26 15:25:09 +0200
commit50223ed214cd89de6c28bc63965438703cddfe4d (patch)
tree98f993c1ed7cfd9bdb33a7c94a5139926556e20a
parent3a6c4ab1b6fc79a6a543088553cdd6bc8cb0a1dd (diff)
Add bpkg-argument-grouping(1) help topic
-rw-r--r--bpkg/.gitignore1
-rw-r--r--bpkg/argument-grouping.cli68
-rw-r--r--bpkg/bpkg.cli5
-rw-r--r--bpkg/buildfile9
-rw-r--r--bpkg/help.cxx3
-rw-r--r--bpkg/pkg-build.cli2
-rwxr-xr-xdoc/cli.sh3
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!
diff --git a/doc/cli.sh b/doc/cli.sh
index f04da12..e37d80c 100755
--- a/doc/cli.sh
+++ b/doc/cli.sh
@@ -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