\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
@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
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.
-
-You can use @code{cl-flet} to disable or modify the behavior of
-functions (including Emacs primitives) in a temporary, localized fashion.
-(Compare this with the idea of advising functions.
-@xref{Advising Functions,,,elisp,GNU Emacs Lisp Reference Manual}.)
+accordingly but only within the body of the @code{cl-flet}, hiding any external
+definition if applicable.
The bindings are lexical in scope. This means that all references to
the named functions must appear physically within the body of the
@node Blocks and Exits
@section Blocks and Exits
+@cindex block
@noindent
Common Lisp @dfn{blocks} provide a non-local exit mechanism very
themselves in @code{nil} blocks.
@end defmac
+@c FIXME? Maybe this should be in a separate section?
+@defmac cl-tagbody &rest labels-or-statements
+This macro executes statements while allowing for control transfer to
+user-defined labels. Each element of @var{labels-or-statements} can
+be either a label (an integer or a symbol), or a cons-cell
+(a statement). This distinction is made before macroexpansion.
+Statements are executed in sequence, discarding any return value.
+Any statement can transfer control at any time to the statements that follow
+one of the labels with the special form @code{(go @var{label})}.
+Labels have lexical scope and dynamic extent.
+@end defmac
+
+
@node Iteration
@section Iteration
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.
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
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
HCoop / bpt / emacs.git / blobdiff