@copying
This file documents the GNU Emacs Common Lisp emulation package.
-Copyright @copyright{} 1993, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2009 Free Software Foundation, Inc.
+Copyright @copyright{} 1993, 2001-2011 Free Software Foundation, Inc.
@quotation
Permission is granted to copy, distribute and/or modify this document
@end quotation
@end copying
-@dircategory Emacs
+@dircategory Emacs lisp libraries
@direntry
-* CL: (cl). Partial Common Lisp support for Emacs Lisp.
+* CL: (cl). Partial Common Lisp support for Emacs Lisp.
@end direntry
@finalout
@end example
@noindent
-If you want to ensure that the new (Gillespie) version of @dfn{CL}
-is the one that is present, add an additional @code{(require 'cl-19)}
-call:
-
-@example
-(require 'cl)
-(require 'cl-19)
-@end example
-
-@noindent
-The second call will fail (with ``@file{cl-19.el} not found'') if
-the old @file{cl.el} package was in use.
-
It is safe to arrange to load @dfn{CL} at all times, e.g.,
in your @file{.emacs} file. But it's a good idea, for portability,
to @code{(require 'cl)} in your code even if you do this.
needed.
There is another file, @file{cl-compat.el}, which defines some
-routines from the older @file{cl.el} package that are no longer
+routines from the older @file{cl.el} package that are not otherwise
present in the new package. This includes internal routines
like @code{setelt} and @code{zip-lists}, deprecated features
like @code{defkeyword}, and an emulation of the old-style
-multiple-values feature. @xref{Old CL Compatibility}.
+multiple-values feature. This file is obsolete and should not be used
+in new code. @xref{Old CL Compatibility}.
@node Installation, Naming Conventions, Organization, Overview
@section Installation
@noindent
-Installation of the @dfn{CL} package is simple: Just put the
-byte-compiled files @file{cl.elc}, @file{cl-extra.elc},
-@file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc}
-into a directory on your @code{load-path}.
-
-There are no special requirements to compile this package:
-The files do not have to be loaded before they are compiled,
-nor do they need to be compiled in any particular order.
-
-You may choose to put the files into your main @file{lisp/}
-directory, replacing the original @file{cl.el} file there. Or,
-you could put them into a directory that comes before @file{lisp/}
-on your @code{load-path} so that the old @file{cl.el} is
-effectively hidden.
-
-Also, format the @file{cl.texinfo} file and put the resulting
-Info files in the @file{info/} directory or another suitable place.
-
-You may instead wish to leave this package's components all in
-their own directory, and then add this directory to your
-@code{load-path} and @code{Info-directory-list}.
-Add the directory to the front of the list so the old @dfn{CL}
-package and its documentation are hidden.
+The @dfn{CL} package is distributed with Emacs, so there is no need
+to install anything.
+
+If you do need to install it, just put the byte-compiled files
+@file{cl.elc}, @file{cl-extra.elc}, @file{cl-seq.elc},
+@file{cl-macs.elc}, and (if necessary) @file{cl-compat.elc} into a
+directory on your @code{load-path}. Also, format the @file{cl.texi}
+file and put the resulting Info files into a directory in your
+@code{Info-directory-list}.
@node Naming Conventions, , Installation, Overview
@section Naming Conventions
calls to it may be expanded into in-line code by the byte compiler.
This is analogous to the @code{defsubst} form;
@code{defsubst*} uses a different method (compiler macros) which
-works in all version of Emacs, and also generates somewhat more
+works in all versions of Emacs, and also generates somewhat more
efficient inline expansions. In particular, @code{defsubst*}
arranges for the processing of keyword arguments, default values,
etc., to be done at compile-time whenever possible.
@code{b} to the keyword @code{:c}, then signal an error because
@code{2} is not a valid keyword.
-If a @var{keyword} symbol is explicitly specified in the argument
-list as shown in the above diagram, then that keyword will be
-used instead of just the variable name prefixed with a colon.
-You can specify a @var{keyword} symbol which does not begin with
-a colon at all, but such symbols will not be self-quoting; you
-will have to quote them explicitly with an apostrophe in the
-function call.
+You can also explicitly specify the keyword argument; it need not be
+simply the variable name prefixed with a colon. For example,
+
+@example
+(defun* bar (&key (a 1) ((baz b) 4)))
+@end example
+
+@noindent
-Ordinarily it is an error to pass an unrecognized keyword to
+specifies a keyword @code{:a} that sets the variable @code{a} with
+default value 1, as well as a keyword @code{baz} that sets the
+variable @code{b} with default value 4. In this case, because
+@code{baz} is not self-quoting, you must quote it explicitly in the
+function call, like this:
+
+@example
+(bar :a 10 'baz 42)
+@end example
+
+Ordinarily, it is an error to pass an unrecognized keyword to
a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask
Lisp to ignore unrecognized keywords, either by adding the
marker @code{&allow-other-keys} after the keyword section
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
+global-key-binding x-get-secondary-selection
+keymap-parent x-get-selection
+local-key-binding
+mark
mark-marker
@end smallexample
or @code{while}.
@item for @var{var} being the hash-keys of @var{hash-table}
-This clause iterates over the entries in @var{hash-table}. For each
-hash table entry, @var{var} is bound to the entry's key. If you write
-@samp{the hash-values} instead, @var{var} is bound to the values
-of the entries. The clause may be followed by the additional
-term @samp{using (hash-values @var{var2})} (where @code{hash-values}
-is the opposite word of the word following @code{the}) to cause
-@var{var} and @var{var2} to be bound to the two parts of each
-hash table entry.
+@itemx for @var{var} being the hash-values of @var{hash-table}
+This clause iterates over the entries in @var{hash-table} with
+@var{var} bound to each key, or value. A @samp{using} clause can bind
+a second variable to the opposite part.
+
+@example
+(loop for k being the hash-keys of h
+ using (hash-values v)
+ do
+ (message "key %S -> value %S" k v))
+@end example
@item for @var{var} being the key-codes of @var{keymap}
+@itemx for @var{var} being the key-bindings of @var{keymap}
This clause iterates over the entries in @var{keymap}.
The iteration does not enter nested keymaps but does enter inherited
(parent) keymaps.
-You can use @samp{the key-bindings} to access the commands bound to
-the keys rather than the key codes, and you can add a @code{using}
-clause to access both the codes and the bindings together.
+A @code{using} clause can access both the codes and the bindings
+together.
+
+@example
+(loop for c being the key-codes of (current-local-map)
+ using (key-bindings b)
+ do
+ (message "key %S -> binding %S" c b))
+@end example
+
@item for @var{var} being the key-seqs of @var{keymap}
This clause iterates over all key sequences defined by @var{keymap}
@code{of} term may specify either a buffer or a string.
@item for @var{var} being the frames
-This clause iterates over all frames, i.e., X window system windows
-open on Emacs files. The
-clause @code{screens} is a synonym for @code{frames}. The frames
-are visited in @code{next-frame} order starting from
-@code{selected-frame}.
+This clause iterates over all Emacs frames. The clause @code{screens} is
+a synonym for @code{frames}. The frames are visited in
+@code{next-frame} order starting from @code{selected-frame}.
@item for @var{var} being the windows [of @var{frame}]
This clause iterates over the windows (in the Emacs sense) of
-the current frame, or of the specified @var{frame}.
+the current frame, or of the specified @var{frame}. It visits windows
+in @code{next-window} order starting from @code{selected-window}
+(or @code{frame-selected-window} if you specify @var{frame}).
+This clause treats the minibuffer window in the same way as
+@code{next-window} does. For greater flexibility, consider using
+@code{walk-windows} instead.
@item for @var{var} being the buffers
This clause iterates over all buffers in Emacs. It is equivalent
than values the trailing variables get the value @code{nil}.
If @code{nil} is used as a variable name, the corresponding
values are ignored. Destructuring may be nested, and dotted
-lists of variables like @code{(x . y)} are allowed.
+lists of variables like @code{(x . y)} are allowed, so for example
+to process an alist
+
+@example
+(loop for (key . value) in '((a . 1) (b . 2))
+ collect value)
+ @result{} (1 2)
+@end example
@node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility
@subsection Iteration Clauses
@code{car}s of the advancing pointers.
@end defun
-@defun mapc function seq &rest more-seqs
+@defun cl-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},
+collected into a list. The return value of @code{cl-mapc} is @var{seq},
the first sequence. This function is more general than the Emacs
primitive @code{mapc}.
@end defun
@noindent
The @dfn{CL} package includes emulations of some features of the
old @file{cl.el}, in the form of a compatibility package
-@code{cl-compat}. To use it, put @code{(require 'cl-compat)} in
-your program.
+@code{cl-compat}. This file is obsolete and may be removed in future,
+so it should not be used in new code.
The old package defined a number of internal routines without
@code{cl-} prefixes or other annotations. Call to these routines
@item
The Common Lisp Object System (CLOS) is not implemented,
nor is the Common Lisp Condition System. However, the EIEIO package
-from @uref{ftp://ftp.ultranet.com/pub/zappo} does implement some
+(@pxref{Top, , Introduction, eieio, EIEIO}) does implement some
CLOS functionality.
@item
@bye
-@ignore
- arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8
-@end ignore
HCoop / bpt / emacs.git / blobdiff