From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Drew Adams Newsgroups: gmane.emacs.bugs Subject: bug#15117: 24.3.50; doc of `(forward|backward)-*': state return value Date: Mon, 10 Feb 2014 22:43:08 -0800 (PST) Message-ID: <68a64949-d801-4d09-8dc8-4b6ae0824855@default> References: <1dc76f7a-5481-41df-b976-ec22229d7283@default> <874n4a42f0.fsf@building.gnus.org> <1281d0fd-77cb-45e2-b99d-f4ad24b0fc4e@default> <2fefcbaf-9417-4f57-93af-490ea73aea98@default> NNTP-Posting-Host: plane.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Trace: ger.gmane.org 1392101099 15497 80.91.229.3 (11 Feb 2014 06:44:59 GMT) X-Complaints-To: usenet@ger.gmane.org NNTP-Posting-Date: Tue, 11 Feb 2014 06:44:59 +0000 (UTC) Cc: 15117@debbugs.gnu.org, Lars Ingebrigtsen To: Juanma Barranquero Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Tue Feb 11 07:45:06 2014 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([208.118.235.17]) by plane.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1WD75d-0007z3-Dw for geb-bug-gnu-emacs@m.gmane.org; Tue, 11 Feb 2014 07:45:05 +0100 Original-Received: from localhost ([::1]:59878 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WD75d-0006H3-2Y for geb-bug-gnu-emacs@m.gmane.org; Tue, 11 Feb 2014 01:45:05 -0500 Original-Received: from eggs.gnu.org ([2001:4830:134:3::10]:57621) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WD74l-00056s-TD for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 01:44:20 -0500 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1WD74d-0003uA-96 for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 01:44:11 -0500 Original-Received: from debbugs.gnu.org ([140.186.70.43]:34516) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1WD74d-0003u6-44 for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 01:44:03 -0500 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.80) (envelope-from ) id 1WD74c-0007Jc-4k for bug-gnu-emacs@gnu.org; Tue, 11 Feb 2014 01:44:02 -0500 X-Loop: help-debbugs@gnu.org Resent-From: Drew Adams Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Tue, 11 Feb 2014 06:44:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 15117 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: wontfix Original-Received: via spool by 15117-submit@debbugs.gnu.org id=B15117.139210100028046 (code B ref 15117); Tue, 11 Feb 2014 06:44:02 +0000 Original-Received: (at 15117) by debbugs.gnu.org; 11 Feb 2014 06:43:20 +0000 Original-Received: from localhost ([127.0.0.1]:42411 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WD73v-0007IH-9b for submit@debbugs.gnu.org; Tue, 11 Feb 2014 01:43:20 -0500 Original-Received: from userp1040.oracle.com ([156.151.31.81]:42496) by debbugs.gnu.org with esmtp (Exim 4.80) (envelope-from ) id 1WD73s-0007I0-B7 for 15117@debbugs.gnu.org; Tue, 11 Feb 2014 01:43:17 -0500 Original-Received: from ucsinet22.oracle.com (ucsinet22.oracle.com [156.151.31.94]) by userp1040.oracle.com (Sentrion-MTA-4.3.2/Sentrion-MTA-4.3.2) with ESMTP id s1B6hAkk023958 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=OK); Tue, 11 Feb 2014 06:43:10 GMT Original-Received: from userz7021.oracle.com (userz7021.oracle.com [156.151.31.85]) by ucsinet22.oracle.com (8.14.5+Sun/8.14.5) with ESMTP id s1B6h9cr018647 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=FAIL); Tue, 11 Feb 2014 06:43:10 GMT Original-Received: from abhmp0005.oracle.com (abhmp0005.oracle.com [141.146.116.11]) by userz7021.oracle.com (8.14.4+Sun/8.14.4) with ESMTP id s1B6h95J007454; Tue, 11 Feb 2014 06:43:09 GMT In-Reply-To: X-Priority: 3 X-Mailer: Oracle Beehive Extensions for Outlook 2.0.1.8 (707110) [OL 12.0.6680.5000 (x86)] X-Source-IP: ucsinet22.oracle.com [156.151.31.94] X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.15 Precedence: list X-detected-operating-system: by eggs.gnu.org: GNU/Linux 3.x X-Received-From: 140.186.70.43 X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:85361 Archived-At: > > Motion functions are not what is typically meant by a > > side-effect function. In Emacs, in the sense of modifying buffer contents. That was what I meant. No, I was not clear enough. But it doesn't really matter. That is anyway *not* a criterion I use for whether a Lisp function should have a defined and documented return value. My criterion for that is just whether such a value is useful and can be counted on. If so, then I say we should let users know that they can count on it. Simple as that. > Why not? Functions intended to move the point are as prototypically > side-effect functions as you can get. That goto-char returns > POSITION is a moderately useful, but not-at-all necessary commodity. > goto-char moving the point as a side effect is its whole raison d'=C3=AAt= re. Agreed; it is. And the resulting position is thus an important part of its effect. And it is handy to use that value directly. It always has been. There is nothing special about this. And nothing special about `goto-char' or `skip-chars-forward' vs `forward-char'. That's the point. Are you arguing not to document `goto-char's return value, as well? And so to discourage its use? After all, one doesn't need to depend on it - it's certainly enough to depend on the side effect and then call `point' to get the new position. If so, go for it. Then what have you gained? Greater liberty for the implementation to change? Bof. More readable code? Bof. Code that is more functional or side-effect free? Certainly not. > > They do not change the contents of the buffer, for > > example, in the sense of `buffer-modified-p'. >=20 > Why would you restrict the definition of "side effects" to > changing the buffer? I don't, actually. Whether something constitutes a "side effect" is relative. This is what I wrote, which engendered the current excitement: If, for some special (good) reason, code should not rely on the return value of some function, then this fact should be stated explicitly in the doc: "This function is used only for its side effects; the return value is undefined." This is Lisp, not C - return values are the norm, not the exception. I was suggesting boilerplate text similar to what we often write for functions, such as `mapc', where we point out that the return value is not to be relied on. We mention side effects here because if the return value is not to be depended on then what else is there, besides the side effect? Nada. We let users know that side effects are (necessarily) the "whole raison d'=C3=AAtre" in that case. That is precisely what the Common Lisp doc does, for example: call attention to the relatively *few* cases where the return value is *not* to be counted on. Lisps have always tended to provide reasonable return values as a general rule. Regardless, BTW, of whether a given function happens to perform side effects. It is not because a function performs side effects that its return value should not be counted on (and so documented). It is because the return value of a given function should not be counted on that it should not be documented (actually, it should be documented that the return value cannot be counted on). And such functions are therefore used for side effect only. There are certain Common Lisp "functions" for which no return value is documented, and which are _called out as such_, explicitly. (And the doc typically says something like what I said above: Use this for its side effects only; do not count on its return value being anything in particular (it can vary among implementations etc.) Such functions are the exception to the rule - in spite of the fact that most Common Lisp "functions" can have side effects. And such an exception is often for reasons of implementation - in particular, to allow different implementors more freedom of implementation. (Common Lisp, unlike GNU Emacs, is intended to have multiple implementations, including for unforeseen situations and uses.) So really the question has nothing particularly to do with side effects, beyond the concerns just mentioned. I should not have mentioned not-even-modifying-buffer-contents in this context. It's all about what we want for programmers. Should they get a useful return value for the given function or not? That's the only question. Consider `when', for instance. I, for one, adopt the convention often used with Common Lisp of NOT using the return value. Why? To signal the programmer intention that what is happening is for the side effects and not for the return value - i.e., that in that particular context, the return value is not important. IOW, this is to help readers of the code; nothing more. That convention makes sense for `when' and `unless' especially because there are alternatives to signal just the opposite programmer intention: I use `if', `and', or `or' when the return value is significant, precisely to show that, for readability. If you were to argue that we should not document the return value of `when' or `unless' you would get no argument from me. (Well, actually, I would again suggest saying explicitly that one should not count on the return value.) This, in spite of the fact that `if', `and', and `or' can, just like `when' and `unless', be used in code that produces side effects. It's really not about side effects at all. (I find it ironic that some of those who've jumped on this to scream that programmers should not be able to count on the return value of `forward-sexp' nevertheless count on the return value of `when' in the code they write, something I won't do.) So I am not against documenting return values for some, even most, functions that perform side effects, including effects that might modify the buffer, if it can be shown that: (a) there is no special benefit (e.g. wrt implementation or for users) to *not* guaranteeing a known return value for users or (b) there is no particularly useful value to return. In the case of the motion functions, there is a useful value to return: the destination position. And my question about that is "Why not?". I've seen no response to that question, so far. Why not? > `recenter' has no documented return value, and does not > modify the buffer. Would you deny that it exists to recenter > as a side effect? No more than I would deny that `goto-char' or `skip-chars-forward' exists to move point. I don't see why that prohibits providing the new `point' (or perhaps even the starting position) as a useful return value, however. I'm not sure the resulting position is particularly useful in the case of `recenter', but if you proposed returning it and documenting that, I might not object. Why not? I don't have a great reason why not for `recenter' - do you? Let's be clear. No one is proposing that additional side effects be introduced anywhere here! This is not pure-function-vs-procedure. These are all procedures. They move point. The position attained is in most cases a reasonable return value, and costs little or nothing to return. So why not? That's all. It is natural to return a value readily available from the implementation. I would not propose that a definition go out of its way to obtain a useful value to return in such cases. But it seems obvious to me that there is no a priori reason for a simple motion function *not* to return a known value such as the position moved to. I gave several examples of motion functions where we already do that. Why do we? Why shouldn't we? Look at those functions. See if you would really argue that we should not document their return values and let users depend on them. See if you want to shout "side effects!" or some other battle cry as a reason for making such a change. Then tell me what we would gain by that. Just what do we gain by not returning the new position or not telling users that we return it? That's really the only question here. And I haven't heard a single argument about that yet. Forget about whether this or that function performs side effects. Please answer the question of why we should not let users write code that counts on the moved-to position as a return value.