[gentoo-dev] [PATCH v2] optfeature.eclass: Introduce optfeature header

[Andreas Sturmlechner]

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.

This change adds a default header text, which may be changed by the ebuild,
that is only printed if optfeature is about to list at least one dependency.

v2: Introduce optfeature_header() function
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.

Signed-off-by: Andreas Sturmlechner <asturm@g.o>

--- 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=" "