From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.org!not-for-mail From: Luc Teirlinck Newsgroups: gmane.emacs.devel Subject: Re: lispref/variables.texi Date: Fri, 24 Jun 2005 19:56:47 -0500 (CDT) Message-ID: <200506250056.j5P0uls11730@raven.dms.auburn.edu> References: <200506240108.j5O182U06623@raven.dms.auburn.edu> NNTP-Posting-Host: main.gmane.org X-Trace: sea.gmane.org 1119661410 29789 80.91.229.2 (25 Jun 2005 01:03:30 GMT) X-Complaints-To: usenet@sea.gmane.org NNTP-Posting-Date: Sat, 25 Jun 2005 01:03:30 +0000 (UTC) Cc: emacs-devel@gnu.org Original-X-From: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Sat Jun 25 03:03:29 2005 Return-path: Original-Received: from lists.gnu.org ([199.232.76.165]) by ciao.gmane.org with esmtp (Exim 4.43) id 1Dlz4q-0002vx-3u for ged-emacs-devel@m.gmane.org; Sat, 25 Jun 2005 03:03:21 +0200 Original-Received: from localhost ([127.0.0.1] helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1DlzBx-0002Np-QT for ged-emacs-devel@m.gmane.org; Fri, 24 Jun 2005 21:10:41 -0400 Original-Received: from mailman by lists.gnu.org with tmda-scanned (Exim 4.43) id 1Dlz5b-0007Mx-Dd for emacs-devel@gnu.org; Fri, 24 Jun 2005 21:04:10 -0400 Original-Received: from exim by lists.gnu.org with spam-scanned (Exim 4.43) id 1Dlz5L-0007Hv-Rn for emacs-devel@gnu.org; Fri, 24 Jun 2005 21:03:52 -0400 Original-Received: from [199.232.76.173] (helo=monty-python.gnu.org) by lists.gnu.org with esmtp (Exim 4.43) id 1Dlz5L-0007HK-Md for emacs-devel@gnu.org; Fri, 24 Jun 2005 21:03:51 -0400 Original-Received: from [131.204.53.104] (helo=manatee.dms.auburn.edu) by monty-python.gnu.org with esmtp (Exim 4.34) id 1Dlz3i-0000Ct-9u for emacs-devel@gnu.org; Fri, 24 Jun 2005 21:02:10 -0400 Original-Received: from raven.dms.auburn.edu (raven.dms.auburn.edu [131.204.53.29]) by manatee.dms.auburn.edu (8.12.10/8.12.10) with ESMTP id j5P0wMCK006723; Fri, 24 Jun 2005 19:58:22 -0500 (CDT) Original-Received: (from teirllm@localhost) by raven.dms.auburn.edu (8.11.7p1+Sun/8.11.7) id j5P0uls11730; Fri, 24 Jun 2005 19:56:47 -0500 (CDT) X-Authentication-Warning: raven.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f Original-To: storm@cua.dk In-reply-to: (storm@cua.dk) X-BeenThere: emacs-devel@gnu.org X-Mailman-Version: 2.1.5 Precedence: list List-Id: "Emacs development discussions." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Original-Sender: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Errors-To: emacs-devel-bounces+ged-emacs-devel=m.gmane.org@gnu.org Xref: news.gmane.org gmane.emacs.devel:39478 X-Report-Spam: http://spam.gmane.org/gmane.emacs.devel:39478 Kim Storm wrote: To "remove" the order, you can specify a non-nil, non-numeric value for ORDER -- in that case, the element's order in the hash table is set to nil (which effitively means "no" ordering). I actually did not know that. Then a few further changes to variables.texi are needed, as well as some changes to the add-to-ordered-list docstring. The current docs suggest that only numbers or nil values for ORDER are allowed. On an unrelated note, the first lines of the docstrings of both add-to-ordered-list and add-to-list needlessly exceed the maximum allowed 67 characters. I believe that the shortened versions in the patch below are actually not only shorter, but better readable as well. Below are a proposed new patch to subr.el and a slightly revised version of my patch to variables.texi. ===File ~/subr.el-diff====================================== *** subr.el 22 Jun 2005 18:21:04 -0500 1.468 --- subr.el 24 Jun 2005 19:22:52 -0500 *************** *** 937,943 **** (set hook hook-value)))))) (defun add-to-list (list-var element &optional append) ! "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet. The test for presence of ELEMENT is done with `equal'. If ELEMENT is added, it is added at the beginning of the list, unless the optional argument APPEND is non-nil, in which case --- 937,943 ---- (set hook hook-value)))))) (defun add-to-list (list-var element &optional append) ! "Add ELEMENT to the value of LIST-VAR if it isn't there yet. The test for presence of ELEMENT is done with `equal'. If ELEMENT is added, it is added at the beginning of the list, unless the optional argument APPEND is non-nil, in which case *************** *** 959,973 **** (defun add-to-ordered-list (list-var element &optional order) ! "Add to the value of LIST-VAR the element ELEMENT if it isn't there yet. The test for presence of ELEMENT is done with `eq'. The resulting list is reordered so that the elements are in the order given by each element's numeric list order. Elements without a numeric list order are placed at the end of the list. ! If the third optional argument ORDER is non-nil, set the ! element's list order to the given value. The list order for each element is stored in LIST-VAR's `list-order' property. --- 959,976 ---- (defun add-to-ordered-list (list-var element &optional order) ! "Add ELEMENT to the value of LIST-VAR if it isn't there yet. The test for presence of ELEMENT is done with `eq'. The resulting list is reordered so that the elements are in the order given by each element's numeric list order. Elements without a numeric list order are placed at the end of the list. ! If the third optional argument ORDER is a number (integer or ! float), set the element's list order to the given value. If ! ORDER is nil or omitted, do not change the numeric order of ! ELEMENT. If ORDER has any other value, remove the numeric order ! of ELEMENT if it has one. The list order for each element is stored in LIST-VAR's `list-order' property. ============================================================ ===File ~/variables.texi-diff=============================== *** variables.texi 20 Jun 2005 17:10:57 -0500 1.66 --- variables.texi 24 Jun 2005 19:17:50 -0500 *************** *** 909,926 **** position specified by @var{order}. If @var{element} is already a member of the list, its position in the list is adjusted according to @var{order}. Membership is tested using @code{eq}. ! The valued returned is the resulting list, whether updated or not. ! The @var{order} is a number, and the elements on list are sorted in ! increasing numerical order. Elements without a numeric list order are ! placed at the end of @var{symbol}. The argument @var{symbol} is not implicitly quoted; @code{add-to-ordered-list} is an ordinary function, like @code{set} and unlike @code{setq}. Quote the argument yourself if that is what you want. ! The ordering information is stored in an alist on @var{symbol}'s @code{list-order} property. @end defun --- 909,933 ---- position specified by @var{order}. If @var{element} is already a member of the list, its position in the list is adjusted according to @var{order}. Membership is tested using @code{eq}. ! This function returns the resulting list, whether updated or not. ! The @var{order} is typically a number (integer or float), and the ! elements of the list are sorted in non-decreasing numerical order. ! ! @var{order} may also be omitted or @code{nil}. Then the numeric order ! of @var{element} stays unchanged if it already has one; otherwise, ! @var{element} has no numeric order. Elements without a numeric list ! order are placed at the end of the list, in no particular order. ! ! Any other value for @var{order} removes the numeric order of @var{element} ! if it already has one; otherwise, it is equivalent to @code{nil}. The argument @var{symbol} is not implicitly quoted; @code{add-to-ordered-list} is an ordinary function, like @code{set} and unlike @code{setq}. Quote the argument yourself if that is what you want. ! The ordering information is stored in a hash table on @var{symbol}'s @code{list-order} property. @end defun *************** *** 945,955 **** (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} @result{} (a c b d) ! (add-to-ordered-list 'foo 'b 2) ;; @r{Move @code{b}.} ! @result{} (a b c d) foo ;; @r{@code{foo} was changed.} ! @result{} (a b c d) @end example @node Variable Scoping --- 952,962 ---- (add-to-ordered-list 'foo 'd) ;; @r{Append @code{d}.} @result{} (a c b d) ! (add-to-ordered-list 'foo 'e) ;; @r{Add @code{e}}. ! @result{} (a c b e d) foo ;; @r{@code{foo} was changed.} ! @result{} (a c b e d) @end example @node Variable Scoping ============================================================