\input texinfo @c -*-texinfo-*-
@setfilename ../../info/cl
@settitle Common Lisp Extensions
+@documentencoding UTF-8
@include emacsver.texi
@copying
This file documents the GNU Emacs Common Lisp emulation package.
-Copyright @copyright{} 1993, 2001-2012 Free Software Foundation, Inc.
+Copyright @copyright{} 1993, 2001--2014 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
is included in the section entitled ``GNU Free Documentation License''.
(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
-modify this GNU manual. Buying copies from the FSF supports it in
-developing GNU and promoting software freedom.''
+modify this GNU manual.''
@end quotation
@end copying
defines aliases to the @file{cl-lib.el} definitions). Where
@file{cl-lib.el} defines a function called, for example,
@code{cl-incf}, @file{cl.el} uses the same name but without the
-@samp{cl-} prefix, e.g.@: @code{incf} in this example. There are a few
+@samp{cl-} prefix, e.g., @code{incf} in this example. There are a few
exceptions to this. First, functions such as @code{cl-defun} where
the unprefixed version was already used for a standard Emacs Lisp
function. In such cases, the @file{cl.el} version adds a @samp{*}
-suffix, e.g.@: @code{defun*}. Second, there are some obsolete features
+suffix, e.g., @code{defun*}. Second, there are some obsolete features
that are only implemented in @file{cl.el}, not in @file{cl-lib.el},
because they are replaced by other standard Emacs Lisp features.
Finally, in a very few cases the old @file{cl.el} versions do not
@node Argument Lists
@section Argument Lists
+@cindex &key
+@cindex &aux
@noindent
Emacs Lisp's notation for argument lists of functions is a subset of
@var{body}))
@end example
+@cindex destructuring, in argument list
Argument lists support @dfn{destructuring}. In Common Lisp,
destructuring is only allowed with @code{defmacro}; this package
allows it with @code{cl-defun} and other argument lists as well.
The type symbols @code{character} and @code{string-char} match
integers in the range from 0 to 255.
-@c No longer relevant, so covered by first item above (float -> floatp).
-@ignore
-@item
-The type symbol @code{float} uses the @code{cl-floatp-safe} predicate
-defined by this package rather than @code{floatp}, so it will work
-correctly even in Emacs versions without floating-point support.
-@end ignore
-
@item
The type list @code{(integer @var{low} @var{high})} represents all
integers between @var{low} and @var{high}, inclusive. Either bound
@var{type}. If @var{object} is already of that type as determined by
@code{cl-typep}, it is simply returned. Otherwise, certain types of
conversions will be made: If @var{type} is any sequence type
-(@code{string}, @code{list}, etc.) then @var{object} will be
+(@code{string}, @code{list}, etc.)@: then @var{object} will be
converted to that type if possible. If @var{type} is
@code{character}, then strings of length one and symbols with
one-character names can be coerced. If @var{type} is @code{float},
Also note that the Common Lisp functions @code{member} and @code{assoc}
use @code{eql} to compare elements, whereas Emacs Lisp follows the
MacLisp tradition and uses @code{equal} for these two functions.
-In Emacs, use @code{memq} (or @code{cl-member}) and @code{assq} (or
-@code{cl-assoc}) to get functions which use @code{eql} for comparisons.
+The functions @code{cl-member} and @code{cl-assoc} use @code{eql},
+as in Common Lisp. The standard Emacs Lisp functions @code{memq} and
+@code{assq} use @code{eq}, and the standard @code{memql} uses @code{eql}.
@node Control Structure
@chapter Control Structure
@node Setf Extensions
@subsection Setf Extensions
-Several standard (e.g.@: @code{car}) and Emacs-specific
-(e.g.@: @code{window-point}) Lisp functions are @code{setf}-able by default.
+Several standard (e.g., @code{car}) and Emacs-specific
+(e.g., @code{window-point}) Lisp functions are @code{setf}-able by default.
This package defines @code{setf} handlers for several additional functions:
@itemize
The generalized variable @code{buffer-substring}, listed above,
also works in this way by replacing a portion of the current buffer.
-@c FIXME? Also `eq'? (see cl-lib.el)
+@c FIXME? Also `eq'? (see cl-lib.el)
@c Currently commented out in cl.el.
@ignore
@xref{Obsolete Setf Customization}.
@end ignore
+@c FIXME? Is this still true?
@item
A macro call, in which case the macro is expanded and @code{setf}
is applied to the resulting form.
-
-@item
-Any form for which a @code{defsetf} or @code{define-setf-method}
-has been made. @xref{Obsolete Setf Customization}.
@end itemize
@c FIXME should this be in lispref? It seems self-evident.
bound on entry, it is simply made unbound by @code{makunbound} or
@code{fmakunbound} on exit.
@end ignore
-
-Note that the @file{cl.el} version of this macro behaves slightly
-differently. @xref{Obsolete Macros}.
@end defmac
@defmac cl-letf* (bindings@dots{}) forms@dots{}
must be a list of the form @samp{(@var{name} @var{arglist}
@var{forms}@dots{})}, which defines a function exactly as if
it were a @code{cl-defun} form. The function @var{name} is defined
-accordingly for the duration of the body of the @code{cl-flet}; then
-the old function definition, or lack thereof, is restored.
+accordingly but only within the body of the @code{cl-flet}, hiding any external
+definition if applicable.
-You can use @code{cl-flet} to disable or modify the behavior of a
-function in a temporary fashion. (Compare this with the idea
-of advising functions.
-@xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
-This will even work on Emacs primitives, although note that some calls
-to primitive functions internal to Emacs are made without going
-through the symbol's function cell, and so will not be affected by
-@code{cl-flet}. For example,
-
-@example
-(cl-flet ((message (&rest args) (push args saved-msgs)))
- (do-something))
-@end example
-
-This code attempts to replace the built-in function @code{message}
-with a function that simply saves the messages in a list rather
-than displaying them. The original definition of @code{message}
-will be restored after @code{do-something} exits. This code will
-work fine on messages generated by other Lisp code, but messages
-generated directly inside Emacs will not be caught since they make
-direct C-language calls to the message routines rather than going
-through the Lisp @code{message} function.
+The bindings are lexical in scope. This means that all references to
+the named functions must appear physically within the body of the
+@code{cl-flet} form.
Functions defined by @code{cl-flet} may use the full Common Lisp
argument notation supported by @code{cl-defun}; also, the function
@xref{Program Structure}.
Note that the @file{cl.el} version of this macro behaves slightly
-differently. @xref{Obsolete Macros}.
+differently. In particular, its binding is dynamic rather than
+lexical. @xref{Obsolete Macros}.
@end defmac
@defmac cl-labels (bindings@dots{}) forms@dots{}
@node Blocks and Exits
@section Blocks and Exits
+@cindex block
@noindent
Common Lisp @dfn{blocks} provide a non-local exit mechanism very
based on the value of @code{x} left over from the previous time
through the loop.
+@cindex destructuring, in cl-loop
Another feature of the @code{cl-loop} macro is @emph{destructuring},
similar in concept to the destructuring provided by @code{defmacro}
(@pxref{Argument Lists}).
or with incorrect keyword arguments.
@end defmac
+@cindex compiler macros
+@cindex define compiler macros
This package also includes the Common Lisp @code{define-compiler-macro}
facility, which allows you to define compile-time expansions and
optimizations for your functions.
This function creates a new, uninterned symbol (using @code{make-symbol})
with a unique name. (The name of an uninterned symbol is relevant
only if the symbol is printed.) By default, the name is generated
-@c FIXME no longer true?
from an increasing sequence of numbers, @samp{G1000}, @samp{G1001},
@samp{G1002}, etc. If the optional argument @var{x} is a string, that
string is used as a prefix instead of @samp{G}. Uninterned symbols
error if the argument is not an integer.
@end defun
-@ignore
-@defun cl-floatp-safe object
-This predicate tests whether @var{object} is a floating-point
-number. On systems that support floating-point, this is equivalent
-to @code{floatp}. On other systems, this always returns @code{nil}.
-@end defun
-@end ignore
-
@node Numerical Functions
@section Numerical Functions
between IEEE floating-point plus and minus zero. The @code{cl-equalp}
predicate has several differences with Common Lisp; @pxref{Predicates}.
-@c FIXME consider moving to lispref
-@ignore
-The @code{setf} mechanism is entirely compatible, except that
-setf-methods return a list of five values rather than five
-values directly. Also, the new ``@code{setf} function'' concept
-(typified by @code{(defun (setf foo) @dots{})}) is not implemented.
-@end ignore
-
The @code{cl-do-all-symbols} form is the same as @code{cl-do-symbols}
with no @var{obarray} argument. In Common Lisp, this form would
iterate over all symbols in all packages. Since Emacs obarrays
that @code{flet} affects indirect calls to a function as well as calls
directly inside the @code{flet} form itself.
+This will even work on Emacs primitives, although note that some calls
+to primitive functions internal to Emacs are made without going
+through the symbol's function cell, and so will not be affected by
+@code{flet}. For example,
+
+@example
+(flet ((message (&rest args) (push args saved-msgs)))
+ (do-something))
+@end example
+
+This code attempts to replace the built-in function @code{message}
+with a function that simply saves the messages in a list rather
+than displaying them. The original definition of @code{message}
+will be restored after @code{do-something} exits. This code will
+work fine on messages generated by other Lisp code, but messages
+generated directly inside Emacs will not be caught since they make
+direct C-language calls to the message routines rather than going
+through the Lisp @code{message} function.
+
+For those cases where the dynamic scoping of @code{flet} is desired,
+@code{cl-flet} is clearly not a substitute. The most direct replacement would
+be instead to use @code{cl-letf} to temporarily rebind @code{(symbol-function
+'@var{fun})}. But in most cases, a better substitute is to use an advice, such
+as:
+
+@example
+(defvar my-fun-advice-enable nil)
+(add-advice '@var{fun} :around
+ (lambda (orig &rest args)
+ (if my-fun-advice-enable (do-something)
+ (apply orig args))))
+@end example
+
+so that you can then replace the @code{flet} with a simple dynamically scoped
+binding of @code{my-fun-advice-enable}.
+
@c Bug#411.
-Note that many primitives (e.g.@: @code{+}) have special byte-compile
-handling. Attempts to redefine such functions using @code{flet} will
-fail if byte-compiled.
+Note that many primitives (e.g., @code{+}) have special byte-compile handling.
+Attempts to redefine such functions using @code{flet}, @code{cl-letf}, or an
+advice will fail when byte-compiled.
@c Or cl-flet.
@c In such cases, use @code{labels} instead.
@end defmac
lexical binding that @code{cl-labels} uses.
@end defmac
-@defmac letf (bindings@dots{}) forms@dots{}
-This macro is almost exactly the same as @code{cl-letf}, which
-replaces it (@pxref{Modify Macros}). The only difference is in
-details that relate to some deprecated usage of @code{symbol-function}
-in place forms.
-@end defmac
-
@node Obsolete Setf Customization
@appendixsec Obsolete Ways to Customize Setf
@code{defsetf}, and @code{define-setf-method}, that allow the
user to extend generalized variables in various ways.
In Emacs, these are obsolete, replaced by various features of
-@file{gv.el} in Emacs 24.3. Many of the implementation
-details in the following are out-of-date.
-@c FIXME this whole section needs updating.
+@file{gv.el} in Emacs 24.3.
+@xref{Adding Generalized Variables,,,elisp,GNU Emacs Lisp Reference Manual}.
+
@defmac define-modify-macro name arglist function [doc-string]
This macro defines a ``read-modify-write'' macro similar to
-@code{cl-incf} and @code{cl-decf}. The macro @var{name} is defined
-to take a @var{place} argument followed by additional arguments
-described by @var{arglist}. The call
+@code{cl-incf} and @code{cl-decf}. You can replace this macro
+with @code{gv-letplace}.
+
+The macro @var{name} is defined to take a @var{place} argument
+followed by additional arguments described by @var{arglist}. The call
@example
(@var{name} @var{place} @var{args}@dots{})
For example:
@example
-(define-modify-macro cl-incf (&optional (n 1)) +)
-(define-modify-macro cl-concatf (&rest args) concat)
+(define-modify-macro incf (&optional (n 1)) +)
+(define-modify-macro concatf (&rest args) concat)
@end example
Note that @code{&key} is not allowed in @var{arglist}, but
follow the pattern of @code{define-modify-macro}. For example,
@code{push} takes its arguments in the wrong order, and @code{pop}
is completely irregular.
+
+The above @code{incf} example could be written using
+@code{gv-letplace} as:
+@example
+(defmacro incf (place &optional n)
+ (gv-letplace (getter setter) place
+ (macroexp-let2 nil v (or n 1)
+ (funcall setter `(+ ,v ,getter)))))
+@end example
+@ignore
+(defmacro concatf (place &rest args)
+ (gv-letplace (getter setter) place
+ (macroexp-let2 nil v (mapconcat 'identity args "")
+ (funcall setter `(concat ,getter ,v)))))
+@end ignore
@end defmac
@defmac defsetf access-fn update-fn
-This is the simpler of two @code{defsetf} forms. Where
-@var{access-fn} is the name of a function which accesses a place,
-this declares @var{update-fn} to be the corresponding store
-function. From now on,
+This is the simpler of two @code{defsetf} forms, and is
+replaced by @code{gv-define-simple-setter}.
+
+With @var{access-fn} the name of a function that accesses a place,
+this declares @var{update-fn} to be the corresponding store function.
+From now on,
@example
(setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value})
@noindent
The @var{update-fn} is required to be either a true function, or
-a macro which evaluates its arguments in a function-like way. Also,
+a macro that evaluates its arguments in a function-like way. Also,
the @var{update-fn} is expected to return @var{value} as its result.
Otherwise, the above expansion would not obey the rules for the way
@code{setf} is supposed to behave.
temp)
@end example
-Some examples of the use of @code{defsetf}, drawn from the standard
-suite of setf methods, are:
+Some examples are:
@example
(defsetf car setcar)
-(defsetf symbol-value set)
(defsetf buffer-name rename-buffer t)
@end example
+
+These translate directly to @code{gv-define-simple-setter}:
+
+@example
+(gv-define-simple-setter car setcar)
+(gv-define-simple-setter buffer-name rename-buffer t)
+@end example
@end defmac
@defmac defsetf access-fn arglist (store-var) forms@dots{}
-This is the second, more complex, form of @code{defsetf}. It is
-rather like @code{defmacro} except for the additional @var{store-var}
-argument. The @var{forms} should return a Lisp form that stores
-the value of @var{store-var} into the generalized variable formed
-by a call to @var{access-fn} with arguments described by @var{arglist}.
-The @var{forms} may begin with a string which documents the @code{setf}
-method (analogous to the doc string that appears at the front of a
-function).
+This is the second, more complex, form of @code{defsetf}.
+It can be replaced by @code{gv-define-setter}.
+
+This form of @code{defsetf} is rather like @code{defmacro} except for
+the additional @var{store-var} argument. The @var{forms} should
+return a Lisp form that stores the value of @var{store-var} into the
+generalized variable formed by a call to @var{access-fn} with
+arguments described by @var{arglist}. The @var{forms} may begin with
+a string which documents the @code{setf} method (analogous to the doc
+string that appears at the front of a function).
For example, the simple form of @code{defsetf} is shorthand for
setf-method will insert temporary variables as needed to make
sure the apparent order of evaluation is preserved.
-Another example drawn from the standard package:
+Another standard example:
@example
(defsetf nth (n x) (store)
- (list 'setcar (list 'nthcdr n x) store))
+ `(setcar (nthcdr ,n ,x) ,store))
+@end example
+
+You could write this using @code{gv-define-setter} as:
+
+@example
+(gv-define-setter nth (store n x)
+ `(setcar (nthcdr ,n ,x) ,store))
@end example
@end defmac
@defmac define-setf-method access-fn arglist forms@dots{}
-This is the most general way to create new place forms. When
-a @code{setf} to @var{access-fn} with arguments described by
-@var{arglist} is expanded, the @var{forms} are evaluated and
-must return a list of five items:
-@c FIXME Is this still true?
+This is the most general way to create new place forms. You can
+replace this by @code{gv-define-setter} or @code{gv-define-expander}.
+
+When a @code{setf} to @var{access-fn} with arguments described by
+@var{arglist} is expanded, the @var{forms} are evaluated and must
+return a list of five items:
@enumerate
@item
except that the method returns a list of five values rather
than the five values themselves, since Emacs Lisp does not
support Common Lisp's notion of multiple return values.
+(Note that the @code{setf} implementation provided by @file{gv.el}
+does not use this five item format. Its use here is only for
+backwards compatibility.)
Once again, the @var{forms} may begin with a documentation string.