From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!.POSTED!not-for-mail From: Mark H Weaver Newsgroups: gmane.lisp.guile.bugs Subject: bug#30145: [PATCH] doc: Document unspecified?. Date: Sun, 21 Jan 2018 09:48:54 -0500 Message-ID: <87wp0bmfmx.fsf@netris.org> References: <20180117175204.1381-1-arunisaac@systemreboot.net> <20180118062029.5655-1-arunisaac@systemreboot.net> NNTP-Posting-Host: blaine.gmane.org Mime-Version: 1.0 Content-Type: text/plain X-Trace: blaine.gmane.org 1516546228 28087 195.159.176.226 (21 Jan 2018 14:50:28 GMT) X-Complaints-To: usenet@blaine.gmane.org NNTP-Posting-Date: Sun, 21 Jan 2018 14:50:28 +0000 (UTC) User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/25.3 (gnu/linux) Cc: 30145@debbugs.gnu.org To: Arun Isaac Original-X-From: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Sun Jan 21 15:50:24 2018 Return-path: Envelope-to: guile-bugs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by blaine.gmane.org with esmtp (Exim 4.84_2) (envelope-from ) id 1edGwk-0006G8-5Z for guile-bugs@m.gmane.org; Sun, 21 Jan 2018 15:50:10 +0100 Original-Received: from localhost ([::1]:60270 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1edGyk-0008Cx-Iv for guile-bugs@m.gmane.org; Sun, 21 Jan 2018 09:52:14 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:39112) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1edGyc-0008C3-CC for bug-guile@gnu.org; Sun, 21 Jan 2018 09:52:07 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1edGyY-000438-2E for bug-guile@gnu.org; Sun, 21 Jan 2018 09:52:05 -0500 Original-Received: from debbugs.gnu.org ([208.118.235.43]:57035) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1edGyX-00042x-Uj for bug-guile@gnu.org; Sun, 21 Jan 2018 09:52:01 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1edGyX-0006fa-K5 for bug-guile@gnu.org; Sun, 21 Jan 2018 09:52:01 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Mark H Weaver Original-Sender: "Debbugs-submit" Resent-CC: bug-guile@gnu.org Resent-Date: Sun, 21 Jan 2018 14:52:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 30145 X-GNU-PR-Package: guile X-GNU-PR-Keywords: patch Original-Received: via spool by 30145-submit@debbugs.gnu.org id=B30145.151654628525596 (code B ref 30145); Sun, 21 Jan 2018 14:52:01 +0000 Original-Received: (at 30145) by debbugs.gnu.org; 21 Jan 2018 14:51:25 +0000 Original-Received: from localhost ([127.0.0.1]:36699 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1edGxx-0006em-3L for submit@debbugs.gnu.org; Sun, 21 Jan 2018 09:51:25 -0500 Original-Received: from world.peace.net ([50.252.239.5]:41534) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1edGxv-0006eZ-13 for 30145@debbugs.gnu.org; Sun, 21 Jan 2018 09:51:23 -0500 Original-Received: from [98.216.255.118] (helo=yeeloong) by world.peace.net with esmtpsa (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.89) (envelope-from ) id 1edGxp-0007Zn-54; Sun, 21 Jan 2018 09:51:17 -0500 In-Reply-To: <20180118062029.5655-1-arunisaac@systemreboot.net> (Arun Isaac's message of "Thu, 18 Jan 2018 11:50:29 +0530") X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 208.118.235.43 X-BeenThere: bug-guile@gnu.org List-Id: "Bug reports for GUILE, GNU's Ubiquitous Extension Language" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-guile-bounces+guile-bugs=m.gmane.org@gnu.org Original-Sender: "bug-guile" Xref: news.gmane.org gmane.lisp.guile.bugs:8975 Archived-At: Hi Arun, Arun Isaac writes: > * doc/ref/data-rep.texi: Document unspecified?. > --- > doc/ref/data-rep.texi | 3 +++ > 1 file changed, 3 insertions(+) > > diff --git a/doc/ref/data-rep.texi b/doc/ref/data-rep.texi > index bb7f74afe..f179a3560 100644 > --- a/doc/ref/data-rep.texi > +++ b/doc/ref/data-rep.texi > @@ -470,6 +470,9 @@ check to see if @var{x} is @code{SCM_UNBOUND}. History will not be kind > to us. > @end deftypefn > > +@deffn {Scheme Procedure} unspecified? x > +Return @code{#t} if @var{x} is unspecified, else @code{#f}. > +@end deffn I'm not sure it's a good idea to document this procedure as part of our public API, but if we were to document it, it would require a more informative description. It's nonsensical to ask whether a given object is "unspecified". When the Scheme standards say that the result of a computation is an unspecified value, that means that *any* Scheme object could be returned. In Guile, for historical reasons, we usually return a particular object SCM_UNSPECIFIED (a.k.a. *unspecified*) in cases where the specification says that the result is unspecified. However, we make no promises that this will remain the case in future versions of Guile. The number of legitimate uses for 'unspecified?' is extremely small. In fact, I can think of only one: when a REPL prints the result of a user's computation, it is nice to avoid printing "*unspecified*" and instead print nothing in that case. In almost every other case, use of 'unspecified?' implies an assumption that it's possible to detect when a value is an "unspecified" value, when in fact that is fundamentally impossible. What do you think? Mark