@setfilename ../info/cl
@settitle Common Lisp Extensions
+@copying
+This file documents the GNU Emacs Common Lisp emulation package.
+
+Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007
+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.2 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.
+@end quotation
+@end copying
+
@dircategory Emacs
@direntry
* CL: (cl). Partial Common Lisp support for Emacs Lisp.
@end direntry
-@iftex
@finalout
-@end iftex
-
-@ifinfo
-This file documents the GNU Emacs Common Lisp emulation package.
-
-Copyright (C) 1993 Free Software Foundation, Inc.
-
-Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' may be
-included in a translation approved by the author instead of in the
-original English.
-@end ifinfo
@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 make and distribute verbatim copies of
-this manual provided the copyright notice and this permission notice
-are preserved on all copies.
-
-@ignore
-Permission is granted to process this file through TeX and print the
-results, provided the printed document carries copying permission notice
-identical to this one except for the removal of this paragraph (this
-paragraph not being relevant to the printed manual).
-
-@end ignore
-Permission is granted to copy and distribute modified versions of this
-manual under the conditions for verbatim copying, provided also that the
-section entitled ``GNU General Public License'' is included exactly as
-in the original, and provided that the entire resulting derived work is
-distributed under the terms of a permission notice identical to this one.
-
-Permission is granted to copy and distribute translations of this manual
-into another language, under the above conditions for modified versions,
-except that the section entitled ``GNU General Public License'' may be
-included in a translation approved by the author instead of in the
-original English.
+@insertcopying
@end titlepage
@node Top, Overview, (dir), (dir)
-@chapter Common Lisp Extensions
+@chapter Introduction
@noindent
This document describes a set of Emacs Lisp facilities borrowed from
* Old CL Compatibility:: All known differences with old cl.el
* Porting Common Lisp:: Hints for porting Common Lisp code
+* GNU Free Documentation License:: The license for this documentation.
* Function Index::
* Variable Index::
@end menu
@node Overview, Program Structure, Top, Top
-@ifinfo
+@ifnottex
@chapter Overview
-@end ifinfo
-@iftex
-@section Overview
-@end iftex
+@end ifnottex
@noindent
Common Lisp is a huge language, and Common Lisp systems tend to be
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:
The package described here was written by Dave Gillespie,
@file{daveg@@synaptics.com}. It is a total rewrite of the original
1986 @file{cl.el} package by Cesar Quiroz. Most features of the
-the Quiroz package have been retained; any incompatibilities are
+Quiroz package have been retained; any incompatibilities are
noted in the descriptions below. Care has been taken in this
version to ensure that each function is defined efficiently,
concisely, and with minimal impact on the rest of the Emacs
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
Thus @code{(typep @var{object} 'null)} is equivalent to
@code{(null @var{object})}.
+@item
+The type symbol @code{atom} represents all objects that are not cons
+cells. Thus @code{(typep @var{object} 'atom)} is equivalent to
+@code{(atom @var{object})}.
+
@item
The type symbol @code{real} is a synonym for @code{number}, and
@code{fixnum} is a synonym for @code{integer}.
@var{form}.
The following Lisp forms will work as generalized variables, and
-so may legally appear in the @var{place} argument of @code{setf}:
+so may appear in the @var{place} argument of @code{setf}:
@itemize @bullet
@item
The following Emacs-specific functions are also @code{setf}-able.
@smallexample
-buffer-file-name marker-position
-buffer-modified-p match-data
-buffer-name mouse-position
-buffer-string overlay-end
-buffer-substring overlay-get
-current-buffer overlay-start
-current-case-table point
-current-column point-marker
-current-global-map point-max
-current-input-mode point-min
-current-local-map process-buffer
-current-window-configuration process-filter
-default-file-modes process-sentinel
-default-value read-mouse-position
-documentation-property screen-height
-extent-data screen-menubar
-extent-end-position screen-width
-extent-start-position selected-window
-face-background selected-screen
-face-background-pixmap selected-frame
-face-font standard-case-table
-face-foreground syntax-table
-face-underline-p window-buffer
-file-modes window-dedicated-p
-frame-height window-display-table
-frame-parameters window-height
-frame-visible-p window-hscroll
-frame-width window-point
-get-register window-start
-getenv window-width
-global-key-binding x-get-cut-buffer
-keymap-parent x-get-cutbuffer
+buffer-file-name marker-position
+buffer-modified-p match-data
+buffer-name mouse-position
+buffer-string overlay-end
+buffer-substring overlay-get
+current-buffer overlay-start
+current-case-table point
+current-column point-marker
+current-global-map point-max
+current-input-mode point-min
+current-local-map process-buffer
+current-window-configuration process-filter
+default-file-modes process-sentinel
+default-value read-mouse-position
+documentation-property screen-height
+extent-data screen-menubar
+extent-end-position screen-width
+extent-start-position selected-window
+face-background selected-screen
+face-background-pixmap selected-frame
+face-font standard-case-table
+face-foreground syntax-table
+face-underline-p window-buffer
+file-modes window-dedicated-p
+frame-height window-display-table
+frame-parameters window-height
+frame-visible-p window-hscroll
+frame-width window-point
+get-register window-start
+getenv window-width
+global-key-binding x-get-cut-buffer
+keymap-parent x-get-cutbuffer
local-key-binding x-get-secondary-selection
-mark x-get-selection
-mark-marker
+mark x-get-selection
+mark-marker
@end smallexample
Most of these have directly corresponding ``set'' functions, like
@item
A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])},
-where @var{subplace} is itself a legal generalized variable whose
+where @var{subplace} is itself a valid generalized variable whose
current value is a string, and where the value stored is also a
string. The new string is spliced into the specified part of the
destination string. For example:
Because they are implemented in terms of Emacs Lisp @code{catch}
and @code{throw}, blocks have the same overhead as actual
@code{catch} constructs (roughly two function calls). However,
-the optimizing byte compiler will optimize away the @code{catch}
+the optimizing byte compiler will optimize away the @code{catch}
if the block does
not in fact contain any @code{return} or @code{return-from} calls
that jump to it. This means that @code{do} loops and @code{defun*}
The @code{by} value is always positive, even for downward-counting
loops. Some sort of @code{from} value is required for downward
-loops; @samp{for x downto 5} is not a legal loop clause all by
+loops; @samp{for x downto 5} is not a valid loop clause all by
itself.
@item for @var{var} in @var{list} by @var{function}
Due to a minor implementation restriction, it will not work to have
more than one @code{for} clause iterating over symbols, hash tables,
keymaps, overlays, or intervals in a given @code{loop}. Fortunately,
-it would rarely if ever be useful to do so. It @emph{is} legal to mix
+it would rarely if ever be useful to do so. It @emph{is} valid to mix
one of these types of clauses with other clauses like @code{for ... to}
or @code{while}.
explicit mechanism, such as @code{finally return}, to return
the accumulated result.
-It is legal for several accumulation clauses of the same type to
+It is valid for several accumulation clauses of the same type to
accumulate into the same place. From Steele:
@example
(defsubst foo (...) ...) ; instead of defun
@end example
-@strong{Note:} This declaration remains in effect after the
+@strong{Please note:} this declaration remains in effect after the
containing source file is done. It is correct to use it to
request that a function you have defined should be inlined,
but it is impolite to use it to request inlining of an external
(get sym prop) @equiv{} (getf (symbol-plist sym) prop)
@end example
-It is legal to use @code{getf} as a @code{setf} place, in which case
-its @var{place} argument must itself be a legal @code{setf} place.
+It is valid to use @code{getf} as a @code{setf} place, in which case
+its @var{place} argument must itself be a valid @code{setf} place.
The @var{default} argument, if any, is ignored in this context.
The effect is to change (via @code{setcar}) the value cell in the
list that corresponds to @var{property}, or to cons a new property-value
* 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
integer; each different integer seed will result in a completely
different sequence of random numbers.
-It is legal to print a @code{random-state} object to a buffer or
+It is valid to print a @code{random-state} object to a buffer or
file and later read it back with @code{read}. If a program wishes
to use a sequence of pseudo-random numbers which can be reproduced
later for debugging, it can call @code{(make-random-state t)} to
@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
fed to the @var{predicate} function. For example,
@example
-(setq data (sort data 'string-lessp :key 'downcase))
+(setq data (sort* data 'string-lessp :key 'downcase))
@end example
@noindent
sorts @var{data}, a sequence of strings, into increasing alphabetical
order without regard to case. A @code{:key} function of @code{car}
-would be useful for sorting association lists.
+would be useful for sorting association lists. It should only be a
+simple accessor though, it's used heavily in the current
+implementation.
The @code{sort*} function is destructive; it sorts lists by actually
rearranging the @code{cdr} pointers in suitable fashion.
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.
do not appear in the argument list are initialized based on the
@var{default-value} in their slot descriptor. Also, @code{&optional}
and @code{&key} arguments which don't specify defaults take their
-defaults from the slot descriptor. It is legal to include arguments
+defaults from the slot descriptor. It is valid to include arguments
which don't correspond to slot names; these are useful if they are
referred to in the defaults for optional, keyword, or @code{&aux}
arguments which @emph{do} correspond to slots.
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}.
@code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use
these names because they conflict with Emacs built-ins.
-@node Porting Common Lisp, Function Index, Old CL Compatibility, Top
+@node Porting Common Lisp, GNU Free Documentation License, Old CL Compatibility, Top
@appendix Porting Common Lisp
@noindent
one, some of the features in this package are not fully compliant
with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there
are also quite a few features that this package does not provide
-at all. Here are some major omissions that you will want watch out
+at all. Here are some major omissions that you will want to watch out
for when bringing Common Lisp code into Emacs.
@itemize @bullet
recursion.
@end itemize
-@node Function Index, Variable Index, Porting Common Lisp, Top
+@node GNU Free Documentation License, Function Index, Porting Common Lisp, Top
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Function Index, Variable Index, GNU Free Documentation License, Top
@unnumbered Function Index
@printindex fn
@setchapternewpage odd
@contents
@bye
+
+@ignore
+ arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8
+@end ignore
HCoop / bpt / emacs.git / blobdiff