From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id 8EE3B139694 for ; Mon, 1 May 2017 10:11:42 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id A1D7FE0DE7; Mon, 1 May 2017 10:11:33 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 57736E0BFA for ; Mon, 1 May 2017 10:11:33 +0000 (UTC) Received: from [10.99.183.21] (public-gprs384117.centertel.pl [37.47.131.182]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: mgorny) by smtp.gentoo.org (Postfix) with ESMTPSA id BD89E3416A8; Mon, 1 May 2017 10:11:28 +0000 (UTC) Date: Mon, 01 May 2017 12:11:13 +0200 User-Agent: K-9 Mail for Android In-Reply-To: <20170430213646.21683-1-kentnl@gentoo.org> References: <20170430213646.21683-1-kentnl@gentoo.org> Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Subject: Re: [gentoo-dev] [PATCH] app-portage/eclass-manpages: Add support for @OUTPUT To: gentoo-dev@lists.gentoo.org,kentnl@gentoo.org CC: vapier@gentoo.org,tools-portage@gentoo.org,Kent Fredric From: =?UTF-8?Q?Micha=C5=82_G=C3=B3rny?= Message-ID: X-Archives-Salt: c7febe91-639b-492c-8996-16795043320d X-Archives-Hash: 24f01f6d140f93b95aaa867e22c6cb33 Dnia 30 kwietnia 2017 23:36:46 CEST, kentnl@gentoo=2Eorg napisa=C5=82(a): >From: Kent Fredric > >@RETURNS is abused presently both as bash exit code values ( that >is, bash return values ), and capturable STOUT values=2E > >This is problematic, as they're not equivalent: One is passed >around via $? , and the other requires VAR=3D$(func) to capture=2E > >Additionally, functions can have both output, and return values, >and both can be used together=2E > >For example: > > function get_thing_version() { > if [[ "${FAIL}" ]]; then > echo "libthing not installed" > return 1 > fi > echo "1=2E0" > return 0 > } > > # this line works and MYVAR gets "1=2E0" > # and does not die > MYVAR=3D$(get_thing_version) \ > || die "Can't get thing version, ${MYVAR}" > > # This dies with the error message communicated from the > # function > FAIL=3D1 > MYVAR=3D$(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=2E3=2E4, Repoman-2=2E3=2E2 >--- > app-portage/eclass-manpages/files/eclass-to-manpage=2Eawk | 9 +++++++++ > 1 file changed, 9 insertions(+) > >diff --git a/app-portage/eclass-manpages/files/eclass-to-manpage=2Eawk >b/app-portage/eclass-manpages/files/eclass-to-manpage=2Eawk >index 0b65162c04=2E=2E0d41f96327 100644 >--- a/app-portage/eclass-manpages/files/eclass-to-manpage=2Eawk >+++ b/app-portage/eclass-manpages/files/eclass-to-manpage=2Eawk >@@ -27,6 +27,7 @@ > # The format of functions: > # @FUNCTION: foo > # @USAGE: [optional arguments to foo] >+# @OUTPUT: > # @RETURN: > # @MAINTAINER: > # >@@ -217,6 +218,7 @@ function show_function_header() { > function handle_function() { > func_name =3D $3 > usage =3D "" >+ funcout =3D "" > funcret =3D "" > maintainer =3D "" > internal =3D 0 >@@ -231,6 +233,8 @@ function handle_function() { > getline > if ($2 =3D=3D "@USAGE:") > usage =3D eat_line() >+ if ($2 =3D=3D "@OUTPUT:") >+ funcout =3D eat_line() > if ($2 =3D=3D "@RETURN:") > funcret =3D eat_line() > if ($2 =3D=3D "@MAINTAINER:") >@@ -257,6 +261,11 @@ function handle_function() { > print "" > print "Return value: " funcret > } >+ if (funcout !=3D "") { >+ if (desc !=3D"") >+ print "" >+ print "Outputs: " funcout >+ } Move this above return value=2E Functions usually output before returning= =2E >=20 > if (blurb =3D=3D "") > fail(func_name ": no @BLURB found") --=20 Best regards, Micha=C5=82 G=C3=B3rny (by phone)