4:58 p.m.
NOTE: This patch has been committed.
Back in January, Alan made a suggestion on the FSF’s emacs-devel that was,
as his suggestions so often are, full of good sense.
http://article.gmane.org/gmane.emacs.devel/49575 for the particular changes
that I’ve incorporated in this patch; at the same time, I’ve also made the
CL macro documentation a bit clearer and more consistent.
lisp/ChangeLog addition:
2006-04-16 Aidan Kehoe <kehoea(a)parhasard.net>
* cl.el (incf):
* cl.el (decf):
* cl.el (pop):
* cl.el (push):
* cl.el (pushnew):
Docstring clarifications; drop non-standard formatting for incf,
decf, pop, move to GNU's parameter names for push, pushnew since
they make it much easier to remember the right order.
src/ChangeLog addition:
2006-04-16 Aidan Kehoe <kehoea(a)parhasard.net>
* data.c (Fconsp):
* data.c (Fsymbolp):
* data.c (Fcar):
* data.c (Flistp):
* data.c (Fsetcar):
* data.c (Fsetcdr):
* data.c (Flss):
* data.c (Fgtr):
Short docstring clarifications to make life easier for people who
are learning Lisp; explain what a cons is in the consp docstring,
what a symbol is in the symbolp docstring, and so forth. Thank you
Alan Mackenzie on emacs-devel.
Expand on "monotonically increasing" and "monotonically
decreasing" in the Flss and Fgtr docstrings.
XEmacs Trunk source patch:
Diff command: cvs -q diff -u
Files affected: src/data.c lisp/cl.el
Index: lisp/cl.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/cl.el,v
retrieving revision 1.15
diff -u -u -r1.15 cl.el
--- lisp/cl.el 2005/01/26 09:53:32 1.15
+++ lisp/cl.el 2006/04/16 15:29:57
＠＠ -132,7 +132,7 ＠＠
;;; can safely be used in .emacs files.
(defmacro incf (place &optional x)
- "(incf PLACE [X]): increment PLACE by X (1 by default).
+ "Increment PLACE by X (1 by default).
PLACE may be a symbol, or any generalized variable allowed by `setf'.
The return value is the incremented value of PLACE."
(if (symbolp place)
＠＠ -142,7 +142,7 ＠＠
(list 'callf '+ place (or x 1))))
(defmacro decf (place &optional x)
- "(decf PLACE [X]): decrement PLACE by X (1 by default).
+ "Decrement PLACE by X (1 by default).
PLACE may be a symbol, or any generalized variable allowed by `setf'.
The return value is the decremented value of PLACE."
(if (symbolp place)
＠＠ -150,7 +150,7 ＠＠
(list 'callf '- place (or x 1))))
(defmacro pop (place)
- "(pop PLACE): remove and return the head of the list stored in PLACE.
+ "Remove and return the head of the list stored in PLACE.
Analogous to (prog1 (car PLACE) (setf PLACE (cdr PLACE))), though more
careful about evaluating each argument only once and in the right order.
PLACE may be a symbol, or any generalized variable allowed by `setf'."
＠＠ -158,21 +158,22 ＠＠
`(car (prog1 ,place (setq ,place (cdr ,place))))
(cl-do-pop place)))
-(defmacro push (x place)
- "(push X PLACE): insert X at the head of the list stored in PLACE.
-Analogous to (setf PLACE (cons X PLACE)), though more careful about
-evaluating each argument only once and in the right order. PLACE may
+(defmacro push (newelt listname)
+ "Add NEWELT to the list stored in LISTNAME.
+Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful about
+evaluating each argument only once and in the right order. LISTNAME may
be a symbol, or any generalized variable allowed by `setf'."
- (if (symbolp place) `(setq ,place (cons ,x ,place))
- (list 'callf2 'cons x place)))
+ (if (symbolp listname) `(setq ,listname (cons ,newelt ,listname))
+ (list 'callf2 'cons newelt listname)))
-(defmacro pushnew (x place &rest keys)
- "(pushnew X PLACE): insert X at the head of the list if not already there.
-Like (push X PLACE), except that the list is unmodified if X is `eql' to
-an element already on the list.
+(defmacro pushnew (newelt listname &rest keys)
+ "Add NEWELT to the list stored in LISTNAME, unless it's already there.
+Like (push NEWELT LISTNAME), except that the list is unmodified if NEWELT is
+`eql' to an element already on the list.
Keywords supported: :test :test-not :key"
- (if (symbolp place) (list 'setq place (list* 'adjoin x place keys))
- (list* 'callf2 'adjoin x place keys)))
+ (if (symbolp listname) (list 'setq listname
+ (list* 'adjoin newelt listname keys))
+ (list* 'callf2 'adjoin newelt listname keys)))
(defun cl-set-elt (seq n val)
(if (listp seq) (setcar (nthcdr n seq) val) (aset seq n val)))
Index: src/data.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/data.c,v
retrieving revision 1.65
diff -u -u -r1.65 data.c
--- src/data.c 2005/10/24 10:07:35 1.65
+++ src/data.c 2006/04/16 15:29:58
＠＠ -216,6 +216,11 ＠＠
DEFUN ("consp", Fconsp, 1, 1, 0, /*
Return t if OBJECT is a cons cell. `nil' is not a cons cell.
+
+A cons cell is a Lisp object (an area in memory) comprising two pointers
+called the CAR and the CDR. Each of these pointers can point to any other
+Lisp object. The common Lisp data type, the list, is a specially-structured
+series of cons cells.
*/
(object))
{
＠＠ -232,6 +237,10 ＠＠
DEFUN ("listp", Flistp, 1, 1, 0, /*
Return t if OBJECT is a list. `nil' is a list.
+
+A list is implemented as a series of cons cells structured such that the CDR
+of each cell either points to another cons cell or to `nil', the special
+Lisp value for both Boolean false and the empty list.
*/
(object))
{
＠＠ -256,6 +265,9 ＠＠
DEFUN ("symbolp", Fsymbolp, 1, 1, 0, /*
Return t if OBJECT is a symbol.
+
+A symbol is a Lisp object with a name. It can optionally have any and all of
+a value, a property list and an associated function.
*/
(object))
{
＠＠ -600,19 +612,21 ＠＠
/* Extract and set components of lists */
DEFUN ("car", Fcar, 1, 1, 0, /*
-Return the car of LIST. If arg is nil, return nil.
-Error if arg is not nil and not a cons cell. See also `car-safe'.
+Return the car of CONS. If CONS is nil, return nil.
+The car of a list or a dotted pair is its first element.
+
+Error if CONS is not nil and not a cons cell. See also `car-safe'.
*/
- (list))
+ (cons))
{
while (1)
{
- if (CONSP (list))
- return XCAR (list);
- else if (NILP (list))
+ if (CONSP (cons))
+ return XCAR (cons);
+ else if (NILP (cons))
return Qnil;
else
- list = wrong_type_argument (Qlistp, list);
+ cons = wrong_type_argument (Qlistp, cons);
}
}
＠＠ -625,19 +639,22 ＠＠
}
DEFUN ("cdr", Fcdr, 1, 1, 0, /*
-Return the cdr of LIST. If arg is nil, return nil.
+Return the cdr of CONS. If CONS is nil, return nil.
+The cdr of a list is the list without its first element. The cdr of a
+dotted pair (A . B) is the second element, B.
+
Error if arg is not nil and not a cons cell. See also `cdr-safe'.
*/
- (list))
+ (cons))
{
while (1)
{
- if (CONSP (list))
- return XCDR (list);
- else if (NILP (list))
+ if (CONSP (cons))
+ return XCDR (cons);
+ else if (NILP (cons))
return Qnil;
else
- list = wrong_type_argument (Qlistp, list);
+ cons = wrong_type_argument (Qlistp, cons);
}
}
＠＠ -651,6 +668,7 ＠＠
DEFUN ("setcar", Fsetcar, 2, 2, 0, /*
Set the car of CONS-CELL to be NEWCAR. Return NEWCAR.
+The car of a list or a dotted pair is its first element.
*/
(cons_cell, newcar))
{
＠＠ -663,6 +681,8 ＠＠
DEFUN ("setcdr", Fsetcdr, 2, 2, 0, /*
Set the cdr of CONS-CELL to be NEWCDR. Return NEWCDR.
+The cdr of a list is the list without its first element. The cdr of a
+dotted pair (A . B) is the second element, B.
*/
(cons_cell, newcdr))
{
＠＠ -986,7 +1006,12 ＠＠
DEFUN ("<", Flss, 1, MANY, 0, /*
Return t if the sequence of arguments is monotonically increasing.
-The arguments may be numbers, characters or markers.
+
+(That is, if there is a second argument, it must be numerically greater than
+the first. If there is a third, it must be numerically greater than the
+second, and so on.) At least one argument is required.
+
+The arguments may be numbers, characters or markers.
*/
(int nargs, Lisp_Object *args))
{
＠＠ -995,6 +1020,11 ＠＠
DEFUN (">", Fgtr, 1, MANY, 0, /*
Return t if the sequence of arguments is monotonically decreasing.
+
+(That is, if there is a second argument, it must be numerically less than
+the first. If there is a third, it must be numerically less than the
+second, and so forth.) At least one argument is required.
+
The arguments may be numbers, characters or markers.
*/
(int nargs, Lisp_Object *args))
--
In the beginning God created the heavens and the earth. And God was a
bug-eyed, hexagonal smurf with a head of electrified hair; and God said:
“Si, mi chiamano Mimi...”
11:29 a.m.
This isn't a veto, but
>>>> "Aidan" == Aidan Kehoe
<kehoea(a)parhasard.net> writes:
-(defmacro push (x place)
- "(push X PLACE): insert X at the head of the list stored in PLACE.
-Analogous to (setf PLACE (cons X PLACE)), though more careful about
-evaluating each argument only once and in the right order. PLACE may
+(defmacro push (newelt listname)
+ "Add NEWELT to the list stored in LISTNAME.
+Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful about
+evaluating each argument only once and in the right order. LISTNAME may
This wording is not an improvement; "add" could be interpreted to mean
"append" or even "insert at some arbitrary, possibly variable,
position." Also, in XEmacs Lisp PLACE need not refer to a list:
(let ((x 'y))
(push 'z x)
x)
=> (z . y)
-(defmacro pushnew (x place &rest keys)
- "(pushnew X PLACE): insert X at the head of the list if not already there.
-Like (push X PLACE), except that the list is unmodified if X is `eql' to
-an element already on the list.
+(defmacro pushnew (newelt listname &rest keys)
+ "Add NEWELT to the list stored in LISTNAME, unless it's already there.
+Like (push NEWELT LISTNAME), except that the list is unmodified if NEWELT is
+`eql' to an element already on the list.
Ditto, except worse since the pseudo-code isn't present.
All of the following could be improved by rewriting to refer to
related functions. Eg,
+A cons cell is a Lisp object (an area in memory) comprising two pointers
+called the CAR and the CDR. Each of these pointers can point to any other
+Lisp object. The common Lisp data type, the list, is a specially-structured
+series of cons cells.
A cons cell is a Lisp object containing two references to
arbitrary Lisp objects. The references are accessed with `car'
and `cdr', and mutated with `setcar' and `setcdr' respectively.
For historical reasons, the aliases `rplaca' and `rplacd' (for
`setcar' and `setcdr') are supported. Many structures are built
up from cons cells (lists, alists, plists).
+A list is implemented as a series of cons cells structured such that the CDR
+of each cell either points to another cons cell or to `nil', the special
+Lisp value for both Boolean false and the empty list.
A list is either the Lisp object nil (a symbol), interpreted as
the empty list in this context, or a cons cell whose CDR refers to
either nil or a cons cell. A "proper list" contains no cycles.
+A symbol is a Lisp object with a name. It can optionally have any and all of
+a value, a property list and an associated function.
A symbol is a Lisp object with a name, and that name always refers
to the same symbol (with a few exceptions, which must be
explicitly invoked). The symbol may be used as a variable (ie, to
contain a value) or function in Lisp code. It also has a property
list which may be accessed with `get' and mutated with `put'.
etc, etc
--
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Ask not how you can "do" free software business;
ask what your business can "do for" free software.
9:17 p.m.
New subject: [COMMIT] Re: Docstring improvements for basic Lisp functions, CL
NOTE: This patch has been committed.
Ar an seachtú lá déag de mí Aibréan, scríobh Stephen J. Turnbull>:
[on my changes to push] This wording is not an improvement;
"add" could
be interpreted to mean "append" or even "insert at some arbitrary,
possibly variable, position." Also, in XEmacs Lisp PLACE need not refer
to a list [...]
[on pushnew] Ditto, except worse since the pseudo-code isn't present.
Okay, points taken on board.
All of the following could be improved by rewriting to refer to
related functions. Eg,
+A cons cell is a Lisp object (an area in memory) comprising two pointers
+called the CAR and the CDR. Each of these pointers can point to any other
+Lisp object. The common Lisp data type, the list, is a specially-structured
+series of cons cells.
A cons cell is a Lisp object containing two references to
arbitrary Lisp objects. The references are accessed with `car'
and `cdr', and mutated with `setcar' and `setcdr' respectively.
For historical reasons, the aliases `rplaca' and `rplacd' (for
`setcar' and `setcdr') are supported. Many structures are built
up from cons cells (lists, alists, plists). [...]
(So much passive voice! Are you sure you were born in the US? :-)
I’ve taken that and the rest of your mail on board, but not in its entirety
as I did for the cl.el changes. I think we can have equally legitimate
differing opinions on questions of prose style.
lisp/ChangeLog addition:
2006-04-23 Aidan Kehoe <kehoea(a)parhasard.net>
* cl.el (push):
* cl.el (pushnew):
Take on board Stephen's criticism of my last changes to the CL
docstrings.
src/ChangeLog addition:
2006-04-23 Aidan Kehoe <kehoea(a)parhasard.net>
* alloc.c:
* data.c:
* data.c (Fconsp):
* data.c (Flistp):
Take on board feedback from Stephen on my last change; move the
explanation of what a cons is to the cons docstring, add cross
references to that from the consp and atomp docstrings.
XEmacs Trunk source patch:
Diff command: cvs -q diff -u
Files affected: src/data.c src/alloc.c lisp/cl.el
Index: lisp/cl.el
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/lisp/cl.el,v
retrieving revision 1.16
diff -u -u -r1.16 cl.el
--- lisp/cl.el 2006/04/16 15:54:16 1.16
+++ lisp/cl.el 2006/04/23 20:07:35
＠＠ -159,15 +159,17 ＠＠
(cl-do-pop place)))
(defmacro push (newelt listname)
- "Add NEWELT to the list stored in LISTNAME.
-Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful about
-evaluating each argument only once and in the right order. LISTNAME may
-be a symbol, or any generalized variable allowed by `setf'."
+ "Add NEWELT at the beginning of the list stored in LISTNAME.
+Analogous to (setf LISTNAME (cons NEWELT LISTNAME)), though more careful
+about evaluating each argument only once and in the right order. LISTNAME
+may be a symbol, or any generalized variable allowed by `setf'; that is, it
+does not necessarily have to be a list, though `push' is most often used on
+lists. "
(if (symbolp listname) `(setq ,listname (cons ,newelt ,listname))
(list 'callf2 'cons newelt listname)))
(defmacro pushnew (newelt listname &rest keys)
- "Add NEWELT to the list stored in LISTNAME, unless it's already there.
+ "Add NEWELT at the beginning of LISTNAME, unless it's already in LISTNAME.
Like (push NEWELT LISTNAME), except that the list is unmodified if NEWELT is
`eql' to an element already on the list.
Keywords supported: :test :test-not :key"
Index: src/alloc.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/alloc.c,v
retrieving revision 1.125
diff -u -u -r1.125 alloc.c
--- src/alloc.c 2006/03/26 15:24:26 1.125
+++ src/alloc.c 2006/04/23 20:07:39
＠＠ -1255,7 +1255,16 ＠＠
Lisp_Cons);
DEFUN ("cons", Fcons, 2, 2, 0, /*
-Create a new cons, give it CAR and CDR as components, and return it.
+Create a new cons cell, give it CAR and CDR as components, and return it.
+
+A cons cell is a Lisp object (an area in memory) made up of two pointers
+called the CAR and the CDR. Each of these pointers can point to any other
+Lisp object. The common Lisp data type, the list, is a specially-structured
+series of cons cells.
+
+The pointers are accessed from Lisp with `car' and `cdr', and mutated with
+`setcar' and `setcdr' respectively. For historical reasons, the aliases
+`rplaca' and `rplacd' (for `setcar' and `setcdr') are supported.
*/
(car, cdr))
{
Index: src/data.c
===================================================================
RCS file: /pack/xemacscvs/XEmacs/xemacs/src/data.c,v
retrieving revision 1.66
diff -u -u -r1.66 data.c
--- src/data.c 2006/04/16 15:54:21 1.66
+++ src/data.c 2006/04/23 20:07:40
＠＠ -217,10 +217,8 ＠＠
DEFUN ("consp", Fconsp, 1, 1, 0, /*
Return t if OBJECT is a cons cell. `nil' is not a cons cell.
-A cons cell is a Lisp object (an area in memory) comprising two pointers
-called the CAR and the CDR. Each of these pointers can point to any other
-Lisp object. The common Lisp data type, the list, is a specially-structured
-series of cons cells.
+See the documentation for `cons' or the Lisp manual for more details on what
+a cons cell is.
*/
(object))
{
＠＠ -229,6 +227,9 ＠＠
DEFUN ("atom", Fatom, 1, 1, 0, /*
Return t if OBJECT is not a cons cell. `nil' is not a cons cell.
+
+See the documentation for `cons' or the Lisp manual for more details on what
+a cons cell is.
*/
(object))
{
＠＠ -238,9 +239,9 ＠＠
DEFUN ("listp", Flistp, 1, 1, 0, /*
Return t if OBJECT is a list. `nil' is a list.
-A list is implemented as a series of cons cells structured such that the CDR
-of each cell either points to another cons cell or to `nil', the special
-Lisp value for both Boolean false and the empty list.
+A list is either the Lisp object nil (a symbol), interpreted as the empty
+list in this context, or a cons cell whose CDR refers to either nil or a
+cons cell. A "proper list" contains no cycles.
*/
(object))
{
--
In the beginning God created the heavens and the earth. And God was a
bug-eyed, hexagonal smurf with a head of electrified hair; and God said:
“Si, mi chiamano Mimi...”
7:39 a.m.
New subject: [COMMIT] Re: Docstring improvements for basic Lisp functions, CL
>>>> "Aidan" == Aidan Kehoe
<kehoea(a)parhasard.net> writes:
Aidan> I think we can have equally legitimate differing opinions
Aidan> on questions of prose style.
Sure. This is a vast improvement over the originals.
N.B. In this case it's arguable that some change in the direction I
suggested is a GoodThang[tm], but (unless there's an outright false
statement, which is a bug) it's always reasonable to say "My change
accomplishes the improvements I wanted ... I don't object to yours,
but I have higher priority things to do. Feel free!"
--
School of Systems and Information Engineering http://turnbull.sk.tsukuba.ac.jp
University of Tsukuba Tennodai 1-1-1 Tsukuba 305-8573 JAPAN
Ask not how you can "do" free software business;
ask what your business can "do for" free software.
6830
days inactive
6838
days old
3 comments
2 participants
participants (2)
-
Aidan Kehoe -
Stephen J. Turnbull