optfeature.eclass: Introduce default header and optfeature_header()

Before this change, optfeature() would print a list of optional dependencies,
or nothing if deps are installed. Ebuilds commonly print their own elog
ahead of optfeature, which then may not be followed up by any list at all.

optfeature_header() will set a custom header or reset to default by calling it
without argument, which is only printed if any follup-up optfeature is about
to list a dependency.

Signed-off-by: Andreas Sturmlechner <asturm@gentoo.org>

1 files changed, 55 insertions, 1 deletions

diff --git a/eclass/optfeature.eclass b/eclass/optfeature.eclass
index e13fc3eba811..b558e8c9084f 100644
--- a/eclass/optfeature.eclass
+++ b/eclass/optfeature.eclass
@@ -1,4 +1,4 @@
-# Copyright 1999-2020 Gentoo Authors
+# Copyright 1999-2021 Gentoo Authors
 # Distributed under the terms of the GNU General Public License v2
 
 # @ECLASS: optfeature.eclass
@@ -14,6 +14,56 @@ esac
 if [[ -z ${_OPTFEATURE_ECLASS} ]]; then
 _OPTFEATURE_ECLASS=1
 
+# @ECLASS-VARIABLE: _OPTFEATURE_DEFAULT_HEADER
+# @INTERNAL
+# @DESCRIPTION:
+# Default header printed ahead of optfeature output. Can be overridden
+# by calling optfeature_header function. Will not be displayed if all optional
+# dependencies are present.
+_OPTFEATURE_DEFAULT_HEADER="Install additional packages for optional runtime features:"
+
+readonly _OPTFEATURE_DEFAULT_HEADER
+
+# @ECLASS-VARIABLE: _OPTFEATURE_HEADER
+# @INTERNAL
+# @DESCRIPTION:
+# Default empty. Custom header printed ahead of optfeature output.
+# Set by calling optfeature_header function with the desired output, or reset
+# by optfeature_header without argument. Will not be displayed if all optional
+# dependencies are present.
+_OPTFEATURE_HEADER=
+
+# @ECLASS-VARIABLE: _OPTFEATURE_DOHEADER
+# @INTERNAL
+# @DESCRIPTION:
+# If true, print header ahead of the first optfeature output.
+_OPTFEATURE_DOHEADER=true
+
+# @FUNCTION: optfeature_header
+# @USAGE: [custom header for follow-up optfeature calls]
+# @DESCRIPTION:
+# Set a custom header for follow-up optfeature calls, or reset to default
+# header by calling it without argument. This can not only be used to customize
+# the header but also to distinguish optfeature "groups", e.g. to list a number
+# of different possible database backends, and then a number of optional
+# regular runtime features.
+#
+# The following snippet will leave the default header untouched for the first
+# two optfeature calls. Then a custom header is set that is going to be
+# displayed in case dev-db/a or dev-db/b are not installed.
+# @CODE
+#	optfeature "foo support" app-misc/foo
+#	optfeature "bar support" app-misc/bar
+#	optfeature_header "Install optional database backends:"
+#	optfeature "a DB backend" dev-db/a
+#	optfeature "b DB backend" dev-db/b
+# @CODE
+optfeature_header() {
+	debug-print-function ${FUNCNAME} "$@"
+	_OPTFEATURE_HEADER="${1}"
+	_OPTFEATURE_DOHEADER=true
+}
+
 # @FUNCTION: optfeature
 # @USAGE: <short description> <package atom to match> [other atoms]
 # @DESCRIPTION:
@@ -51,6 +101,10 @@ optfeature() {
 		fi
 	done
 	if [[ ${flag} -eq 0 ]]; then
+		if [[ ${_OPTFEATURE_DOHEADER} == true ]]; then
+			elog ${_OPTFEATURE_HEADER:-${_OPTFEATURE_DEFAULT_HEADER}}
+			_OPTFEATURE_DOHEADER=false
+		fi
 		for i; do
 			read -r -d '' -a arr <<<"${i}"
 			msg=" "