From: "Michał Górny" <mgorny@gentoo.org>
To: gentoo-dev@lists.gentoo.org,kentnl@gentoo.org
Cc: vapier@gentoo.org,tools-portage@gentoo.org,Kent Fredric
<kentnl@gentoo.org>
Subject: Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT
Date: Mon, 01 May 2017 12:11:13 +0200 [thread overview]
Message-ID: <F9F371BB-5D50-46DC-A0FB-C11E2EFD503A@gentoo.org> (raw)
In-Reply-To: <20170430213646.21683-1-kentnl@gentoo.org>
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)
prev parent reply other threads:[~2017-05-01 10:11 UTC|newest]
Thread overview: 2+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-04-30 21:36 [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT kentnl
2017-05-01 10:11 ` Michał Górny [this message]
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=F9F371BB-5D50-46DC-A0FB-C11E2EFD503A@gentoo.org \
--to=mgorny@gentoo.org \
--cc=gentoo-dev@lists.gentoo.org \
--cc=kentnl@gentoo.org \
--cc=tools-portage@gentoo.org \
--cc=vapier@gentoo.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox