From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: MON KEY Newsgroups: gmane.emacs.bugs Subject: bug#6591: 24.0.50; incorrect doc for `catch' Date: Sat, 10 Jul 2010 01:44:40 -0400 Message-ID: References: NNTP-Posting-Host: lo.gmane.org Mime-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable X-Trace: dough.gmane.org 1278741621 11003 80.91.229.12 (10 Jul 2010 06:00:21 GMT) X-Complaints-To: usenet@dough.gmane.org NNTP-Posting-Date: Sat, 10 Jul 2010 06:00:21 +0000 (UTC) To: 6591@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Sat Jul 10 08:00:18 2010 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane.org Original-Received: from lists.gnu.org ([199.232.76.165]) by lo.gmane.org with esmtp (Exim 4.69) (envelope-from ) id 1OXT6l-0000q8-Bz for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 08:00:15 +0200 Original-Received: from localhost ([127.0.0.1]:40892 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXT6k-0006a0-M5 for geb-bug-gnu-emacs@m.gmane.org; Sat, 10 Jul 2010 02:00:14 -0400 Original-Received: from [140.186.70.92] (port=36379 helo=eggs.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1OXT6a-0006Zt-OY for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 02:00:06 -0400 Original-Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.69) (envelope-from ) id 1OXT6Y-0007rp-62 for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 02:00:03 -0400 Original-Received: from debbugs.gnu.org ([140.186.70.43]:40044) by eggs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXT6Y-0007ri-4J for bug-gnu-emacs@gnu.org; Sat, 10 Jul 2010 02:00:02 -0400 Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.69) (envelope-from ) id 1OXSs2-0002S1-EU; Sat, 10 Jul 2010 01:45:02 -0400 X-Loop: help-debbugs@gnu.org In-Reply-To: Resent-From: MON KEY Original-Sender: debbugs-submit-bounces@debbugs.gnu.org Resent-To: owner@debbugs.gnu.org Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Sat, 10 Jul 2010 05:45:02 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 6591 X-GNU-PR-Package: emacs X-GNU-PR-Keywords: Original-Received: via spool by 6591-submit@debbugs.gnu.org id=B6591.12787406889401 (code B ref 6591); Sat, 10 Jul 2010 05:45:02 +0000 Original-Received: (at 6591) by debbugs.gnu.org; 10 Jul 2010 05:44:48 +0000 Original-Received: from localhost ([127.0.0.1] helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXSrn-0002Ra-BW for submit@debbugs.gnu.org; Sat, 10 Jul 2010 01:44:47 -0400 Original-Received: from mail-gw0-f44.google.com ([74.125.83.44]) by debbugs.gnu.org with esmtp (Exim 4.69) (envelope-from ) id 1OXSrl-0002RV-D0 for 6591@debbugs.gnu.org; Sat, 10 Jul 2010 01:44:46 -0400 Original-Received: by gwj15 with SMTP id 15so1729631gwj.3 for <6591@debbugs.gnu.org>; Fri, 09 Jul 2010 22:44:42 -0700 (PDT) Original-Received: by 10.150.13.18 with SMTP id 18mr2924550ybm.198.1278740680507; Fri, 09 Jul 2010 22:44:40 -0700 (PDT) Original-Received: by 10.151.98.19 with HTTP; Fri, 9 Jul 2010 22:44:40 -0700 (PDT) X-Google-Sender-Auth: E4Vuxjg-NEWVSOe0HiIS8mE56PQ X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.11 Precedence: list Resent-Date: Sat, 10 Jul 2010 01:45:02 -0400 X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.6 (newer, 3) 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: , Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.bugs:38335 Archived-At: ,---- | The description is not consistent and clear. In particular, this | part: | | "With the return point in effect, `catch' evaluates the forms of | the BODY in textual order. If the forms execute normally (without | error or nonlocal exit) the value of the last body form is | returned from the `catch'." | | "The forms of the BODY" is problematic - which BODY? And it's | incorrect. The forms within a BODY are not necessarily evaled in | textual order. `---- Given that the Emacs Lisp dialect is described as being derived from Maclisp and being a Lisp2 in some respects resembles Common Lisp the following excerpts may of interest/relevance: ---- Following from the Pitmanual "Sunday Morning Edition" The Revised Maclisp Manual Page A-5 :SOURCE (URL `http://maclisp.info/pitmanual/contro.html#5.13.3') CATCH Special Form (CATCH form [tag]) CATCH is an archaic (destined to become obsolete) special form for doing structured non-local exits. See documentation on its replacement, *CATCH. CATCH forms can be translated to *CATCH as follows: old new (CATCH form tag) (*CATCH 'tag form) (CATCH form) (*CATCH NIL form). Historically, (CATCH form) evolved to handle the fact that programmers were using (ERRSET (...(ERR)...)) to accomplish non-local returns since there was once no other way to get that functionality. CATCH and THROW were introduced so that programmers could write (CATCH (...(THROW val)...)) instead where there was really no error condition. However, it was found that confusion would often result using unlabelled CATCH/THROW because an unlablled CATCH could catch a throw it hadn't intended to. This is why named CATCH was invented. It is strongly recommended, therefore, that if you are re-writing (CATCH form) to a *CATCH according to the above rules, you also go to the extra trouble to choose some tag. This is not as easy because it involves changing related THROW's in the same module to all use the same tag (and perhaps other CATCH's, or even some *THROW's and/or *CATCH's), but it'll enhance the reliability of your code quite a lot. See also: *CATCH, CATCH-BARRIER, CATCHALL, THROW, ERRSET THROW Special Form (THROW form [tag]) THROW is an archaic (destined to become obsolete) special form. See documentation on its replacement, *THROW. THROW forms can be translated to *THROW as follows: old new (THROW form tag) (*THROW 'tag form). (THROW form) (*THROW NIL form). See also: *THROW, CATCH, ERR ;;; =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D Following from an unofficial version of dpans3-texi of ANSI Common Lisp: catch (Special Operator) Syntax: -- Special Form: catch TAG {form}* =E2=86=92 {result}* Arguments and Values: TAG--a catch tag; evaluated. FORMS--an implicit progn. RESULTS--if the FORMS exit normally, the values returned by the FORMS; if a throw occurs to the TAG, the values that are thrown. Description: =E2=80=98catch=E2=80=99 is used as the destination of a non-local control t= ransfer by =E2=80=98throw=E2=80=99. TAGS are used to find the =E2=80=98catch=E2=80=99= to which a =E2=80=98throw=E2=80=99 is transferring control. =E2=80=98(catch 'foo form)=E2=80=99 catches a =E2=80= =98(throw 'foo form)=E2=80=99 but not a =E2=80=98(throw 'bar form)=E2=80=99. The order of execution of =E2=80=98catch=E2=80=99 follows: 1. TAG is evaluated. It serves as the name of the =E2=80=98catch=E2=80= =99. 2. FORMS are then evaluated as an implicit =E2=80=98progn=E2=80=99, and t= he results of the last FORM are returned unless a =E2=80=98throw=E2=80=99 occurs. 3. If a =E2=80=98throw=E2=80=99 occurs during the execution of one of the= FORMS, control is transferred to the =E2=80=98catch=E2=80=99 form whose TAG = is =E2=80=98eq=E2=80=99 to the tag argument of the =E2=80=98throw=E2=80=99 and which is the most = recently established =E2=80=98catch=E2=80=99 with that TAG. No further evaluat= ion of FORMS occurs. 4. The TAG established by =E2=80=98catch=E2=80=99 is disestablished just = before the results are returned. If during the execution of one of the FORMS, a =E2=80=98throw=E2=80=99 is e= xecuted whose tag is =E2=80=98eq=E2=80=99 to the =E2=80=98catch=E2=80=99 tag, then = the values specified by the =E2=80=98throw=E2=80=99 are returned as the result of the dynamically most = recently established =E2=80=98catch=E2=80=99 form with that tag. The mechanism for =E2=80=98catch=E2=80=99 and =E2=80=98throw=E2=80=99 works= even if =E2=80=98throw=E2=80=99 is not within the lexical scope of =E2=80=98catch=E2=80=99. =E2=80=98throw=E2=80= =99 must occur within the dynamic extent of the evaluation of the body of a =E2=80=98catch=E2=80=99 w= ith a corresponding TAG. Examples: (catch 'dummy-tag 1 2 (throw 'dummy-tag 3) 4) =E2=86=92 3 (catch 'dummy-tag 1 2 3 4) =E2=86=92 4 (defun throw-back (tag) (throw tag t)) =E2=86=92 THROW-BACK (catch 'dummy-tag (throw-back 'dummy-tag) 2) =E2=86=92 T ;; Contrast behavior of this example with corresponding example of BLOCK. (catch 'c (flet ((c1 () (throw 'c 1))) (catch 'c (c1) (print 'unreachable)) 2)) =E2=86=92 2 Exceptional Situations: An error of type =E2=80=98control-error=E2=80=99 is signaled if =E2=80=98th= row=E2=80=99 is done when there is no suitable =E2=80=98catch=E2=80=99 TAG. See Also: throw Notes: It is customary for symbols to be used as TAGS, but any object is permitted. However, numbers should not be used because the comparison is done using =E2=80=98eq=E2=80=99. =E2=80=98catch=E2=80=99 differs from =E2=80=98block=E2=80=99 in that =E2=80= =98catch=E2=80=99 tags have dynamic scope while =E2=80=98block=E2=80=99 names have lexical scope. -- throw (Special Operator) Syntax: -- Special Form: throw tag result-form =E2=86=92| Arguments and Values: TAG--a catch tag; evaluated. RESULT-FORM--a form; evaluated as described below. Description: =E2=80=98throw=E2=80=99 causes a non-local control transfer to a =E2=80=98c= atch=E2=80=99 whose tag is =E2=80=98eq=E2=80=99 to TAG. TAG is evaluated first to produce an object called the throw tag; then RESULT-FORM is evaluated, and its results are saved. If the RESULT-FORM produces multiple values, then all the values are saved. The most recent outstanding =E2=80=98catch=E2=80=99 whose TAG is =E2=80=98eq=E2=80= =99 to the throw tag is exited; the saved results are returned as the value or values of =E2=80=98catch=E2=80=99. The transfer of control initiated by =E2=80=98throw=E2=80=99 is performed a= s described in Section 5.2. Examples: (catch 'result (setq i 0 j 0) (loop (incf j 3) (incf i) (if (=3D i 3) (throw 'result (values i j))))) =E2=86=92 3, 9 (catch nil (unwind-protect (throw nil 1) (throw nil 2))) =E2=86=92 2 The consequences of the following are undefined because the =E2=80=98catch= =E2=80=99 of =E2=80=98b=E2=80=99 is passed over by the first =E2=80=98throw=E2=80=99, he= nce portable programs must assume that its dynamic extent is terminated. The binding of the catch tag is not yet disestablished and therefore it is the target of the second =E2=80=98throw=E2=80=99. (catch 'a (catch 'b (unwind-protect (throw 'a 1) (throw 'b 2)))) The following prints "=E2=80=98The inner catch returns :SECOND-THROW=E2=80= =99" and then returns =E2=80=98:outer-catch=E2=80=99. (catch 'foo (format t "The inner catch returns ~s.~%" (catch 'foo (unwind-protect (throw 'foo :first-throw) (throw 'foo :second-throw)))) :outer-catch) =E2=96=B7 The inner catch returns :SECOND-THROW =E2=86=92 :OUTER-CATCH Exceptional Situations: If there is no outstanding catch tag that matches the throw tag, no unwinding of the stack is performed, and an error of type =E2=80=98control-error=E2=80=99 is signaled. When the error is signaled, t= he dynamic environment is that which was in force at the point of the =E2=80=98throw= =E2=80=99. See Also: block, catch, return-from, unwind-protect Notes: =E2=80=98catch=E2=80=99 and =E2=80=98throw=E2=80=99 are normally used when = the exit point must have dynamic scope (e.g., the =E2=80=98throw=E2=80=99 is not lexically enclosed = by the =E2=80=98catch=E2=80=99), while =E2=80=98block=E2=80=99 and =E2=80=98return= =E2=80=99 are used when lexical scope is sufficient. -- /s_P\