@setfilename ../info/cl
@settitle Common Lisp Extensions
-@dircategory Emacs
-@direntry
-* CL: (cl). Partial Common Lisp support for Emacs Lisp.
-@end direntry
-
-@iftex
-@finalout
-@end iftex
-
-@ifinfo
+@copying
This file documents the GNU Emacs Common Lisp emulation package.
-Copyright (C) 1993 Free Software Foundation, Inc.
-
+Copyright (C) 1993, 2002 Free Software Foundation, Inc.
+@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Documentation License. If you want to distribute this document
separately from the collection, you can do so by adding a copy of the
license to the document, as described in section 6 of the license.
-@end ifinfo
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* CL: (cl). Partial Common Lisp support for Emacs Lisp.
+@end direntry
+
+@finalout
@titlepage
@sp 6
@center Dave Gillespie
@center daveg@@synaptics.com
@page
-
@vskip 0pt plus 1filll
-Copyright @copyright{} 1993 Free Software Foundation, Inc.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with no
-Invariant Sections, with the Front-Cover texts being ``A GNU
-Manual'', and with the Back-Cover Texts as in (a) below. A copy of the
-license is included in the section entitled ``GNU Free Documentation
-License'' in the Emacs manual.
-
-(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
-this GNU Manual, like GNU software. Copies published by the Free
-Software Foundation raise funds for GNU development.''
-
-This document is part of a collection distributed under the GNU Free
-Documentation License. If you want to distribute this document
-separately from the collection, you can do so by adding a copy of the
-license to the document, as described in section 6 of the license.
+@insertcopying
@end titlepage
@node Top, Overview, (dir), (dir)
implementation of Common Lisp, @dfn{CL} adds enough functionality
to make Emacs Lisp programming significantly more convenient.
+@strong{Please note:} the @dfn{CL} functions are not standard parts of
+the Emacs Lisp name space, so it is legitimate for users to define
+them with other, conflicting meanings. To avoid conflicting with
+those user activities, we have a policy that packages installed in
+Emacs must not load @dfn{CL} at run time. (It is ok for them to load
+@dfn{CL} at compile time only, with @code{eval-when-compile}, and use
+the macros it provides.) If you are writing packages that you plan to
+distribute and invite widespread use for, you might want to observe
+the same rule.
+
Some Common Lisp features have been omitted from this package
for various reasons:
member* assoc* rassoc* get*
remove* delete* mapcar* sort*
floor* ceiling* truncate* round*
-mod* rem* random* last*
+mod* rem* random*
@end example
Internal function and variable names in the package are prefixed
@example
eql floatp-safe endp
evenp oddp plusp minusp
-butlast nbutlast caaar .. cddddr
+caaar .. cddddr
list* ldiff rest first .. tenth
copy-list subst mapcar* [2]
adjoin [3] acons pairlis pop [4]
keep both @code{find-thing} and @code{member*} from complaining
about each others' keywords in the arguments.
-As a (significant) performance optimization, this package
-implements the scan for keyword arguments by calling @code{memq}
-to search for keywords in a ``rest'' argument. Technically
-speaking, this is incorrect, since @code{memq} looks at the
-odd-numbered values as well as the even-numbered keywords.
-The net effect is that if you happen to pass a keyword symbol
-as the @emph{value} of another keyword argument, where that
-keyword symbol happens to equal the name of a valid keyword
-argument of the same function, then the keyword parser will
-become confused. This minor bug can only affect you if you
-use keyword symbols as general-purpose data in your program;
-this practice is strongly discouraged in Emacs Lisp.
-
The fifth section of the argument list consists of @dfn{auxiliary
variables}. These are not really arguments at all, but simply
variables which are bound to @code{nil} or to the specified
* Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
* Numerical Functions:: `abs', `floor*', etc.
* Random Numbers:: `random*', `make-random-state'
-* Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
+* Implementation Parameters:: `most-positive-float'
@end menu
@iftex
@noindent
This package defines several useful constants having to with numbers.
-@defvar most-positive-fixnum
-This constant equals the largest value a Lisp integer can hold.
-It is typically @code{2^23-1} or @code{2^25-1}.
-@end defvar
-
-@defvar most-negative-fixnum
-This constant equals the smallest (most negative) value a Lisp
-integer can hold.
-@end defvar
-
The following parameters have to do with floating-point numbers.
This package determines their values by exercising the computer's
floating-point arithmetic in various ways. Because this operation
@end defun
@defun mapc function seq &rest more-seqs
-This function is like @code{mapcar*}, except that the values
-returned by @var{function} are ignored and thrown away rather
-than being collected into a list. The return value of @code{mapc}
-is @var{seq}, the first sequence.
+This function is like @code{mapcar*}, except that the values returned
+by @var{function} are ignored and thrown away rather than being
+collected into a list. The return value of @code{mapc} is @var{seq},
+the first sequence. This function is more general than the Emacs
+primitive @code{mapc}.
@end defun
@defun mapl function list &rest more-lists
The functions described here operate on lists.
@menu
-* List Functions:: `caddr', `first', `last*', `list*', etc.
+* List Functions:: `caddr', `first', `list*', etc.
* Substitution of Expressions:: `subst', `sublis', etc.
* Lists as Sets:: `member*', `adjoin', `union', etc.
* Association Lists:: `assoc*', `rassoc*', `acons', `pairlis'
@code{length} function would get stuck if given a circular list.)
@end defun
-@defun last* x &optional n
-This function returns the last cons, or the @var{n}th-to-last cons,
-of the list @var{x}. If @var{n} is omitted it defaults to 1.
-The ``last cons'' means the first cons cell of the list whose
-@code{cdr} is not another cons cell. (For normal lists, the
-@code{cdr} of the last cons will be @code{nil}.) This function
-returns @code{nil} if @var{x} is @code{nil} or shorter than
-@var{n}. Note that the last @emph{element} of the list is
-@code{(car (last @var{x}))}.
-
-The Emacs function @code{last} does the same thing
-except that it does not handle the optional argument @var{n}.
-@end defun
-
-@defun butlast x &optional n
-This function returns the list @var{x} with the last element,
-or the last @var{n} elements, removed. If @var{n} is greater
-than zero it makes a copy of the list so as not to damage the
-original list. In general, @code{(append (butlast @var{x} @var{n})
-(last @var{x} @var{n}))} will return a list equal to @var{x}.
-@end defun
-
-@defun nbutlast x &optional n
-This is a version of @code{butlast} that works by destructively
-modifying the @code{cdr} of the appropriate element, rather than
-making a copy of the list.
-@end defun
-
@defun list* arg &rest others
This function constructs a list of its arguments. The final
argument becomes the @code{cdr} of the last cell constructed.
Common Lisp compliance has in general not been sacrificed for the
sake of efficiency. A few exceptions have been made for cases
where substantial gains were possible at the expense of marginal
-incompatibility. One example is the use of @code{memq} (which is
-treated very efficiently by the byte-compiler) to scan for keyword
-arguments; this can become confused in rare cases when keyword
-symbols are used as both keywords and data values at once. This
-is extremely unlikely to occur in practical code, and the use of
-@code{memq} allows functions with keyword arguments to be nearly
-as fast as functions that use @code{&optional} arguments.
+incompatibility.
The Common Lisp standard (as embodied in Steele's book) uses the
phrase ``it is an error if'' to indicate a situation which is not
keyword does not work in @code{defmacro} argument lists (except
inside recursive argument lists).
-In order to allow an efficient implementation, keyword arguments use
-a slightly cheesy parser which may be confused if a keyword symbol
-is passed as the @emph{value} of another keyword argument.
-(Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})}
-is used to scan for @code{:@var{keyword}} among the supplied
-keyword arguments.)
-
The @code{eql} and @code{equal} predicates do not distinguish
between IEEE floating-point plus and minus zero. The @code{equalp}
predicate has several differences with Common Lisp; @pxref{Predicates}.