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...”