[gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT

[gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT

[kentnl]

From: Kent Fredric <kentnl@gentoo.org>

@RETURNS is abused presently both as bash exit code values ( that
is, bash return values ), and capturable STOUT values.

This is problematic, as they're not equivalent: One is passed
around via $? , and the other requires VAR=$(func) to capture.

Additionally, functions can have both output, and return values,
and both can be used together.

For example:

  function get_thing_version() {
    if [[ "${FAIL}" ]]; then
      echo "libthing not installed"
      return 1
    fi
    echo "1.0"
    return 0
  }

  # this line works and MYVAR gets "1.0"
  # and does not die
  MYVAR=$(get_thing_version) \
        || die "Can't get thing version, ${MYVAR}"

  # This dies with the error message communicated from the
  # function
  FAIL=1
  MYVAR=$(get_thing_version) \
        || die "Can't get thing version, ${MYVAR}"

Hence, a reasonable documentation for a function like this would
be:

  @OUTPUT: version of thing when present, explanation of cause for thing missing otherwise
  @RETURN: 0 on success, non-zero otherwise

Package-Manager: Portage-2.3.4, Repoman-2.3.2
---
 app-portage/eclass-manpages/files/eclass-to-manpage.awk | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
index 0b65162c04..0d41f96327 100644
--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
@@ -27,6 +27,7 @@
 # The format of functions:
 # @FUNCTION: foo
 # @USAGE: <required arguments to foo> [optional arguments to foo]
+# @OUTPUT: <values emitted to STDOUT>
 # @RETURN: <whatever foo returns>
 # @MAINTAINER:
 # <optional; list of contacts, one per line>
@@ -217,6 +218,7 @@ function show_function_header() {
 function handle_function() {
 	func_name = $3
 	usage = ""
+	funcout = ""
 	funcret = ""
 	maintainer = ""
 	internal = 0
@@ -231,6 +233,8 @@ function handle_function() {
 	getline
 	if ($2 == "@USAGE:")
 		usage = eat_line()
+	if ($2 == "@OUTPUT:")
+		funcout = eat_line()
 	if ($2 == "@RETURN:")
 		funcret = eat_line()
 	if ($2 == "@MAINTAINER:")
@@ -257,6 +261,11 @@ function handle_function() {
 			print ""
 		print "Return value: " funcret
 	}
+	if (funcout != "") {
+		if (desc !="")
+			print ""
+		print "Outputs: " funcout
+	}
 
 	if (blurb == "")
 		fail(func_name ": no @BLURB found")
-- 
2.12.2

Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT

[Michał Górny]

Dnia 30 kwietnia 2017 23:36:46 CEST, kentnl@gentoo.org napisał(a):
>From: Kent Fredric <kentnl@gentoo.org>
>
>@RETURNS is abused presently both as bash exit code values ( that
>is, bash return values ), and capturable STOUT values.
>
>This is problematic, as they're not equivalent: One is passed
>around via $? , and the other requires VAR=$(func) to capture.
>
>Additionally, functions can have both output, and return values,
>and both can be used together.
>
>For example:
>
>  function get_thing_version() {
>    if [[ "${FAIL}" ]]; then
>      echo "libthing not installed"
>      return 1
>    fi
>    echo "1.0"
>    return 0
>  }
>
>  # this line works and MYVAR gets "1.0"
>  # and does not die
>  MYVAR=$(get_thing_version) \
>        || die "Can't get thing version, ${MYVAR}"
>
>  # This dies with the error message communicated from the
>  # function
>  FAIL=1
>  MYVAR=$(get_thing_version) \
>        || die "Can't get thing version, ${MYVAR}"
>
>Hence, a reasonable documentation for a function like this would
>be:
>
>@OUTPUT: version of thing when present, explanation of cause for thing
>missing otherwise
>  @RETURN: 0 on success, non-zero otherwise
>
>Package-Manager: Portage-2.3.4, Repoman-2.3.2
>---
> app-portage/eclass-manpages/files/eclass-to-manpage.awk | 9 +++++++++
> 1 file changed, 9 insertions(+)
>
>diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>index 0b65162c04..0d41f96327 100644
>--- a/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>+++ b/app-portage/eclass-manpages/files/eclass-to-manpage.awk
>@@ -27,6 +27,7 @@
> # The format of functions:
> # @FUNCTION: foo
> # @USAGE: <required arguments to foo> [optional arguments to foo]
>+# @OUTPUT: <values emitted to STDOUT>
> # @RETURN: <whatever foo returns>
> # @MAINTAINER:
> # <optional; list of contacts, one per line>
>@@ -217,6 +218,7 @@ function show_function_header() {
> function handle_function() {
> 	func_name = $3
> 	usage = ""
>+	funcout = ""
> 	funcret = ""
> 	maintainer = ""
> 	internal = 0
>@@ -231,6 +233,8 @@ function handle_function() {
> 	getline
> 	if ($2 == "@USAGE:")
> 		usage = eat_line()
>+	if ($2 == "@OUTPUT:")
>+		funcout = eat_line()
> 	if ($2 == "@RETURN:")
> 		funcret = eat_line()
> 	if ($2 == "@MAINTAINER:")
>@@ -257,6 +261,11 @@ function handle_function() {
> 			print ""
> 		print "Return value: " funcret
> 	}
>+	if (funcout != "") {
>+		if (desc !="")
>+			print ""
>+		print "Outputs: " funcout
>+	}

Move this above return value. Functions usually output before returning.

> 
> 	if (blurb == "")
> 		fail(func_name ": no @BLURB found")


-- 
Best regards,
Michał Górny (by phone)