Mercurial > hg > xemacs-beta
annotate man/cl.texi @ 5353:38e24b8be4ea
Improve the lexical scoping in #'block, #'return-from.
lisp/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el:
* bytecomp.el (byte-compile-initial-macro-environment):
Shadow `block', `return-from' here, we implement them differently
when byte-compiling.
* bytecomp.el (byte-compile-active-blocks): New.
* bytecomp.el (byte-compile-block-1): New.
* bytecomp.el (byte-compile-return-from-1): New.
* bytecomp.el (return-from-1): New.
* bytecomp.el (block-1): New.
These are two aliases that exist to have their own associated
byte-compile functions, which functions implement `block' and
`return-from'.
* cl-extra.el (cl-macroexpand-all):
Fix a bug here when macros in the environment have been compiled.
* cl-macs.el (block):
* cl-macs.el (return):
* cl-macs.el (return-from):
Be more careful about lexical scope in these macros.
* cl.el:
* cl.el ('cl-block-wrapper): Removed.
* cl.el ('cl-block-throw): Removed.
These aren't needed in code generated by this XEmacs. They
shouldn't be needed in code generated by XEmacs 21.4, but if it
turns out the packages do need them, we can put them back.
2011-01-30 Mike Sperber <mike@xemacs.org>
* font-lock.el (font-lock-fontify-pending-extents): Don't fail if
`font-lock-mode' is unset, which can happen in the middle of
`revert-buffer'.
2011-01-23 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete):
* cl-macs.el (delq):
* cl-macs.el (remove):
* cl-macs.el (remq):
Don't use the compiler macro if these functions were given the
wrong number of arguments, as happens in lisp-tests.el.
* cl-seq.el (remove, remq): Removed.
I added these to subr.el, and forgot to remove them from here.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-setq, byte-compile-set):
Remove kludge allowing keywords' values to be set, all the code
that does that is gone.
* cl-compat.el (elt-satisfies-test-p):
* faces.el (set-face-parent):
* faces.el (face-doc-string):
* gtk-font-menu.el:
* gtk-font-menu.el (gtk-reset-device-font-menus):
* msw-font-menu.el:
* msw-font-menu.el (mswindows-reset-device-font-menus):
* package-get.el (package-get-installedp):
* select.el (select-convert-from-image-data):
* sound.el:
* sound.el (load-sound-file):
* x-font-menu.el (x-reset-device-font-menus-core):
Don't quote keywords, they're self-quoting, and the
win from backward-compatibility is sufficiently small now that the
style problem overrides it.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (block, return-from): Require that NAME be a symbol
in these macros, as always documented in the #'block docstring and
as required by Common Lisp.
* descr-text.el (unidata-initialize-unihan-database):
Correct the use of non-symbols in #'block and #'return-from in
this function.
2011-01-15 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (concatenate): Accept more complicated TYPEs in this
function, handing the sequences over to #'coerce if we don't
understand them here.
* cl-macs.el (inline): Don't proclaim #'concatenate as inline, its
compiler macro is more useful than doing that.
2011-01-11 Aidan Kehoe <kehoea@parhasard.net>
* subr.el (delete, delq, remove, remq): Move #'remove, #'remq
here, they don't belong in cl-seq.el; move #'delete, #'delq here
from fns.c, implement them in terms of #'delete*, allowing support
for sequences generally.
* update-elc.el (do-autoload-commands): Use #'delete*, not #'delq
here, now the latter's no longer dumped.
* cl-macs.el (delete, delq): Add compiler macros transforming
#'delete and #'delq to #'delete* calls.
2011-01-10 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box): Correct a misplaced parenthesis
here, thank you Mats Lidell in 87zkr9gqrh.fsf@mail.contactor.se !
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box):
* list-mode.el (display-completion-list):
These functions used to use cl-parsing-keywords; change them to
use defun* instead, fixing the build. (Not sure what led to me
not including this change in d1b17a33450b!)
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (define-star-compiler-macros):
Make sure the form has ITEM and LIST specified before attempting
to change to calls with explicit tests; necessary for some tests
in lisp-tests.el to compile correctly.
(stable-union, stable-intersection): Add compiler macros for these
functions, in the same way we do for most of the other functions
in cl-seq.el.
2011-01-01 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (dolist, dotimes, do-symbols, macrolet)
(symbol-macrolet):
Define these macros with defmacro* instead of parsing the argument
list by hand, for the sake of style and readability; use backquote
where appropriate, instead of calling #'list and and friends, for
the same reason.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* x-misc.el (device-x-display):
Provide this function, documented in the Lispref for years, but
not existing previously. Thank you Julian Bradfield, thank you
Jeff Mincy.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl-seq.el:
Move the heavy lifting from this file to C. Dump the
cl-parsing-keywords macro, but don't use defun* for the functions
we define that do take keywords, dynamic scope lossage makes that
not practical.
* subr.el (sort, fillarray): Move these aliases here.
(map-plist): #'nsublis is now built-in, but at this point #'eql
isn't necessarily available as a test; use #'eq.
* obsolete.el (cl-delete-duplicates): Make this available for old
compiler macros and old code.
(memql): Document that this is equivalent to #'member*, and worse.
* cl.el (adjoin, subst): Removed. These are in C.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* simple.el (assoc-ignore-case): Remove a duplicate definition of
this function (it's already in subr.el).
* iso8859-1.el (char-width):
On non-Mule, make this function equivalent to that produced by
(constantly 1), but preserve its docstring.
* subr.el (subst-char-in-string): Define this in terms of
#'substitute, #'nsubstitute.
(string-width): Define this using #'reduce and #'char-width.
(char-width): Give this a simpler definition, it makes far more
sense to check for mule at load time and redefine, as we do in
iso8859-1.el.
(store-substring): Implement this in terms of #'replace, now
#'replace is cheap.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* update-elc.el (lisp-files-needed-for-byte-compilation)
(lisp-files-needing-early-byte-compilation):
cl-macs belongs in the former, not the latter, it is as
fundamental as bytecomp.el.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl.el:
Provde the Common Lisp program-error, type-error as error
symbols. This doesn't nearly go far enough for anyone using the
Common Lisp errors.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete-duplicates):
If the form has an incorrect number of arguments, don't attempt a
compiler macroexpansion.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (cl-safe-expr-p):
Forms that start with the symbol lambda are also safe.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
For these functions' compiler macros, the optimisation is safe
even if the first and the last arguments have side effects, since
they're only used the once.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (inline-side-effect-free-compiler-macros):
Unroll a loop here at macro-expansion time, so these compiler
macros are compiled. Use #'eql instead of #'eq in a couple of
places for better style.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (notany, notevery): Avoid some dynamic scope
stupidity with local variable names in these functions, when they
weren't prefixed with cl-; go into some more detail in the doc
strings.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns): #'remove, #'remq are
free of side-effects.
(side-effect-and-error-free-fns):
Drop dot, dot-marker from the list.
2010-11-17 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (coerce):
In the argument list, name the first argument OBJECT, not X; the
former name was always used in the doc string and is clearer.
Handle vector type specifications which include the length of the
target sequence, error if there's a mismatch.
* cl-macs.el (cl-make-type-test): Handle type specifications
starting with the symbol 'eql.
2010-11-14 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (eql): Don't remove the byte-compile property of this
symbol. That was necessary to override a bug in bytecomp.el where
#'eql was confused with #'eq, which bug we no longer have.
If neither expression is constant, don't attempt to handle the
expression in this compiler macro, leave it to byte-compile-eql,
which produces better code anyway.
* bytecomp.el (eq): #'eql is not the function associated with the
byte-eq byte code.
(byte-compile-eql): Add an explicit compile method for this
function, for cases where the cl-macs compiler macro hasn't
reduced it to #'eq or #'equal.
2010-10-25 Aidan Kehoe <kehoea@parhasard.net>
Add compiler macros and compilation sanity-checking for various
functions that take keywords.
* byte-optimize.el (side-effect-free-fns): #'symbol-value is
side-effect free and not error free.
* bytecomp.el (byte-compile-normal-call): Check keyword argument
lists for sanity; store information about the positions where
keyword arguments start using the new byte-compile-keyword-start
property.
* cl-macs.el (cl-const-expr-val): Take a new optional argument,
cl-not-constant, defaulting to nil, in this function; return it if
the expression is not constant.
(cl-non-fixnum-number-p): Make this into a separate function, we
want to pass it to #'every.
(eql): Use it.
(define-star-compiler-macros): Use the same code to generate the
member*, assoc* and rassoc* compiler macros; special-case some
code in #'add-to-list in subr.el.
(remove, remq): Add compiler macros for these two functions, in
preparation for #'remove being in C.
(define-foo-if-compiler-macros): Transform (remove-if-not ...) calls to
(remove ... :if-not) at compile time, which will be a real win
once the latter is in C.
(define-substitute-if-compiler-macros)
(define-subst-if-compiler-macros): Similarly for these functions.
(delete-duplicates): Change this compiler macro to use
#'plists-equal; if we don't have information about the type of
SEQUENCE at compile time, don't bother attempting to inline the
call, the function will be in C soon enough.
(equalp): Remove an old commented-out compiler macro for this, if
we want to see it it's in version control.
(subst-char-in-string): Transform this to a call to nsubstitute or
nsubstitute, if that is appropriate.
* cl.el (ldiff): Don't call setf here, this makes for a load-time
dependency problem in cl-macs.el
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* term/vt100.el:
Refer to XEmacs, not GNU Emacs, in permissions.
* term/bg-mouse.el:
* term/sup-mouse.el:
Put copyright notice in canonical "Copyright DATE AUTHOR" form.
Refer to XEmacs, not GNU Emacs, in permissions.
* site-load.el:
Add permission boilerplate.
* mule/canna-leim.el:
* alist.el:
Refer to XEmacs, not APEL/this program, in permissions.
* mule/canna-leim.el:
Remove my copyright, I've assigned it to the FSF.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* gtk.el:
* gtk-widget-accessors.el:
* gtk-package.el:
* gtk-marshal.el:
* gtk-compose.el:
* gnome.el:
Add copyright notice based on internal evidence.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* easymenu.el: Add reference to COPYING to permission notice.
* gutter.el:
* gutter-items.el:
* menubar-items.el:
Fix typo "Xmacs" in permissions notice.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* auto-save.el:
* font.el:
* fontconfig.el:
* mule/kinsoku.el:
Add "part of XEmacs" text to permission notice.
2010-10-14 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns):
* cl-macs.el (remf, getf):
* cl-extra.el (tailp, cl-set-getf, cl-do-remf):
* cl.el (ldiff, endp):
Tighten up Common Lisp compatibility for #'ldiff, #'endp, #'tailp;
add circularity checking for the first two.
#'cl-set-getf and #'cl-do-remf were Lisp implementations of
#'plist-put and #'plist-remprop; change the names to aliases,
changes the macros that use them to using #'plist-put and
#'plist-remprop directly.
2010-10-12 Aidan Kehoe <kehoea@parhasard.net>
* abbrev.el (fundamental-mode-abbrev-table, global-abbrev-table):
Create both these abbrev tables using the usual
#'define-abbrev-table calls, rather than attempting to
special-case them.
* cl-extra.el: Force cl-macs to be loaded here, if cl-extra.el is
being loaded interpreted. Previously other, later files would
redundantly call (load "cl-macs") when interpreted, it's more
reasonable to do it here, once.
* cmdloop.el (read-quoted-char-radix): Use defcustom here, we
don't have any dump-order dependencies that would prevent that.
* custom.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling, rely on cl-extra.el in the
former case and the appropriate entry in bytecomp-load-hook in the
latter. Get rid of custom-declare-variable-list, we have no
dump-time dependencies that would require it.
* faces.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling.
* packages.el: Remove some inaccurate comments.
* post-gc.el (cleanup-simple-finalizers): Use #'delete-if-not
here, now the order of preloaded-file-list has been changed to
make it available.
* subr.el (custom-declare-variable-list): Remove. No need for it.
Also remove a stub define-abbrev-table from this file, given the
current order of preloaded-file-list there's no need for it.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-constp) Forms quoted with FUNCTION are
also constant.
(byte-compile-initial-macro-environment): In #'the, if FORM is
constant and does not match TYPE, warn at byte-compile time.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* backquote.el (bq-vector-contents, bq-list*): Remove; the former
is equivalent to (append VECTOR nil), the latter to (list* ...).
(bq-process-2): Use (append VECTOR nil) instead of using
#'bq-vector-contents to convert to a list.
(bq-process-1): Now we use list* instead of bq-list
* subr.el (list*): Moved from cl.el, since it is now required to
be available the first time a backquoted form is encountered.
* cl.el (list*): Move to subr.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* test-harness.el (Check-Message):
Add an omitted comma here, thank you the buildbot.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* hash-table.el (hash-table-key-list, hash-table-value-list)
(hash-table-key-value-alist, hash-table-key-value-plist):
Remove some useless #'nreverse calls in these files; our hash
tables have no order, it's not helpful to pretend they do.
* behavior.el (read-behavior):
Do the same in this file, in some code evidently copied from
hash-table.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* info.el (Info-insert-dir):
* format.el (format-deannotate-region):
* files.el (cd, save-buffers-kill-emacs):
Use #'some, #'every and related functions for applying boolean
operations to lists, instead of rolling our own ones that cons and
don't short-circuit.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-initial-macro-environment):
* cl-macs.el (the):
Rephrase the docstring, make its implementation when compiling
files a little nicer.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* descr-text.el (unidata-initialize-unicodedata-database)
(unidata-initialize-unihan-database, describe-char-unicode-data)
(describe-char-unicode-data):
Wrap calls to the database functions with (with-fboundp ...),
avoiding byte compile warnings on builds without support for the
database functions.
(describe-char): (reduce #'max ...), not (apply #'max ...), no
need to cons needlessly.
(describe-char): Remove a redundant lambda wrapping
#'extent-properties.
(describe-char-unicode-data): Call #'nsubst when replacing "" with
nil in the result of #'split-string, instead of consing inside
mapcar.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* x-faces.el (x-available-font-sizes):
* specifier.el (let-specifier):
* package-ui.el (pui-add-required-packages):
* msw-faces.el (mswindows-available-font-sizes):
* modeline.el (modeline-minor-mode-menu):
* minibuf.el (minibuf-directory-files):
Replace the O2N (delq nil (mapcar (lambda (W) (and X Y)) Z)) with
the ON (mapcan (lambda (W) (and X (list Y))) Z) in these files.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
When these functions are handed more than two arguments, and those
arguments have no side effects, transform to a series of two
argument calls, avoiding funcall in the byte-compiled code.
* mule/mule-cmds.el (finish-set-language-environment):
Take advantage of this change in a function called 256 times at
startup.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-function-form, byte-compile-quote)
(byte-compile-quote-form):
Warn at compile time, and error at runtime, if a (quote ...) or a
(function ...) form attempts to quote more than one object.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (byte-optimize-apply): Transform (apply 'nconc
(mapcar ...)) to (mapcan ...); warn about use of the first idiom.
* update-elc.el (do-autoload-commands):
* packages.el (packages-find-package-library-path):
* frame.el (frame-list):
* extents.el (extent-descendants):
* etags.el (buffer-tag-table-files):
* dumped-lisp.el (preloaded-file-list):
* device.el (device-list):
* bytecomp-runtime.el (proclaim-inline, proclaim-notinline)
Use #'mapcan, not (apply #'nconc (mapcar ...) in all these files.
* bytecomp-runtime.el (eval-when-compile, eval-and-compile):
In passing, mention that these macros also evaluate the body when
interpreted.
tests/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test lexical scope for `block', `return-from'; add a
Known-Bug-Expect-Failure for a contorted example that fails when
byte-compiled.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Mon, 07 Feb 2011 12:01:24 +0000 |
| parents | 378a34562cbe |
| children | 62b9ef1ed4ac |
| rev | line source |
|---|---|
| 428 | 1 \input texinfo @c -*-texinfo-*- |
| 2 @setfilename ../info/cl.info | |
| 3 @settitle Common Lisp Extensions | |
| 4 | |
| 5 @iftex | |
| 6 @finalout | |
| 7 @end iftex | |
| 8 | |
| 9 @ifinfo | |
| 10 @dircategory XEmacs Editor | |
| 11 @direntry | |
| 1353 | 12 * Common Lisp: (cl). XEmacs Common Lisp emulation package. |
| 428 | 13 @end direntry |
| 14 | |
| 1353 | 15 This file documents the XEmacs Common Lisp emulation package. |
| 428 | 16 |
| 17 Copyright (C) 1993 Free Software Foundation, Inc. | |
| 18 | |
| 19 Permission is granted to make and distribute verbatim copies of this | |
| 20 manual provided the copyright notice and this permission notice are | |
| 21 preserved on all copies. | |
| 22 | |
| 23 @ignore | |
| 24 Permission is granted to process this file through TeX and print the | |
| 25 results, provided the printed document carries copying permission notice | |
| 26 identical to this one except for the removal of this paragraph (this | |
| 27 paragraph not being relevant to the printed manual). | |
| 28 | |
| 29 @end ignore | |
| 30 Permission is granted to copy and distribute modified versions of this | |
| 31 manual under the conditions for verbatim copying, provided also that the | |
| 32 section entitled ``GNU General Public License'' is included exactly as | |
| 33 in the original, and provided that the entire resulting derived work is | |
| 34 distributed under the terms of a permission notice identical to this one. | |
| 35 | |
| 36 Permission is granted to copy and distribute translations of this manual | |
| 37 into another language, under the above conditions for modified versions, | |
| 38 except that the section entitled ``GNU General Public License'' may be | |
| 39 included in a translation approved by the author instead of in the | |
| 40 original English. | |
| 41 @end ifinfo | |
| 42 | |
| 43 @titlepage | |
| 44 @sp 6 | |
| 45 @center @titlefont{Common Lisp Extensions} | |
| 46 @sp 4 | |
| 47 @center For GNU Emacs Lisp | |
| 48 @sp 1 | |
| 49 @center Version 2.02 | |
| 50 @sp 5 | |
| 51 @center Dave Gillespie | |
| 52 @center daveg@@synaptics.com | |
| 53 @page | |
| 54 | |
| 55 @vskip 0pt plus 1filll | |
| 56 Copyright @copyright{} 1993 Free Software Foundation, Inc. | |
| 57 | |
| 58 Permission is granted to make and distribute verbatim copies of | |
| 59 this manual provided the copyright notice and this permission notice | |
| 60 are preserved on all copies. | |
| 61 | |
| 62 @ignore | |
| 63 Permission is granted to process this file through TeX and print the | |
| 64 results, provided the printed document carries copying permission notice | |
| 65 identical to this one except for the removal of this paragraph (this | |
| 66 paragraph not being relevant to the printed manual). | |
| 67 | |
| 68 @end ignore | |
| 69 Permission is granted to copy and distribute modified versions of this | |
| 70 manual under the conditions for verbatim copying, provided also that the | |
| 71 section entitled ``GNU General Public License'' is included exactly as | |
| 72 in the original, and provided that the entire resulting derived work is | |
| 73 distributed under the terms of a permission notice identical to this one. | |
| 74 | |
| 75 Permission is granted to copy and distribute translations of this manual | |
| 76 into another language, under the above conditions for modified versions, | |
| 77 except that the section entitled ``GNU General Public License'' may be | |
| 78 included in a translation approved by the author instead of in the | |
| 79 original English. | |
| 80 @end titlepage | |
| 81 | |
| 82 @node Top, Overview,, (dir) | |
| 83 @chapter Common Lisp Extensions | |
| 84 | |
| 85 @noindent | |
| 86 This document describes a set of Emacs Lisp facilities borrowed from | |
| 87 Common Lisp. All the facilities are described here in detail; for | |
| 88 more discussion and examples, Guy L. Steele's @cite{Common Lisp, the | |
| 89 Language}, second edition, is the definitive book on Common Lisp. | |
| 90 @iftex | |
| 91 Chapter numbers and most section numbers of this document parallel | |
| 92 those of Steele's book. | |
| 93 @end iftex | |
| 94 While this document does not assume any prior knowledge of Common | |
| 95 Lisp, it does assume a basic familiarity with Emacs Lisp. | |
| 96 | |
| 97 @menu | |
| 98 * Overview:: Installation, usage, etc. | |
| 99 * Program Structure:: Arglists, `eval-when', `defalias' | |
| 100 * Predicates:: `typep', `eql', and `equalp' | |
| 101 * Control Structure:: `setf', `when', `do', `loop', etc. | |
| 102 * Macros:: Destructuring, `define-compiler-macro' | |
| 103 * Declarations:: `proclaim', `declare', etc. | |
| 104 * Symbols:: Property lists, `gensym' | |
| 105 * Numbers:: Predicates, functions, random numbers | |
| 106 * Sequences:: Mapping, functions, searching, sorting | |
| 107 * Lists:: `cadr', `sublis', `member*', `assoc*', etc. | |
| 108 * Hash Tables:: `make-hash-table', `gethash', etc. | |
| 109 * Structures:: `defstruct' | |
| 110 * Assertions:: `check-type', `assert', `ignore-errors'. | |
| 111 | |
| 112 * Efficiency Concerns:: Hints and techniques | |
| 113 * Common Lisp Compatibility:: All known differences with Steele | |
| 114 * Old CL Compatibility:: All known differences with old cl.el | |
| 115 * Porting Common Lisp:: Hints for porting Common Lisp code | |
| 116 | |
| 117 * Function Index:: | |
| 118 * Variable Index:: | |
| 119 @end menu | |
| 120 | |
| 121 @node Overview, Program Structure, Top, Top | |
| 122 @ifinfo | |
| 123 @chapter Overview | |
| 124 @end ifinfo | |
| 125 @iftex | |
| 126 @section Overview | |
| 127 @end iftex | |
| 128 | |
| 129 @noindent | |
| 130 Common Lisp is a huge language, and Common Lisp systems tend to be | |
| 131 massive and extremely complex. Emacs Lisp, by contrast, is rather | |
| 132 minimalist in the choice of Lisp features it offers the programmer. | |
| 133 As Emacs Lisp programmers have grown in number, and the applications | |
| 134 they write have grown more ambitious, it has become clear that Emacs | |
| 135 Lisp could benefit from many of the conveniences of Common Lisp. | |
| 136 | |
| 137 The @dfn{CL} package adds a number of Common Lisp functions and | |
| 138 control structures to Emacs Lisp. While not a 100% complete | |
| 139 implementation of Common Lisp, @dfn{CL} adds enough functionality | |
| 140 to make Emacs Lisp programming significantly more convenient. | |
| 141 | |
| 142 Some Common Lisp features have been omitted from this package | |
| 143 for various reasons: | |
| 144 | |
| 145 @itemize @bullet | |
| 146 @item | |
| 147 Some features are too complex or bulky relative to their benefit | |
| 148 to Emacs Lisp programmers. CLOS and Common Lisp streams are fine | |
| 149 examples of this group. | |
| 150 | |
| 151 @item | |
| 152 Other features cannot be implemented without modification to the | |
| 153 Emacs Lisp interpreter itself, such as multiple return values, | |
| 154 lexical scoping, case-insensitive symbols, and complex numbers. | |
| 155 The @dfn{CL} package generally makes no attempt to emulate these | |
| 156 features. | |
| 157 | |
| 158 @item | |
| 159 Some features conflict with existing things in Emacs Lisp. For | |
| 160 example, Emacs' @code{assoc} function is incompatible with the | |
| 161 Common Lisp @code{assoc}. In such cases, this package usually | |
| 162 adds the suffix @samp{*} to the function name of the Common | |
| 163 Lisp version of the function (e.g., @code{assoc*}). | |
| 164 @end itemize | |
| 165 | |
| 166 The package described here was written by Dave Gillespie, | |
| 167 @file{daveg@@synaptics.com}. It is a total rewrite of the original | |
| 168 1986 @file{cl.el} package by Cesar Quiroz. Most features of | |
| 169 the Quiroz package have been retained; any incompatibilities are | |
| 170 noted in the descriptions below. Care has been taken in this | |
| 171 version to ensure that each function is defined efficiently, | |
| 172 concisely, and with minimal impact on the rest of the Emacs | |
| 173 environment. | |
| 174 | |
| 175 @menu | |
| 176 * Usage:: How to use the CL package | |
| 177 * Organization:: The package's five component files | |
| 178 * Installation:: Compiling and installing CL | |
| 179 * Naming Conventions:: Notes on CL function names | |
| 180 @end menu | |
| 181 | |
| 182 @node Usage, Organization, Overview, Overview | |
| 183 @section Usage | |
| 184 | |
| 185 @noindent | |
| 186 Lisp code that uses features from the @dfn{CL} package should | |
| 187 include at the beginning: | |
| 188 | |
| 189 @example | |
| 190 (require 'cl) | |
| 191 @end example | |
| 192 | |
| 193 @noindent | |
| 194 If you want to ensure that the new (Gillespie) version of @dfn{CL} | |
| 195 is the one that is present, add an additional @code{(require 'cl-19)} | |
| 196 call: | |
| 197 | |
| 198 @example | |
| 199 (require 'cl) | |
| 200 (require 'cl-19) | |
| 201 @end example | |
| 202 | |
| 203 @noindent | |
| 204 The second call will fail (with ``@file{cl-19.el} not found'') if | |
| 205 the old @file{cl.el} package was in use. | |
| 206 | |
| 207 It is safe to arrange to load @dfn{CL} at all times, e.g., | |
| 208 in your @file{.emacs} file. But it's a good idea, for portability, | |
| 209 to @code{(require 'cl)} in your code even if you do this. | |
| 210 | |
| 211 @node Organization, Installation, Usage, Overview | |
| 212 @section Organization | |
| 213 | |
| 214 @noindent | |
| 215 The Common Lisp package is organized into four files: | |
| 216 | |
| 217 @table @file | |
| 218 @item cl.el | |
| 219 This is the ``main'' file, which contains basic functions | |
| 220 and information about the package. This file is relatively | |
| 221 compact---about 700 lines. | |
| 222 | |
| 223 @item cl-extra.el | |
| 224 This file contains the larger, more complex or unusual functions. | |
| 225 It is kept separate so that packages which only want to use Common | |
| 226 Lisp fundamentals like the @code{cadr} function won't need to pay | |
| 227 the overhead of loading the more advanced functions. | |
| 228 | |
| 229 @item cl-seq.el | |
| 230 This file contains most of the advanced functions for operating | |
| 231 on sequences or lists, such as @code{delete-if} and @code{assoc*}. | |
| 232 | |
| 233 @item cl-macs.el | |
| 234 This file contains the features of the packages which are macros | |
| 235 instead of functions. Macros expand when the caller is compiled, | |
| 236 not when it is run, so the macros generally only need to be | |
| 237 present when the byte-compiler is running (or when the macros are | |
| 238 used in uncompiled code such as a @file{.emacs} file). Most of | |
| 239 the macros of this package are isolated in @file{cl-macs.el} so | |
| 240 that they won't take up memory unless you are compiling. | |
| 241 @end table | |
| 242 | |
| 243 The file @file{cl.el} includes all necessary @code{autoload} | |
| 244 commands for the functions and macros in the other three files. | |
| 245 All you have to do is @code{(require 'cl)}, and @file{cl.el} | |
| 246 will take care of pulling in the other files when they are | |
| 247 needed. | |
| 248 | |
| 249 There is another file, @file{cl-compat.el}, which defines some | |
| 250 routines from the older @file{cl.el} package that are no longer | |
| 251 present in the new package. This includes internal routines | |
|
4677
8f1ee2d15784
Support full Common Lisp multiple values in C.
Aidan Kehoe <kehoea@parhasard.net>
parents:
1353
diff
changeset
|
252 like @code{setelt} and @code{zip-lists}, and deprecated features |
|
8f1ee2d15784
Support full Common Lisp multiple values in C.
Aidan Kehoe <kehoea@parhasard.net>
parents:
1353
diff
changeset
|
253 like @code{defkeyword}. @xref{Old CL Compatibility}. |
| 428 | 254 |
| 255 @node Installation, Naming Conventions, Organization, Overview | |
| 256 @section Installation | |
| 257 | |
| 258 @noindent | |
| 259 Installation of the @dfn{CL} package is simple: Just put the | |
| 260 byte-compiled files @file{cl.elc}, @file{cl-extra.elc}, | |
| 261 @file{cl-seq.elc}, @file{cl-macs.elc}, and @file{cl-compat.elc} | |
| 262 into a directory on your @code{load-path}. | |
| 263 | |
| 264 There are no special requirements to compile this package: | |
| 265 The files do not have to be loaded before they are compiled, | |
| 266 nor do they need to be compiled in any particular order. | |
| 267 | |
| 268 You may choose to put the files into your main @file{lisp/} | |
| 269 directory, replacing the original @file{cl.el} file there. Or, | |
| 270 you could put them into a directory that comes before @file{lisp/} | |
| 271 on your @code{load-path} so that the old @file{cl.el} is | |
| 272 effectively hidden. | |
| 273 | |
| 274 Also, format the @file{cl.texinfo} file and put the resulting | |
| 275 Info files in the @file{info/} directory or another suitable place. | |
| 276 | |
| 277 You may instead wish to leave this package's components all in | |
| 278 their own directory, and then add this directory to your | |
| 279 @code{load-path} and (Emacs 19 only) @code{Info-directory-list}. | |
| 280 Add the directory to the front of the list so the old @dfn{CL} | |
| 281 package and its documentation are hidden. | |
| 282 | |
| 283 @node Naming Conventions, , Installation, Overview | |
| 284 @section Naming Conventions | |
| 285 | |
| 286 @noindent | |
| 287 Except where noted, all functions defined by this package have the | |
| 288 same names and calling conventions as their Common Lisp counterparts. | |
| 289 | |
| 290 Following is a complete list of functions whose names were changed | |
| 291 from Common Lisp, usually to avoid conflicts with Emacs. In each | |
| 292 case, a @samp{*} has been appended to the Common Lisp name to obtain | |
| 293 the Emacs name: | |
| 294 | |
| 295 @example | |
| 296 defun* defsubst* defmacro* function* | |
| 440 | 297 member* assoc* rassoc* remove* |
| 298 delete* mapcar* sort* floor* | |
| 299 ceiling* truncate* round* mod* | |
| 300 rem* random* | |
| 428 | 301 @end example |
| 302 | |
| 303 Internal function and variable names in the package are prefixed | |
| 304 by @code{cl-}. Here is a complete list of functions @emph{not} | |
| 305 prefixed by @code{cl-} which were not taken from Common Lisp: | |
| 306 | |
| 307 @example | |
| 308 member delete remove remq | |
| 309 rassoc floatp-safe lexical-let lexical-let* | |
| 310 callf callf2 letf letf* | |
| 311 defsubst* defalias add-hook eval-when-compile | |
| 312 @end example | |
| 313 | |
| 314 @noindent | |
| 315 (Most of these are Emacs 19 features provided to Emacs 18 users, | |
| 316 or introduced, like @code{remq}, for reasons of symmetry | |
| 317 with similar features.) | |
| 318 | |
| 319 The following simple functions and macros are defined in @file{cl.el}; | |
| 320 they do not cause other components like @file{cl-extra} to be loaded. | |
| 321 | |
| 322 @example | |
| 323 eql floatp-safe abs endp | |
| 324 evenp oddp plusp minusp | |
| 325 last butlast nbutlast caar .. cddddr | |
| 326 list* ldiff rest first .. tenth | |
| 327 member [1] copy-list subst mapcar* [2] | |
| 328 adjoin [3] acons pairlis when | |
| 329 unless pop [4] push [4] pushnew [3,4] | |
| 330 incf [4] decf [4] proclaim declaim | |
| 331 add-hook | |
| 332 @end example | |
| 333 | |
| 334 @noindent | |
| 335 [1] This is the Emacs 19-compatible function, not @code{member*}. | |
| 336 | |
| 337 @noindent | |
| 338 [2] Only for one sequence argument or two list arguments. | |
| 339 | |
| 340 @noindent | |
| 341 [3] Only if @code{:test} is @code{eq}, @code{equal}, or unspecified, | |
| 342 and @code{:key} is not used. | |
| 343 | |
| 344 @noindent | |
| 345 [4] Only when @var{place} is a plain variable name. | |
| 346 | |
| 347 @iftex | |
| 348 @chapno=4 | |
| 349 @end iftex | |
| 350 | |
| 351 @node Program Structure, Predicates, Overview, Top | |
| 352 @chapter Program Structure | |
| 353 | |
| 354 @noindent | |
| 355 This section describes features of the @dfn{CL} package which have to | |
| 356 do with programs as a whole: advanced argument lists for functions, | |
| 357 and the @code{eval-when} construct. | |
| 358 | |
| 359 @menu | |
| 360 * Argument Lists:: `&key', `&aux', `defun*', `defmacro*'. | |
| 361 * Time of Evaluation:: The `eval-when' construct. | |
| 362 * Function Aliases:: The `defalias' function. | |
| 363 @end menu | |
| 364 | |
| 365 @iftex | |
| 366 @secno=1 | |
| 367 @end iftex | |
| 368 | |
| 369 @node Argument Lists, Time of Evaluation, Program Structure, Program Structure | |
| 370 @section Argument Lists | |
| 371 | |
| 372 @noindent | |
| 373 Emacs Lisp's notation for argument lists of functions is a subset of | |
| 374 the Common Lisp notation. As well as the familiar @code{&optional} | |
| 375 and @code{&rest} markers, Common Lisp allows you to specify default | |
| 376 values for optional arguments, and it provides the additional markers | |
| 377 @code{&key} and @code{&aux}. | |
| 378 | |
| 379 Since argument parsing is built-in to Emacs, there is no way for | |
| 380 this package to implement Common Lisp argument lists seamlessly. | |
| 381 Instead, this package defines alternates for several Lisp forms | |
| 382 which you must use if you need Common Lisp argument lists. | |
| 383 | |
| 384 @defspec defun* name arglist body... | |
| 385 This form is identical to the regular @code{defun} form, except | |
| 386 that @var{arglist} is allowed to be a full Common Lisp argument | |
| 387 list. Also, the function body is enclosed in an implicit block | |
| 388 called @var{name}; @pxref{Blocks and Exits}. | |
| 389 @end defspec | |
| 390 | |
| 391 @defspec defsubst* name arglist body... | |
| 392 This is just like @code{defun*}, except that the function that | |
| 393 is defined is automatically proclaimed @code{inline}, i.e., | |
| 394 calls to it may be expanded into in-line code by the byte compiler. | |
| 395 This is analogous to the @code{defsubst} form in Emacs 19; | |
| 396 @code{defsubst*} uses a different method (compiler macros) which | |
| 397 works in all version of Emacs, and also generates somewhat more | |
| 398 efficient inline expansions. In particular, @code{defsubst*} | |
| 399 arranges for the processing of keyword arguments, default values, | |
| 400 etc., to be done at compile-time whenever possible. | |
| 401 @end defspec | |
| 402 | |
| 403 @defspec defmacro* name arglist body... | |
| 404 This is identical to the regular @code{defmacro} form, | |
| 405 except that @var{arglist} is allowed to be a full Common Lisp | |
| 406 argument list. The @code{&environment} keyword is supported as | |
| 407 described in Steele. The @code{&whole} keyword is supported only | |
| 408 within destructured lists (see below); top-level @code{&whole} | |
| 409 cannot be implemented with the current Emacs Lisp interpreter. | |
| 410 The macro expander body is enclosed in an implicit block called | |
| 411 @var{name}. | |
| 412 @end defspec | |
| 413 | |
| 414 @defspec function* symbol-or-lambda | |
| 415 This is identical to the regular @code{function} form, | |
| 416 except that if the argument is a @code{lambda} form then that | |
| 417 form may use a full Common Lisp argument list. | |
| 418 @end defspec | |
| 419 | |
| 420 Also, all forms (such as @code{defsetf} and @code{flet}) defined | |
| 421 in this package that include @var{arglist}s in their syntax allow | |
| 422 full Common Lisp argument lists. | |
| 423 | |
| 424 Note that it is @emph{not} necessary to use @code{defun*} in | |
| 425 order to have access to most @dfn{CL} features in your function. | |
| 426 These features are always present; @code{defun*}'s only | |
| 427 difference from @code{defun} is its more flexible argument | |
| 428 lists and its implicit block. | |
| 429 | |
| 430 The full form of a Common Lisp argument list is | |
| 431 | |
| 432 @example | |
| 433 (@var{var}... | |
| 434 &optional (@var{var} @var{initform} @var{svar})... | |
| 435 &rest @var{var} | |
| 436 &key ((@var{keyword} @var{var}) @var{initform} @var{svar})... | |
| 437 &aux (@var{var} @var{initform})...) | |
| 438 @end example | |
| 439 | |
| 440 Each of the five argument list sections is optional. The @var{svar}, | |
| 441 @var{initform}, and @var{keyword} parts are optional; if they are | |
| 442 omitted, then @samp{(@var{var})} may be written simply @samp{@var{var}}. | |
| 443 | |
| 444 The first section consists of zero or more @dfn{required} arguments. | |
| 445 These arguments must always be specified in a call to the function; | |
| 446 there is no difference between Emacs Lisp and Common Lisp as far as | |
| 447 required arguments are concerned. | |
| 448 | |
| 449 The second section consists of @dfn{optional} arguments. These | |
| 450 arguments may be specified in the function call; if they are not, | |
| 451 @var{initform} specifies the default value used for the argument. | |
| 452 (No @var{initform} means to use @code{nil} as the default.) The | |
| 453 @var{initform} is evaluated with the bindings for the preceding | |
| 454 arguments already established; @code{(a &optional (b (1+ a)))} | |
| 455 matches one or two arguments, with the second argument defaulting | |
| 456 to one plus the first argument. If the @var{svar} is specified, | |
| 457 it is an auxiliary variable which is bound to @code{t} if the optional | |
| 458 argument was specified, or to @code{nil} if the argument was omitted. | |
| 459 If you don't use an @var{svar}, then there will be no way for your | |
| 460 function to tell whether it was called with no argument, or with | |
| 461 the default value passed explicitly as an argument. | |
| 462 | |
| 463 The third section consists of a single @dfn{rest} argument. If | |
| 464 more arguments were passed to the function than are accounted for | |
| 465 by the required and optional arguments, those extra arguments are | |
| 466 collected into a list and bound to the ``rest'' argument variable. | |
| 467 Common Lisp's @code{&rest} is equivalent to that of Emacs Lisp. | |
| 468 Common Lisp accepts @code{&body} as a synonym for @code{&rest} in | |
| 469 macro contexts; this package accepts it all the time. | |
| 470 | |
| 471 The fourth section consists of @dfn{keyword} arguments. These | |
| 472 are optional arguments which are specified by name rather than | |
| 473 positionally in the argument list. For example, | |
| 474 | |
| 475 @example | |
| 476 (defun* foo (a &optional b &key c d (e 17))) | |
| 477 @end example | |
| 478 | |
| 479 @noindent | |
| 480 defines a function which may be called with one, two, or more | |
| 481 arguments. The first two arguments are bound to @code{a} and | |
| 482 @code{b} in the usual way. The remaining arguments must be | |
| 483 pairs of the form @code{:c}, @code{:d}, or @code{:e} followed | |
| 484 by the value to be bound to the corresponding argument variable. | |
| 485 (Symbols whose names begin with a colon are called @dfn{keywords}, | |
| 486 and they are self-quoting in the same way as @code{nil} and | |
| 487 @code{t}.) | |
| 488 | |
| 489 For example, the call @code{(foo 1 2 :d 3 :c 4)} sets the five | |
| 490 arguments to 1, 2, 4, 3, and 17, respectively. If the same keyword | |
| 491 appears more than once in the function call, the first occurrence | |
| 492 takes precedence over the later ones. Note that it is not possible | |
| 493 to specify keyword arguments without specifying the optional | |
| 494 argument @code{b} as well, since @code{(foo 1 :c 2)} would bind | |
| 495 @code{b} to the keyword @code{:c}, then signal an error because | |
| 496 @code{2} is not a valid keyword. | |
| 497 | |
| 498 If a @var{keyword} symbol is explicitly specified in the argument | |
| 499 list as shown in the above diagram, then that keyword will be | |
| 500 used instead of just the variable name prefixed with a colon. | |
| 501 You can specify a @var{keyword} symbol which does not begin with | |
| 502 a colon at all, but such symbols will not be self-quoting; you | |
| 503 will have to quote them explicitly with an apostrophe in the | |
| 504 function call. | |
| 505 | |
| 506 Ordinarily it is an error to pass an unrecognized keyword to | |
| 507 a function, e.g., @code{(foo 1 2 :c 3 :goober 4)}. You can ask | |
| 508 Lisp to ignore unrecognized keywords, either by adding the | |
| 509 marker @code{&allow-other-keys} after the keyword section | |
| 510 of the argument list, or by specifying an @code{:allow-other-keys} | |
| 511 argument in the call whose value is non-@code{nil}. If the | |
| 512 function uses both @code{&rest} and @code{&key} at the same time, | |
| 513 the ``rest'' argument is bound to the keyword list as it appears | |
| 514 in the call. For example: | |
| 515 | |
| 516 @smallexample | |
| 517 (defun* find-thing (thing &rest rest &key need &allow-other-keys) | |
| 518 (or (apply 'member* thing thing-list :allow-other-keys t rest) | |
| 519 (if need (error "Thing not found")))) | |
| 520 @end smallexample | |
| 521 | |
| 522 @noindent | |
| 523 This function takes a @code{:need} keyword argument, but also | |
| 524 accepts other keyword arguments which are passed on to the | |
| 525 @code{member*} function. @code{allow-other-keys} is used to | |
| 526 keep both @code{find-thing} and @code{member*} from complaining | |
| 527 about each others' keywords in the arguments. | |
| 528 | |
| 529 As a (significant) performance optimization, this package | |
| 530 implements the scan for keyword arguments by calling @code{memq} | |
| 531 to search for keywords in a ``rest'' argument. Technically | |
| 532 speaking, this is incorrect, since @code{memq} looks at the | |
| 533 odd-numbered values as well as the even-numbered keywords. | |
| 534 The net effect is that if you happen to pass a keyword symbol | |
| 535 as the @emph{value} of another keyword argument, where that | |
| 536 keyword symbol happens to equal the name of a valid keyword | |
| 537 argument of the same function, then the keyword parser will | |
| 538 become confused. This minor bug can only affect you if you | |
| 539 use keyword symbols as general-purpose data in your program; | |
| 540 this practice is strongly discouraged in Emacs Lisp. | |
| 541 | |
| 542 The fifth section of the argument list consists of @dfn{auxiliary | |
| 543 variables}. These are not really arguments at all, but simply | |
| 544 variables which are bound to @code{nil} or to the specified | |
| 545 @var{initforms} during execution of the function. There is no | |
| 546 difference between the following two functions, except for a | |
| 547 matter of stylistic taste: | |
| 548 | |
| 549 @example | |
| 550 (defun* foo (a b &aux (c (+ a b)) d) | |
| 551 @var{body}) | |
| 552 | |
| 553 (defun* foo (a b) | |
| 554 (let ((c (+ a b)) d) | |
| 555 @var{body})) | |
| 556 @end example | |
| 557 | |
| 558 Argument lists support @dfn{destructuring}. In Common Lisp, | |
| 559 destructuring is only allowed with @code{defmacro}; this package | |
| 560 allows it with @code{defun*} and other argument lists as well. | |
| 561 In destructuring, any argument variable (@var{var} in the above | |
| 562 diagram) can be replaced by a list of variables, or more generally, | |
| 563 a recursive argument list. The corresponding argument value must | |
| 564 be a list whose elements match this recursive argument list. | |
| 565 For example: | |
| 566 | |
| 567 @example | |
| 568 (defmacro* dolist ((var listform &optional resultform) | |
| 569 &rest body) | |
| 570 ...) | |
| 571 @end example | |
| 572 | |
| 573 This says that the first argument of @code{dolist} must be a list | |
| 574 of two or three items; if there are other arguments as well as this | |
| 575 list, they are stored in @code{body}. All features allowed in | |
| 576 regular argument lists are allowed in these recursive argument lists. | |
| 577 In addition, the clause @samp{&whole @var{var}} is allowed at the | |
| 578 front of a recursive argument list. It binds @var{var} to the | |
| 579 whole list being matched; thus @code{(&whole all a b)} matches | |
| 580 a list of two things, with @code{a} bound to the first thing, | |
| 581 @code{b} bound to the second thing, and @code{all} bound to the | |
| 582 list itself. (Common Lisp allows @code{&whole} in top-level | |
| 583 @code{defmacro} argument lists as well, but Emacs Lisp does not | |
| 584 support this usage.) | |
| 585 | |
| 586 One last feature of destructuring is that the argument list may be | |
| 587 dotted, so that the argument list @code{(a b . c)} is functionally | |
| 588 equivalent to @code{(a b &rest c)}. | |
| 589 | |
| 590 If the optimization quality @code{safety} is set to 0 | |
| 591 (@pxref{Declarations}), error checking for wrong number of | |
| 592 arguments and invalid keyword arguments is disabled. By default, | |
| 593 argument lists are rigorously checked. | |
| 594 | |
| 595 @node Time of Evaluation, Function Aliases, Argument Lists, Program Structure | |
| 596 @section Time of Evaluation | |
| 597 | |
| 598 @noindent | |
| 599 Normally, the byte-compiler does not actually execute the forms in | |
| 600 a file it compiles. For example, if a file contains @code{(setq foo t)}, | |
| 601 the act of compiling it will not actually set @code{foo} to @code{t}. | |
| 602 This is true even if the @code{setq} was a top-level form (i.e., not | |
| 603 enclosed in a @code{defun} or other form). Sometimes, though, you | |
| 604 would like to have certain top-level forms evaluated at compile-time. | |
| 605 For example, the compiler effectively evaluates @code{defmacro} forms | |
| 606 at compile-time so that later parts of the file can refer to the | |
| 607 macros that are defined. | |
| 608 | |
| 609 @defspec eval-when (situations...) forms... | |
| 610 This form controls when the body @var{forms} are evaluated. | |
| 611 The @var{situations} list may contain any set of the symbols | |
| 612 @code{compile}, @code{load}, and @code{eval} (or their long-winded | |
| 613 ANSI equivalents, @code{:compile-toplevel}, @code{:load-toplevel}, | |
| 614 and @code{:execute}). | |
| 615 | |
| 616 The @code{eval-when} form is handled differently depending on | |
| 617 whether or not it is being compiled as a top-level form. | |
| 618 Specifically, it gets special treatment if it is being compiled | |
| 619 by a command such as @code{byte-compile-file} which compiles files | |
| 620 or buffers of code, and it appears either literally at the | |
| 621 top level of the file or inside a top-level @code{progn}. | |
| 622 | |
| 623 For compiled top-level @code{eval-when}s, the body @var{forms} are | |
| 624 executed at compile-time if @code{compile} is in the @var{situations} | |
| 625 list, and the @var{forms} are written out to the file (to be executed | |
| 626 at load-time) if @code{load} is in the @var{situations} list. | |
| 627 | |
| 628 For non-compiled-top-level forms, only the @code{eval} situation is | |
| 629 relevant. (This includes forms executed by the interpreter, forms | |
| 630 compiled with @code{byte-compile} rather than @code{byte-compile-file}, | |
| 631 and non-top-level forms.) The @code{eval-when} acts like a | |
| 632 @code{progn} if @code{eval} is specified, and like @code{nil} | |
| 633 (ignoring the body @var{forms}) if not. | |
| 634 | |
| 635 The rules become more subtle when @code{eval-when}s are nested; | |
| 636 consult Steele (second edition) for the gruesome details (and | |
| 637 some gruesome examples). | |
| 638 | |
| 639 Some simple examples: | |
| 640 | |
| 641 @example | |
| 642 ;; Top-level forms in foo.el: | |
| 643 (eval-when (compile) (setq foo1 'bar)) | |
| 644 (eval-when (load) (setq foo2 'bar)) | |
| 645 (eval-when (compile load) (setq foo3 'bar)) | |
| 646 (eval-when (eval) (setq foo4 'bar)) | |
| 647 (eval-when (eval compile) (setq foo5 'bar)) | |
| 648 (eval-when (eval load) (setq foo6 'bar)) | |
| 649 (eval-when (eval compile load) (setq foo7 'bar)) | |
| 650 @end example | |
| 651 | |
| 652 When @file{foo.el} is compiled, these variables will be set during | |
| 653 the compilation itself: | |
| 654 | |
| 655 @example | |
| 656 foo1 foo3 foo5 foo7 ; `compile' | |
| 657 @end example | |
| 658 | |
| 659 When @file{foo.elc} is loaded, these variables will be set: | |
| 660 | |
| 661 @example | |
| 662 foo2 foo3 foo6 foo7 ; `load' | |
| 663 @end example | |
| 664 | |
| 665 And if @file{foo.el} is loaded uncompiled, these variables will | |
| 666 be set: | |
| 667 | |
| 668 @example | |
| 669 foo4 foo5 foo6 foo7 ; `eval' | |
| 670 @end example | |
| 671 | |
| 672 If these seven @code{eval-when}s had been, say, inside a @code{defun}, | |
| 673 then the first three would have been equivalent to @code{nil} and the | |
| 674 last four would have been equivalent to the corresponding @code{setq}s. | |
| 675 | |
| 676 Note that @code{(eval-when (load eval) @dots{})} is equivalent | |
| 677 to @code{(progn @dots{})} in all contexts. The compiler treats | |
| 678 certain top-level forms, like @code{defmacro} (sort-of) and | |
| 679 @code{require}, as if they were wrapped in @code{(eval-when | |
| 680 (compile load eval) @dots{})}. | |
| 681 @end defspec | |
| 682 | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4677
diff
changeset
|
683 Emacs 19 includes two special operators related to @code{eval-when}. |
| 428 | 684 One of these, @code{eval-when-compile}, is not quite equivalent to |
| 685 any @code{eval-when} construct and is described below. This package | |
| 686 defines a version of @code{eval-when-compile} for the benefit of | |
| 687 Emacs 18 users. | |
| 688 | |
| 689 The other form, @code{(eval-and-compile @dots{})}, is exactly | |
| 690 equivalent to @samp{(eval-when (compile load eval) @dots{})} and | |
| 691 so is not itself defined by this package. | |
| 692 | |
| 693 @defspec eval-when-compile forms... | |
| 694 The @var{forms} are evaluated at compile-time; at execution time, | |
| 695 this form acts like a quoted constant of the resulting value. Used | |
| 696 at top-level, @code{eval-when-compile} is just like @samp{eval-when | |
| 697 (compile eval)}. In other contexts, @code{eval-when-compile} | |
| 698 allows code to be evaluated once at compile-time for efficiency | |
| 699 or other reasons. | |
| 700 | |
| 701 This form is similar to the @samp{#.} syntax of true Common Lisp. | |
| 702 @end defspec | |
| 703 | |
| 704 @defspec load-time-value form | |
| 705 The @var{form} is evaluated at load-time; at execution time, | |
| 706 this form acts like a quoted constant of the resulting value. | |
| 707 | |
| 708 Early Common Lisp had a @samp{#,} syntax that was similar to | |
| 709 this, but ANSI Common Lisp replaced it with @code{load-time-value} | |
| 710 and gave it more well-defined semantics. | |
| 711 | |
| 712 In a compiled file, @code{load-time-value} arranges for @var{form} | |
| 713 to be evaluated when the @file{.elc} file is loaded and then used | |
| 714 as if it were a quoted constant. In code compiled by | |
| 715 @code{byte-compile} rather than @code{byte-compile-file}, the | |
| 716 effect is identical to @code{eval-when-compile}. In uncompiled | |
| 717 code, both @code{eval-when-compile} and @code{load-time-value} | |
| 718 act exactly like @code{progn}. | |
| 719 | |
| 720 @example | |
| 721 (defun report () | |
| 722 (insert "This function was executed on: " | |
| 723 (current-time-string) | |
| 724 ", compiled on: " | |
| 725 (eval-when-compile (current-time-string)) | |
| 726 ;; or '#.(current-time-string) in real Common Lisp | |
| 727 ", and loaded on: " | |
| 728 (load-time-value (current-time-string)))) | |
| 729 @end example | |
| 730 | |
| 731 @noindent | |
| 732 Byte-compiled, the above defun will result in the following code | |
| 733 (or its compiled equivalent, of course) in the @file{.elc} file: | |
| 734 | |
| 735 @example | |
| 736 (setq --temp-- (current-time-string)) | |
| 737 (defun report () | |
| 738 (insert "This function was executed on: " | |
| 739 (current-time-string) | |
| 740 ", compiled on: " | |
| 741 '"Wed Jun 23 18:33:43 1993" | |
| 742 ", and loaded on: " | |
| 743 --temp--)) | |
| 744 @end example | |
| 745 @end defspec | |
| 746 | |
| 747 @node Function Aliases, , Time of Evaluation, Program Structure | |
| 748 @section Function Aliases | |
| 749 | |
| 750 @noindent | |
| 751 This section describes a feature from GNU Emacs 19 which this | |
| 752 package makes available in other versions of Emacs. | |
| 753 | |
| 754 @defun defalias symbol function | |
| 755 This function sets @var{symbol}'s function cell to @var{function}. | |
| 756 It is equivalent to @code{fset}, except that in GNU Emacs 19 it also | |
| 757 records the setting in @code{load-history} so that it can be undone | |
| 758 by a later @code{unload-feature}. | |
| 759 | |
| 760 In other versions of Emacs, @code{defalias} is a synonym for | |
| 761 @code{fset}. | |
| 762 @end defun | |
| 763 | |
| 764 @node Predicates, Control Structure, Program Structure, Top | |
| 765 @chapter Predicates | |
| 766 | |
| 767 @noindent | |
| 768 This section describes functions for testing whether various | |
| 769 facts are true or false. | |
| 770 | |
| 771 @menu | |
| 772 * Type Predicates:: `typep', `deftype', and `coerce' | |
| 773 * Equality Predicates:: `eql' and `equalp' | |
| 774 @end menu | |
| 775 | |
| 776 @node Type Predicates, Equality Predicates, Predicates, Predicates | |
| 777 @section Type Predicates | |
| 778 | |
| 779 @noindent | |
| 780 The @dfn{CL} package defines a version of the Common Lisp @code{typep} | |
| 781 predicate. | |
| 782 | |
| 783 @defun typep object type | |
| 784 Check if @var{object} is of type @var{type}, where @var{type} is a | |
| 785 (quoted) type name of the sort used by Common Lisp. For example, | |
| 786 @code{(typep foo 'integer)} is equivalent to @code{(integerp foo)}. | |
| 787 @end defun | |
| 788 | |
| 789 The @var{type} argument to the above function is either a symbol | |
| 790 or a list beginning with a symbol. | |
| 791 | |
| 792 @itemize @bullet | |
| 793 @item | |
| 794 If the type name is a symbol, Emacs appends @samp{-p} to the | |
| 795 symbol name to form the name of a predicate function for testing | |
| 796 the type. (Built-in predicates whose names end in @samp{p} rather | |
| 797 than @samp{-p} are used when appropriate.) | |
| 798 | |
| 799 @item | |
| 800 The type symbol @code{t} stands for the union of all types. | |
| 801 @code{(typep @var{object} t)} is always true. Likewise, the | |
| 802 type symbol @code{nil} stands for nothing at all, and | |
| 803 @code{(typep @var{object} nil)} is always false. | |
| 804 | |
| 805 @item | |
| 806 The type symbol @code{null} represents the symbol @code{nil}. | |
| 807 Thus @code{(typep @var{object} 'null)} is equivalent to | |
| 808 @code{(null @var{object})}. | |
| 809 | |
| 810 @item | |
| 811 The type symbol @code{real} is a synonym for @code{number}, and | |
| 812 @code{fixnum} is a synonym for @code{integer}. | |
| 813 | |
| 814 @item | |
| 815 The type symbols @code{character} and @code{string-char} match | |
| 816 characters. In Emacs-19 and XEmacs-19, characters are the same thing as | |
| 817 integers in the range 0-255. In XEmacs-20, where characters are a | |
| 818 first-class data type, this checks for actual characters, and | |
| 819 @code{(typep @var{8bit-integer} 'character)} will return @code{nil}. | |
| 820 | |
| 821 @item | |
| 822 The type symbol @code{float} uses the @code{floatp-safe} predicate | |
| 823 defined by this package rather than @code{floatp}, so it will work | |
| 824 correctly even in Emacs versions without floating-point support. | |
| 825 | |
| 826 @item | |
| 827 The type list @code{(integer @var{low} @var{high})} represents all | |
| 828 integers between @var{low} and @var{high}, inclusive. Either bound | |
| 829 may be a list of a single integer to specify an exclusive limit, | |
| 830 or a @code{*} to specify no limit. The type @code{(integer * *)} | |
| 831 is thus equivalent to @code{integer}. | |
| 832 | |
| 833 @item | |
| 834 Likewise, lists beginning with @code{float}, @code{real}, or | |
| 835 @code{number} represent numbers of that type falling in a particular | |
| 836 range. | |
| 837 | |
| 838 @item | |
| 839 Lists beginning with @code{and}, @code{or}, and @code{not} form | |
| 840 combinations of types. For example, @code{(or integer (float 0 *))} | |
| 841 represents all objects that are integers or non-negative floats. | |
| 842 | |
| 843 @item | |
| 844 Lists beginning with @code{member} or @code{member*} represent | |
| 845 objects @code{eql} to any of the following values. For example, | |
| 846 @code{(member 1 2 3 4)} is equivalent to @code{(integer 1 4)}, | |
| 847 and @code{(member nil)} is equivalent to @code{null}. | |
| 848 | |
| 849 @item | |
| 850 Lists of the form @code{(satisfies @var{predicate})} represent | |
| 851 all objects for which @var{predicate} returns true when called | |
| 852 with that object as an argument. | |
| 853 @end itemize | |
| 854 | |
| 855 The following function and macro (not technically predicates) are | |
| 856 related to @code{typep}. | |
| 857 | |
| 858 @defun coerce object type | |
| 859 This function attempts to convert @var{object} to the specified | |
| 860 @var{type}. If @var{object} is already of that type as determined by | |
| 861 @code{typep}, it is simply returned. Otherwise, certain types of | |
| 862 conversions will be made: If @var{type} is any sequence type | |
| 863 (@code{string}, @code{list}, etc.) then @var{object} will be | |
| 864 converted to that type if possible. If @var{type} is | |
| 865 @code{character}, then strings of length one and symbols with | |
| 866 one-character names can be coerced. If @var{type} is @code{float}, | |
| 867 then integers can be coerced in versions of Emacs that support | |
| 868 floats. In all other circumstances, @code{coerce} signals an | |
| 869 error. | |
| 870 @end defun | |
| 871 | |
| 872 @defspec deftype name arglist forms... | |
| 873 This macro defines a new type called @var{name}. It is similar | |
| 874 to @code{defmacro} in many ways; when @var{name} is encountered | |
| 875 as a type name, the body @var{forms} are evaluated and should | |
| 876 return a type specifier that is equivalent to the type. The | |
| 877 @var{arglist} is a Common Lisp argument list of the sort accepted | |
| 878 by @code{defmacro*}. The type specifier @samp{(@var{name} @var{args}...)} | |
| 879 is expanded by calling the expander with those arguments; the type | |
| 880 symbol @samp{@var{name}} is expanded by calling the expander with | |
| 881 no arguments. The @var{arglist} is processed the same as for | |
| 882 @code{defmacro*} except that optional arguments without explicit | |
| 883 defaults use @code{*} instead of @code{nil} as the ``default'' | |
| 884 default. Some examples: | |
| 885 | |
| 886 @example | |
| 887 (deftype null () '(satisfies null)) ; predefined | |
| 888 (deftype list () '(or null cons)) ; predefined | |
| 889 (deftype unsigned-byte (&optional bits) | |
| 890 (list 'integer 0 (if (eq bits '*) bits (1- (lsh 1 bits))))) | |
| 891 (unsigned-byte 8) @equiv{} (integer 0 255) | |
| 892 (unsigned-byte) @equiv{} (integer 0 *) | |
| 893 unsigned-byte @equiv{} (integer 0 *) | |
| 894 @end example | |
| 895 | |
| 896 @noindent | |
| 897 The last example shows how the Common Lisp @code{unsigned-byte} | |
| 898 type specifier could be implemented if desired; this package does | |
| 899 not implement @code{unsigned-byte} by default. | |
| 900 @end defspec | |
| 901 | |
| 902 The @code{typecase} and @code{check-type} macros also use type | |
| 903 names. @xref{Conditionals}. @xref{Assertions}. The @code{map}, | |
| 904 @code{concatenate}, and @code{merge} functions take type-name | |
| 905 arguments to specify the type of sequence to return. @xref{Sequences}. | |
| 906 | |
| 907 @node Equality Predicates, , Type Predicates, Predicates | |
| 908 @section Equality Predicates | |
| 909 | |
| 910 @noindent | |
| 911 This package defines two Common Lisp predicates, @code{eql} and | |
| 912 @code{equalp}. | |
| 913 | |
| 914 @defun eql a b | |
| 915 This function is almost the same as @code{eq}, except that if @var{a} | |
| 916 and @var{b} are numbers of the same type, it compares them for numeric | |
| 917 equality (as if by @code{equal} instead of @code{eq}). This makes a | |
| 918 difference only for versions of Emacs that are compiled with | |
| 919 floating-point support, such as Emacs 19. Emacs floats are allocated | |
| 920 objects just like cons cells, which means that @code{(eq 3.0 3.0)} | |
| 921 will not necessarily be true---if the two @code{3.0}s were allocated | |
| 922 separately, the pointers will be different even though the numbers are | |
| 923 the same. But @code{(eql 3.0 3.0)} will always be true. | |
| 924 | |
| 925 The types of the arguments must match, so @code{(eql 3 3.0)} is | |
| 926 still false. | |
| 927 | |
| 928 Note that Emacs integers are ``direct'' rather than allocated, which | |
| 929 basically means @code{(eq 3 3)} will always be true. Thus @code{eq} | |
| 930 and @code{eql} behave differently only if floating-point numbers are | |
| 931 involved, and are indistinguishable on Emacs versions that don't | |
| 932 support floats. | |
| 933 | |
| 934 There is a slight inconsistency with Common Lisp in the treatment of | |
| 935 positive and negative zeros. Some machines, notably those with IEEE | |
| 936 standard arithmetic, represent @code{+0} and @code{-0} as distinct | |
| 937 values. Normally this doesn't matter because the standard specifies | |
| 938 that @code{(= 0.0 -0.0)} should always be true, and this is indeed | |
| 939 what Emacs Lisp and Common Lisp do. But the Common Lisp standard | |
| 940 states that @code{(eql 0.0 -0.0)} and @code{(equal 0.0 -0.0)} should | |
| 941 be false on IEEE-like machines; Emacs Lisp does not do this, and in | |
| 942 fact the only known way to distinguish between the two zeros in Emacs | |
| 943 Lisp is to @code{format} them and check for a minus sign. | |
| 944 @end defun | |
| 945 | |
| 946 @defun equalp a b | |
| 947 This function is a more flexible version of @code{equal}. In | |
| 948 particular, it compares strings and characters case-insensitively, and | |
| 949 it compares numbers without regard to type (so that @code{(equalp 3 | |
| 950 3.0)} is true). Vectors and conses are compared recursively. All other | |
| 951 objects are compared as if by @code{equal}. | |
| 952 | |
| 953 This function differs from Common Lisp @code{equalp} in several | |
| 954 respects. In keeping with the idea that strings are less | |
| 955 vector-like in Emacs Lisp, this package's @code{equalp} also will not | |
| 956 compare strings against vectors of integers. | |
| 957 @end defun | |
| 958 | |
| 959 Also note that the Common Lisp functions @code{member} and @code{assoc} | |
| 960 use @code{eql} to compare elements, whereas Emacs Lisp follows the | |
| 961 MacLisp tradition and uses @code{equal} for these two functions. | |
| 962 In Emacs, use @code{member*} and @code{assoc*} to get functions | |
| 963 which use @code{eql} for comparisons. | |
| 964 | |
| 965 @node Control Structure, Macros, Predicates, Top | |
| 966 @chapter Control Structure | |
| 967 | |
| 968 @noindent | |
| 969 The features described in the following sections implement | |
| 970 various advanced control structures, including the powerful | |
| 971 @code{setf} facility and a number of looping and conditional | |
| 972 constructs. | |
| 973 | |
| 974 @menu | |
| 975 * Assignment:: The `psetq' form | |
| 976 * Generalized Variables:: `setf', `incf', `push', etc. | |
| 977 * Variable Bindings:: `progv', `lexical-let', `flet', `macrolet' | |
| 978 * Conditionals:: `when', `unless', `case', `typecase' | |
| 979 * Blocks and Exits:: `block', `return', `return-from' | |
| 980 * Iteration:: `do', `dotimes', `dolist', `do-symbols' | |
| 981 * Loop Facility:: The Common Lisp `loop' macro | |
| 982 * Multiple Values:: `values', `multiple-value-bind', etc. | |
| 983 @end menu | |
| 984 | |
| 985 @node Assignment, Generalized Variables, Control Structure, Control Structure | |
| 986 @section Assignment | |
| 987 | |
| 988 @noindent | |
| 989 The @code{psetq} form is just like @code{setq}, except that multiple | |
| 990 assignments are done in parallel rather than sequentially. | |
| 991 | |
| 992 @defspec psetq [symbol form]@dots{} | |
|
4905
755ae5b97edb
Change "special form" to "special operator" in our sources.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4677
diff
changeset
|
993 This macro is used to assign to several |
| 428 | 994 variables simultaneously. Given only one @var{symbol} and @var{form}, |
| 995 it has the same effect as @code{setq}. Given several @var{symbol} | |
| 996 and @var{form} pairs, it evaluates all the @var{form}s in advance | |
| 997 and then stores the corresponding variables afterwards. | |
| 998 | |
| 999 @example | |
| 1000 (setq x 2 y 3) | |
| 1001 (setq x (+ x y) y (* x y)) | |
| 1002 x | |
| 1003 @result{} 5 | |
| 1004 y ; @r{@code{y} was computed after @code{x} was set.} | |
| 1005 @result{} 15 | |
| 1006 (setq x 2 y 3) | |
| 1007 (psetq x (+ x y) y (* x y)) | |
| 1008 x | |
| 1009 @result{} 5 | |
| 1010 y ; @r{@code{y} was computed before @code{x} was set.} | |
| 1011 @result{} 6 | |
| 1012 @end example | |
| 1013 | |
| 1014 The simplest use of @code{psetq} is @code{(psetq x y y x)}, which | |
| 1015 exchanges the values of two variables. (The @code{rotatef} form | |
| 1016 provides an even more convenient way to swap two variables; | |
| 1017 @pxref{Modify Macros}.) | |
| 1018 | |
| 1019 @code{psetq} always returns @code{nil}. | |
| 1020 @end defspec | |
| 1021 | |
| 1022 @node Generalized Variables, Variable Bindings, Assignment, Control Structure | |
| 1023 @section Generalized Variables | |
| 1024 | |
| 1025 @noindent | |
| 1026 A ``generalized variable'' or ``place form'' is one of the many places | |
| 1027 in Lisp memory where values can be stored. The simplest place form is | |
| 1028 a regular Lisp variable. But the cars and cdrs of lists, elements | |
| 1029 of arrays, properties of symbols, and many other locations are also | |
| 1030 places where Lisp values are stored. | |
| 1031 | |
| 1032 The @code{setf} form is like @code{setq}, except that it accepts | |
| 1033 arbitrary place forms on the left side rather than just | |
| 1034 symbols. For example, @code{(setf (car a) b)} sets the car of | |
| 1035 @code{a} to @code{b}, doing the same operation as @code{(setcar a b)} | |
| 1036 but without having to remember two separate functions for setting | |
| 1037 and accessing every type of place. | |
| 1038 | |
| 1039 Generalized variables are analogous to ``lvalues'' in the C | |
| 1040 language, where @samp{x = a[i]} gets an element from an array | |
| 1041 and @samp{a[i] = x} stores an element using the same notation. | |
| 1042 Just as certain forms like @code{a[i]} can be lvalues in C, there | |
| 1043 is a set of forms that can be generalized variables in Lisp. | |
| 1044 | |
| 1045 @menu | |
| 1046 * Basic Setf:: `setf' and place forms | |
| 1047 * Modify Macros:: `incf', `push', `rotatef', `letf', `callf', etc. | |
| 1048 * Customizing Setf:: `define-modify-macro', `defsetf', `define-setf-method' | |
| 1049 @end menu | |
| 1050 | |
| 1051 @node Basic Setf, Modify Macros, Generalized Variables, Generalized Variables | |
| 1052 @subsection Basic Setf | |
| 1053 | |
| 1054 @noindent | |
| 1055 The @code{setf} macro is the most basic way to operate on generalized | |
| 1056 variables. | |
| 1057 | |
| 1058 @defspec setf [place form]@dots{} | |
| 1059 This macro evaluates @var{form} and stores it in @var{place}, which | |
| 1060 must be a valid generalized variable form. If there are several | |
| 1061 @var{place} and @var{form} pairs, the assignments are done sequentially | |
| 1062 just as with @code{setq}. @code{setf} returns the value of the last | |
| 1063 @var{form}. | |
| 1064 | |
| 1065 The following Lisp forms will work as generalized variables, and | |
| 1066 so may legally appear in the @var{place} argument of @code{setf}: | |
| 1067 | |
| 1068 @itemize @bullet | |
| 1069 @item | |
| 1070 A symbol naming a variable. In other words, @code{(setf x y)} is | |
| 1071 exactly equivalent to @code{(setq x y)}, and @code{setq} itself is | |
| 1072 strictly speaking redundant now that @code{setf} exists. Many | |
| 1073 programmers continue to prefer @code{setq} for setting simple | |
| 1074 variables, though, purely for stylistic or historical reasons. | |
| 446 | 1075 The form @code{(setf x y)} actually expands to @code{(setq x y)}, |
| 428 | 1076 so there is no performance penalty for using it in compiled code. |
| 1077 | |
| 1078 @item | |
| 1079 A call to any of the following Lisp functions: | |
| 1080 | |
| 1081 @smallexample | |
| 1082 car cdr caar .. cddddr | |
| 1083 nth rest first .. tenth | |
| 1084 aref elt nthcdr | |
| 1085 symbol-function symbol-value symbol-plist | |
| 440 | 1086 get getf gethash |
| 1087 subseq | |
| 428 | 1088 @end smallexample |
| 1089 | |
| 1090 @noindent | |
| 1091 Note that for @code{nthcdr} and @code{getf}, the list argument | |
| 1092 of the function must itself be a valid @var{place} form. For | |
| 1093 example, @code{(setf (nthcdr 0 foo) 7)} will set @code{foo} itself | |
| 1094 to 7. Note that @code{push} and @code{pop} on an @code{nthcdr} | |
| 1095 place can be used to insert or delete at any position in a list. | |
| 1096 The use of @code{nthcdr} as a @var{place} form is an extension | |
| 1097 to standard Common Lisp. | |
| 1098 | |
| 1099 @item | |
| 1100 The following Emacs-specific functions are also @code{setf}-able. | |
| 1101 (Some of these are defined only in Emacs 19 or only in XEmacs.) | |
| 1102 | |
| 1103 @smallexample | |
| 1104 buffer-file-name marker-position | |
| 1105 buffer-modified-p match-data | |
| 1106 buffer-name mouse-position | |
| 1107 buffer-string overlay-end | |
| 1108 buffer-substring overlay-get | |
| 1109 current-buffer overlay-start | |
| 1110 current-case-table point | |
| 1111 current-column point-marker | |
| 1112 current-global-map point-max | |
| 1113 current-input-mode point-min | |
| 1114 current-local-map process-buffer | |
| 1115 current-window-configuration process-filter | |
| 1116 default-file-modes process-sentinel | |
| 1117 default-value read-mouse-position | |
| 1118 documentation-property screen-height | |
| 1119 extent-data screen-menubar | |
| 1120 extent-end-position screen-width | |
| 1121 extent-start-position selected-window | |
| 1122 face-background selected-screen | |
| 1123 face-background-pixmap selected-frame | |
| 1124 face-font standard-case-table | |
| 1125 face-foreground syntax-table | |
| 1126 face-underline-p window-buffer | |
| 1127 file-modes window-dedicated-p | |
| 1128 frame-height window-display-table | |
| 1129 frame-parameters window-height | |
| 1130 frame-visible-p window-hscroll | |
| 1131 frame-width window-point | |
| 1132 get-register window-start | |
| 1133 getenv window-width | |
| 1134 global-key-binding x-get-cut-buffer | |
| 1135 keymap-parent x-get-cutbuffer | |
| 1136 local-key-binding x-get-secondary-selection | |
| 1137 mark x-get-selection | |
| 1138 mark-marker | |
| 1139 @end smallexample | |
| 1140 | |
| 1141 Most of these have directly corresponding ``set'' functions, like | |
| 1142 @code{use-local-map} for @code{current-local-map}, or @code{goto-char} | |
| 1143 for @code{point}. A few, like @code{point-min}, expand to longer | |
| 1144 sequences of code when they are @code{setf}'d (@code{(narrow-to-region | |
| 1145 x (point-max))} in this case). | |
| 1146 | |
| 1147 @item | |
| 1148 A call of the form @code{(substring @var{subplace} @var{n} [@var{m}])}, | |
| 1149 where @var{subplace} is itself a legal generalized variable whose | |
| 1150 current value is a string, and where the value stored is also a | |
| 1151 string. The new string is spliced into the specified part of the | |
| 1152 destination string. For example: | |
| 1153 | |
| 1154 @example | |
| 1155 (setq a (list "hello" "world")) | |
| 1156 @result{} ("hello" "world") | |
| 1157 (cadr a) | |
| 1158 @result{} "world" | |
| 1159 (substring (cadr a) 2 4) | |
| 1160 @result{} "rl" | |
| 1161 (setf (substring (cadr a) 2 4) "o") | |
| 1162 @result{} "o" | |
| 1163 (cadr a) | |
| 1164 @result{} "wood" | |
| 1165 a | |
| 1166 @result{} ("hello" "wood") | |
| 1167 @end example | |
| 1168 | |
| 1169 The generalized variable @code{buffer-substring}, listed above, | |
| 1170 also works in this way by replacing a portion of the current buffer. | |
| 1171 | |
| 1172 @item | |
| 1173 A call of the form @code{(apply '@var{func} @dots{})} or | |
| 1174 @code{(apply (function @var{func}) @dots{})}, where @var{func} | |
| 1175 is a @code{setf}-able function whose store function is ``suitable'' | |
| 1176 in the sense described in Steele's book; since none of the standard | |
| 1177 Emacs place functions are suitable in this sense, this feature is | |
| 1178 only interesting when used with places you define yourself with | |
| 1179 @code{define-setf-method} or the long form of @code{defsetf}. | |
| 1180 | |
| 1181 @item | |
| 1182 A macro call, in which case the macro is expanded and @code{setf} | |
| 1183 is applied to the resulting form. | |
| 1184 | |
| 1185 @item | |
| 1186 Any form for which a @code{defsetf} or @code{define-setf-method} | |
| 1187 has been made. | |
| 1188 @end itemize | |
| 1189 | |
| 1190 Using any forms other than these in the @var{place} argument to | |
| 1191 @code{setf} will signal an error. | |
| 1192 | |
| 1193 The @code{setf} macro takes care to evaluate all subforms in | |
| 1194 the proper left-to-right order; for example, | |
| 1195 | |
| 1196 @example | |
| 1197 (setf (aref vec (incf i)) i) | |
| 1198 @end example | |
| 1199 | |
| 1200 @noindent | |
| 1201 looks like it will evaluate @code{(incf i)} exactly once, before the | |
| 1202 following access to @code{i}; the @code{setf} expander will insert | |
| 1203 temporary variables as necessary to ensure that it does in fact work | |
| 1204 this way no matter what setf-method is defined for @code{aref}. | |
| 1205 (In this case, @code{aset} would be used and no such steps would | |
| 1206 be necessary since @code{aset} takes its arguments in a convenient | |
| 1207 order.) | |
| 1208 | |
| 1209 However, if the @var{place} form is a macro which explicitly | |
| 1210 evaluates its arguments in an unusual order, this unusual order | |
| 1211 will be preserved. Adapting an example from Steele, given | |
| 1212 | |
| 1213 @example | |
| 1214 (defmacro wrong-order (x y) (list 'aref y x)) | |
| 1215 @end example | |
| 1216 | |
| 1217 @noindent | |
| 1218 the form @code{(setf (wrong-order @var{a} @var{b}) 17)} will | |
| 1219 evaluate @var{b} first, then @var{a}, just as in an actual call | |
| 1220 to @code{wrong-order}. | |
| 1221 @end defspec | |
| 1222 | |
| 1223 @node Modify Macros, Customizing Setf, Basic Setf, Generalized Variables | |
| 1224 @subsection Modify Macros | |
| 1225 | |
| 1226 @noindent | |
| 1227 This package defines a number of other macros besides @code{setf} | |
| 1228 that operate on generalized variables. Many are interesting and | |
| 1229 useful even when the @var{place} is just a variable name. | |
| 1230 | |
| 1231 @defspec psetf [place form]@dots{} | |
| 1232 This macro is to @code{setf} what @code{psetq} is to @code{setq}: | |
| 1233 When several @var{place}s and @var{form}s are involved, the | |
| 1234 assignments take place in parallel rather than sequentially. | |
| 1235 Specifically, all subforms are evaluated from left to right, then | |
| 1236 all the assignments are done (in an undefined order). | |
| 1237 @end defspec | |
| 1238 | |
| 1239 @defspec incf place &optional x | |
| 1240 This macro increments the number stored in @var{place} by one, or | |
| 1241 by @var{x} if specified. The incremented value is returned. For | |
| 1242 example, @code{(incf i)} is equivalent to @code{(setq i (1+ i))}, and | |
| 1243 @code{(incf (car x) 2)} is equivalent to @code{(setcar x (+ (car x) 2))}. | |
| 1244 | |
| 1245 Once again, care is taken to preserve the ``apparent'' order of | |
| 1246 evaluation. For example, | |
| 1247 | |
| 1248 @example | |
| 1249 (incf (aref vec (incf i))) | |
| 1250 @end example | |
| 1251 | |
| 1252 @noindent | |
| 1253 appears to increment @code{i} once, then increment the element of | |
| 1254 @code{vec} addressed by @code{i}; this is indeed exactly what it | |
| 1255 does, which means the above form is @emph{not} equivalent to the | |
| 1256 ``obvious'' expansion, | |
| 1257 | |
| 1258 @example | |
| 1259 (setf (aref vec (incf i)) (1+ (aref vec (incf i)))) ; Wrong! | |
| 1260 @end example | |
| 1261 | |
| 1262 @noindent | |
| 1263 but rather to something more like | |
| 1264 | |
| 1265 @example | |
| 1266 (let ((temp (incf i))) | |
| 1267 (setf (aref vec temp) (1+ (aref vec temp)))) | |
| 1268 @end example | |
| 1269 | |
| 1270 @noindent | |
| 1271 Again, all of this is taken care of automatically by @code{incf} and | |
| 1272 the other generalized-variable macros. | |
| 1273 | |
| 1274 As a more Emacs-specific example of @code{incf}, the expression | |
| 1275 @code{(incf (point) @var{n})} is essentially equivalent to | |
| 1276 @code{(forward-char @var{n})}. | |
| 1277 @end defspec | |
| 1278 | |
| 1279 @defspec decf place &optional x | |
| 1280 This macro decrements the number stored in @var{place} by one, or | |
| 1281 by @var{x} if specified. | |
| 1282 @end defspec | |
| 1283 | |
| 1284 @defspec pop place | |
| 1285 This macro removes and returns the first element of the list stored | |
| 1286 in @var{place}. It is analogous to @code{(prog1 (car @var{place}) | |
| 1287 (setf @var{place} (cdr @var{place})))}, except that it takes care | |
| 1288 to evaluate all subforms only once. | |
| 1289 @end defspec | |
| 1290 | |
| 1291 @defspec push x place | |
| 1292 This macro inserts @var{x} at the front of the list stored in | |
| 1293 @var{place}. It is analogous to @code{(setf @var{place} (cons | |
| 1294 @var{x} @var{place}))}, except for evaluation of the subforms. | |
| 1295 @end defspec | |
| 1296 | |
| 1297 @defspec pushnew x place @t{&key :test :test-not :key} | |
| 1298 This macro inserts @var{x} at the front of the list stored in | |
| 1299 @var{place}, but only if @var{x} was not @code{eql} to any | |
| 1300 existing element of the list. The optional keyword arguments | |
| 1301 are interpreted in the same way as for @code{adjoin}. | |
| 1302 @xref{Lists as Sets}. | |
| 1303 @end defspec | |
| 1304 | |
| 1305 @defspec shiftf place@dots{} newvalue | |
| 1306 This macro shifts the @var{place}s left by one, shifting in the | |
| 1307 value of @var{newvalue} (which may be any Lisp expression, not just | |
| 1308 a generalized variable), and returning the value shifted out of | |
| 1309 the first @var{place}. Thus, @code{(shiftf @var{a} @var{b} @var{c} | |
| 1310 @var{d})} is equivalent to | |
| 1311 | |
| 1312 @example | |
| 1313 (prog1 | |
| 1314 @var{a} | |
| 1315 (psetf @var{a} @var{b} | |
| 1316 @var{b} @var{c} | |
| 1317 @var{c} @var{d})) | |
| 1318 @end example | |
| 1319 | |
| 1320 @noindent | |
| 1321 except that the subforms of @var{a}, @var{b}, and @var{c} are actually | |
| 1322 evaluated only once each and in the apparent order. | |
| 1323 @end defspec | |
| 1324 | |
| 1325 @defspec rotatef place@dots{} | |
| 1326 This macro rotates the @var{place}s left by one in circular fashion. | |
| 1327 Thus, @code{(rotatef @var{a} @var{b} @var{c} @var{d})} is equivalent to | |
| 1328 | |
| 1329 @example | |
| 1330 (psetf @var{a} @var{b} | |
| 1331 @var{b} @var{c} | |
| 1332 @var{c} @var{d} | |
| 1333 @var{d} @var{a}) | |
| 1334 @end example | |
| 1335 | |
| 1336 @noindent | |
| 1337 except for the evaluation of subforms. @code{rotatef} always | |
| 1338 returns @code{nil}. Note that @code{(rotatef @var{a} @var{b})} | |
| 1339 conveniently exchanges @var{a} and @var{b}. | |
| 1340 @end defspec | |
| 1341 | |
| 1342 The following macros were invented for this package; they have no | |
| 1343 analogues in Common Lisp. | |
| 1344 | |
| 1345 @defspec letf (bindings@dots{}) forms@dots{} | |
| 1346 This macro is analogous to @code{let}, but for generalized variables | |
| 1347 rather than just symbols. Each @var{binding} should be of the form | |
| 1348 @code{(@var{place} @var{value})}; the original contents of the | |
| 1349 @var{place}s are saved, the @var{value}s are stored in them, and | |
| 1350 then the body @var{form}s are executed. Afterwards, the @var{places} | |
| 1351 are set back to their original saved contents. This cleanup happens | |
| 1352 even if the @var{form}s exit irregularly due to a @code{throw} or an | |
| 1353 error. | |
| 1354 | |
| 1355 For example, | |
| 1356 | |
| 1357 @example | |
| 1358 (letf (((point) (point-min)) | |
| 1359 (a 17)) | |
| 1360 ...) | |
| 1361 @end example | |
| 1362 | |
| 1363 @noindent | |
| 1364 moves ``point'' in the current buffer to the beginning of the buffer, | |
| 1365 and also binds @code{a} to 17 (as if by a normal @code{let}, since | |
| 1366 @code{a} is just a regular variable). After the body exits, @code{a} | |
| 1367 is set back to its original value and point is moved back to its | |
| 1368 original position. | |
| 1369 | |
| 1370 Note that @code{letf} on @code{(point)} is not quite like a | |
| 1371 @code{save-excursion}, as the latter effectively saves a marker | |
| 1372 which tracks insertions and deletions in the buffer. Actually, | |
| 1373 a @code{letf} of @code{(point-marker)} is much closer to this | |
| 1374 behavior. (@code{point} and @code{point-marker} are equivalent | |
| 1375 as @code{setf} places; each will accept either an integer or a | |
| 1376 marker as the stored value.) | |
| 1377 | |
| 1378 Since generalized variables look like lists, @code{let}'s shorthand | |
| 1379 of using @samp{foo} for @samp{(foo nil)} as a @var{binding} would | |
| 1380 be ambiguous in @code{letf} and is not allowed. | |
| 1381 | |
| 1382 However, a @var{binding} specifier may be a one-element list | |
| 1383 @samp{(@var{place})}, which is similar to @samp{(@var{place} | |
| 1384 @var{place})}. In other words, the @var{place} is not disturbed | |
| 1385 on entry to the body, and the only effect of the @code{letf} is | |
| 1386 to restore the original value of @var{place} afterwards. (The | |
| 1387 redundant access-and-store suggested by the @code{(@var{place} | |
| 1388 @var{place})} example does not actually occur.) | |
| 1389 | |
| 1390 In most cases, the @var{place} must have a well-defined value on | |
| 1391 entry to the @code{letf} form. The only exceptions are plain | |
| 1392 variables and calls to @code{symbol-value} and @code{symbol-function}. | |
| 1393 If the symbol is not bound on entry, it is simply made unbound by | |
| 1394 @code{makunbound} or @code{fmakunbound} on exit. | |
| 1395 @end defspec | |
| 1396 | |
| 1397 @defspec letf* (bindings@dots{}) forms@dots{} | |
| 1398 This macro is to @code{letf} what @code{let*} is to @code{let}: | |
| 1399 It does the bindings in sequential rather than parallel order. | |
| 1400 @end defspec | |
| 1401 | |
| 1402 @defspec callf @var{function} @var{place} @var{args}@dots{} | |
| 1403 This is the ``generic'' modify macro. It calls @var{function}, | |
| 1404 which should be an unquoted function name, macro name, or lambda. | |
| 1405 It passes @var{place} and @var{args} as arguments, and assigns the | |
| 1406 result back to @var{place}. For example, @code{(incf @var{place} | |
| 1407 @var{n})} is the same as @code{(callf + @var{place} @var{n})}. | |
| 1408 Some more examples: | |
| 1409 | |
| 1410 @example | |
| 1411 (callf abs my-number) | |
| 1412 (callf concat (buffer-name) "<" (int-to-string n) ">") | |
| 1413 (callf union happy-people (list joe bob) :test 'same-person) | |
| 1414 @end example | |
| 1415 | |
| 1416 @xref{Customizing Setf}, for @code{define-modify-macro}, a way | |
| 1417 to create even more concise notations for modify macros. Note | |
| 1418 again that @code{callf} is an extension to standard Common Lisp. | |
| 1419 @end defspec | |
| 1420 | |
| 1421 @defspec callf2 @var{function} @var{arg1} @var{place} @var{args}@dots{} | |
| 1422 This macro is like @code{callf}, except that @var{place} is | |
| 1423 the @emph{second} argument of @var{function} rather than the | |
| 1424 first. For example, @code{(push @var{x} @var{place})} is | |
| 1425 equivalent to @code{(callf2 cons @var{x} @var{place})}. | |
| 1426 @end defspec | |
| 1427 | |
| 1428 The @code{callf} and @code{callf2} macros serve as building | |
| 1429 blocks for other macros like @code{incf}, @code{pushnew}, and | |
| 1430 @code{define-modify-macro}. The @code{letf} and @code{letf*} | |
| 1431 macros are used in the processing of symbol macros; | |
| 1432 @pxref{Macro Bindings}. | |
| 1433 | |
| 1434 @node Customizing Setf, , Modify Macros, Generalized Variables | |
| 1435 @subsection Customizing Setf | |
| 1436 | |
| 1437 @noindent | |
| 1438 Common Lisp defines three macros, @code{define-modify-macro}, | |
| 1439 @code{defsetf}, and @code{define-setf-method}, that allow the | |
| 1440 user to extend generalized variables in various ways. | |
| 1441 | |
| 1442 @defspec define-modify-macro name arglist function [doc-string] | |
| 1443 This macro defines a ``read-modify-write'' macro similar to | |
| 1444 @code{incf} and @code{decf}. The macro @var{name} is defined | |
| 1445 to take a @var{place} argument followed by additional arguments | |
| 1446 described by @var{arglist}. The call | |
| 1447 | |
| 1448 @example | |
| 1449 (@var{name} @var{place} @var{args}...) | |
| 1450 @end example | |
| 1451 | |
| 1452 @noindent | |
| 1453 will be expanded to | |
| 1454 | |
| 1455 @example | |
| 1456 (callf @var{func} @var{place} @var{args}...) | |
| 1457 @end example | |
| 1458 | |
| 1459 @noindent | |
| 1460 which in turn is roughly equivalent to | |
| 1461 | |
| 1462 @example | |
| 1463 (setf @var{place} (@var{func} @var{place} @var{args}...)) | |
| 1464 @end example | |
| 1465 | |
| 1466 For example: | |
| 1467 | |
| 1468 @example | |
| 1469 (define-modify-macro incf (&optional (n 1)) +) | |
| 1470 (define-modify-macro concatf (&rest args) concat) | |
| 1471 @end example | |
| 1472 | |
| 1473 Note that @code{&key} is not allowed in @var{arglist}, but | |
| 1474 @code{&rest} is sufficient to pass keywords on to the function. | |
| 1475 | |
| 1476 Most of the modify macros defined by Common Lisp do not exactly | |
| 1477 follow the pattern of @code{define-modify-macro}. For example, | |
| 1478 @code{push} takes its arguments in the wrong order, and @code{pop} | |
| 1479 is completely irregular. You can define these macros ``by hand'' | |
| 1480 using @code{get-setf-method}, or consult the source file | |
| 1481 @file{cl-macs.el} to see how to use the internal @code{setf} | |
| 1482 building blocks. | |
| 1483 @end defspec | |
| 1484 | |
| 1485 @defspec defsetf access-fn update-fn | |
| 1486 This is the simpler of two @code{defsetf} forms. Where | |
| 1487 @var{access-fn} is the name of a function which accesses a place, | |
| 1488 this declares @var{update-fn} to be the corresponding store | |
| 1489 function. From now on, | |
| 1490 | |
| 1491 @example | |
| 1492 (setf (@var{access-fn} @var{arg1} @var{arg2} @var{arg3}) @var{value}) | |
| 1493 @end example | |
| 1494 | |
| 1495 @noindent | |
| 1496 will be expanded to | |
| 1497 | |
| 1498 @example | |
| 1499 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} @var{value}) | |
| 1500 @end example | |
| 1501 | |
| 1502 @noindent | |
| 1503 The @var{update-fn} is required to be either a true function, or | |
| 1504 a macro which evaluates its arguments in a function-like way. Also, | |
| 1505 the @var{update-fn} is expected to return @var{value} as its result. | |
| 1506 Otherwise, the above expansion would not obey the rules for the way | |
| 1507 @code{setf} is supposed to behave. | |
| 1508 | |
| 1509 As a special (non-Common-Lisp) extension, a third argument of @code{t} | |
| 1510 to @code{defsetf} says that the @code{update-fn}'s return value is | |
| 1511 not suitable, so that the above @code{setf} should be expanded to | |
| 1512 something more like | |
| 1513 | |
| 1514 @example | |
| 1515 (let ((temp @var{value})) | |
| 1516 (@var{update-fn} @var{arg1} @var{arg2} @var{arg3} temp) | |
| 1517 temp) | |
| 1518 @end example | |
| 1519 | |
| 1520 Some examples of the use of @code{defsetf}, drawn from the standard | |
| 1521 suite of setf methods, are: | |
| 1522 | |
| 1523 @example | |
| 1524 (defsetf car setcar) | |
| 1525 (defsetf symbol-value set) | |
| 1526 (defsetf buffer-name rename-buffer t) | |
| 1527 @end example | |
| 1528 @end defspec | |
| 1529 | |
| 1530 @defspec defsetf access-fn arglist (store-var) forms@dots{} | |
| 1531 This is the second, more complex, form of @code{defsetf}. It is | |
| 1532 rather like @code{defmacro} except for the additional @var{store-var} | |
| 1533 argument. The @var{forms} should return a Lisp form which stores | |
| 1534 the value of @var{store-var} into the generalized variable formed | |
| 1535 by a call to @var{access-fn} with arguments described by @var{arglist}. | |
| 1536 The @var{forms} may begin with a string which documents the @code{setf} | |
| 1537 method (analogous to the doc string that appears at the front of a | |
| 1538 function). | |
| 1539 | |
| 1540 For example, the simple form of @code{defsetf} is shorthand for | |
| 1541 | |
| 1542 @example | |
| 1543 (defsetf @var{access-fn} (&rest args) (store) | |
| 1544 (append '(@var{update-fn}) args (list store))) | |
| 1545 @end example | |
| 1546 | |
| 1547 The Lisp form that is returned can access the arguments from | |
| 1548 @var{arglist} and @var{store-var} in an unrestricted fashion; | |
| 1549 macros like @code{setf} and @code{incf} which invoke this | |
| 1550 setf-method will insert temporary variables as needed to make | |
| 1551 sure the apparent order of evaluation is preserved. | |
| 1552 | |
| 1553 Another example drawn from the standard package: | |
| 1554 | |
| 1555 @example | |
| 1556 (defsetf nth (n x) (store) | |
| 1557 (list 'setcar (list 'nthcdr n x) store)) | |
| 1558 @end example | |
| 1559 @end defspec | |
| 1560 | |
| 1561 @defspec define-setf-method access-fn arglist forms@dots{} | |
| 1562 This is the most general way to create new place forms. When | |
| 1563 a @code{setf} to @var{access-fn} with arguments described by | |
| 1564 @var{arglist} is expanded, the @var{forms} are evaluated and | |
| 1565 must return a list of five items: | |
| 1566 | |
| 1567 @enumerate | |
| 1568 @item | |
| 1569 A list of @dfn{temporary variables}. | |
| 1570 | |
| 1571 @item | |
| 1572 A list of @dfn{value forms} corresponding to the temporary variables | |
| 1573 above. The temporary variables will be bound to these value forms | |
| 1574 as the first step of any operation on the generalized variable. | |
| 1575 | |
| 1576 @item | |
| 1577 A list of exactly one @dfn{store variable} (generally obtained | |
| 1578 from a call to @code{gensym}). | |
| 1579 | |
| 1580 @item | |
| 1581 A Lisp form which stores the contents of the store variable into | |
| 1582 the generalized variable, assuming the temporaries have been | |
| 1583 bound as described above. | |
| 1584 | |
| 1585 @item | |
| 1586 A Lisp form which accesses the contents of the generalized variable, | |
| 1587 assuming the temporaries have been bound. | |
| 1588 @end enumerate | |
| 1589 | |
| 1590 This is exactly like the Common Lisp macro of the same name, | |
| 1591 except that the method returns a list of five values rather | |
| 1592 than the five values themselves, since Emacs Lisp does not | |
| 1593 support Common Lisp's notion of multiple return values. | |
| 1594 | |
| 1595 Once again, the @var{forms} may begin with a documentation string. | |
| 1596 | |
| 1597 A setf-method should be maximally conservative with regard to | |
| 1598 temporary variables. In the setf-methods generated by | |
| 1599 @code{defsetf}, the second return value is simply the list of | |
| 1600 arguments in the place form, and the first return value is a | |
| 1601 list of a corresponding number of temporary variables generated | |
| 1602 by @code{gensym}. Macros like @code{setf} and @code{incf} which | |
| 1603 use this setf-method will optimize away most temporaries that | |
| 1604 turn out to be unnecessary, so there is little reason for the | |
| 1605 setf-method itself to optimize. | |
| 1606 @end defspec | |
| 1607 | |
| 1608 @defun get-setf-method place &optional env | |
| 1609 This function returns the setf-method for @var{place}, by | |
| 1610 invoking the definition previously recorded by @code{defsetf} | |
| 1611 or @code{define-setf-method}. The result is a list of five | |
| 1612 values as described above. You can use this function to build | |
| 1613 your own @code{incf}-like modify macros. (Actually, it is | |
| 1614 better to use the internal functions @code{cl-setf-do-modify} | |
| 1615 and @code{cl-setf-do-store}, which are a bit easier to use and | |
| 1616 which also do a number of optimizations; consult the source | |
| 1617 code for the @code{incf} function for a simple example.) | |
| 1618 | |
| 1619 The argument @var{env} specifies the ``environment'' to be | |
| 1620 passed on to @code{macroexpand} if @code{get-setf-method} should | |
| 1621 need to expand a macro in @var{place}. It should come from | |
| 1622 an @code{&environment} argument to the macro or setf-method | |
| 1623 that called @code{get-setf-method}. | |
| 1624 | |
| 1625 See also the source code for the setf-methods for @code{apply} | |
| 1626 and @code{substring}, each of which works by calling | |
| 1627 @code{get-setf-method} on a simpler case, then massaging | |
| 1628 the result in various ways. | |
| 1629 @end defun | |
| 1630 | |
| 1631 Modern Common Lisp defines a second, independent way to specify | |
| 1632 the @code{setf} behavior of a function, namely ``@code{setf} | |
| 1633 functions'' whose names are lists @code{(setf @var{name})} | |
| 1634 rather than symbols. For example, @code{(defun (setf foo) @dots{})} | |
| 1635 defines the function that is used when @code{setf} is applied to | |
| 1636 @code{foo}. This package does not currently support @code{setf} | |
| 1637 functions. In particular, it is a compile-time error to use | |
| 1638 @code{setf} on a form which has not already been @code{defsetf}'d | |
| 1639 or otherwise declared; in newer Common Lisps, this would not be | |
| 1640 an error since the function @code{(setf @var{func})} might be | |
| 1641 defined later. | |
| 1642 | |
| 1643 @iftex | |
| 1644 @secno=4 | |
| 1645 @end iftex | |
| 1646 | |
| 1647 @node Variable Bindings, Conditionals, Generalized Variables, Control Structure | |
| 1648 @section Variable Bindings | |
| 1649 | |
| 1650 @noindent | |
| 1651 These Lisp forms make bindings to variables and function names, | |
| 1652 analogous to Lisp's built-in @code{let} form. | |
| 1653 | |
| 1654 @xref{Modify Macros}, for the @code{letf} and @code{letf*} forms which | |
| 1655 are also related to variable bindings. | |
| 1656 | |
| 1657 @menu | |
| 1658 * Dynamic Bindings:: The `progv' form | |
| 1659 * Lexical Bindings:: `lexical-let' and lexical closures | |
| 1660 * Function Bindings:: `flet' and `labels' | |
| 1661 * Macro Bindings:: `macrolet' and `symbol-macrolet' | |
| 1662 @end menu | |
| 1663 | |
| 1664 @node Dynamic Bindings, Lexical Bindings, Variable Bindings, Variable Bindings | |
| 1665 @subsection Dynamic Bindings | |
| 1666 | |
| 1667 @noindent | |
| 1668 The standard @code{let} form binds variables whose names are known | |
| 1669 at compile-time. The @code{progv} form provides an easy way to | |
| 1670 bind variables whose names are computed at run-time. | |
| 1671 | |
| 1672 @defspec progv symbols values forms@dots{} | |
| 1673 This form establishes @code{let}-style variable bindings on a | |
| 1674 set of variables computed at run-time. The expressions | |
| 1675 @var{symbols} and @var{values} are evaluated, and must return lists | |
| 1676 of symbols and values, respectively. The symbols are bound to the | |
| 1677 corresponding values for the duration of the body @var{form}s. | |
| 1678 If @var{values} is shorter than @var{symbols}, the last few symbols | |
| 1679 are made unbound (as if by @code{makunbound}) inside the body. | |
| 1680 If @var{symbols} is shorter than @var{values}, the excess values | |
| 1681 are ignored. | |
| 1682 @end defspec | |
| 1683 | |
| 1684 @node Lexical Bindings, Function Bindings, Dynamic Bindings, Variable Bindings | |
| 1685 @subsection Lexical Bindings | |
| 1686 | |
| 1687 @noindent | |
| 1688 The @dfn{CL} package defines the following macro which | |
| 1689 more closely follows the Common Lisp @code{let} form: | |
| 1690 | |
| 1691 @defspec lexical-let (bindings@dots{}) forms@dots{} | |
| 1692 This form is exactly like @code{let} except that the bindings it | |
| 1693 establishes are purely lexical. Lexical bindings are similar to | |
| 1694 local variables in a language like C: Only the code physically | |
| 1695 within the body of the @code{lexical-let} (after macro expansion) | |
| 1696 may refer to the bound variables. | |
| 1697 | |
| 1698 @example | |
| 1699 (setq a 5) | |
| 1700 (defun foo (b) (+ a b)) | |
| 1701 (let ((a 2)) (foo a)) | |
| 1702 @result{} 4 | |
| 1703 (lexical-let ((a 2)) (foo a)) | |
| 1704 @result{} 7 | |
| 1705 @end example | |
| 1706 | |
| 1707 @noindent | |
| 1708 In this example, a regular @code{let} binding of @code{a} actually | |
| 1709 makes a temporary change to the global variable @code{a}, so @code{foo} | |
| 1710 is able to see the binding of @code{a} to 2. But @code{lexical-let} | |
| 1711 actually creates a distinct local variable @code{a} for use within its | |
| 1712 body, without any effect on the global variable of the same name. | |
| 1713 | |
| 1714 The most important use of lexical bindings is to create @dfn{closures}. | |
| 1715 A closure is a function object that refers to an outside lexical | |
| 1716 variable. For example: | |
| 1717 | |
| 1718 @example | |
| 1719 (defun make-adder (n) | |
| 1720 (lexical-let ((n n)) | |
| 1721 (function (lambda (m) (+ n m))))) | |
| 1722 (setq add17 (make-adder 17)) | |
| 1723 (funcall add17 4) | |
| 1724 @result{} 21 | |
| 1725 @end example | |
| 1726 | |
| 1727 @noindent | |
| 1728 The call @code{(make-adder 17)} returns a function object which adds | |
| 1729 17 to its argument. If @code{let} had been used instead of | |
| 1730 @code{lexical-let}, the function object would have referred to the | |
| 1731 global @code{n}, which would have been bound to 17 only during the | |
| 1732 call to @code{make-adder} itself. | |
| 1733 | |
| 1734 @example | |
| 1735 (defun make-counter () | |
| 1736 (lexical-let ((n 0)) | |
| 1737 (function* (lambda (&optional (m 1)) (incf n m))))) | |
| 1738 (setq count-1 (make-counter)) | |
| 1739 (funcall count-1 3) | |
| 1740 @result{} 3 | |
| 1741 (funcall count-1 14) | |
| 1742 @result{} 17 | |
| 1743 (setq count-2 (make-counter)) | |
| 1744 (funcall count-2 5) | |
| 1745 @result{} 5 | |
| 1746 (funcall count-1 2) | |
| 1747 @result{} 19 | |
| 1748 (funcall count-2) | |
| 1749 @result{} 6 | |
| 1750 @end example | |
| 1751 | |
| 1752 @noindent | |
| 1753 Here we see that each call to @code{make-counter} creates a distinct | |
| 1754 local variable @code{n}, which serves as a private counter for the | |
| 1755 function object that is returned. | |
| 1756 | |
| 1757 Closed-over lexical variables persist until the last reference to | |
| 1758 them goes away, just like all other Lisp objects. For example, | |
| 1759 @code{count-2} refers to a function object which refers to an | |
| 1760 instance of the variable @code{n}; this is the only reference | |
| 1761 to that variable, so after @code{(setq count-2 nil)} the garbage | |
| 1762 collector would be able to delete this instance of @code{n}. | |
| 1763 Of course, if a @code{lexical-let} does not actually create any | |
| 1764 closures, then the lexical variables are free as soon as the | |
| 1765 @code{lexical-let} returns. | |
| 1766 | |
| 1767 Many closures are used only during the extent of the bindings they | |
| 1768 refer to; these are known as ``downward funargs'' in Lisp parlance. | |
| 1769 When a closure is used in this way, regular Emacs Lisp dynamic | |
| 1770 bindings suffice and will be more efficient than @code{lexical-let} | |
| 1771 closures: | |
| 1772 | |
| 1773 @example | |
| 1774 (defun add-to-list (x list) | |
| 1775 (mapcar (function (lambda (y) (+ x y))) list)) | |
| 1776 (add-to-list 7 '(1 2 5)) | |
| 1777 @result{} (8 9 12) | |
| 1778 @end example | |
| 1779 | |
| 1780 @noindent | |
| 1781 Since this lambda is only used while @code{x} is still bound, | |
| 1782 it is not necessary to make a true closure out of it. | |
| 1783 | |
| 1784 You can use @code{defun} or @code{flet} inside a @code{lexical-let} | |
| 1785 to create a named closure. If several closures are created in the | |
| 1786 body of a single @code{lexical-let}, they all close over the same | |
| 1787 instance of the lexical variable. | |
| 1788 | |
| 1789 The @code{lexical-let} form is an extension to Common Lisp. In | |
| 1790 true Common Lisp, all bindings are lexical unless declared otherwise. | |
| 1791 @end defspec | |
| 1792 | |
| 1793 @defspec lexical-let* (bindings@dots{}) forms@dots{} | |
| 1794 This form is just like @code{lexical-let}, except that the bindings | |
| 1795 are made sequentially in the manner of @code{let*}. | |
| 1796 @end defspec | |
| 1797 | |
| 1798 @node Function Bindings, Macro Bindings, Lexical Bindings, Variable Bindings | |
| 1799 @subsection Function Bindings | |
| 1800 | |
| 1801 @noindent | |
| 1802 These forms make @code{let}-like bindings to functions instead | |
| 1803 of variables. | |
| 1804 | |
| 1805 @defspec flet (bindings@dots{}) forms@dots{} | |
| 1806 This form establishes @code{let}-style bindings on the function | |
| 1807 cells of symbols rather than on the value cells. Each @var{binding} | |
| 1808 must be a list of the form @samp{(@var{name} @var{arglist} | |
| 1809 @var{forms}@dots{})}, which defines a function exactly as if | |
| 1810 it were a @code{defun*} form. The function @var{name} is defined | |
| 1811 accordingly for the duration of the body of the @code{flet}; then | |
| 1812 the old function definition, or lack thereof, is restored. | |
| 1813 | |
| 1814 While @code{flet} in Common Lisp establishes a lexical binding of | |
| 1815 @var{name}, Emacs Lisp @code{flet} makes a dynamic binding. The | |
| 1816 result is that @code{flet} affects indirect calls to a function as | |
| 1817 well as calls directly inside the @code{flet} form itself. | |
| 1818 | |
| 1819 You can use @code{flet} to disable or modify the behavior of a | |
| 1820 function in a temporary fashion. This will even work on Emacs | |
| 1821 primitives, although note that some calls to primitive functions | |
| 1822 internal to Emacs are made without going through the symbol's | |
| 1823 function cell, and so will not be affected by @code{flet}. For | |
| 1824 example, | |
| 1825 | |
| 1826 @example | |
| 1827 (flet ((message (&rest args) (push args saved-msgs))) | |
| 1828 (do-something)) | |
| 1829 @end example | |
| 1830 | |
| 1831 This code attempts to replace the built-in function @code{message} | |
| 1832 with a function that simply saves the messages in a list rather | |
| 1833 than displaying them. The original definition of @code{message} | |
| 1834 will be restored after @code{do-something} exits. This code will | |
| 1835 work fine on messages generated by other Lisp code, but messages | |
| 1836 generated directly inside Emacs will not be caught since they make | |
| 1837 direct C-language calls to the message routines rather than going | |
| 1838 through the Lisp @code{message} function. | |
| 1839 | |
| 1840 Functions defined by @code{flet} may use the full Common Lisp | |
| 1841 argument notation supported by @code{defun*}; also, the function | |
| 1842 body is enclosed in an implicit block as if by @code{defun*}. | |
| 1843 @xref{Program Structure}. | |
| 1844 @end defspec | |
| 1845 | |
| 1846 @defspec labels (bindings@dots{}) forms@dots{} | |
| 1847 The @code{labels} form is a synonym for @code{flet}. (In Common | |
| 1848 Lisp, @code{labels} and @code{flet} differ in ways that depend on | |
| 1849 their lexical scoping; these distinctions vanish in dynamically | |
| 1850 scoped Emacs Lisp.) | |
| 1851 @end defspec | |
| 1852 | |
| 1853 @node Macro Bindings, , Function Bindings, Variable Bindings | |
| 1854 @subsection Macro Bindings | |
| 1855 | |
| 1856 @noindent | |
| 1857 These forms create local macros and ``symbol macros.'' | |
| 1858 | |
| 1859 @defspec macrolet (bindings@dots{}) forms@dots{} | |
| 1860 This form is analogous to @code{flet}, but for macros instead of | |
| 1861 functions. Each @var{binding} is a list of the same form as the | |
| 1862 arguments to @code{defmacro*} (i.e., a macro name, argument list, | |
| 1863 and macro-expander forms). The macro is defined accordingly for | |
| 1864 use within the body of the @code{macrolet}. | |
| 1865 | |
| 1866 Because of the nature of macros, @code{macrolet} is lexically | |
| 1867 scoped even in Emacs Lisp: The @code{macrolet} binding will | |
| 1868 affect only calls that appear physically within the body | |
| 1869 @var{forms}, possibly after expansion of other macros in the | |
| 1870 body. | |
| 1871 @end defspec | |
| 1872 | |
| 1873 @defspec symbol-macrolet (bindings@dots{}) forms@dots{} | |
| 1874 This form creates @dfn{symbol macros}, which are macros that look | |
| 1875 like variable references rather than function calls. Each | |
| 1876 @var{binding} is a list @samp{(@var{var} @var{expansion})}; | |
| 1877 any reference to @var{var} within the body @var{forms} is | |
| 1878 replaced by @var{expansion}. | |
| 1879 | |
| 1880 @example | |
| 1881 (setq bar '(5 . 9)) | |
| 1882 (symbol-macrolet ((foo (car bar))) | |
| 1883 (incf foo)) | |
| 1884 bar | |
| 1885 @result{} (6 . 9) | |
| 1886 @end example | |
| 1887 | |
| 1888 A @code{setq} of a symbol macro is treated the same as a @code{setf}. | |
| 1889 I.e., @code{(setq foo 4)} in the above would be equivalent to | |
| 1890 @code{(setf foo 4)}, which in turn expands to @code{(setf (car bar) 4)}. | |
| 1891 | |
| 1892 Likewise, a @code{let} or @code{let*} binding a symbol macro is | |
| 1893 treated like a @code{letf} or @code{letf*}. This differs from true | |
| 1894 Common Lisp, where the rules of lexical scoping cause a @code{let} | |
| 1895 binding to shadow a @code{symbol-macrolet} binding. In this package, | |
| 1896 only @code{lexical-let} and @code{lexical-let*} will shadow a symbol | |
| 1897 macro. | |
| 1898 | |
| 1899 There is no analogue of @code{defmacro} for symbol macros; all symbol | |
| 1900 macros are local. A typical use of @code{symbol-macrolet} is in the | |
| 1901 expansion of another macro: | |
| 1902 | |
| 1903 @example | |
| 1904 (defmacro* my-dolist ((x list) &rest body) | |
| 1905 (let ((var (gensym))) | |
| 1906 (list 'loop 'for var 'on list 'do | |
| 1907 (list* 'symbol-macrolet (list (list x (list 'car var))) | |
| 1908 body)))) | |
| 1909 | |
| 1910 (setq mylist '(1 2 3 4)) | |
| 1911 (my-dolist (x mylist) (incf x)) | |
| 1912 mylist | |
| 1913 @result{} (2 3 4 5) | |
| 1914 @end example | |
| 1915 | |
| 1916 @noindent | |
| 1917 In this example, the @code{my-dolist} macro is similar to @code{dolist} | |
| 1918 (@pxref{Iteration}) except that the variable @code{x} becomes a true | |
| 1919 reference onto the elements of the list. The @code{my-dolist} call | |
| 1920 shown here expands to | |
| 1921 | |
| 1922 @example | |
| 1923 (loop for G1234 on mylist do | |
| 1924 (symbol-macrolet ((x (car G1234))) | |
| 1925 (incf x))) | |
| 1926 @end example | |
| 1927 | |
| 1928 @noindent | |
| 1929 which in turn expands to | |
| 1930 | |
| 1931 @example | |
| 1932 (loop for G1234 on mylist do (incf (car G1234))) | |
| 1933 @end example | |
| 1934 | |
| 1935 @xref{Loop Facility}, for a description of the @code{loop} macro. | |
| 1936 This package defines a nonstandard @code{in-ref} loop clause that | |
| 1937 works much like @code{my-dolist}. | |
| 1938 @end defspec | |
| 1939 | |
| 1940 @node Conditionals, Blocks and Exits, Variable Bindings, Control Structure | |
| 1941 @section Conditionals | |
| 1942 | |
| 1943 @noindent | |
| 1944 These conditional forms augment Emacs Lisp's simple @code{if}, | |
| 1945 @code{and}, @code{or}, and @code{cond} forms. | |
| 1946 | |
| 1947 @defspec when test forms@dots{} | |
| 1948 This is a variant of @code{if} where there are no ``else'' forms, | |
| 1949 and possibly several ``then'' forms. In particular, | |
| 1950 | |
| 1951 @example | |
| 1952 (when @var{test} @var{a} @var{b} @var{c}) | |
| 1953 @end example | |
| 1954 | |
| 1955 @noindent | |
| 1956 is entirely equivalent to | |
| 1957 | |
| 1958 @example | |
| 1959 (if @var{test} (progn @var{a} @var{b} @var{c}) nil) | |
| 1960 @end example | |
| 1961 @end defspec | |
| 1962 | |
| 1963 @defspec unless test forms@dots{} | |
| 1964 This is a variant of @code{if} where there are no ``then'' forms, | |
| 1965 and possibly several ``else'' forms: | |
| 1966 | |
| 1967 @example | |
| 1968 (unless @var{test} @var{a} @var{b} @var{c}) | |
| 1969 @end example | |
| 1970 | |
| 1971 @noindent | |
| 1972 is entirely equivalent to | |
| 1973 | |
| 1974 @example | |
| 1975 (when (not @var{test}) @var{a} @var{b} @var{c}) | |
| 1976 @end example | |
| 1977 @end defspec | |
| 1978 | |
| 1979 @defspec case keyform clause@dots{} | |
| 1980 This macro evaluates @var{keyform}, then compares it with the key | |
| 1981 values listed in the various @var{clause}s. Whichever clause matches | |
| 1982 the key is executed; comparison is done by @code{eql}. If no clause | |
| 1983 matches, the @code{case} form returns @code{nil}. The clauses are | |
| 1984 of the form | |
| 1985 | |
| 1986 @example | |
| 1987 (@var{keylist} @var{body-forms}@dots{}) | |
| 1988 @end example | |
| 1989 | |
| 1990 @noindent | |
| 1991 where @var{keylist} is a list of key values. If there is exactly | |
| 1992 one value, and it is not a cons cell or the symbol @code{nil} or | |
| 1993 @code{t}, then it can be used by itself as a @var{keylist} without | |
| 1994 being enclosed in a list. All key values in the @code{case} form | |
| 1995 must be distinct. The final clauses may use @code{t} in place of | |
| 1996 a @var{keylist} to indicate a default clause that should be taken | |
| 1997 if none of the other clauses match. (The symbol @code{otherwise} | |
| 1998 is also recognized in place of @code{t}. To make a clause that | |
| 1999 matches the actual symbol @code{t}, @code{nil}, or @code{otherwise}, | |
| 2000 enclose the symbol in a list.) | |
| 2001 | |
| 2002 For example, this expression reads a keystroke, then does one of | |
| 2003 four things depending on whether it is an @samp{a}, a @samp{b}, | |
| 2004 a @key{RET} or @key{LFD}, or anything else. | |
| 2005 | |
| 2006 @example | |
| 2007 (case (read-char) | |
| 2008 (?a (do-a-thing)) | |
| 2009 (?b (do-b-thing)) | |
| 2010 ((?\r ?\n) (do-ret-thing)) | |
| 2011 (t (do-other-thing))) | |
| 2012 @end example | |
| 2013 @end defspec | |
| 2014 | |
| 2015 @defspec ecase keyform clause@dots{} | |
| 2016 This macro is just like @code{case}, except that if the key does | |
| 2017 not match any of the clauses, an error is signalled rather than | |
| 2018 simply returning @code{nil}. | |
| 2019 @end defspec | |
| 2020 | |
| 2021 @defspec typecase keyform clause@dots{} | |
| 2022 This macro is a version of @code{case} that checks for types | |
| 2023 rather than values. Each @var{clause} is of the form | |
| 2024 @samp{(@var{type} @var{body}...)}. @xref{Type Predicates}, | |
| 2025 for a description of type specifiers. For example, | |
| 2026 | |
| 2027 @example | |
| 2028 (typecase x | |
| 2029 (integer (munch-integer x)) | |
| 2030 (float (munch-float x)) | |
| 2031 (string (munch-integer (string-to-int x))) | |
| 2032 (t (munch-anything x))) | |
| 2033 @end example | |
| 2034 | |
| 2035 The type specifier @code{t} matches any type of object; the word | |
| 2036 @code{otherwise} is also allowed. To make one clause match any of | |
| 2037 several types, use an @code{(or ...)} type specifier. | |
| 2038 @end defspec | |
| 2039 | |
| 2040 @defspec etypecase keyform clause@dots{} | |
| 2041 This macro is just like @code{typecase}, except that if the key does | |
| 2042 not match any of the clauses, an error is signalled rather than | |
| 2043 simply returning @code{nil}. | |
| 2044 @end defspec | |
| 2045 | |
| 2046 @node Blocks and Exits, Iteration, Conditionals, Control Structure | |
| 2047 @section Blocks and Exits | |
| 2048 | |
| 2049 @noindent | |
| 2050 Common Lisp @dfn{blocks} provide a non-local exit mechanism very | |
| 2051 similar to @code{catch} and @code{throw}, but lexically rather than | |
| 2052 dynamically scoped. This package actually implements @code{block} | |
| 2053 in terms of @code{catch}; however, the lexical scoping allows the | |
| 2054 optimizing byte-compiler to omit the costly @code{catch} step if the | |
| 2055 body of the block does not actually @code{return-from} the block. | |
| 2056 | |
| 2057 @defspec block name forms@dots{} | |
| 2058 The @var{forms} are evaluated as if by a @code{progn}. However, | |
| 2059 if any of the @var{forms} execute @code{(return-from @var{name})}, | |
| 2060 they will jump out and return directly from the @code{block} form. | |
| 2061 The @code{block} returns the result of the last @var{form} unless | |
| 2062 a @code{return-from} occurs. | |
| 2063 | |
| 2064 The @code{block}/@code{return-from} mechanism is quite similar to | |
| 2065 the @code{catch}/@code{throw} mechanism. The main differences are | |
| 2066 that block @var{name}s are unevaluated symbols, rather than forms | |
| 2067 (such as quoted symbols) which evaluate to a tag at run-time; and | |
| 2068 also that blocks are lexically scoped whereas @code{catch}/@code{throw} | |
| 2069 are dynamically scoped. This means that functions called from the | |
| 2070 body of a @code{catch} can also @code{throw} to the @code{catch}, | |
| 2071 but the @code{return-from} referring to a block name must appear | |
| 2072 physically within the @var{forms} that make up the body of the block. | |
| 2073 They may not appear within other called functions, although they may | |
| 2074 appear within macro expansions or @code{lambda}s in the body. Block | |
| 2075 names and @code{catch} names form independent name-spaces. | |
| 2076 | |
| 2077 In true Common Lisp, @code{defun} and @code{defmacro} surround | |
| 2078 the function or expander bodies with implicit blocks with the | |
| 2079 same name as the function or macro. This does not occur in Emacs | |
| 2080 Lisp, but this package provides @code{defun*} and @code{defmacro*} | |
| 2081 forms which do create the implicit block. | |
| 2082 | |
| 2083 The Common Lisp looping constructs defined by this package, | |
| 2084 such as @code{loop} and @code{dolist}, also create implicit blocks | |
| 2085 just as in Common Lisp. | |
| 2086 | |
| 2087 Because they are implemented in terms of Emacs Lisp @code{catch} | |
| 2088 and @code{throw}, blocks have the same overhead as actual | |
| 2089 @code{catch} constructs (roughly two function calls). However, | |
| 2090 Zawinski and Furuseth's optimizing byte compiler (standard in | |
| 2091 Emacs 19) will optimize away the @code{catch} if the block does | |
| 2092 not in fact contain any @code{return} or @code{return-from} calls | |
| 2093 that jump to it. This means that @code{do} loops and @code{defun*} | |
| 2094 functions which don't use @code{return} don't pay the overhead to | |
| 2095 support it. | |
| 2096 @end defspec | |
| 2097 | |
| 2098 @defspec return-from name [result] | |
| 2099 This macro returns from the block named @var{name}, which must be | |
| 2100 an (unevaluated) symbol. If a @var{result} form is specified, it | |
| 2101 is evaluated to produce the result returned from the @code{block}. | |
| 2102 Otherwise, @code{nil} is returned. | |
| 2103 @end defspec | |
| 2104 | |
| 2105 @defspec return [result] | |
| 2106 This macro is exactly like @code{(return-from nil @var{result})}. | |
| 2107 Common Lisp loops like @code{do} and @code{dolist} implicitly enclose | |
| 2108 themselves in @code{nil} blocks. | |
| 2109 @end defspec | |
| 2110 | |
| 2111 @node Iteration, Loop Facility, Blocks and Exits, Control Structure | |
| 2112 @section Iteration | |
| 2113 | |
| 2114 @noindent | |
| 2115 The macros described here provide more sophisticated, high-level | |
| 2116 looping constructs to complement Emacs Lisp's basic @code{while} | |
| 2117 loop. | |
| 2118 | |
| 2119 @defspec loop forms@dots{} | |
| 2120 The @dfn{CL} package supports both the simple, old-style meaning of | |
| 2121 @code{loop} and the extremely powerful and flexible feature known as | |
| 2122 the @dfn{Loop Facility} or @dfn{Loop Macro}. This more advanced | |
| 2123 facility is discussed in the following section; @pxref{Loop Facility}. | |
| 2124 The simple form of @code{loop} is described here. | |
| 2125 | |
| 2126 If @code{loop} is followed by zero or more Lisp expressions, | |
| 2127 then @code{(loop @var{exprs}@dots{})} simply creates an infinite | |
| 2128 loop executing the expressions over and over. The loop is | |
| 2129 enclosed in an implicit @code{nil} block. Thus, | |
| 2130 | |
| 2131 @example | |
| 2132 (loop (foo) (if (no-more) (return 72)) (bar)) | |
| 2133 @end example | |
| 2134 | |
| 2135 @noindent | |
| 2136 is exactly equivalent to | |
| 2137 | |
| 2138 @example | |
| 2139 (block nil (while t (foo) (if (no-more) (return 72)) (bar))) | |
| 2140 @end example | |
| 2141 | |
| 2142 If any of the expressions are plain symbols, the loop is instead | |
| 2143 interpreted as a Loop Macro specification as described later. | |
| 2144 (This is not a restriction in practice, since a plain symbol | |
| 2145 in the above notation would simply access and throw away the | |
| 2146 value of a variable.) | |
| 2147 @end defspec | |
| 2148 | |
| 2149 @defspec do (spec@dots{}) (end-test [result@dots{}]) forms@dots{} | |
| 2150 This macro creates a general iterative loop. Each @var{spec} is | |
| 2151 of the form | |
| 2152 | |
| 2153 @example | |
| 2154 (@var{var} [@var{init} [@var{step}]]) | |
| 2155 @end example | |
| 2156 | |
| 2157 The loop works as follows: First, each @var{var} is bound to the | |
| 2158 associated @var{init} value as if by a @code{let} form. Then, in | |
| 2159 each iteration of the loop, the @var{end-test} is evaluated; if | |
| 2160 true, the loop is finished. Otherwise, the body @var{forms} are | |
| 2161 evaluated, then each @var{var} is set to the associated @var{step} | |
| 2162 expression (as if by a @code{psetq} form) and the next iteration | |
| 2163 begins. Once the @var{end-test} becomes true, the @var{result} | |
| 2164 forms are evaluated (with the @var{var}s still bound to their | |
| 2165 values) to produce the result returned by @code{do}. | |
| 2166 | |
| 2167 The entire @code{do} loop is enclosed in an implicit @code{nil} | |
| 2168 block, so that you can use @code{(return)} to break out of the | |
| 2169 loop at any time. | |
| 2170 | |
| 2171 If there are no @var{result} forms, the loop returns @code{nil}. | |
| 2172 If a given @var{var} has no @var{step} form, it is bound to its | |
| 2173 @var{init} value but not otherwise modified during the @code{do} | |
| 2174 loop (unless the code explicitly modifies it); this case is just | |
| 2175 a shorthand for putting a @code{(let ((@var{var} @var{init})) @dots{})} | |
| 2176 around the loop. If @var{init} is also omitted it defaults to | |
| 2177 @code{nil}, and in this case a plain @samp{@var{var}} can be used | |
| 2178 in place of @samp{(@var{var})}, again following the analogy with | |
| 2179 @code{let}. | |
| 2180 | |
| 2181 This example (from Steele) illustrates a loop which applies the | |
| 2182 function @code{f} to successive pairs of values from the lists | |
| 2183 @code{foo} and @code{bar}; it is equivalent to the call | |
| 2184 @code{(mapcar* 'f foo bar)}. Note that this loop has no body | |
| 2185 @var{forms} at all, performing all its work as side effects of | |
| 2186 the rest of the loop. | |
| 2187 | |
| 2188 @example | |
| 2189 (do ((x foo (cdr x)) | |
| 2190 (y bar (cdr y)) | |
| 2191 (z nil (cons (f (car x) (car y)) z))) | |
| 2192 ((or (null x) (null y)) | |
| 2193 (nreverse z))) | |
| 2194 @end example | |
| 2195 @end defspec | |
| 2196 | |
| 2197 @defspec do* (spec@dots{}) (end-test [result@dots{}]) forms@dots{} | |
| 2198 This is to @code{do} what @code{let*} is to @code{let}. In | |
| 2199 particular, the initial values are bound as if by @code{let*} | |
| 2200 rather than @code{let}, and the steps are assigned as if by | |
| 2201 @code{setq} rather than @code{psetq}. | |
| 2202 | |
| 2203 Here is another way to write the above loop: | |
| 2204 | |
| 2205 @example | |
| 2206 (do* ((xp foo (cdr xp)) | |
| 2207 (yp bar (cdr yp)) | |
| 2208 (x (car xp) (car xp)) | |
| 2209 (y (car yp) (car yp)) | |
| 2210 z) | |
| 2211 ((or (null xp) (null yp)) | |
| 2212 (nreverse z)) | |
| 2213 (push (f x y) z)) | |
| 2214 @end example | |
| 2215 @end defspec | |
| 2216 | |
| 2217 @defspec dolist (var list [result]) forms@dots{} | |
| 2218 This is a more specialized loop which iterates across the elements | |
| 2219 of a list. @var{list} should evaluate to a list; the body @var{forms} | |
| 2220 are executed with @var{var} bound to each element of the list in | |
| 2221 turn. Finally, the @var{result} form (or @code{nil}) is evaluated | |
| 2222 with @var{var} bound to @code{nil} to produce the result returned by | |
| 2223 the loop. The loop is surrounded by an implicit @code{nil} block. | |
| 2224 @end defspec | |
| 2225 | |
| 2226 @defspec dotimes (var count [result]) forms@dots{} | |
| 2227 This is a more specialized loop which iterates a specified number | |
| 2228 of times. The body is executed with @var{var} bound to the integers | |
| 2229 from zero (inclusive) to @var{count} (exclusive), in turn. Then | |
| 2230 the @code{result} form is evaluated with @var{var} bound to the total | |
| 2231 number of iterations that were done (i.e., @code{(max 0 @var{count})}) | |
| 2232 to get the return value for the loop form. The loop is surrounded | |
| 2233 by an implicit @code{nil} block. | |
| 2234 @end defspec | |
| 2235 | |
| 2236 @defspec do-symbols (var [obarray [result]]) forms@dots{} | |
| 2237 This loop iterates over all interned symbols. If @var{obarray} | |
| 2238 is specified and is not @code{nil}, it loops over all symbols in | |
| 2239 that obarray. For each symbol, the body @var{forms} are evaluated | |
| 2240 with @var{var} bound to that symbol. The symbols are visited in | |
| 2241 an unspecified order. Afterward the @var{result} form, if any, | |
| 2242 is evaluated (with @var{var} bound to @code{nil}) to get the return | |
| 2243 value. The loop is surrounded by an implicit @code{nil} block. | |
| 2244 @end defspec | |
| 2245 | |
| 2246 @defspec do-all-symbols (var [result]) forms@dots{} | |
| 2247 This is identical to @code{do-symbols} except that the @var{obarray} | |
| 2248 argument is omitted; it always iterates over the default obarray. | |
| 2249 @end defspec | |
| 2250 | |
| 2251 @xref{Mapping over Sequences}, for some more functions for | |
| 2252 iterating over vectors or lists. | |
| 2253 | |
| 2254 @node Loop Facility, Multiple Values, Iteration, Control Structure | |
| 2255 @section Loop Facility | |
| 2256 | |
| 2257 @noindent | |
| 2258 A common complaint with Lisp's traditional looping constructs is | |
| 2259 that they are either too simple and limited, such as Common Lisp's | |
| 2260 @code{dotimes} or Emacs Lisp's @code{while}, or too unreadable and | |
| 2261 obscure, like Common Lisp's @code{do} loop. | |
| 2262 | |
| 2263 To remedy this, recent versions of Common Lisp have added a new | |
| 2264 construct called the ``Loop Facility'' or ``@code{loop} macro,'' | |
| 2265 with an easy-to-use but very powerful and expressive syntax. | |
| 2266 | |
| 2267 @menu | |
| 2268 * Loop Basics:: `loop' macro, basic clause structure | |
| 2269 * Loop Examples:: Working examples of `loop' macro | |
| 2270 * For Clauses:: Clauses introduced by `for' or `as' | |
| 2271 * Iteration Clauses:: `repeat', `while', `thereis', etc. | |
| 2272 * Accumulation Clauses:: `collect', `sum', `maximize', etc. | |
| 2273 * Other Clauses:: `with', `if', `initially', `finally' | |
| 2274 @end menu | |
| 2275 | |
| 2276 @node Loop Basics, Loop Examples, Loop Facility, Loop Facility | |
| 2277 @subsection Loop Basics | |
| 2278 | |
| 2279 @noindent | |
| 2280 The @code{loop} macro essentially creates a mini-language within | |
| 2281 Lisp that is specially tailored for describing loops. While this | |
| 2282 language is a little strange-looking by the standards of regular Lisp, | |
| 2283 it turns out to be very easy to learn and well-suited to its purpose. | |
| 2284 | |
| 2285 Since @code{loop} is a macro, all parsing of the loop language | |
| 2286 takes place at byte-compile time; compiled @code{loop}s are just | |
| 2287 as efficient as the equivalent @code{while} loops written longhand. | |
| 2288 | |
| 2289 @defspec loop clauses@dots{} | |
| 2290 A loop construct consists of a series of @var{clause}s, each | |
| 2291 introduced by a symbol like @code{for} or @code{do}. Clauses | |
| 2292 are simply strung together in the argument list of @code{loop}, | |
| 2293 with minimal extra parentheses. The various types of clauses | |
| 2294 specify initializations, such as the binding of temporary | |
| 2295 variables, actions to be taken in the loop, stepping actions, | |
| 2296 and final cleanup. | |
| 2297 | |
| 2298 Common Lisp specifies a certain general order of clauses in a | |
| 2299 loop: | |
| 2300 | |
| 2301 @example | |
| 2302 (loop @var{name-clause} | |
| 2303 @var{var-clauses}@dots{} | |
| 2304 @var{action-clauses}@dots{}) | |
| 2305 @end example | |
| 2306 | |
| 2307 The @var{name-clause} optionally gives a name to the implicit | |
| 2308 block that surrounds the loop. By default, the implicit block | |
| 2309 is named @code{nil}. The @var{var-clauses} specify what | |
| 2310 variables should be bound during the loop, and how they should | |
| 2311 be modified or iterated throughout the course of the loop. The | |
| 2312 @var{action-clauses} are things to be done during the loop, such | |
| 2313 as computing, collecting, and returning values. | |
| 2314 | |
| 2315 The Emacs version of the @code{loop} macro is less restrictive about | |
| 2316 the order of clauses, but things will behave most predictably if | |
| 2317 you put the variable-binding clauses @code{with}, @code{for}, and | |
| 2318 @code{repeat} before the action clauses. As in Common Lisp, | |
| 2319 @code{initially} and @code{finally} clauses can go anywhere. | |
| 2320 | |
| 2321 Loops generally return @code{nil} by default, but you can cause | |
| 2322 them to return a value by using an accumulation clause like | |
| 2323 @code{collect}, an end-test clause like @code{always}, or an | |
| 2324 explicit @code{return} clause to jump out of the implicit block. | |
| 2325 (Because the loop body is enclosed in an implicit block, you can | |
| 2326 also use regular Lisp @code{return} or @code{return-from} to | |
| 2327 break out of the loop.) | |
| 2328 @end defspec | |
| 2329 | |
| 2330 The following sections give some examples of the Loop Macro in | |
| 2331 action, and describe the particular loop clauses in great detail. | |
| 2332 Consult the second edition of Steele's @dfn{Common Lisp, the Language}, | |
| 2333 for additional discussion and examples of the @code{loop} macro. | |
| 2334 | |
| 2335 @node Loop Examples, For Clauses, Loop Basics, Loop Facility | |
| 2336 @subsection Loop Examples | |
| 2337 | |
| 2338 @noindent | |
| 2339 Before listing the full set of clauses that are allowed, let's | |
| 2340 look at a few example loops just to get a feel for the @code{loop} | |
| 2341 language. | |
| 2342 | |
| 2343 @example | |
| 2344 (loop for buf in (buffer-list) | |
| 2345 collect (buffer-file-name buf)) | |
| 2346 @end example | |
| 2347 | |
| 2348 @noindent | |
| 2349 This loop iterates over all Emacs buffers, using the list | |
| 2350 returned by @code{buffer-list}. For each buffer @code{buf}, | |
| 2351 it calls @code{buffer-file-name} and collects the results into | |
| 2352 a list, which is then returned from the @code{loop} construct. | |
| 2353 The result is a list of the file names of all the buffers in | |
| 2354 Emacs' memory. The words @code{for}, @code{in}, and @code{collect} | |
| 2355 are reserved words in the @code{loop} language. | |
| 2356 | |
| 2357 @example | |
| 2358 (loop repeat 20 do (insert "Yowsa\n")) | |
| 2359 @end example | |
| 2360 | |
| 2361 @noindent | |
| 2362 This loop inserts the phrase ``Yowsa'' twenty times in the | |
| 2363 current buffer. | |
| 2364 | |
| 2365 @example | |
| 2366 (loop until (eobp) do (munch-line) (forward-line 1)) | |
| 2367 @end example | |
| 2368 | |
| 2369 @noindent | |
| 2370 This loop calls @code{munch-line} on every line until the end | |
| 2371 of the buffer. If point is already at the end of the buffer, | |
| 2372 the loop exits immediately. | |
| 2373 | |
| 2374 @example | |
| 2375 (loop do (munch-line) until (eobp) do (forward-line 1)) | |
| 2376 @end example | |
| 2377 | |
| 2378 @noindent | |
| 2379 This loop is similar to the above one, except that @code{munch-line} | |
| 2380 is always called at least once. | |
| 2381 | |
| 2382 @example | |
| 2383 (loop for x from 1 to 100 | |
| 2384 for y = (* x x) | |
| 2385 until (>= y 729) | |
| 2386 finally return (list x (= y 729))) | |
| 2387 @end example | |
| 2388 | |
| 2389 @noindent | |
| 2390 This more complicated loop searches for a number @code{x} whose | |
| 2391 square is 729. For safety's sake it only examines @code{x} | |
| 2392 values up to 100; dropping the phrase @samp{to 100} would | |
| 2393 cause the loop to count upwards with no limit. The second | |
| 2394 @code{for} clause defines @code{y} to be the square of @code{x} | |
| 2395 within the loop; the expression after the @code{=} sign is | |
| 2396 reevaluated each time through the loop. The @code{until} | |
| 2397 clause gives a condition for terminating the loop, and the | |
| 2398 @code{finally} clause says what to do when the loop finishes. | |
| 2399 (This particular example was written less concisely than it | |
| 2400 could have been, just for the sake of illustration.) | |
| 2401 | |
| 2402 Note that even though this loop contains three clauses (two | |
| 2403 @code{for}s and an @code{until}) that would have been enough to | |
| 2404 define loops all by themselves, it still creates a single loop | |
| 2405 rather than some sort of triple-nested loop. You must explicitly | |
| 2406 nest your @code{loop} constructs if you want nested loops. | |
| 2407 | |
| 2408 @node For Clauses, Iteration Clauses, Loop Examples, Loop Facility | |
| 2409 @subsection For Clauses | |
| 2410 | |
| 2411 @noindent | |
| 2412 Most loops are governed by one or more @code{for} clauses. | |
| 2413 A @code{for} clause simultaneously describes variables to be | |
| 2414 bound, how those variables are to be stepped during the loop, | |
| 2415 and usually an end condition based on those variables. | |
| 2416 | |
| 2417 The word @code{as} is a synonym for the word @code{for}. This | |
| 2418 word is followed by a variable name, then a word like @code{from} | |
| 2419 or @code{across} that describes the kind of iteration desired. | |
| 2420 In Common Lisp, the phrase @code{being the} sometimes precedes | |
| 2421 the type of iteration; in this package both @code{being} and | |
| 2422 @code{the} are optional. The word @code{each} is a synonym | |
| 2423 for @code{the}, and the word that follows it may be singular | |
| 2424 or plural: @samp{for x being the elements of y} or | |
| 2425 @samp{for x being each element of y}. Which form you use | |
| 2426 is purely a matter of style. | |
| 2427 | |
| 2428 The variable is bound around the loop as if by @code{let}: | |
| 2429 | |
| 2430 @example | |
| 2431 (setq i 'happy) | |
| 2432 (loop for i from 1 to 10 do (do-something-with i)) | |
| 2433 i | |
| 2434 @result{} happy | |
| 2435 @end example | |
| 2436 | |
| 2437 @table @code | |
| 2438 @item for @var{var} from @var{expr1} to @var{expr2} by @var{expr3} | |
| 2439 This type of @code{for} clause creates a counting loop. Each of | |
| 2440 the three sub-terms is optional, though there must be at least one | |
| 2441 term so that the clause is marked as a counting clause. | |
| 2442 | |
| 2443 The three expressions are the starting value, the ending value, and | |
| 2444 the step value, respectively, of the variable. The loop counts | |
| 2445 upwards by default (@var{expr3} must be positive), from @var{expr1} | |
| 2446 to @var{expr2} inclusively. If you omit the @code{from} term, the | |
| 2447 loop counts from zero; if you omit the @code{to} term, the loop | |
| 2448 counts forever without stopping (unless stopped by some other | |
| 2449 loop clause, of course); if you omit the @code{by} term, the loop | |
| 2450 counts in steps of one. | |
| 2451 | |
| 2452 You can replace the word @code{from} with @code{upfrom} or | |
| 2453 @code{downfrom} to indicate the direction of the loop. Likewise, | |
| 2454 you can replace @code{to} with @code{upto} or @code{downto}. | |
| 2455 For example, @samp{for x from 5 downto 1} executes five times | |
| 2456 with @code{x} taking on the integers from 5 down to 1 in turn. | |
| 2457 Also, you can replace @code{to} with @code{below} or @code{above}, | |
| 2458 which are like @code{upto} and @code{downto} respectively except | |
| 2459 that they are exclusive rather than inclusive limits: | |
| 2460 | |
| 2461 @example | |
| 2462 (loop for x to 10 collect x) | |
| 2463 @result{} (0 1 2 3 4 5 6 7 8 9 10) | |
| 2464 (loop for x below 10 collect x) | |
| 2465 @result{} (0 1 2 3 4 5 6 7 8 9) | |
| 2466 @end example | |
| 2467 | |
| 2468 The @code{by} value is always positive, even for downward-counting | |
| 2469 loops. Some sort of @code{from} value is required for downward | |
| 2470 loops; @samp{for x downto 5} is not a legal loop clause all by | |
| 2471 itself. | |
| 2472 | |
| 2473 @item for @var{var} in @var{list} by @var{function} | |
| 2474 This clause iterates @var{var} over all the elements of @var{list}, | |
| 2475 in turn. If you specify the @code{by} term, then @var{function} | |
| 2476 is used to traverse the list instead of @code{cdr}; it must be a | |
| 2477 function taking one argument. For example: | |
| 2478 | |
| 2479 @example | |
| 2480 (loop for x in '(1 2 3 4 5 6) collect (* x x)) | |
| 2481 @result{} (1 4 9 16 25 36) | |
| 2482 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x)) | |
| 2483 @result{} (1 9 25) | |
| 2484 @end example | |
| 2485 | |
| 2486 @item for @var{var} on @var{list} by @var{function} | |
| 2487 This clause iterates @var{var} over all the cons cells of @var{list}. | |
| 2488 | |
| 2489 @example | |
| 2490 (loop for x on '(1 2 3 4) collect x) | |
| 2491 @result{} ((1 2 3 4) (2 3 4) (3 4) (4)) | |
| 2492 @end example | |
| 2493 | |
| 2494 With @code{by}, there is no real reason that the @code{on} expression | |
| 2495 must be a list. For example: | |
| 2496 | |
| 2497 @example | |
| 2498 (loop for x on first-animal by 'next-animal collect x) | |
| 2499 @end example | |
| 2500 | |
| 2501 @noindent | |
| 2502 where @code{(next-animal x)} takes an ``animal'' @var{x} and returns | |
| 2503 the next in the (assumed) sequence of animals, or @code{nil} if | |
| 2504 @var{x} was the last animal in the sequence. | |
| 2505 | |
| 2506 @item for @var{var} in-ref @var{list} by @var{function} | |
| 2507 This is like a regular @code{in} clause, but @var{var} becomes | |
| 2508 a @code{setf}-able ``reference'' onto the elements of the list | |
| 2509 rather than just a temporary variable. For example, | |
| 2510 | |
| 2511 @example | |
| 2512 (loop for x in-ref my-list do (incf x)) | |
| 2513 @end example | |
| 2514 | |
| 2515 @noindent | |
| 2516 increments every element of @code{my-list} in place. This clause | |
| 2517 is an extension to standard Common Lisp. | |
| 2518 | |
| 2519 @item for @var{var} across @var{array} | |
| 2520 This clause iterates @var{var} over all the elements of @var{array}, | |
| 2521 which may be a vector or a string. | |
| 2522 | |
| 2523 @example | |
| 2524 (loop for x across "aeiou" | |
| 2525 do (use-vowel (char-to-string x))) | |
| 2526 @end example | |
| 2527 | |
| 2528 @item for @var{var} across-ref @var{array} | |
| 2529 This clause iterates over an array, with @var{var} a @code{setf}-able | |
| 2530 reference onto the elements; see @code{in-ref} above. | |
| 2531 | |
| 2532 @item for @var{var} being the elements of @var{sequence} | |
| 2533 This clause iterates over the elements of @var{sequence}, which may | |
| 2534 be a list, vector, or string. Since the type must be determined | |
| 2535 at run-time, this is somewhat less efficient than @code{in} or | |
| 2536 @code{across}. The clause may be followed by the additional term | |
| 2537 @samp{using (index @var{var2})} to cause @var{var2} to be bound to | |
| 2538 the successive indices (starting at 0) of the elements. | |
| 2539 | |
| 2540 This clause type is taken from older versions of the @code{loop} macro, | |
| 2541 and is not present in modern Common Lisp. The @samp{using (sequence ...)} | |
| 2542 term of the older macros is not supported. | |
| 2543 | |
| 2544 @item for @var{var} being the elements of-ref @var{sequence} | |
| 2545 This clause iterates over a sequence, with @var{var} a @code{setf}-able | |
| 2546 reference onto the elements; see @code{in-ref} above. | |
| 2547 | |
| 2548 @item for @var{var} being the symbols [of @var{obarray}] | |
| 2549 This clause iterates over symbols, either over all interned symbols | |
| 2550 or over all symbols in @var{obarray}. The loop is executed with | |
| 2551 @var{var} bound to each symbol in turn. The symbols are visited in | |
| 2552 an unspecified order. | |
| 2553 | |
| 2554 As an example, | |
| 2555 | |
| 2556 @example | |
| 2557 (loop for sym being the symbols | |
| 2558 when (fboundp sym) | |
| 2559 when (string-match "^map" (symbol-name sym)) | |
| 2560 collect sym) | |
| 2561 @end example | |
| 2562 | |
| 2563 @noindent | |
| 2564 returns a list of all the functions whose names begin with @samp{map}. | |
| 2565 | |
| 2566 The Common Lisp words @code{external-symbols} and @code{present-symbols} | |
| 2567 are also recognized but are equivalent to @code{symbols} in Emacs Lisp. | |
| 2568 | |
| 2569 Due to a minor implementation restriction, it will not work to have | |
| 2570 more than one @code{for} clause iterating over symbols, hash tables, | |
| 2571 keymaps, overlays, or intervals in a given @code{loop}. Fortunately, | |
| 2572 it would rarely if ever be useful to do so. It @emph{is} legal to mix | |
| 2573 one of these types of clauses with other clauses like @code{for ... to} | |
| 2574 or @code{while}. | |
| 2575 | |
| 2576 @item for @var{var} being the hash-keys of @var{hash-table} | |
| 2577 This clause iterates over the entries in @var{hash-table}. For each | |
| 2578 hash table entry, @var{var} is bound to the entry's key. If you write | |
| 2579 @samp{the hash-values} instead, @var{var} is bound to the values | |
| 2580 of the entries. The clause may be followed by the additional | |
| 2581 term @samp{using (hash-values @var{var2})} (where @code{hash-values} | |
| 2582 is the opposite word of the word following @code{the}) to cause | |
| 2583 @var{var} and @var{var2} to be bound to the two parts of each | |
| 2584 hash table entry. | |
| 2585 | |
| 2586 @item for @var{var} being the key-codes of @var{keymap} | |
| 2587 This clause iterates over the entries in @var{keymap}. In GNU Emacs 18 | |
| 2588 and 19, keymaps are either alists or vectors, and key-codes are integers | |
| 2589 or symbols. In XEmacs, keymaps are a special new data type, and | |
| 2590 key-codes are symbols or lists of symbols. The iteration does not enter | |
| 2591 nested keymaps or inherited (parent) keymaps. You can use @samp{the | |
| 2592 key-bindings} to access the commands bound to the keys rather than the | |
| 2593 key codes, and you can add a @code{using} clause to access both the | |
| 2594 codes and the bindings together. | |
| 2595 | |
| 2596 @item for @var{var} being the key-seqs of @var{keymap} | |
| 2597 This clause iterates over all key sequences defined by @var{keymap} | |
| 2598 and its nested keymaps, where @var{var} takes on values which are | |
| 2599 strings in Emacs 18 or vectors in Emacs 19. The strings or vectors | |
| 2600 are reused for each iteration, so you must copy them if you wish to keep | |
| 2601 them permanently. You can add a @samp{using (key-bindings ...)} | |
| 2602 clause to get the command bindings as well. | |
| 2603 | |
| 2604 @item for @var{var} being the overlays [of @var{buffer}] @dots{} | |
| 2605 This clause iterates over the Emacs 19 ``overlays'' or XEmacs | |
| 2606 ``extents'' of a buffer (the clause @code{extents} is synonymous with | |
| 2607 @code{overlays}). Under Emacs 18, this clause iterates zero times. If | |
| 2608 the @code{of} term is omitted, the current buffer is used. This clause | |
| 2609 also accepts optional @samp{from @var{pos}} and @samp{to @var{pos}} | |
| 2610 terms, limiting the clause to overlays which overlap the specified | |
| 2611 region. | |
| 2612 | |
| 2613 @item for @var{var} being the intervals [of @var{buffer}] @dots{} | |
| 2614 This clause iterates over all intervals of a buffer with constant | |
| 2615 text properties. The variable @var{var} will be bound to conses | |
| 2616 of start and end positions, where one start position is always equal | |
| 2617 to the previous end position. The clause allows @code{of}, | |
| 2618 @code{from}, @code{to}, and @code{property} terms, where the latter | |
| 2619 term restricts the search to just the specified property. The | |
| 2620 @code{of} term may specify either a buffer or a string. This | |
| 2621 clause is useful only in GNU Emacs 19; in other versions, all | |
| 2622 buffers and strings consist of a single interval. | |
| 2623 | |
| 2624 @item for @var{var} being the frames | |
| 2625 This clause iterates over all frames, i.e., X window system windows | |
| 2626 open on Emacs files. This clause works only under Emacs 19. The | |
| 2627 clause @code{screens} is a synonym for @code{frames}. The frames | |
| 2628 are visited in @code{next-frame} order starting from | |
| 2629 @code{selected-frame}. | |
| 2630 | |
| 2631 @item for @var{var} being the windows [of @var{frame}] | |
| 2632 This clause iterates over the windows (in the Emacs sense) of | |
| 2633 the current frame, or of the specified @var{frame}. (In Emacs 18 | |
| 2634 there is only ever one frame, and the @code{of} term is not | |
| 2635 allowed there.) | |
| 2636 | |
| 2637 @item for @var{var} being the buffers | |
| 2638 This clause iterates over all buffers in Emacs. It is equivalent | |
| 2639 to @samp{for @var{var} in (buffer-list)}. | |
| 2640 | |
| 2641 @item for @var{var} = @var{expr1} then @var{expr2} | |
| 2642 This clause does a general iteration. The first time through | |
| 2643 the loop, @var{var} will be bound to @var{expr1}. On the second | |
| 2644 and successive iterations it will be set by evaluating @var{expr2} | |
| 2645 (which may refer to the old value of @var{var}). For example, | |
| 2646 these two loops are effectively the same: | |
| 2647 | |
| 2648 @example | |
| 2649 (loop for x on my-list by 'cddr do ...) | |
| 2650 (loop for x = my-list then (cddr x) while x do ...) | |
| 2651 @end example | |
| 2652 | |
| 2653 Note that this type of @code{for} clause does not imply any sort | |
| 2654 of terminating condition; the above example combines it with a | |
| 2655 @code{while} clause to tell when to end the loop. | |
| 2656 | |
| 2657 If you omit the @code{then} term, @var{expr1} is used both for | |
| 2658 the initial setting and for successive settings: | |
| 2659 | |
| 2660 @example | |
| 2661 (loop for x = (random) when (> x 0) return x) | |
| 2662 @end example | |
| 2663 | |
| 2664 @noindent | |
| 2665 This loop keeps taking random numbers from the @code{(random)} | |
| 2666 function until it gets a positive one, which it then returns. | |
| 2667 @end table | |
| 2668 | |
| 2669 If you include several @code{for} clauses in a row, they are | |
| 2670 treated sequentially (as if by @code{let*} and @code{setq}). | |
| 2671 You can instead use the word @code{and} to link the clauses, | |
| 2672 in which case they are processed in parallel (as if by @code{let} | |
| 2673 and @code{psetq}). | |
| 2674 | |
| 2675 @example | |
| 2676 (loop for x below 5 for y = nil then x collect (list x y)) | |
| 2677 @result{} ((0 nil) (1 1) (2 2) (3 3) (4 4)) | |
| 2678 (loop for x below 5 and y = nil then x collect (list x y)) | |
| 2679 @result{} ((0 nil) (1 0) (2 1) (3 2) (4 3)) | |
| 2680 @end example | |
| 2681 | |
| 2682 @noindent | |
| 2683 In the first loop, @code{y} is set based on the value of @code{x} | |
| 2684 that was just set by the previous clause; in the second loop, | |
| 2685 @code{x} and @code{y} are set simultaneously so @code{y} is set | |
| 2686 based on the value of @code{x} left over from the previous time | |
| 2687 through the loop. | |
| 2688 | |
| 2689 Another feature of the @code{loop} macro is @dfn{destructuring}, | |
| 2690 similar in concept to the destructuring provided by @code{defmacro}. | |
| 2691 The @var{var} part of any @code{for} clause can be given as a list | |
| 2692 of variables instead of a single variable. The values produced | |
| 2693 during loop execution must be lists; the values in the lists are | |
| 2694 stored in the corresponding variables. | |
| 2695 | |
| 2696 @example | |
| 2697 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y)) | |
| 2698 @result{} (5 9 13) | |
| 2699 @end example | |
| 2700 | |
| 2701 In loop destructuring, if there are more values than variables | |
| 2702 the trailing values are ignored, and if there are more variables | |
| 2703 than values the trailing variables get the value @code{nil}. | |
| 2704 If @code{nil} is used as a variable name, the corresponding | |
| 2705 values are ignored. Destructuring may be nested, and dotted | |
| 2706 lists of variables like @code{(x . y)} are allowed. | |
| 2707 | |
| 2708 @node Iteration Clauses, Accumulation Clauses, For Clauses, Loop Facility | |
| 2709 @subsection Iteration Clauses | |
| 2710 | |
| 2711 @noindent | |
| 2712 Aside from @code{for} clauses, there are several other loop clauses | |
| 2713 that control the way the loop operates. They might be used by | |
| 2714 themselves, or in conjunction with one or more @code{for} clauses. | |
| 2715 | |
| 2716 @table @code | |
| 2717 @item repeat @var{integer} | |
| 2718 This clause simply counts up to the specified number using an | |
| 2719 internal temporary variable. The loops | |
| 2720 | |
| 2721 @example | |
| 2722 (loop repeat n do ...) | |
| 2723 (loop for temp to n do ...) | |
| 2724 @end example | |
| 2725 | |
| 2726 @noindent | |
| 2727 are identical except that the second one forces you to choose | |
| 2728 a name for a variable you aren't actually going to use. | |
| 2729 | |
| 2730 @item while @var{condition} | |
| 2731 This clause stops the loop when the specified condition (any Lisp | |
| 2732 expression) becomes @code{nil}. For example, the following two | |
| 2733 loops are equivalent, except for the implicit @code{nil} block | |
| 2734 that surrounds the second one: | |
| 2735 | |
| 2736 @example | |
| 2737 (while @var{cond} @var{forms}@dots{}) | |
| 2738 (loop while @var{cond} do @var{forms}@dots{}) | |
| 2739 @end example | |
| 2740 | |
| 2741 @item until @var{condition} | |
| 2742 This clause stops the loop when the specified condition is true, | |
| 2743 i.e., non-@code{nil}. | |
| 2744 | |
| 2745 @item always @var{condition} | |
| 2746 This clause stops the loop when the specified condition is @code{nil}. | |
| 2747 Unlike @code{while}, it stops the loop using @code{return nil} so that | |
| 2748 the @code{finally} clauses are not executed. If all the conditions | |
| 2749 were non-@code{nil}, the loop returns @code{t}: | |
| 2750 | |
| 2751 @example | |
| 2752 (if (loop for size in size-list always (> size 10)) | |
| 2753 (some-big-sizes) | |
| 2754 (no-big-sizes)) | |
| 2755 @end example | |
| 2756 | |
| 2757 @item never @var{condition} | |
| 2758 This clause is like @code{always}, except that the loop returns | |
| 2759 @code{t} if any conditions were false, or @code{nil} otherwise. | |
| 2760 | |
| 2761 @item thereis @var{condition} | |
| 2762 This clause stops the loop when the specified form is non-@code{nil}; | |
| 2763 in this case, it returns that non-@code{nil} value. If all the | |
| 2764 values were @code{nil}, the loop returns @code{nil}. | |
| 2765 @end table | |
| 2766 | |
| 2767 @node Accumulation Clauses, Other Clauses, Iteration Clauses, Loop Facility | |
| 2768 @subsection Accumulation Clauses | |
| 2769 | |
| 2770 @noindent | |
| 2771 These clauses cause the loop to accumulate information about the | |
| 2772 specified Lisp @var{form}. The accumulated result is returned | |
| 2773 from the loop unless overridden, say, by a @code{return} clause. | |
| 2774 | |
| 2775 @table @code | |
| 2776 @item collect @var{form} | |
| 2777 This clause collects the values of @var{form} into a list. Several | |
| 2778 examples of @code{collect} appear elsewhere in this manual. | |
| 2779 | |
| 2780 The word @code{collecting} is a synonym for @code{collect}, and | |
| 2781 likewise for the other accumulation clauses. | |
| 2782 | |
| 2783 @item append @var{form} | |
| 2784 This clause collects lists of values into a result list using | |
| 2785 @code{append}. | |
| 2786 | |
| 2787 @item nconc @var{form} | |
| 2788 This clause collects lists of values into a result list by | |
| 2789 destructively modifying the lists rather than copying them. | |
| 2790 | |
| 2791 @item concat @var{form} | |
| 2792 This clause concatenates the values of the specified @var{form} | |
| 2793 into a string. (It and the following clause are extensions to | |
| 2794 standard Common Lisp.) | |
| 2795 | |
| 2796 @item vconcat @var{form} | |
| 2797 This clause concatenates the values of the specified @var{form} | |
| 2798 into a vector. | |
| 2799 | |
| 2800 @item count @var{form} | |
| 2801 This clause counts the number of times the specified @var{form} | |
| 2802 evaluates to a non-@code{nil} value. | |
| 2803 | |
| 2804 @item sum @var{form} | |
| 2805 This clause accumulates the sum of the values of the specified | |
| 2806 @var{form}, which must evaluate to a number. | |
| 2807 | |
| 2808 @item maximize @var{form} | |
| 2809 This clause accumulates the maximum value of the specified @var{form}, | |
| 2810 which must evaluate to a number. The return value is undefined if | |
| 2811 @code{maximize} is executed zero times. | |
| 2812 | |
| 2813 @item minimize @var{form} | |
| 2814 This clause accumulates the minimum value of the specified @var{form}. | |
| 2815 @end table | |
| 2816 | |
| 2817 Accumulation clauses can be followed by @samp{into @var{var}} to | |
| 2818 cause the data to be collected into variable @var{var} (which is | |
| 2819 automatically @code{let}-bound during the loop) rather than an | |
| 2820 unnamed temporary variable. Also, @code{into} accumulations do | |
| 2821 not automatically imply a return value. The loop must use some | |
| 2822 explicit mechanism, such as @code{finally return}, to return | |
| 2823 the accumulated result. | |
| 2824 | |
| 2825 It is legal for several accumulation clauses of the same type to | |
| 2826 accumulate into the same place. From Steele: | |
| 2827 | |
| 2828 @example | |
| 2829 (loop for name in '(fred sue alice joe june) | |
| 2830 for kids in '((bob ken) () () (kris sunshine) ()) | |
| 2831 collect name | |
| 2832 append kids) | |
| 2833 @result{} (fred bob ken sue alice joe kris sunshine june) | |
| 2834 @end example | |
| 2835 | |
| 2836 @node Other Clauses, , Accumulation Clauses, Loop Facility | |
| 2837 @subsection Other Clauses | |
| 2838 | |
| 2839 @noindent | |
| 2840 This section describes the remaining loop clauses. | |
| 2841 | |
| 2842 @table @code | |
| 2843 @item with @var{var} = @var{value} | |
| 2844 This clause binds a variable to a value around the loop, but | |
| 2845 otherwise leaves the variable alone during the loop. The following | |
| 2846 loops are basically equivalent: | |
| 2847 | |
| 2848 @example | |
| 2849 (loop with x = 17 do ...) | |
| 2850 (let ((x 17)) (loop do ...)) | |
| 2851 (loop for x = 17 then x do ...) | |
| 2852 @end example | |
| 2853 | |
| 2854 Naturally, the variable @var{var} might be used for some purpose | |
| 2855 in the rest of the loop. For example: | |
| 2856 | |
| 2857 @example | |
| 2858 (loop for x in my-list with res = nil do (push x res) | |
| 2859 finally return res) | |
| 2860 @end example | |
| 2861 | |
| 2862 This loop inserts the elements of @code{my-list} at the front of | |
| 2863 a new list being accumulated in @code{res}, then returns the | |
| 2864 list @code{res} at the end of the loop. The effect is similar | |
| 2865 to that of a @code{collect} clause, but the list gets reversed | |
| 2866 by virtue of the fact that elements are being pushed onto the | |
| 2867 front of @code{res} rather than the end. | |
| 2868 | |
| 2869 If you omit the @code{=} term, the variable is initialized to | |
| 2870 @code{nil}. (Thus the @samp{= nil} in the above example is | |
| 2871 unnecessary.) | |
| 2872 | |
| 2873 Bindings made by @code{with} are sequential by default, as if | |
| 2874 by @code{let*}. Just like @code{for} clauses, @code{with} clauses | |
| 2875 can be linked with @code{and} to cause the bindings to be made by | |
| 2876 @code{let} instead. | |
| 2877 | |
| 2878 @item if @var{condition} @var{clause} | |
| 2879 This clause executes the following loop clause only if the specified | |
| 2880 condition is true. The following @var{clause} should be an accumulation, | |
| 2881 @code{do}, @code{return}, @code{if}, or @code{unless} clause. | |
| 2882 Several clauses may be linked by separating them with @code{and}. | |
| 2883 These clauses may be followed by @code{else} and a clause or clauses | |
| 2884 to execute if the condition was false. The whole construct may | |
| 2885 optionally be followed by the word @code{end} (which may be used to | |
| 2886 disambiguate an @code{else} or @code{and} in a nested @code{if}). | |
| 2887 | |
| 2888 The actual non-@code{nil} value of the condition form is available | |
| 2889 by the name @code{it} in the ``then'' part. For example: | |
| 2890 | |
| 2891 @example | |
| 2892 (setq funny-numbers '(6 13 -1)) | |
| 2893 @result{} (6 13 -1) | |
| 2894 (loop for x below 10 | |
| 2895 if (oddp x) | |
| 2896 collect x into odds | |
| 2897 and if (memq x funny-numbers) return (cdr it) end | |
| 2898 else | |
| 2899 collect x into evens | |
| 2900 finally return (vector odds evens)) | |
| 2901 @result{} [(1 3 5 7 9) (0 2 4 6 8)] | |
| 2902 (setq funny-numbers '(6 7 13 -1)) | |
| 2903 @result{} (6 7 13 -1) | |
| 2904 (loop <@r{same thing again}>) | |
| 2905 @result{} (13 -1) | |
| 2906 @end example | |
| 2907 | |
| 2908 Note the use of @code{and} to put two clauses into the ``then'' | |
| 2909 part, one of which is itself an @code{if} clause. Note also that | |
| 2910 @code{end}, while normally optional, was necessary here to make | |
| 2911 it clear that the @code{else} refers to the outermost @code{if} | |
| 2912 clause. In the first case, the loop returns a vector of lists | |
| 2913 of the odd and even values of @var{x}. In the second case, the | |
| 2914 odd number 7 is one of the @code{funny-numbers} so the loop | |
| 2915 returns early; the actual returned value is based on the result | |
| 2916 of the @code{memq} call. | |
| 2917 | |
| 2918 @item when @var{condition} @var{clause} | |
| 2919 This clause is just a synonym for @code{if}. | |
| 2920 | |
| 2921 @item unless @var{condition} @var{clause} | |
| 2922 The @code{unless} clause is just like @code{if} except that the | |
| 2923 sense of the condition is reversed. | |
| 2924 | |
| 2925 @item named @var{name} | |
| 2926 This clause gives a name other than @code{nil} to the implicit | |
| 2927 block surrounding the loop. The @var{name} is the symbol to be | |
| 2928 used as the block name. | |
| 2929 | |
| 2930 @item initially [do] @var{forms}... | |
| 2931 This keyword introduces one or more Lisp forms which will be | |
| 2932 executed before the loop itself begins (but after any variables | |
| 2933 requested by @code{for} or @code{with} have been bound to their | |
| 2934 initial values). @code{initially} clauses can appear anywhere; | |
| 2935 if there are several, they are executed in the order they appear | |
| 2936 in the loop. The keyword @code{do} is optional. | |
| 2937 | |
| 2938 @item finally [do] @var{forms}... | |
| 2939 This introduces Lisp forms which will be executed after the loop | |
| 2940 finishes (say, on request of a @code{for} or @code{while}). | |
| 2941 @code{initially} and @code{finally} clauses may appear anywhere | |
| 2942 in the loop construct, but they are executed (in the specified | |
| 2943 order) at the beginning or end, respectively, of the loop. | |
| 2944 | |
| 2945 @item finally return @var{form} | |
| 2946 This says that @var{form} should be executed after the loop | |
| 2947 is done to obtain a return value. (Without this, or some other | |
| 2948 clause like @code{collect} or @code{return}, the loop will simply | |
| 2949 return @code{nil}.) Variables bound by @code{for}, @code{with}, | |
| 2950 or @code{into} will still contain their final values when @var{form} | |
| 2951 is executed. | |
| 2952 | |
| 2953 @item do @var{forms}... | |
| 2954 The word @code{do} may be followed by any number of Lisp expressions | |
| 2955 which are executed as an implicit @code{progn} in the body of the | |
| 2956 loop. Many of the examples in this section illustrate the use of | |
| 2957 @code{do}. | |
| 2958 | |
| 2959 @item return @var{form} | |
| 2960 This clause causes the loop to return immediately. The following | |
| 2961 Lisp form is evaluated to give the return value of the @code{loop} | |
| 2962 form. The @code{finally} clauses, if any, are not executed. | |
| 2963 Of course, @code{return} is generally used inside an @code{if} or | |
| 2964 @code{unless}, as its use in a top-level loop clause would mean | |
| 2965 the loop would never get to ``loop'' more than once. | |
| 2966 | |
| 2967 The clause @samp{return @var{form}} is equivalent to | |
| 2968 @samp{do (return @var{form})} (or @code{return-from} if the loop | |
| 2969 was named). The @code{return} clause is implemented a bit more | |
| 2970 efficiently, though. | |
| 2971 @end table | |
| 2972 | |
| 2973 While there is no high-level way to add user extensions to @code{loop} | |
| 2974 (comparable to @code{defsetf} for @code{setf}, say), this package | |
| 2975 does offer two properties called @code{cl-loop-handler} and | |
| 2976 @code{cl-loop-for-handler} which are functions to be called when | |
| 2977 a given symbol is encountered as a top-level loop clause or | |
| 2978 @code{for} clause, respectively. Consult the source code in | |
| 2979 file @file{cl-macs.el} for details. | |
| 2980 | |
| 2981 This package's @code{loop} macro is compatible with that of Common | |
| 2982 Lisp, except that a few features are not implemented: @code{loop-finish} | |
| 2983 and data-type specifiers. Naturally, the @code{for} clauses which | |
| 2984 iterate over keymaps, overlays, intervals, frames, windows, and | |
| 2985 buffers are Emacs-specific extensions. | |
| 2986 | |
| 2987 @node Multiple Values, , Loop Facility, Control Structure | |
| 2988 @section Multiple Values | |
| 2989 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
2990 This functionality has been moved to core XEmacs, and is documented in |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
2991 the XEmacs Lisp reference, @pxref{(lispref.info)Multiple values}. |
| 428 | 2992 |
| 2993 @node Macros, Declarations, Control Structure, Top | |
| 2994 @chapter Macros | |
| 2995 | |
| 2996 @noindent | |
| 2997 This package implements the various Common Lisp features of | |
| 2998 @code{defmacro}, such as destructuring, @code{&environment}, | |
| 2999 and @code{&body}. Top-level @code{&whole} is not implemented | |
| 3000 for @code{defmacro} due to technical difficulties. | |
| 3001 @xref{Argument Lists}. | |
| 3002 | |
| 3003 Destructuring is made available to the user by way of the | |
| 3004 following macro: | |
| 3005 | |
| 3006 @defspec destructuring-bind arglist expr forms@dots{} | |
| 3007 This macro expands to code which executes @var{forms}, with | |
| 3008 the variables in @var{arglist} bound to the list of values | |
| 3009 returned by @var{expr}. The @var{arglist} can include all | |
| 3010 the features allowed for @code{defmacro} argument lists, | |
| 3011 including destructuring. (The @code{&environment} keyword | |
| 3012 is not allowed.) The macro expansion will signal an error | |
| 3013 if @var{expr} returns a list of the wrong number of arguments | |
| 3014 or with incorrect keyword arguments. | |
| 3015 @end defspec | |
| 3016 | |
| 3017 This package also includes the Common Lisp @code{define-compiler-macro} | |
| 3018 facility, which allows you to define compile-time expansions and | |
| 3019 optimizations for your functions. | |
| 3020 | |
| 3021 @defspec define-compiler-macro name arglist forms@dots{} | |
| 3022 This form is similar to @code{defmacro}, except that it only expands | |
| 3023 calls to @var{name} at compile-time; calls processed by the Lisp | |
| 3024 interpreter are not expanded, nor are they expanded by the | |
| 3025 @code{macroexpand} function. | |
| 3026 | |
| 3027 The argument list may begin with a @code{&whole} keyword and a | |
| 3028 variable. This variable is bound to the macro-call form itself, | |
| 3029 i.e., to a list of the form @samp{(@var{name} @var{args}@dots{})}. | |
| 3030 If the macro expander returns this form unchanged, then the | |
| 3031 compiler treats it as a normal function call. This allows | |
| 3032 compiler macros to work as optimizers for special cases of a | |
| 3033 function, leaving complicated cases alone. | |
| 3034 | |
| 3035 For example, here is a simplified version of a definition that | |
| 3036 appears as a standard part of this package: | |
| 3037 | |
| 3038 @example | |
| 3039 (define-compiler-macro member* (&whole form a list &rest keys) | |
| 3040 (if (and (null keys) | |
| 3041 (eq (car-safe a) 'quote) | |
| 3042 (not (floatp-safe (cadr a)))) | |
| 3043 (list 'memq a list) | |
| 3044 form)) | |
| 3045 @end example | |
| 3046 | |
| 3047 @noindent | |
| 3048 This definition causes @code{(member* @var{a} @var{list})} to change | |
| 3049 to a call to the faster @code{memq} in the common case where @var{a} | |
| 3050 is a non-floating-point constant; if @var{a} is anything else, or | |
| 3051 if there are any keyword arguments in the call, then the original | |
| 3052 @code{member*} call is left intact. (The actual compiler macro | |
| 3053 for @code{member*} optimizes a number of other cases, including | |
| 3054 common @code{:test} predicates.) | |
| 3055 @end defspec | |
| 3056 | |
| 3057 @defun compiler-macroexpand form | |
| 3058 This function is analogous to @code{macroexpand}, except that it | |
| 3059 expands compiler macros rather than regular macros. It returns | |
| 3060 @var{form} unchanged if it is not a call to a function for which | |
| 3061 a compiler macro has been defined, or if that compiler macro | |
| 3062 decided to punt by returning its @code{&whole} argument. Like | |
| 3063 @code{macroexpand}, it expands repeatedly until it reaches a form | |
| 3064 for which no further expansion is possible. | |
| 3065 @end defun | |
| 3066 | |
| 3067 @xref{Macro Bindings}, for descriptions of the @code{macrolet} | |
| 3068 and @code{symbol-macrolet} forms for making ``local'' macro | |
| 3069 definitions. | |
| 3070 | |
| 3071 @node Declarations, Symbols, Macros, Top | |
| 3072 @chapter Declarations | |
| 3073 | |
| 3074 @noindent | |
| 3075 Common Lisp includes a complex and powerful ``declaration'' | |
| 3076 mechanism that allows you to give the compiler special hints | |
| 3077 about the types of data that will be stored in particular variables, | |
| 3078 and about the ways those variables and functions will be used. This | |
| 3079 package defines versions of all the Common Lisp declaration forms: | |
| 3080 @code{declare}, @code{locally}, @code{proclaim}, @code{declaim}, | |
| 3081 and @code{the}. | |
| 3082 | |
| 3083 Most of the Common Lisp declarations are not currently useful in | |
| 3084 Emacs Lisp, as the byte-code system provides little opportunity | |
| 3085 to benefit from type information, and @code{special} declarations | |
| 3086 are redundant in a fully dynamically-scoped Lisp. A few | |
| 3087 declarations are meaningful when the optimizing Emacs 19 byte | |
| 3088 compiler is being used, however. Under the earlier non-optimizing | |
| 3089 compiler, these declarations will effectively be ignored. | |
| 3090 | |
| 3091 @defun proclaim decl-spec | |
| 3092 This function records a ``global'' declaration specified by | |
| 3093 @var{decl-spec}. Since @code{proclaim} is a function, @var{decl-spec} | |
| 3094 is evaluated and thus should normally be quoted. | |
| 3095 @end defun | |
| 3096 | |
| 3097 @defspec declaim decl-specs@dots{} | |
| 3098 This macro is like @code{proclaim}, except that it takes any number | |
| 3099 of @var{decl-spec} arguments, and the arguments are unevaluated and | |
| 3100 unquoted. The @code{declaim} macro also puts an @code{(eval-when | |
| 3101 (compile load eval) ...)} around the declarations so that they will | |
| 3102 be registered at compile-time as well as at run-time. (This is vital, | |
| 3103 since normally the declarations are meant to influence the way the | |
| 3104 compiler treats the rest of the file that contains the @code{declaim} | |
| 3105 form.) | |
| 3106 @end defspec | |
| 3107 | |
| 3108 @defspec declare decl-specs@dots{} | |
| 3109 This macro is used to make declarations within functions and other | |
| 3110 code. Common Lisp allows declarations in various locations, generally | |
| 3111 at the beginning of any of the many ``implicit @code{progn}s'' | |
| 3112 throughout Lisp syntax, such as function bodies, @code{let} bodies, | |
| 3113 etc. Currently the only declaration understood by @code{declare} | |
| 3114 is @code{special}. | |
| 3115 @end defspec | |
| 3116 | |
| 3117 @defspec locally declarations@dots{} forms@dots{} | |
| 3118 In this package, @code{locally} is no different from @code{progn}. | |
| 3119 @end defspec | |
| 3120 | |
| 3121 @defspec the type form | |
| 3122 Type information provided by @code{the} is ignored in this package; | |
| 3123 in other words, @code{(the @var{type} @var{form})} is equivalent | |
| 3124 to @var{form}. Future versions of the optimizing byte-compiler may | |
| 3125 make use of this information. | |
| 3126 | |
| 3127 For example, @code{mapcar} can map over both lists and arrays. It is | |
| 3128 hard for the compiler to expand @code{mapcar} into an in-line loop | |
| 3129 unless it knows whether the sequence will be a list or an array ahead | |
| 3130 of time. With @code{(mapcar 'car (the vector foo))}, a future | |
| 3131 compiler would have enough information to expand the loop in-line. | |
| 3132 For now, Emacs Lisp will treat the above code as exactly equivalent | |
| 3133 to @code{(mapcar 'car foo)}. | |
| 3134 @end defspec | |
| 3135 | |
| 3136 Each @var{decl-spec} in a @code{proclaim}, @code{declaim}, or | |
| 3137 @code{declare} should be a list beginning with a symbol that says | |
| 3138 what kind of declaration it is. This package currently understands | |
| 3139 @code{special}, @code{inline}, @code{notinline}, @code{optimize}, | |
| 3140 and @code{warn} declarations. (The @code{warn} declaration is an | |
| 3141 extension of standard Common Lisp.) Other Common Lisp declarations, | |
| 3142 such as @code{type} and @code{ftype}, are silently ignored. | |
| 3143 | |
| 3144 @table @code | |
| 3145 @item special | |
| 3146 Since all variables in Emacs Lisp are ``special'' (in the Common | |
| 3147 Lisp sense), @code{special} declarations are only advisory. They | |
| 3148 simply tell the optimizing byte compiler that the specified | |
| 3149 variables are intentionally being referred to without being | |
| 3150 bound in the body of the function. The compiler normally emits | |
| 3151 warnings for such references, since they could be typographical | |
| 3152 errors for references to local variables. | |
| 3153 | |
| 3154 The declaration @code{(declare (special @var{var1} @var{var2}))} is | |
| 3155 equivalent to @code{(defvar @var{var1}) (defvar @var{var2})} in the | |
| 3156 optimizing compiler, or to nothing at all in older compilers (which | |
| 3157 do not warn for non-local references). | |
| 3158 | |
| 3159 In top-level contexts, it is generally better to write | |
| 3160 @code{(defvar @var{var})} than @code{(declaim (special @var{var}))}, | |
| 3161 since @code{defvar} makes your intentions clearer. But the older | |
| 3162 byte compilers can not handle @code{defvar}s appearing inside of | |
| 3163 functions, while @code{(declare (special @var{var}))} takes care | |
| 3164 to work correctly with all compilers. | |
| 3165 | |
| 3166 @item inline | |
| 3167 The @code{inline} @var{decl-spec} lists one or more functions | |
| 3168 whose bodies should be expanded ``in-line'' into calling functions | |
| 3169 whenever the compiler is able to arrange for it. For example, | |
| 3170 the Common Lisp function @code{cadr} is declared @code{inline} | |
| 3171 by this package so that the form @code{(cadr @var{x})} will | |
| 3172 expand directly into @code{(car (cdr @var{x}))} when it is called | |
| 3173 in user functions, for a savings of one (relatively expensive) | |
| 3174 function call. | |
| 3175 | |
| 3176 The following declarations are all equivalent. Note that the | |
| 3177 @code{defsubst} form is a convenient way to define a function | |
| 3178 and declare it inline all at once, but it is available only in | |
| 3179 Emacs 19. | |
| 3180 | |
| 3181 @example | |
| 3182 (declaim (inline foo bar)) | |
| 3183 (eval-when (compile load eval) (proclaim '(inline foo bar))) | |
| 442 | 3184 (proclaim-inline foo bar) ; XEmacs only |
| 3185 (defsubst foo (...) ...) ; instead of defun; Emacs 19 only | |
| 428 | 3186 @end example |
| 3187 | |
| 3188 @strong{Please note:} This declaration remains in effect after the | |
| 3189 containing source file is done. It is correct to use it to | |
| 3190 request that a function you have defined should be inlined, | |
| 3191 but it is impolite to use it to request inlining of an external | |
| 3192 function. | |
| 3193 | |
| 3194 In Common Lisp, it is possible to use @code{(declare (inline @dots{}))} | |
| 3195 before a particular call to a function to cause just that call to | |
| 3196 be inlined; the current byte compilers provide no way to implement | |
| 3197 this, so @code{(declare (inline @dots{}))} is currently ignored by | |
| 3198 this package. | |
| 3199 | |
| 3200 @item notinline | |
| 3201 The @code{notinline} declaration lists functions which should | |
| 3202 not be inlined after all; it cancels a previous @code{inline} | |
| 3203 declaration. | |
| 3204 | |
| 3205 @item optimize | |
| 3206 This declaration controls how much optimization is performed by | |
| 3207 the compiler. Naturally, it is ignored by the earlier non-optimizing | |
| 3208 compilers. | |
| 3209 | |
| 3210 The word @code{optimize} is followed by any number of lists like | |
| 3211 @code{(speed 3)} or @code{(safety 2)}. Common Lisp defines several | |
| 3212 optimization ``qualities''; this package ignores all but @code{speed} | |
| 3213 and @code{safety}. The value of a quality should be an integer from | |
| 3214 0 to 3, with 0 meaning ``unimportant'' and 3 meaning ``very important.'' | |
| 3215 The default level for both qualities is 1. | |
| 3216 | |
| 3217 In this package, with the Emacs 19 optimizing compiler, the | |
| 3218 @code{speed} quality is tied to the @code{byte-compile-optimize} | |
| 3219 flag, which is set to @code{nil} for @code{(speed 0)} and to | |
| 3220 @code{t} for higher settings; and the @code{safety} quality is | |
| 3221 tied to the @code{byte-compile-delete-errors} flag, which is | |
| 3222 set to @code{t} for @code{(safety 3)} and to @code{nil} for all | |
| 3223 lower settings. (The latter flag controls whether the compiler | |
| 3224 is allowed to optimize out code whose only side-effect could | |
| 3225 be to signal an error, e.g., rewriting @code{(progn foo bar)} to | |
| 3226 @code{bar} when it is not known whether @code{foo} will be bound | |
| 3227 at run-time.) | |
| 3228 | |
| 3229 Note that even compiling with @code{(safety 0)}, the Emacs | |
| 3230 byte-code system provides sufficient checking to prevent real | |
| 3231 harm from being done. For example, barring serious bugs in | |
| 3232 Emacs itself, Emacs will not crash with a segmentation fault | |
| 3233 just because of an error in a fully-optimized Lisp program. | |
| 3234 | |
| 3235 The @code{optimize} declaration is normally used in a top-level | |
| 3236 @code{proclaim} or @code{declaim} in a file; Common Lisp allows | |
| 3237 it to be used with @code{declare} to set the level of optimization | |
| 3238 locally for a given form, but this will not work correctly with the | |
| 3239 current version of the optimizing compiler. (The @code{declare} | |
| 3240 will set the new optimization level, but that level will not | |
| 3241 automatically be unset after the enclosing form is done.) | |
| 3242 | |
| 3243 @item warn | |
| 3244 This declaration controls what sorts of warnings are generated | |
| 3245 by the byte compiler. Again, only the optimizing compiler | |
| 3246 generates warnings. The word @code{warn} is followed by any | |
| 3247 number of ``warning qualities,'' similar in form to optimization | |
| 3248 qualities. The currently supported warning types are | |
| 3249 @code{redefine}, @code{callargs}, @code{unresolved}, and | |
| 3250 @code{free-vars}; in the current system, a value of 0 will | |
| 3251 disable these warnings and any higher value will enable them. | |
| 3252 See the documentation for the optimizing byte compiler for details. | |
| 3253 @end table | |
| 3254 | |
| 3255 @node Symbols, Numbers, Declarations, Top | |
| 3256 @chapter Symbols | |
| 3257 | |
| 3258 @noindent | |
| 3259 This package defines several symbol-related features that were | |
| 3260 missing from Emacs Lisp. | |
| 3261 | |
| 3262 @menu | |
| 442 | 3263 * Property Lists:: `getf', `remf' |
| 428 | 3264 * Creating Symbols:: `gensym', `gentemp' |
| 3265 @end menu | |
| 3266 | |
| 3267 @node Property Lists, Creating Symbols, Symbols, Symbols | |
| 3268 @section Property Lists | |
| 3269 | |
| 3270 @noindent | |
| 3271 These functions augment the standard Emacs Lisp functions @code{get} | |
| 442 | 3272 and @code{put} for operating on properties attached to objects. |
| 428 | 3273 There are also functions for working with property lists as |
| 442 | 3274 first-class data structures not attached to particular objects. |
| 428 | 3275 |
| 3276 @defun getf place property &optional default | |
| 3277 This function scans the list @var{place} as if it were a property | |
| 3278 list, i.e., a list of alternating property names and values. If | |
| 3279 an even-numbered element of @var{place} is found which is @code{eq} | |
| 3280 to @var{property}, the following odd-numbered element is returned. | |
| 3281 Otherwise, @var{default} is returned (or @code{nil} if no default | |
| 3282 is given). | |
| 3283 | |
| 3284 In particular, | |
| 3285 | |
| 3286 @example | |
| 3287 (get sym prop) @equiv{} (getf (symbol-plist sym) prop) | |
| 3288 @end example | |
| 3289 | |
| 3290 It is legal to use @code{getf} as a @code{setf} place, in which case | |
| 3291 its @var{place} argument must itself be a legal @code{setf} place. | |
| 3292 The @var{default} argument, if any, is ignored in this context. | |
| 3293 The effect is to change (via @code{setcar}) the value cell in the | |
| 3294 list that corresponds to @var{property}, or to cons a new property-value | |
| 3295 pair onto the list if the property is not yet present. | |
| 3296 | |
| 3297 @example | |
| 3298 (put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) | |
| 3299 @end example | |
| 3300 | |
| 440 | 3301 The @code{get} function is also @code{setf}-able. The fact that |
| 3302 @code{default} is ignored can sometimes be useful: | |
| 428 | 3303 |
| 3304 @example | |
| 440 | 3305 (incf (get 'foo 'usage-count 0)) |
| 428 | 3306 @end example |
| 3307 | |
| 3308 Here, symbol @code{foo}'s @code{usage-count} property is incremented | |
| 3309 if it exists, or set to 1 (an incremented 0) otherwise. | |
| 3310 | |
| 3311 When not used as a @code{setf} form, @code{getf} is just a regular | |
| 3312 function and its @var{place} argument can actually be any Lisp | |
| 3313 expression. | |
| 3314 @end defun | |
| 3315 | |
| 3316 @defspec remf place property | |
| 3317 This macro removes the property-value pair for @var{property} from | |
| 3318 the property list stored at @var{place}, which is any @code{setf}-able | |
| 3319 place expression. It returns true if the property was found. Note | |
| 3320 that if @var{property} happens to be first on the list, this will | |
| 3321 effectively do a @code{(setf @var{place} (cddr @var{place}))}, | |
| 3322 whereas if it occurs later, this simply uses @code{setcdr} to splice | |
| 3323 out the property and value cells. | |
| 3324 @end defspec | |
| 3325 | |
| 3326 @iftex | |
| 3327 @secno=2 | |
| 3328 @end iftex | |
| 3329 | |
| 3330 @node Creating Symbols, , Property Lists, Symbols | |
| 3331 @section Creating Symbols | |
| 3332 | |
| 3333 @noindent | |
| 3334 These functions create unique symbols, typically for use as | |
| 3335 temporary variables. | |
| 3336 | |
| 3337 @defun gensym &optional x | |
| 3338 This function creates a new, uninterned symbol (using @code{make-symbol}) | |
| 3339 with a unique name. (The name of an uninterned symbol is relevant | |
| 3340 only if the symbol is printed.) By default, the name is generated | |
| 3341 from an increasing sequence of numbers, @samp{G1000}, @samp{G1001}, | |
| 3342 @samp{G1002}, etc. If the optional argument @var{x} is a string, that | |
| 3343 string is used as a prefix instead of @samp{G}. Uninterned symbols | |
| 3344 are used in macro expansions for temporary variables, to ensure that | |
| 3345 their names will not conflict with ``real'' variables in the user's | |
| 3346 code. | |
| 3347 @end defun | |
| 3348 | |
| 3349 @defvar *gensym-counter* | |
| 3350 This variable holds the counter used to generate @code{gensym} names. | |
| 3351 It is incremented after each use by @code{gensym}. In Common Lisp | |
| 3352 this is initialized with 0, but this package initializes it with a | |
| 3353 random (time-dependent) value to avoid trouble when two files that | |
| 3354 each used @code{gensym} in their compilation are loaded together. | |
| 3355 | |
| 3356 @strong{XEmacs note:} As of XEmacs 21.0, an uninterned symbol remains | |
| 3357 uninterned even after being dumped to bytecode. Older versions of Emacs | |
| 3358 didn't distinguish the printed representation of interned and uninterned | |
| 3359 symbols, so their names had to be treated more carefully. | |
| 3360 @end defvar | |
| 3361 | |
| 3362 @defun gentemp &optional x | |
| 3363 This function is like @code{gensym}, except that it produces a new | |
| 3364 @emph{interned} symbol. If the symbol that is generated already | |
| 3365 exists, the function keeps incrementing the counter and trying | |
| 3366 again until a new symbol is generated. | |
| 3367 @end defun | |
| 3368 | |
| 3369 The Quiroz @file{cl.el} package also defined a @code{defkeyword} | |
| 3370 form for creating self-quoting keyword symbols. This package | |
| 3371 automatically creates all keywords that are called for by | |
| 3372 @code{&key} argument specifiers, and discourages the use of | |
| 3373 keywords as data unrelated to keyword arguments, so the | |
| 3374 @code{defkeyword} form has been discontinued. | |
| 3375 | |
| 3376 @iftex | |
| 3377 @chapno=11 | |
| 3378 @end iftex | |
| 3379 | |
| 3380 @node Numbers, Sequences, Symbols, Top | |
| 3381 @chapter Numbers | |
| 3382 | |
| 3383 @noindent | |
| 3384 This section defines a few simple Common Lisp operations on numbers | |
| 3385 which were left out of Emacs Lisp. | |
| 3386 | |
| 3387 @menu | |
| 3388 * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. | |
| 3389 * Numerical Functions:: `abs', `expt', `floor*', etc. | |
| 3390 * Random Numbers:: `random*', `make-random-state' | |
| 3391 * Implementation Parameters:: `most-positive-fixnum', `most-positive-float' | |
| 3392 @end menu | |
| 3393 | |
| 3394 @iftex | |
| 3395 @secno=1 | |
| 3396 @end iftex | |
| 3397 | |
| 3398 @node Predicates on Numbers, Numerical Functions, Numbers, Numbers | |
| 3399 @section Predicates on Numbers | |
| 3400 | |
| 3401 @noindent | |
| 3402 These functions return @code{t} if the specified condition is | |
| 3403 true of the numerical argument, or @code{nil} otherwise. | |
| 3404 | |
| 3405 @defun plusp number | |
| 3406 This predicate tests whether @var{number} is positive. It is an | |
| 3407 error if the argument is not a number. | |
| 3408 @end defun | |
| 3409 | |
| 3410 @defun minusp number | |
| 3411 This predicate tests whether @var{number} is negative. It is an | |
| 3412 error if the argument is not a number. | |
| 3413 @end defun | |
| 3414 | |
| 3415 @defun oddp integer | |
| 3416 This predicate tests whether @var{integer} is odd. It is an | |
| 3417 error if the argument is not an integer. | |
| 3418 @end defun | |
| 3419 | |
| 3420 @defun evenp integer | |
| 3421 This predicate tests whether @var{integer} is even. It is an | |
| 3422 error if the argument is not an integer. | |
| 3423 @end defun | |
| 3424 | |
| 3425 @defun floatp-safe object | |
| 3426 This predicate tests whether @var{object} is a floating-point | |
| 3427 number. On systems that support floating-point, this is equivalent | |
| 3428 to @code{floatp}. On other systems, this always returns @code{nil}. | |
| 3429 @end defun | |
| 3430 | |
| 3431 @iftex | |
| 3432 @secno=3 | |
| 3433 @end iftex | |
| 3434 | |
| 3435 @node Numerical Functions, Random Numbers, Predicates on Numbers, Numbers | |
| 3436 @section Numerical Functions | |
| 3437 | |
| 3438 @noindent | |
| 3439 These functions perform various arithmetic operations on numbers. | |
| 3440 | |
| 3441 @defun abs number | |
| 3442 This function returns the absolute value of @var{number}. (Newer | |
| 3443 versions of Emacs provide this as a built-in function; this package | |
| 3444 defines @code{abs} only for Emacs 18 versions which don't provide | |
| 3445 it as a primitive.) | |
| 3446 @end defun | |
| 3447 | |
| 3448 @defun expt base power | |
| 3449 This function returns @var{base} raised to the power of @var{number}. | |
| 3450 (Newer versions of Emacs provide this as a built-in function; this | |
| 3451 package defines @code{expt} only for Emacs 18 versions which don't | |
| 3452 provide it as a primitive.) | |
| 3453 @end defun | |
| 3454 | |
| 3455 @defun gcd &rest integers | |
| 3456 This function returns the Greatest Common Divisor of the arguments. | |
| 3457 For one argument, it returns the absolute value of that argument. | |
| 3458 For zero arguments, it returns zero. | |
| 3459 @end defun | |
| 3460 | |
| 3461 @defun lcm &rest integers | |
| 3462 This function returns the Least Common Multiple of the arguments. | |
| 3463 For one argument, it returns the absolute value of that argument. | |
| 3464 For zero arguments, it returns one. | |
| 3465 @end defun | |
| 3466 | |
| 3467 @defun isqrt integer | |
| 3468 This function computes the ``integer square root'' of its integer | |
| 3469 argument, i.e., the greatest integer less than or equal to the true | |
| 3470 square root of the argument. | |
| 3471 @end defun | |
| 3472 | |
| 3473 @defun mod* number divisor | |
| 3474 This function returns the same value as the second return value | |
| 3475 of @code{floor}. | |
| 3476 @end defun | |
| 3477 | |
| 3478 @defun rem* number divisor | |
| 3479 This function returns the same value as the second return value | |
| 3480 of @code{truncate}. | |
| 3481 @end defun | |
| 3482 | |
|
5252
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3483 @noindent |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3484 The following functions are identical to their built-in counterparts, |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3485 without the trailing @code{*} in their names, but they return lists |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3486 instead of multiple values. @pxref{(lispref.info)Rounding Operations} |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3487 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3488 @defun floor* number &optional divisor |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3489 @end defun |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3490 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3491 @defun ceiling* number &optional divisor |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3492 @end defun |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3493 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3494 @defun truncate* number &optional divisor |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3495 @end defun |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3496 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3497 @defun round* number &optional divisor |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3498 @end defun |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3499 |
|
378a34562cbe
Fix style, documentation for rounding functions and multiple values.
Aidan Kehoe <kehoea@parhasard.net>
parents:
4905
diff
changeset
|
3500 All the above definitions are compatible with those in the Quiroz |
| 428 | 3501 @file{cl.el} package, except that this package appends @samp{*} |
| 3502 to certain function names to avoid conflicts with existing | |
| 3503 Emacs 19 functions, and that the mechanism for returning | |
| 3504 multiple values is different. | |
| 3505 | |
| 3506 @iftex | |
| 3507 @secno=8 | |
| 3508 @end iftex | |
| 3509 | |
| 3510 @node Random Numbers, Implementation Parameters, Numerical Functions, Numbers | |
| 3511 @section Random Numbers | |
| 3512 | |
| 3513 @noindent | |
| 3514 This package also provides an implementation of the Common Lisp | |
| 3515 random number generator. It uses its own additive-congruential | |
| 3516 algorithm, which is much more likely to give statistically clean | |
| 3517 random numbers than the simple generators supplied by many | |
| 3518 operating systems. | |
| 3519 | |
| 3520 @defun random* number &optional state | |
| 3521 This function returns a random nonnegative number less than | |
| 3522 @var{number}, and of the same type (either integer or floating-point). | |
| 3523 The @var{state} argument should be a @code{random-state} object | |
| 3524 which holds the state of the random number generator. The | |
| 3525 function modifies this state object as a side effect. If | |
| 3526 @var{state} is omitted, it defaults to the variable | |
| 3527 @code{*random-state*}, which contains a pre-initialized | |
| 3528 @code{random-state} object. | |
| 3529 @end defun | |
| 3530 | |
| 3531 @defvar *random-state* | |
| 3532 This variable contains the system ``default'' @code{random-state} | |
| 3533 object, used for calls to @code{random*} that do not specify an | |
| 3534 alternative state object. Since any number of programs in the | |
| 3535 Emacs process may be accessing @code{*random-state*} in interleaved | |
| 3536 fashion, the sequence generated from this variable will be | |
| 3537 irreproducible for all intents and purposes. | |
| 3538 @end defvar | |
| 3539 | |
| 3540 @defun make-random-state &optional state | |
| 3541 This function creates or copies a @code{random-state} object. | |
| 3542 If @var{state} is omitted or @code{nil}, it returns a new copy of | |
| 3543 @code{*random-state*}. This is a copy in the sense that future | |
| 3544 sequences of calls to @code{(random* @var{n})} and | |
| 3545 @code{(random* @var{n} @var{s})} (where @var{s} is the new | |
| 3546 random-state object) will return identical sequences of random | |
| 3547 numbers. | |
| 3548 | |
| 3549 If @var{state} is a @code{random-state} object, this function | |
| 3550 returns a copy of that object. If @var{state} is @code{t}, this | |
| 3551 function returns a new @code{random-state} object seeded from the | |
| 3552 date and time. As an extension to Common Lisp, @var{state} may also | |
| 3553 be an integer in which case the new object is seeded from that | |
| 3554 integer; each different integer seed will result in a completely | |
| 3555 different sequence of random numbers. | |
| 3556 | |
| 3557 It is legal to print a @code{random-state} object to a buffer or | |
| 3558 file and later read it back with @code{read}. If a program wishes | |
| 3559 to use a sequence of pseudo-random numbers which can be reproduced | |
| 3560 later for debugging, it can call @code{(make-random-state t)} to | |
| 3561 get a new sequence, then print this sequence to a file. When the | |
| 3562 program is later rerun, it can read the original run's random-state | |
| 3563 from the file. | |
| 3564 @end defun | |
| 3565 | |
| 3566 @defun random-state-p object | |
| 3567 This predicate returns @code{t} if @var{object} is a | |
| 3568 @code{random-state} object, or @code{nil} otherwise. | |
| 3569 @end defun | |
| 3570 | |
| 3571 @node Implementation Parameters, , Random Numbers, Numbers | |
| 3572 @section Implementation Parameters | |
| 3573 | |
| 3574 @noindent | |
| 3575 This package defines several useful constants having to with numbers. | |
| 3576 | |
| 3577 @defvar most-positive-fixnum | |
| 3578 This constant equals the largest value a Lisp integer can hold. | |
| 3579 It is typically @code{2^23-1} or @code{2^25-1}. | |
| 3580 @end defvar | |
| 3581 | |
| 3582 @defvar most-negative-fixnum | |
| 3583 This constant equals the smallest (most negative) value a Lisp | |
| 3584 integer can hold. | |
| 3585 @end defvar | |
| 3586 | |
| 3587 The following parameters have to do with floating-point numbers. | |
| 3588 This package determines their values by exercising the computer's | |
| 3589 floating-point arithmetic in various ways. Because this operation | |
| 3590 might be slow, the code for initializing them is kept in a separate | |
| 3591 function that must be called before the parameters can be used. | |
| 3592 | |
| 3593 @defun cl-float-limits | |
| 3594 This function makes sure that the Common Lisp floating-point | |
| 3595 parameters like @code{most-positive-float} have been initialized. | |
| 3596 Until it is called, these parameters will be @code{nil}. If this | |
| 3597 version of Emacs does not support floats (e.g., most versions of | |
| 3598 Emacs 18), the parameters will remain @code{nil}. If the parameters | |
| 3599 have already been initialized, the function returns immediately. | |
| 3600 | |
| 3601 The algorithm makes assumptions that will be valid for most modern | |
| 3602 machines, but will fail if the machine's arithmetic is extremely | |
| 3603 unusual, e.g., decimal. | |
| 3604 @end defun | |
| 3605 | |
| 3606 Since true Common Lisp supports up to four different floating-point | |
| 3607 precisions, it has families of constants like | |
| 3608 @code{most-positive-single-float}, @code{most-positive-double-float}, | |
| 3609 @code{most-positive-long-float}, and so on. Emacs has only one | |
| 3610 floating-point precision, so this package omits the precision word | |
| 3611 from the constants' names. | |
| 3612 | |
| 3613 @defvar most-positive-float | |
| 3614 This constant equals the largest value a Lisp float can hold. | |
| 3615 For those systems whose arithmetic supports infinities, this is | |
| 3616 the largest @emph{finite} value. For IEEE machines, the value | |
| 3617 is approximately @code{1.79e+308}. | |
| 3618 @end defvar | |
| 3619 | |
| 3620 @defvar most-negative-float | |
| 3621 This constant equals the most-negative value a Lisp float can hold. | |
| 3622 (It is assumed to be equal to @code{(- most-positive-float)}.) | |
| 3623 @end defvar | |
| 3624 | |
| 3625 @defvar least-positive-float | |
| 3626 This constant equals the smallest Lisp float value greater than zero. | |
| 3627 For IEEE machines, it is about @code{4.94e-324} if denormals are | |
| 3628 supported or @code{2.22e-308} if not. | |
| 3629 @end defvar | |
| 3630 | |
| 3631 @defvar least-positive-normalized-float | |
| 3632 This constant equals the smallest @emph{normalized} Lisp float greater | |
| 3633 than zero, i.e., the smallest value for which IEEE denormalization | |
| 3634 will not result in a loss of precision. For IEEE machines, this | |
| 3635 value is about @code{2.22e-308}. For machines that do not support | |
| 3636 the concept of denormalization and gradual underflow, this constant | |
| 3637 will always equal @code{least-positive-float}. | |
| 3638 @end defvar | |
| 3639 | |
| 3640 @defvar least-negative-float | |
| 3641 This constant is the negative counterpart of @code{least-positive-float}. | |
| 3642 @end defvar | |
| 3643 | |
| 3644 @defvar least-negative-normalized-float | |
| 3645 This constant is the negative counterpart of | |
| 3646 @code{least-positive-normalized-float}. | |
| 3647 @end defvar | |
| 3648 | |
| 3649 @defvar float-epsilon | |
| 3650 This constant is the smallest positive Lisp float that can be added | |
| 3651 to 1.0 to produce a distinct value. Adding a smaller number to 1.0 | |
| 3652 will yield 1.0 again due to roundoff. For IEEE machines, epsilon | |
| 3653 is about @code{2.22e-16}. | |
| 3654 @end defvar | |
| 3655 | |
| 3656 @defvar float-negative-epsilon | |
| 3657 This is the smallest positive value that can be subtracted from | |
| 3658 1.0 to produce a distinct value. For IEEE machines, it is about | |
| 3659 @code{1.11e-16}. | |
| 3660 @end defvar | |
| 3661 | |
| 3662 @iftex | |
| 3663 @chapno=13 | |
| 3664 @end iftex | |
| 3665 | |
| 3666 @node Sequences, Lists, Numbers, Top | |
| 3667 @chapter Sequences | |
| 3668 | |
| 3669 @noindent | |
| 3670 Common Lisp defines a number of functions that operate on | |
| 3671 @dfn{sequences}, which are either lists, strings, or vectors. | |
| 3672 Emacs Lisp includes a few of these, notably @code{elt} and | |
| 3673 @code{length}; this package defines most of the rest. | |
| 3674 | |
| 3675 @menu | |
| 3676 * Sequence Basics:: Arguments shared by all sequence functions | |
| 3677 * Mapping over Sequences:: `mapcar*', `mapcan', `map', `every', etc. | |
| 3678 * Sequence Functions:: `subseq', `remove*', `substitute', etc. | |
| 3679 * Searching Sequences:: `find', `position', `count', `search', etc. | |
| 3680 * Sorting Sequences:: `sort*', `stable-sort', `merge' | |
| 3681 @end menu | |
| 3682 | |
| 3683 @node Sequence Basics, Mapping over Sequences, Sequences, Sequences | |
| 3684 @section Sequence Basics | |
| 3685 | |
| 778 | 3686 @noindent Many of the sequence functions take keyword arguments; |
| 3687 @pxref{Argument Lists}. All keyword arguments are optional and, if | |
| 3688 specified, may appear in any order. | |
| 428 | 3689 |
| 3690 The @code{:key} argument should be passed either @code{nil}, or a | |
| 3691 function of one argument. This key function is used as a filter | |
| 3692 through which the elements of the sequence are seen; for example, | |
| 3693 @code{(find x y :key 'car)} is similar to @code{(assoc* x y)}: | |
| 3694 It searches for an element of the list whose @code{car} equals | |
| 3695 @code{x}, rather than for an element which equals @code{x} itself. | |
| 3696 If @code{:key} is omitted or @code{nil}, the filter is effectively | |
| 3697 the identity function. | |
| 3698 | |
| 3699 The @code{:test} and @code{:test-not} arguments should be either | |
| 3700 @code{nil}, or functions of two arguments. The test function is | |
| 3701 used to compare two sequence elements, or to compare a search value | |
| 3702 with sequence elements. (The two values are passed to the test | |
| 3703 function in the same order as the original sequence function | |
| 3704 arguments from which they are derived, or, if they both come from | |
| 3705 the same sequence, in the same order as they appear in that sequence.) | |
| 3706 The @code{:test} argument specifies a function which must return | |
| 3707 true (non-@code{nil}) to indicate a match; instead, you may use | |
| 3708 @code{:test-not} to give a function which returns @emph{false} to | |
| 3709 indicate a match. The default test function is @code{:test 'eql}. | |
| 3710 | |
| 3711 Many functions which take @var{item} and @code{:test} or @code{:test-not} | |
| 3712 arguments also come in @code{-if} and @code{-if-not} varieties, | |
| 3713 where a @var{predicate} function is passed instead of @var{item}, | |
| 3714 and sequence elements match if the predicate returns true on them | |
| 3715 (or false in the case of @code{-if-not}). For example: | |
| 3716 | |
| 3717 @example | |
| 3718 (remove* 0 seq :test '=) @equiv{} (remove-if 'zerop seq) | |
| 3719 @end example | |
| 3720 | |
| 3721 @noindent | |
| 3722 to remove all zeros from sequence @code{seq}. | |
| 3723 | |
| 3724 Some operations can work on a subsequence of the argument sequence; | |
| 3725 these function take @code{:start} and @code{:end} arguments which | |
| 3726 default to zero and the length of the sequence, respectively. | |
| 3727 Only elements between @var{start} (inclusive) and @var{end} | |
| 3728 (exclusive) are affected by the operation. The @var{end} argument | |
| 3729 may be passed @code{nil} to signify the length of the sequence; | |
| 3730 otherwise, both @var{start} and @var{end} must be integers, with | |
| 3731 @code{0 <= @var{start} <= @var{end} <= (length @var{seq})}. | |
| 3732 If the function takes two sequence arguments, the limits are | |
| 3733 defined by keywords @code{:start1} and @code{:end1} for the first, | |
| 3734 and @code{:start2} and @code{:end2} for the second. | |
| 3735 | |
| 3736 A few functions accept a @code{:from-end} argument, which, if | |
| 3737 non-@code{nil}, causes the operation to go from right-to-left | |
| 3738 through the sequence instead of left-to-right, and a @code{:count} | |
| 3739 argument, which specifies an integer maximum number of elements | |
| 3740 to be removed or otherwise processed. | |
| 3741 | |
| 3742 The sequence functions make no guarantees about the order in | |
| 3743 which the @code{:test}, @code{:test-not}, and @code{:key} functions | |
| 3744 are called on various elements. Therefore, it is a bad idea to depend | |
| 3745 on side effects of these functions. For example, @code{:from-end} | |
| 3746 may cause the sequence to be scanned actually in reverse, or it may | |
| 3747 be scanned forwards but computing a result ``as if'' it were scanned | |
| 3748 backwards. (Some functions, like @code{mapcar*} and @code{every}, | |
| 3749 @emph{do} specify exactly the order in which the function is called | |
| 3750 so side effects are perfectly acceptable in those cases.) | |
| 3751 | |
| 3752 Strings in GNU Emacs 19 may contain ``text properties'' as well | |
| 3753 as character data. Except as noted, it is undefined whether or | |
| 3754 not text properties are preserved by sequence functions. For | |
| 3755 example, @code{(remove* ?A @var{str})} may or may not preserve | |
| 3756 the properties of the characters copied from @var{str} into the | |
| 3757 result. | |
| 3758 | |
| 3759 @node Mapping over Sequences, Sequence Functions, Sequence Basics, Sequences | |
| 3760 @section Mapping over Sequences | |
| 3761 | |
| 3762 @noindent | |
| 3763 These functions ``map'' the function you specify over the elements | |
| 3764 of lists or arrays. They are all variations on the theme of the | |
| 3765 built-in function @code{mapcar}. | |
| 3766 | |
| 3767 @defun mapcar* function seq &rest more-seqs | |
| 3768 This function calls @var{function} on successive parallel sets of | |
| 3769 elements from its argument sequences. Given a single @var{seq} | |
| 3770 argument it is equivalent to @code{mapcar}; given @var{n} sequences, | |
| 3771 it calls the function with the first elements of each of the sequences | |
| 3772 as the @var{n} arguments to yield the first element of the result | |
| 3773 list, then with the second elements, and so on. The mapping stops as | |
| 3774 soon as the shortest sequence runs out. The argument sequences may | |
| 3775 be any mixture of lists, strings, and vectors; the return sequence | |
| 3776 is always a list. | |
| 3777 | |
| 3778 Common Lisp's @code{mapcar} accepts multiple arguments but works | |
| 3779 only on lists; Emacs Lisp's @code{mapcar} accepts a single sequence | |
| 3780 argument. This package's @code{mapcar*} works as a compatible | |
| 3781 superset of both. | |
| 3782 @end defun | |
| 3783 | |
| 3784 @defun map result-type function seq &rest more-seqs | |
| 3785 This function maps @var{function} over the argument sequences, | |
| 3786 just like @code{mapcar*}, but it returns a sequence of type | |
| 3787 @var{result-type} rather than a list. @var{result-type} must | |
| 3788 be one of the following symbols: @code{vector}, @code{string}, | |
| 3789 @code{list} (in which case the effect is the same as for | |
| 3790 @code{mapcar*}), or @code{nil} (in which case the results are | |
| 3791 thrown away and @code{map} returns @code{nil}). | |
| 3792 @end defun | |
| 3793 | |
| 3794 @defun maplist function list &rest more-lists | |
| 3795 This function calls @var{function} on each of its argument lists, | |
| 3796 then on the @code{cdr}s of those lists, and so on, until the | |
| 3797 shortest list runs out. The results are returned in the form | |
| 3798 of a list. Thus, @code{maplist} is like @code{mapcar*} except | |
| 3799 that it passes in the list pointers themselves rather than the | |
| 3800 @code{car}s of the advancing pointers. | |
| 3801 @end defun | |
| 3802 | |
| 3803 @defun mapc function seq &rest more-seqs | |
| 3804 This function is like @code{mapcar*}, except that the values | |
| 3805 returned by @var{function} are ignored and thrown away rather | |
| 3806 than being collected into a list. The return value of @code{mapc} | |
| 3807 is @var{seq}, the first sequence. | |
| 3808 @end defun | |
| 3809 | |
| 3810 @defun mapl function list &rest more-lists | |
| 3811 This function is like @code{maplist}, except that it throws away | |
| 3812 the values returned by @var{function}. | |
| 3813 @end defun | |
| 3814 | |
| 3815 @defun mapcan function seq &rest more-seqs | |
| 3816 This function is like @code{mapcar*}, except that it concatenates | |
| 3817 the return values (which must be lists) using @code{nconc}, | |
| 3818 rather than simply collecting them into a list. | |
| 3819 @end defun | |
| 3820 | |
| 3821 @defun mapcon function list &rest more-lists | |
| 3822 This function is like @code{maplist}, except that it concatenates | |
| 3823 the return values using @code{nconc}. | |
| 3824 @end defun | |
| 3825 | |
| 3826 @defun some predicate seq &rest more-seqs | |
| 3827 This function calls @var{predicate} on each element of @var{seq} | |
| 3828 in turn; if @var{predicate} returns a non-@code{nil} value, | |
| 3829 @code{some} returns that value, otherwise it returns @code{nil}. | |
| 3830 Given several sequence arguments, it steps through the sequences | |
| 3831 in parallel until the shortest one runs out, just as in | |
| 3832 @code{mapcar*}. You can rely on the left-to-right order in which | |
| 3833 the elements are visited, and on the fact that mapping stops | |
| 3834 immediately as soon as @var{predicate} returns non-@code{nil}. | |
| 3835 @end defun | |
| 3836 | |
| 3837 @defun every predicate seq &rest more-seqs | |
| 3838 This function calls @var{predicate} on each element of the sequence(s) | |
| 3839 in turn; it returns @code{nil} as soon as @var{predicate} returns | |
| 3840 @code{nil} for any element, or @code{t} if the predicate was true | |
| 3841 for all elements. | |
| 3842 @end defun | |
| 3843 | |
| 3844 @defun notany predicate seq &rest more-seqs | |
| 3845 This function calls @var{predicate} on each element of the sequence(s) | |
| 3846 in turn; it returns @code{nil} as soon as @var{predicate} returns | |
| 3847 a non-@code{nil} value for any element, or @code{t} if the predicate | |
| 3848 was @code{nil} for all elements. | |
| 3849 @end defun | |
| 3850 | |
| 3851 @defun notevery predicate seq &rest more-seqs | |
| 3852 This function calls @var{predicate} on each element of the sequence(s) | |
| 3853 in turn; it returns a non-@code{nil} value as soon as @var{predicate} | |
| 3854 returns @code{nil} for any element, or @code{t} if the predicate was | |
| 3855 true for all elements. | |
| 3856 @end defun | |
| 3857 | |
| 3858 @defun reduce function seq @t{&key :from-end :start :end :initial-value :key} | |
| 3859 This function combines the elements of @var{seq} using an associative | |
| 3860 binary operation. Suppose @var{function} is @code{*} and @var{seq} is | |
| 3861 the list @code{(2 3 4 5)}. The first two elements of the list are | |
| 3862 combined with @code{(* 2 3) = 6}; this is combined with the next | |
| 3863 element, @code{(* 6 4) = 24}, and that is combined with the final | |
| 3864 element: @code{(* 24 5) = 120}. Note that the @code{*} function happens | |
| 3865 to be self-reducing, so that @code{(* 2 3 4 5)} has the same effect as | |
| 3866 an explicit call to @code{reduce}. | |
| 3867 | |
| 3868 If @code{:from-end} is true, the reduction is right-associative instead | |
| 3869 of left-associative: | |
| 3870 | |
| 3871 @example | |
| 3872 (reduce '- '(1 2 3 4)) | |
| 3873 @equiv{} (- (- (- 1 2) 3) 4) @result{} -8 | |
| 3874 (reduce '- '(1 2 3 4) :from-end t) | |
| 3875 @equiv{} (- 1 (- 2 (- 3 4))) @result{} -2 | |
| 3876 @end example | |
| 3877 | |
| 3878 If @code{:key} is specified, it is a function of one argument which | |
| 3879 is called on each of the sequence elements in turn. | |
| 3880 | |
| 3881 If @code{:initial-value} is specified, it is effectively added to the | |
| 3882 front (or rear in the case of @code{:from-end}) of the sequence. | |
| 3883 The @code{:key} function is @emph{not} applied to the initial value. | |
| 3884 | |
| 3885 If the sequence, including the initial value, has exactly one element | |
| 3886 then that element is returned without ever calling @var{function}. | |
| 3887 If the sequence is empty (and there is no initial value), then | |
| 3888 @var{function} is called with no arguments to obtain the return value. | |
| 3889 @end defun | |
| 3890 | |
| 3891 All of these mapping operations can be expressed conveniently in | |
| 3892 terms of the @code{loop} macro. In compiled code, @code{loop} will | |
| 3893 be faster since it generates the loop as in-line code with no | |
| 3894 function calls. | |
| 3895 | |
| 3896 @node Sequence Functions, Searching Sequences, Mapping over Sequences, Sequences | |
| 3897 @section Sequence Functions | |
| 3898 | |
| 3899 @noindent | |
| 3900 This section describes a number of Common Lisp functions for | |
| 3901 operating on sequences. | |
| 3902 | |
| 3903 @defun subseq sequence start &optional end | |
| 3904 This function returns a given subsequence of the argument | |
| 3905 @var{sequence}, which may be a list, string, or vector. | |
| 3906 The indices @var{start} and @var{end} must be in range, and | |
| 3907 @var{start} must be no greater than @var{end}. If @var{end} | |
| 3908 is omitted, it defaults to the length of the sequence. The | |
| 3909 return value is always a copy; it does not share structure | |
| 3910 with @var{sequence}. | |
| 3911 | |
| 3912 As an extension to Common Lisp, @var{start} and/or @var{end} | |
| 3913 may be negative, in which case they represent a distance back | |
| 3914 from the end of the sequence. This is for compatibility with | |
| 3915 Emacs' @code{substring} function. Note that @code{subseq} is | |
| 3916 the @emph{only} sequence function that allows negative | |
| 3917 @var{start} and @var{end}. | |
| 3918 | |
| 3919 You can use @code{setf} on a @code{subseq} form to replace a | |
| 3920 specified range of elements with elements from another sequence. | |
| 3921 The replacement is done as if by @code{replace}, described below. | |
| 3922 @end defun | |
| 3923 | |
| 3924 @defun concatenate result-type &rest seqs | |
| 3925 This function concatenates the argument sequences together to | |
| 3926 form a result sequence of type @var{result-type}, one of the | |
| 3927 symbols @code{vector}, @code{string}, or @code{list}. The | |
| 3928 arguments are always copied, even in cases such as | |
| 3929 @code{(concatenate 'list '(1 2 3))} where the result is | |
| 3930 identical to an argument. | |
| 3931 @end defun | |
| 3932 | |
| 3933 @defun fill seq item @t{&key :start :end} | |
| 3934 This function fills the elements of the sequence (or the specified | |
| 3935 part of the sequence) with the value @var{item}. | |
| 3936 @end defun | |
| 3937 | |
| 3938 @defun replace seq1 seq2 @t{&key :start1 :end1 :start2 :end2} | |
| 3939 This function copies part of @var{seq2} into part of @var{seq1}. | |
| 3940 The sequence @var{seq1} is not stretched or resized; the amount | |
| 3941 of data copied is simply the shorter of the source and destination | |
| 3942 (sub)sequences. The function returns @var{seq1}. | |
| 3943 | |
| 3944 If @var{seq1} and @var{seq2} are @code{eq}, then the replacement | |
| 3945 will work correctly even if the regions indicated by the start | |
| 3946 and end arguments overlap. However, if @var{seq1} and @var{seq2} | |
| 3947 are lists which share storage but are not @code{eq}, and the | |
| 3948 start and end arguments specify overlapping regions, the effect | |
| 3949 is undefined. | |
| 3950 @end defun | |
| 3951 | |
| 3952 @defun remove* item seq @t{&key :test :test-not :key :count :start :end :from-end} | |
| 3953 This returns a copy of @var{seq} with all elements matching | |
| 3954 @var{item} removed. The result may share storage with or be | |
| 3955 @code{eq} to @var{seq} in some circumstances, but the original | |
| 3956 @var{seq} will not be modified. The @code{:test}, @code{:test-not}, | |
| 3957 and @code{:key} arguments define the matching test that is used; | |
| 3958 by default, elements @code{eql} to @var{item} are removed. The | |
| 3959 @code{:count} argument specifies the maximum number of matching | |
| 3960 elements that can be removed (only the leftmost @var{count} matches | |
| 3961 are removed). The @code{:start} and @code{:end} arguments specify | |
| 3962 a region in @var{seq} in which elements will be removed; elements | |
| 3963 outside that region are not matched or removed. The @code{:from-end} | |
| 3964 argument, if true, says that elements should be deleted from the | |
| 3965 end of the sequence rather than the beginning (this matters only | |
| 3966 if @var{count} was also specified). | |
| 3967 @end defun | |
| 3968 | |
| 3969 @defun delete* item seq @t{&key :test :test-not :key :count :start :end :from-end} | |
| 3970 This deletes all elements of @var{seq} which match @var{item}. | |
| 3971 It is a destructive operation. Since Emacs Lisp does not support | |
| 3972 stretchable strings or vectors, this is the same as @code{remove*} | |
| 3973 for those sequence types. On lists, @code{remove*} will copy the | |
| 3974 list if necessary to preserve the original list, whereas | |
| 3975 @code{delete*} will splice out parts of the argument list. | |
| 3976 Compare @code{append} and @code{nconc}, which are analogous | |
| 3977 non-destructive and destructive list operations in Emacs Lisp. | |
| 3978 @end defun | |
| 3979 | |
| 3980 @findex remove-if | |
| 3981 @findex remove-if-not | |
| 3982 @findex delete-if | |
| 3983 @findex delete-if-not | |
| 3984 The predicate-oriented functions @code{remove-if}, @code{remove-if-not}, | |
| 3985 @code{delete-if}, and @code{delete-if-not} are defined similarly. | |
| 3986 | |
| 3987 @defun delete item list | |
| 3988 This MacLisp-compatible function deletes from @var{list} all elements | |
| 3989 which are @code{equal} to @var{item}. The @code{delete} function is | |
| 3990 built-in to Emacs 19; this package defines it equivalently in Emacs 18. | |
| 3991 @end defun | |
| 3992 | |
| 3993 @defun remove item list | |
| 3994 This function removes from @var{list} all elements which are | |
| 3995 @code{equal} to @var{item}. This package defines it for symmetry | |
| 3996 with @code{delete}, even though @code{remove} is not built-in to | |
| 3997 Emacs 19. | |
| 3998 @end defun | |
| 3999 | |
| 4000 @defun remq item list | |
| 4001 This function removes from @var{list} all elements which are | |
| 4002 @code{eq} to @var{item}. This package defines it for symmetry | |
| 4003 with @code{delq}, even though @code{remq} is not built-in to | |
| 4004 Emacs 19. | |
| 4005 @end defun | |
| 4006 | |
| 4007 @defun remove-duplicates seq @t{&key :test :test-not :key :start :end :from-end} | |
| 4008 This function returns a copy of @var{seq} with duplicate elements | |
| 4009 removed. Specifically, if two elements from the sequence match | |
| 4010 according to the @code{:test}, @code{:test-not}, and @code{:key} | |
| 4011 arguments, only the rightmost one is retained. If @code{:from-end} | |
| 4012 is true, the leftmost one is retained instead. If @code{:start} or | |
| 4013 @code{:end} is specified, only elements within that subsequence are | |
| 4014 examined or removed. | |
| 4015 @end defun | |
| 4016 | |
| 4017 @defun delete-duplicates seq @t{&key :test :test-not :key :start :end :from-end} | |
| 4018 This function deletes duplicate elements from @var{seq}. It is | |
| 4019 a destructive version of @code{remove-duplicates}. | |
| 4020 @end defun | |
| 4021 | |
| 4022 @defun substitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} | |
| 4023 This function returns a copy of @var{seq}, with all elements | |
| 4024 matching @var{old} replaced with @var{new}. The @code{:count}, | |
| 4025 @code{:start}, @code{:end}, and @code{:from-end} arguments may be | |
| 4026 used to limit the number of substitutions made. | |
| 4027 @end defun | |
| 4028 | |
| 4029 @defun nsubstitute new old seq @t{&key :test :test-not :key :count :start :end :from-end} | |
| 4030 This is a destructive version of @code{substitute}; it performs | |
| 4031 the substitution using @code{setcar} or @code{aset} rather than | |
| 4032 by returning a changed copy of the sequence. | |
| 4033 @end defun | |
| 4034 | |
| 4035 @findex substitute-if | |
| 4036 @findex substitute-if-not | |
| 4037 @findex nsubstitute-if | |
| 4038 @findex nsubstitute-if-not | |
| 4039 The @code{substitute-if}, @code{substitute-if-not}, @code{nsubstitute-if}, | |
| 4040 and @code{nsubstitute-if-not} functions are defined similarly. For | |
| 4041 these, a @var{predicate} is given in place of the @var{old} argument. | |
| 4042 | |
| 4043 @node Searching Sequences, Sorting Sequences, Sequence Functions, Sequences | |
| 4044 @section Searching Sequences | |
| 4045 | |
| 4046 @noindent | |
| 4047 These functions search for elements or subsequences in a sequence. | |
| 4048 (See also @code{member*} and @code{assoc*}; @pxref{Lists}.) | |
| 4049 | |
| 4050 @defun find item seq @t{&key :test :test-not :key :start :end :from-end} | |
| 4051 This function searches @var{seq} for an element matching @var{item}. | |
| 4052 If it finds a match, it returns the matching element. Otherwise, | |
| 4053 it returns @code{nil}. It returns the leftmost match, unless | |
| 4054 @code{:from-end} is true, in which case it returns the rightmost | |
| 4055 match. The @code{:start} and @code{:end} arguments may be used to | |
| 4056 limit the range of elements that are searched. | |
| 4057 @end defun | |
| 4058 | |
| 4059 @defun position item seq @t{&key :test :test-not :key :start :end :from-end} | |
| 4060 This function is like @code{find}, except that it returns the | |
| 4061 integer position in the sequence of the matching item rather than | |
| 4062 the item itself. The position is relative to the start of the | |
| 4063 sequence as a whole, even if @code{:start} is non-zero. The function | |
| 4064 returns @code{nil} if no matching element was found. | |
| 4065 @end defun | |
| 4066 | |
| 4067 @defun count item seq @t{&key :test :test-not :key :start :end} | |
| 4068 This function returns the number of elements of @var{seq} which | |
| 4069 match @var{item}. The result is always a nonnegative integer. | |
| 4070 @end defun | |
| 4071 | |
| 4072 @findex find-if | |
| 4073 @findex find-if-not | |
| 4074 @findex position-if | |
| 4075 @findex position-if-not | |
| 4076 @findex count-if | |
| 4077 @findex count-if-not | |
| 4078 The @code{find-if}, @code{find-if-not}, @code{position-if}, | |
| 4079 @code{position-if-not}, @code{count-if}, and @code{count-if-not} | |
| 4080 functions are defined similarly. | |
| 4081 | |
| 4082 @defun mismatch seq1 seq2 @t{&key :test :test-not :key :start1 :end1 :start2 :end2 :from-end} | |
| 4083 This function compares the specified parts of @var{seq1} and | |
| 4084 @var{seq2}. If they are the same length and the corresponding | |
| 4085 elements match (according to @code{:test}, @code{:test-not}, | |
| 4086 and @code{:key}), the function returns @code{nil}. If there is | |
| 4087 a mismatch, the function returns the index (relative to @var{seq1}) | |
| 4088 of the first mismatching element. This will be the leftmost pair of | |
| 4089 elements which do not match, or the position at which the shorter of | |
| 4090 the two otherwise-matching sequences runs out. | |
| 4091 | |
| 4092 If @code{:from-end} is true, then the elements are compared from right | |
| 4093 to left starting at @code{(1- @var{end1})} and @code{(1- @var{end2})}. | |
| 4094 If the sequences differ, then one plus the index of the rightmost | |
| 4095 difference (relative to @var{seq1}) is returned. | |
| 4096 | |
| 4097 An interesting example is @code{(mismatch str1 str2 :key 'upcase)}, | |
| 4098 which compares two strings case-insensitively. | |
| 4099 @end defun | |
| 4100 | |
| 4101 @defun search seq1 seq2 @t{&key :test :test-not :key :from-end :start1 :end1 :start2 :end2} | |
| 4102 This function searches @var{seq2} for a subsequence that matches | |
| 4103 @var{seq1} (or part of it specified by @code{:start1} and | |
| 4104 @code{:end1}.) Only matches which fall entirely within the region | |
| 4105 defined by @code{:start2} and @code{:end2} will be considered. | |
| 4106 The return value is the index of the leftmost element of the | |
| 4107 leftmost match, relative to the start of @var{seq2}, or @code{nil} | |
| 4108 if no matches were found. If @code{:from-end} is true, the | |
| 4109 function finds the @emph{rightmost} matching subsequence. | |
| 4110 @end defun | |
| 4111 | |
| 4112 @node Sorting Sequences, , Searching Sequences, Sequences | |
| 4113 @section Sorting Sequences | |
| 4114 | |
| 4115 @defun sort* seq predicate @t{&key :key} | |
| 4116 This function sorts @var{seq} into increasing order as determined | |
| 4117 by using @var{predicate} to compare pairs of elements. @var{predicate} | |
| 4118 should return true (non-@code{nil}) if and only if its first argument | |
| 4119 is less than (not equal to) its second argument. For example, | |
| 4120 @code{<} and @code{string-lessp} are suitable predicate functions | |
| 4121 for sorting numbers and strings, respectively; @code{>} would sort | |
| 4122 numbers into decreasing rather than increasing order. | |
| 4123 | |
| 4124 This function differs from Emacs' built-in @code{sort} in that it | |
| 4125 can operate on any type of sequence, not just lists. Also, it | |
| 4126 accepts a @code{:key} argument which is used to preprocess data | |
| 4127 fed to the @var{predicate} function. For example, | |
| 4128 | |
| 4129 @example | |
| 4130 (setq data (sort data 'string-lessp :key 'downcase)) | |
| 4131 @end example | |
| 4132 | |
| 4133 @noindent | |
| 4134 sorts @var{data}, a sequence of strings, into increasing alphabetical | |
| 4135 order without regard to case. A @code{:key} function of @code{car} | |
| 4136 would be useful for sorting association lists. | |
| 4137 | |
| 4138 The @code{sort*} function is destructive; it sorts lists by actually | |
| 4139 rearranging the @code{cdr} pointers in suitable fashion. | |
| 4140 @end defun | |
| 4141 | |
| 4142 @defun stable-sort seq predicate @t{&key :key} | |
| 4143 This function sorts @var{seq} @dfn{stably}, meaning two elements | |
| 4144 which are equal in terms of @var{predicate} are guaranteed not to | |
| 4145 be rearranged out of their original order by the sort. | |
| 4146 | |
| 4147 In practice, @code{sort*} and @code{stable-sort} are equivalent | |
| 4148 in Emacs Lisp because the underlying @code{sort} function is | |
| 4149 stable by default. However, this package reserves the right to | |
| 4150 use non-stable methods for @code{sort*} in the future. | |
| 4151 @end defun | |
| 4152 | |
| 4153 @defun merge type seq1 seq2 predicate @t{&key :key} | |
| 4154 This function merges two sequences @var{seq1} and @var{seq2} by | |
| 4155 interleaving their elements. The result sequence, of type @var{type} | |
| 4156 (in the sense of @code{concatenate}), has length equal to the sum | |
| 4157 of the lengths of the two input sequences. The sequences may be | |
| 4158 modified destructively. Order of elements within @var{seq1} and | |
| 4159 @var{seq2} is preserved in the interleaving; elements of the two | |
| 4160 sequences are compared by @var{predicate} (in the sense of | |
| 4161 @code{sort}) and the lesser element goes first in the result. | |
| 4162 When elements are equal, those from @var{seq1} precede those from | |
| 4163 @var{seq2} in the result. Thus, if @var{seq1} and @var{seq2} are | |
| 4164 both sorted according to @var{predicate}, then the result will be | |
| 4165 a merged sequence which is (stably) sorted according to | |
| 4166 @var{predicate}. | |
| 4167 @end defun | |
| 4168 | |
| 4169 @node Lists, Hash Tables, Sequences, Top | |
| 4170 @chapter Lists | |
| 4171 | |
| 4172 @noindent | |
| 4173 The functions described here operate on lists. | |
| 4174 | |
| 4175 @menu | |
| 4176 * List Functions:: `caddr', `first', `last', `list*', etc. | |
| 4177 * Substitution of Expressions:: `subst', `sublis', etc. | |
| 4178 * Lists as Sets:: `member*', `adjoin', `union', etc. | |
| 4179 * Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' | |
| 4180 @end menu | |
| 4181 | |
| 4182 @node List Functions, Substitution of Expressions, Lists, Lists | |
| 4183 @section List Functions | |
| 4184 | |
| 4185 @noindent | |
| 4186 This section describes a number of simple operations on lists, | |
| 4187 i.e., chains of cons cells. | |
| 4188 | |
| 4189 @defun caddr x | |
| 4190 This function is equivalent to @code{(car (cdr (cdr @var{x})))}. | |
| 4191 Likewise, this package defines all 28 @code{c@var{xxx}r} functions | |
| 4192 where @var{xxx} is up to four @samp{a}s and/or @samp{d}s. | |
| 4193 All of these functions are @code{setf}-able, and calls to them | |
| 4194 are expanded inline by the byte-compiler for maximum efficiency. | |
| 4195 @end defun | |
| 4196 | |
| 4197 @defun first x | |
| 4198 This function is a synonym for @code{(car @var{x})}. Likewise, | |
| 4199 the functions @code{second}, @code{third}, @dots{}, through | |
| 4200 @code{tenth} return the given element of the list @var{x}. | |
| 4201 @end defun | |
| 4202 | |
| 4203 @defun rest x | |
| 4204 This function is a synonym for @code{(cdr @var{x})}. | |
| 4205 @end defun | |
| 4206 | |
| 4207 @defun endp x | |
| 4208 Common Lisp defines this function to act like @code{null}, but | |
| 4209 signalling an error if @code{x} is neither a @code{nil} nor a | |
| 4210 cons cell. This package simply defines @code{endp} as a synonym | |
| 4211 for @code{null}. | |
| 4212 @end defun | |
| 4213 | |
| 4214 @defun list-length x | |
| 4215 This function returns the length of list @var{x}, exactly like | |
| 4216 @code{(length @var{x})}, except that if @var{x} is a circular | |
| 4217 list (where the cdr-chain forms a loop rather than terminating | |
| 4218 with @code{nil}), this function returns @code{nil}. (The regular | |
| 4219 @code{length} function would get stuck if given a circular list.) | |
| 4220 @end defun | |
| 4221 | |
| 4222 @defun last x &optional n | |
| 4223 This function returns the last cons, or the @var{n}th-to-last cons, | |
| 4224 of the list @var{x}. If @var{n} is omitted it defaults to 1. | |
| 4225 The ``last cons'' means the first cons cell of the list whose | |
| 4226 @code{cdr} is not another cons cell. (For normal lists, the | |
| 4227 @code{cdr} of the last cons will be @code{nil}.) This function | |
| 4228 returns @code{nil} if @var{x} is @code{nil} or shorter than | |
| 4229 @var{n}. Note that the last @emph{element} of the list is | |
| 4230 @code{(car (last @var{x}))}. | |
| 4231 @end defun | |
| 4232 | |
| 4233 @defun butlast x &optional n | |
| 4234 This function returns the list @var{x} with the last element, | |
| 4235 or the last @var{n} elements, removed. If @var{n} is greater | |
| 4236 than zero it makes a copy of the list so as not to damage the | |
| 4237 original list. In general, @code{(append (butlast @var{x} @var{n}) | |
| 4238 (last @var{x} @var{n}))} will return a list equal to @var{x}. | |
| 4239 @end defun | |
| 4240 | |
| 4241 @defun nbutlast x &optional n | |
| 4242 This is a version of @code{butlast} that works by destructively | |
| 4243 modifying the @code{cdr} of the appropriate element, rather than | |
| 4244 making a copy of the list. | |
| 4245 @end defun | |
| 4246 | |
| 4247 @defun list* arg &rest others | |
| 4248 This function constructs a list of its arguments. The final | |
| 4249 argument becomes the @code{cdr} of the last cell constructed. | |
| 4250 Thus, @code{(list* @var{a} @var{b} @var{c})} is equivalent to | |
| 4251 @code{(cons @var{a} (cons @var{b} @var{c}))}, and | |
| 4252 @code{(list* @var{a} @var{b} nil)} is equivalent to | |
| 4253 @code{(list @var{a} @var{b})}. | |
| 4254 | |
| 4255 (Note that this function really is called @code{list*} in Common | |
| 4256 Lisp; it is not a name invented for this package like @code{member*} | |
| 4257 or @code{defun*}.) | |
| 4258 @end defun | |
| 4259 | |
| 4260 @defun ldiff list sublist | |
| 4261 If @var{sublist} is a sublist of @var{list}, i.e., is @code{eq} to | |
| 4262 one of the cons cells of @var{list}, then this function returns | |
| 4263 a copy of the part of @var{list} up to but not including | |
| 4264 @var{sublist}. For example, @code{(ldiff x (cddr x))} returns | |
| 4265 the first two elements of the list @code{x}. The result is a | |
| 4266 copy; the original @var{list} is not modified. If @var{sublist} | |
| 4267 is not a sublist of @var{list}, a copy of the entire @var{list} | |
| 4268 is returned. | |
| 4269 @end defun | |
| 4270 | |
| 4271 @defun copy-list list | |
| 4272 This function returns a copy of the list @var{list}. It copies | |
| 4273 dotted lists like @code{(1 2 . 3)} correctly. | |
| 4274 @end defun | |
| 4275 | |
| 4276 @defun copy-tree x &optional vecp | |
| 4277 This function returns a copy of the tree of cons cells @var{x}. | |
| 4278 Unlike @code{copy-sequence} (and its alias @code{copy-list}), | |
| 4279 which copies only along the @code{cdr} direction, this function | |
| 4280 copies (recursively) along both the @code{car} and the @code{cdr} | |
| 4281 directions. If @var{x} is not a cons cell, the function simply | |
| 4282 returns @var{x} unchanged. If the optional @var{vecp} argument | |
| 4283 is true, this function copies vectors (recursively) as well as | |
| 4284 cons cells. | |
| 4285 @end defun | |
| 4286 | |
| 4287 @defun tree-equal x y @t{&key :test :test-not :key} | |
| 4288 This function compares two trees of cons cells. If @var{x} and | |
| 4289 @var{y} are both cons cells, their @code{car}s and @code{cdr}s are | |
| 4290 compared recursively. If neither @var{x} nor @var{y} is a cons | |
| 4291 cell, they are compared by @code{eql}, or according to the | |
| 4292 specified test. The @code{:key} function, if specified, is | |
| 4293 applied to the elements of both trees. @xref{Sequences}. | |
| 4294 @end defun | |
| 4295 | |
| 4296 @iftex | |
| 4297 @secno=3 | |
| 4298 @end iftex | |
| 4299 | |
| 4300 @node Substitution of Expressions, Lists as Sets, List Functions, Lists | |
| 4301 @section Substitution of Expressions | |
| 4302 | |
| 4303 @noindent | |
| 4304 These functions substitute elements throughout a tree of cons | |
| 4305 cells. (@xref{Sequence Functions}, for the @code{substitute} | |
| 4306 function, which works on just the top-level elements of a list.) | |
| 4307 | |
| 4308 @defun subst new old tree @t{&key :test :test-not :key} | |
| 4309 This function substitutes occurrences of @var{old} with @var{new} | |
| 4310 in @var{tree}, a tree of cons cells. It returns a substituted | |
| 4311 tree, which will be a copy except that it may share storage with | |
| 4312 the argument @var{tree} in parts where no substitutions occurred. | |
| 4313 The original @var{tree} is not modified. This function recurses | |
| 4314 on, and compares against @var{old}, both @code{car}s and @code{cdr}s | |
| 4315 of the component cons cells. If @var{old} is itself a cons cell, | |
| 4316 then matching cells in the tree are substituted as usual without | |
| 4317 recursively substituting in that cell. Comparisons with @var{old} | |
| 4318 are done according to the specified test (@code{eql} by default). | |
| 4319 The @code{:key} function is applied to the elements of the tree | |
| 4320 but not to @var{old}. | |
| 4321 @end defun | |
| 4322 | |
| 4323 @defun nsubst new old tree @t{&key :test :test-not :key} | |
| 4324 This function is like @code{subst}, except that it works by | |
| 4325 destructive modification (by @code{setcar} or @code{setcdr}) | |
| 4326 rather than copying. | |
| 4327 @end defun | |
| 4328 | |
| 4329 @findex subst-if | |
| 4330 @findex subst-if-not | |
| 4331 @findex nsubst-if | |
| 4332 @findex nsubst-if-not | |
| 4333 The @code{subst-if}, @code{subst-if-not}, @code{nsubst-if}, and | |
| 4334 @code{nsubst-if-not} functions are defined similarly. | |
| 4335 | |
| 4336 @defun sublis alist tree @t{&key :test :test-not :key} | |
| 4337 This function is like @code{subst}, except that it takes an | |
| 4338 association list @var{alist} of @var{old}-@var{new} pairs. | |
| 4339 Each element of the tree (after applying the @code{:key} | |
| 4340 function, if any), is compared with the @code{car}s of | |
| 4341 @var{alist}; if it matches, it is replaced by the corresponding | |
| 4342 @code{cdr}. | |
| 4343 @end defun | |
| 4344 | |
| 4345 @defun nsublis alist tree @t{&key :test :test-not :key} | |
| 4346 This is a destructive version of @code{sublis}. | |
| 4347 @end defun | |
| 4348 | |
| 4349 @node Lists as Sets, Association Lists, Substitution of Expressions, Lists | |
| 4350 @section Lists as Sets | |
| 4351 | |
| 4352 @noindent | |
| 4353 These functions perform operations on lists which represent sets | |
| 4354 of elements. | |
| 4355 | |
| 4356 @defun member item list | |
| 4357 This MacLisp-compatible function searches @var{list} for an element | |
| 4358 which is @code{equal} to @var{item}. The @code{member} function is | |
| 4359 built-in to Emacs 19; this package defines it equivalently in Emacs 18. | |
| 4360 See the following function for a Common-Lisp compatible version. | |
| 4361 @end defun | |
| 4362 | |
| 4363 @defun member* item list @t{&key :test :test-not :key} | |
| 4364 This function searches @var{list} for an element matching @var{item}. | |
| 4365 If a match is found, it returns the cons cell whose @code{car} was | |
| 4366 the matching element. Otherwise, it returns @code{nil}. Elements | |
| 4367 are compared by @code{eql} by default; you can use the @code{:test}, | |
| 4368 @code{:test-not}, and @code{:key} arguments to modify this behavior. | |
| 4369 @xref{Sequences}. | |
| 4370 | |
| 4371 Note that this function's name is suffixed by @samp{*} to avoid | |
| 4372 the incompatible @code{member} function defined in Emacs 19. | |
| 4373 (That function uses @code{equal} for comparisons; it is equivalent | |
| 4374 to @code{(member* @var{item} @var{list} :test 'equal)}.) | |
| 4375 @end defun | |
| 4376 | |
| 4377 @findex member-if | |
| 4378 @findex member-if-not | |
| 4379 The @code{member-if} and @code{member-if-not} functions | |
| 4380 analogously search for elements which satisfy a given predicate. | |
| 4381 | |
| 4382 @defun tailp sublist list | |
| 4383 This function returns @code{t} if @var{sublist} is a sublist of | |
| 4384 @var{list}, i.e., if @var{sublist} is @code{eql} to @var{list} or to | |
| 4385 any of its @code{cdr}s. | |
| 4386 @end defun | |
| 4387 | |
| 4388 @defun adjoin item list @t{&key :test :test-not :key} | |
| 4389 This function conses @var{item} onto the front of @var{list}, | |
| 4390 like @code{(cons @var{item} @var{list})}, but only if @var{item} | |
| 4391 is not already present on the list (as determined by @code{member*}). | |
| 4392 If a @code{:key} argument is specified, it is applied to | |
| 4393 @var{item} as well as to the elements of @var{list} during | |
| 4394 the search, on the reasoning that @var{item} is ``about'' to | |
| 4395 become part of the list. | |
| 4396 @end defun | |
| 4397 | |
| 4398 @defun union list1 list2 @t{&key :test :test-not :key} | |
| 4399 This function combines two lists which represent sets of items, | |
| 4400 returning a list that represents the union of those two sets. | |
| 4401 The result list will contain all items which appear in @var{list1} | |
| 4402 or @var{list2}, and no others. If an item appears in both | |
| 4403 @var{list1} and @var{list2} it will be copied only once. If | |
| 4404 an item is duplicated in @var{list1} or @var{list2}, it is | |
| 4405 undefined whether or not that duplication will survive in the | |
| 4406 result list. The order of elements in the result list is also | |
| 4407 undefined. | |
| 4408 @end defun | |
| 4409 | |
| 4410 @defun nunion list1 list2 @t{&key :test :test-not :key} | |
| 4411 This is a destructive version of @code{union}; rather than copying, | |
| 4412 it tries to reuse the storage of the argument lists if possible. | |
| 4413 @end defun | |
| 4414 | |
| 4415 @defun intersection list1 list2 @t{&key :test :test-not :key} | |
| 4416 This function computes the intersection of the sets represented | |
| 4417 by @var{list1} and @var{list2}. It returns the list of items | |
| 4418 which appear in both @var{list1} and @var{list2}. | |
| 4419 @end defun | |
| 4420 | |
| 4421 @defun nintersection list1 list2 @t{&key :test :test-not :key} | |
| 4422 This is a destructive version of @code{intersection}. It | |
| 4423 tries to reuse storage of @var{list1} rather than copying. | |
| 4424 It does @emph{not} reuse the storage of @var{list2}. | |
| 4425 @end defun | |
| 4426 | |
| 4427 @defun set-difference list1 list2 @t{&key :test :test-not :key} | |
| 4428 This function computes the ``set difference'' of @var{list1} | |
| 4429 and @var{list2}, i.e., the set of elements that appear in | |
| 4430 @var{list1} but @emph{not} in @var{list2}. | |
| 4431 @end defun | |
| 4432 | |
| 4433 @defun nset-difference list1 list2 @t{&key :test :test-not :key} | |
| 4434 This is a destructive @code{set-difference}, which will try | |
| 4435 to reuse @var{list1} if possible. | |
| 4436 @end defun | |
| 4437 | |
| 4438 @defun set-exclusive-or list1 list2 @t{&key :test :test-not :key} | |
| 4439 This function computes the ``set exclusive or'' of @var{list1} | |
| 4440 and @var{list2}, i.e., the set of elements that appear in | |
| 4441 exactly one of @var{list1} and @var{list2}. | |
| 4442 @end defun | |
| 4443 | |
| 4444 @defun nset-exclusive-or list1 list2 @t{&key :test :test-not :key} | |
| 4445 This is a destructive @code{set-exclusive-or}, which will try | |
| 4446 to reuse @var{list1} and @var{list2} if possible. | |
| 4447 @end defun | |
| 4448 | |
| 4449 @defun subsetp list1 list2 @t{&key :test :test-not :key} | |
| 4450 This function checks whether @var{list1} represents a subset | |
| 4451 of @var{list2}, i.e., whether every element of @var{list1} | |
| 4452 also appears in @var{list2}. | |
| 4453 @end defun | |
| 4454 | |
| 4455 @node Association Lists, , Lists as Sets, Lists | |
| 4456 @section Association Lists | |
| 4457 | |
| 4458 @noindent | |
| 4459 An @dfn{association list} is a list representing a mapping from | |
| 4460 one set of values to another; any list whose elements are cons | |
| 4461 cells is an association list. | |
| 4462 | |
| 4463 @defun assoc* item a-list @t{&key :test :test-not :key} | |
| 4464 This function searches the association list @var{a-list} for an | |
| 4465 element whose @code{car} matches (in the sense of @code{:test}, | |
| 4466 @code{:test-not}, and @code{:key}, or by comparison with @code{eql}) | |
| 4467 a given @var{item}. It returns the matching element, if any, | |
| 4468 otherwise @code{nil}. It ignores elements of @var{a-list} which | |
| 4469 are not cons cells. (This corresponds to the behavior of | |
| 4470 @code{assq} and @code{assoc} in Emacs Lisp; Common Lisp's | |
| 4471 @code{assoc} ignores @code{nil}s but considers any other non-cons | |
| 4472 elements of @var{a-list} to be an error.) | |
| 4473 @end defun | |
| 4474 | |
| 4475 @defun rassoc* item a-list @t{&key :test :test-not :key} | |
| 4476 This function searches for an element whose @code{cdr} matches | |
| 4477 @var{item}. If @var{a-list} represents a mapping, this applies | |
| 4478 the inverse of the mapping to @var{item}. | |
| 4479 @end defun | |
| 4480 | |
| 4481 @defun rassoc item a-list | |
| 4482 This function searches like @code{rassoc*} with a @code{:test} | |
| 4483 argument of @code{equal}. It is analogous to Emacs Lisp's | |
| 4484 standard @code{assoc} function, which derives from the MacLisp | |
| 4485 rather than the Common Lisp tradition. | |
| 4486 @end defun | |
| 4487 | |
| 4488 @findex assoc-if | |
| 4489 @findex assoc-if-not | |
| 4490 @findex rassoc-if | |
| 4491 @findex rassoc-if-not | |
| 4492 The @code{assoc-if}, @code{assoc-if-not}, @code{rassoc-if}, | |
| 4493 and @code{rassoc-if-not} functions are defined similarly. | |
| 4494 | |
| 4495 Two simple functions for constructing association lists are: | |
| 4496 | |
| 4497 @defun acons key value alist | |
| 4498 This is equivalent to @code{(cons (cons @var{key} @var{value}) @var{alist})}. | |
| 4499 @end defun | |
| 4500 | |
| 4501 @defun pairlis keys values &optional alist | |
| 4502 This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) | |
| 4503 @var{alist})}. | |
| 4504 @end defun | |
| 4505 | |
| 4506 @node Hash Tables, Structures, Lists, Top | |
| 4507 @chapter Hash Tables | |
| 4508 | |
| 4509 @noindent | |
| 4510 Hash tables are now implemented directly in the C code and documented in | |
| 446 | 4511 @ref{Hash Tables,,, lispref, XEmacs Lisp Reference Manual}. |
| 428 | 4512 |
| 4513 @ignore | |
| 4514 A @dfn{hash table} is a data structure that maps ``keys'' onto | |
| 4515 ``values.'' Keys and values can be arbitrary Lisp data objects. | |
| 4516 Hash tables have the property that the time to search for a given | |
| 4517 key is roughly constant; simpler data structures like association | |
| 4518 lists take time proportional to the number of entries in the list. | |
| 4519 | |
| 4520 @defun make-hash-table @t{&key :test :size} | |
| 4521 This function creates and returns a hash-table object whose | |
| 4522 function for comparing elements is @code{:test} (@code{eql} | |
| 4523 by default), and which is allocated to fit about @code{:size} | |
| 4524 elements. The @code{:size} argument is purely advisory; the | |
| 4525 table will stretch automatically if you store more elements in | |
| 4526 it. If @code{:size} is omitted, a reasonable default is used. | |
| 4527 | |
| 4528 Common Lisp allows only @code{eq}, @code{eql}, @code{equal}, | |
| 4529 and @code{equalp} as legal values for the @code{:test} argument. | |
| 4530 In this package, any reasonable predicate function will work, | |
| 4531 though if you use something else you should check the details of | |
| 4532 the hashing function described below to make sure it is suitable | |
| 4533 for your predicate. | |
| 4534 | |
| 4535 Some versions of Emacs (like XEmacs) include a built-in hash | |
| 4536 table type; in these versions, @code{make-hash-table} with a test of | |
| 4537 @code{eq}, @code{eql}, or @code{equal} will use these built-in hash | |
| 4538 tables. In all other cases, it will return a hash-table object which | |
| 4539 takes the form of a list with an identifying ``tag'' symbol at the | |
| 4540 front. All of the hash table functions in this package can operate on | |
| 4541 both types of hash table; normally you will never know which type is | |
| 4542 being used. | |
| 4543 | |
| 4544 This function accepts the additional Common Lisp keywords | |
| 4545 @code{:rehash-size} and @code{:rehash-threshold}, but it ignores | |
| 4546 their values. | |
| 4547 @end defun | |
| 4548 | |
| 4549 @defun gethash key table &optional default | |
| 4550 This function looks up @var{key} in @var{table}. If @var{key} | |
| 4551 exists in the table, in the sense that it matches any of the existing | |
| 4552 keys according to the table's test function, then the associated value | |
| 4553 is returned. Otherwise, @var{default} (or @code{nil}) is returned. | |
| 4554 | |
| 4555 To store new data in the hash table, use @code{setf} on a call to | |
| 4556 @code{gethash}. If @var{key} already exists in the table, the | |
| 4557 corresponding value is changed to the stored value. If @var{key} | |
| 4558 does not already exist, a new entry is added to the table and the | |
| 4559 table is reallocated to a larger size if necessary. The @var{default} | |
| 4560 argument is allowed but ignored in this case. The situation is | |
| 440 | 4561 exactly analogous to that of @code{get}; @pxref{Property Lists}. |
| 428 | 4562 @end defun |
| 4563 | |
| 4564 @defun remhash key table | |
| 4565 This function removes the entry for @var{key} from @var{table}. | |
| 4566 If an entry was removed, it returns @code{t}. If @var{key} does | |
| 4567 not appear in the table, it does nothing and returns @code{nil}. | |
| 4568 @end defun | |
| 4569 | |
| 4570 @defun clrhash table | |
| 4571 This function removes all the entries from @var{table}, leaving | |
| 4572 an empty hash table. | |
| 4573 @end defun | |
| 4574 | |
| 4575 @defun maphash function table | |
| 4576 This function calls @var{function} for each entry in @var{table}. | |
| 4577 It passes two arguments to @var{function}, the key and the value | |
| 4578 of the given entry. The return value of @var{function} is ignored; | |
| 4579 @var{maphash} itself returns @code{nil}. @xref{Loop Facility}, for | |
| 4580 an alternate way of iterating over hash tables. | |
| 4581 @end defun | |
| 4582 | |
| 4583 @defun hash-table-count table This function returns the number of | |
| 4584 entries in @var{table}. @strong{Warning:} The current implementation of | |
| 4585 XEmacs hash-tables does not decrement the stored @code{count} | |
| 4586 when @code{remhash} removes an entry. Therefore, the return value of | |
| 4587 this function is not dependable if you have used @code{remhash} on the | |
| 4588 table and the table's test is @code{eq}, @code{eql}, or @code{equal}. | |
| 4589 A slower, but reliable, way to count the entries is | |
| 4590 @code{(loop for x being the hash-keys of @var{table} count t)}. | |
| 4591 @end defun | |
| 4592 | |
| 4593 @defun hash-table-p object This function returns @code{t} if | |
| 4594 @var{object} is a hash table, @code{nil} otherwise. It recognizes both | |
| 4595 types of hash tables (both XEmacs built-in tables and tables implemented | |
| 4596 with special lists.) | |
| 4597 @end defun | |
| 4598 | |
| 4599 Sometimes when dealing with hash tables it is useful to know the | |
| 4600 exact ``hash function'' that is used. This package implements | |
| 4601 hash tables using Emacs Lisp ``obarrays,'' which are the same | |
| 4602 data structure that Emacs Lisp uses to keep track of symbols. | |
| 4603 Each hash table includes an embedded obarray. Key values given | |
| 4604 to @code{gethash} are converted by various means into strings, | |
| 4605 which are then looked up in the obarray using @code{intern} and | |
| 4606 @code{intern-soft}. The symbol, or ``bucket,'' corresponding to | |
| 4607 a given key string includes as its @code{symbol-value} an association | |
| 4608 list of all key-value pairs which hash to that string. Depending | |
| 4609 on the test function, it is possible for many entries to hash to | |
| 4610 the same bucket. For example, if the test is @code{eql}, then the | |
| 4611 symbol @code{foo} and two separately built strings @code{"foo"} will | |
| 4612 create three entries in the same bucket. Search time is linear | |
| 4613 within buckets, so hash tables will be most effective if you arrange | |
| 4614 not to store too many things that hash the same. | |
| 4615 | |
| 4616 The following algorithm is used to convert Lisp objects to hash | |
| 4617 strings: | |
| 4618 | |
| 4619 @itemize @bullet | |
| 4620 @item | |
| 4621 Strings are used directly as hash strings. (However, if the test | |
| 4622 function is @code{equalp}, strings are @code{downcase}d first.) | |
| 4623 | |
| 4624 @item | |
| 4625 Symbols are hashed according to their @code{symbol-name}. | |
| 4626 | |
| 4627 @item | |
| 4628 Integers are hashed into one of 16 buckets depending on their value | |
| 4629 modulo 16. Floating-point numbers are truncated to integers and | |
| 4630 hashed modulo 16. | |
| 4631 | |
| 4632 @item | |
| 4633 Cons cells are hashed according to their @code{car}s; nonempty vectors | |
| 4634 are hashed according to their first element. | |
| 4635 | |
| 4636 @item | |
| 4637 All other types of objects hash into a single bucket named @code{"*"}. | |
| 4638 @end itemize | |
| 4639 | |
| 4640 @noindent | |
| 4641 Thus, for example, searching among many buffer objects in a hash table | |
| 4642 will devolve to a (still fairly fast) linear-time search through a | |
| 4643 single bucket, whereas searching for different symbols will be very | |
| 4644 fast since each symbol will, in general, hash into its own bucket. | |
| 4645 | |
| 4646 The size of the obarray in a hash table is automatically adjusted | |
| 4647 as the number of elements increases. | |
| 4648 | |
| 4649 As a special case, @code{make-hash-table} with a @code{:size} argument | |
| 4650 of 0 or 1 will create a hash-table object that uses a single association | |
| 4651 list rather than an obarray of many lists. For very small tables this | |
| 4652 structure will be more efficient since lookup does not require | |
| 4653 converting the key to a string or looking it up in an obarray. | |
| 4654 However, such tables are guaranteed to take time proportional to | |
| 4655 their size to do a search. | |
| 4656 @end ignore | |
| 4657 | |
| 4658 @iftex | |
| 4659 @chapno=18 | |
| 4660 @end iftex | |
| 4661 | |
| 4662 @node Structures, Assertions, Hash Tables, Top | |
| 4663 @chapter Structures | |
| 4664 | |
| 4665 @noindent | |
| 4666 The Common Lisp @dfn{structure} mechanism provides a general way | |
| 4667 to define data types similar to C's @code{struct} types. A | |
| 4668 structure is a Lisp object containing some number of @dfn{slots}, | |
| 4669 each of which can hold any Lisp data object. Functions are | |
| 4670 provided for accessing and setting the slots, creating or copying | |
| 4671 structure objects, and recognizing objects of a particular structure | |
| 4672 type. | |
| 4673 | |
| 4674 In true Common Lisp, each structure type is a new type distinct | |
| 4675 from all existing Lisp types. Since the underlying Emacs Lisp | |
| 4676 system provides no way to create new distinct types, this package | |
| 4677 implements structures as vectors (or lists upon request) with a | |
| 4678 special ``tag'' symbol to identify them. | |
| 4679 | |
| 4680 @defspec defstruct name slots@dots{} | |
| 4681 The @code{defstruct} form defines a new structure type called | |
| 4682 @var{name}, with the specified @var{slots}. (The @var{slots} | |
| 4683 may begin with a string which documents the structure type.) | |
| 4684 In the simplest case, @var{name} and each of the @var{slots} | |
| 4685 are symbols. For example, | |
| 4686 | |
| 4687 @example | |
| 4688 (defstruct person name age sex) | |
| 4689 @end example | |
| 4690 | |
| 4691 @noindent | |
| 4692 defines a struct type called @code{person} which contains three | |
| 4693 slots. Given a @code{person} object @var{p}, you can access those | |
| 4694 slots by calling @code{(person-name @var{p})}, @code{(person-age @var{p})}, | |
| 4695 and @code{(person-sex @var{p})}. You can also change these slots by | |
| 4696 using @code{setf} on any of these place forms: | |
| 4697 | |
| 4698 @example | |
| 4699 (incf (person-age birthday-boy)) | |
| 4700 @end example | |
| 4701 | |
| 4702 You can create a new @code{person} by calling @code{make-person}, | |
| 4703 which takes keyword arguments @code{:name}, @code{:age}, and | |
| 4704 @code{:sex} to specify the initial values of these slots in the | |
| 4705 new object. (Omitting any of these arguments leaves the corresponding | |
| 4706 slot ``undefined,'' according to the Common Lisp standard; in Emacs | |
| 4707 Lisp, such uninitialized slots are filled with @code{nil}.) | |
| 4708 | |
| 4709 Given a @code{person}, @code{(copy-person @var{p})} makes a new | |
| 4710 object of the same type whose slots are @code{eq} to those of @var{p}. | |
| 4711 | |
| 4712 Given any Lisp object @var{x}, @code{(person-p @var{x})} returns | |
| 4713 true if @var{x} looks like a @code{person}, false otherwise. (Again, | |
| 4714 in Common Lisp this predicate would be exact; in Emacs Lisp the | |
| 4715 best it can do is verify that @var{x} is a vector of the correct | |
| 4716 length which starts with the correct tag symbol.) | |
| 4717 | |
| 4718 Accessors like @code{person-name} normally check their arguments | |
| 4719 (effectively using @code{person-p}) and signal an error if the | |
| 4720 argument is the wrong type. This check is affected by | |
| 4721 @code{(optimize (safety @dots{}))} declarations. Safety level 1, | |
| 4722 the default, uses a somewhat optimized check that will detect all | |
| 4723 incorrect arguments, but may use an uninformative error message | |
| 4724 (e.g., ``expected a vector'' instead of ``expected a @code{person}''). | |
| 4725 Safety level 0 omits all checks except as provided by the underlying | |
| 4726 @code{aref} call; safety levels 2 and 3 do rigorous checking that will | |
| 4727 always print a descriptive error message for incorrect inputs. | |
| 4728 @xref{Declarations}. | |
| 4729 | |
| 4730 @example | |
| 4731 (setq dave (make-person :name "Dave" :sex 'male)) | |
| 4732 @result{} [cl-struct-person "Dave" nil male] | |
| 4733 (setq other (copy-person dave)) | |
| 4734 @result{} [cl-struct-person "Dave" nil male] | |
| 4735 (eq dave other) | |
| 4736 @result{} nil | |
| 4737 (eq (person-name dave) (person-name other)) | |
| 4738 @result{} t | |
| 4739 (person-p dave) | |
| 4740 @result{} t | |
| 4741 (person-p [1 2 3 4]) | |
| 4742 @result{} nil | |
| 4743 (person-p "Bogus") | |
| 4744 @result{} nil | |
| 4745 (person-p '[cl-struct-person counterfeit person object]) | |
| 4746 @result{} t | |
| 4747 @end example | |
| 4748 | |
| 4749 In general, @var{name} is either a name symbol or a list of a name | |
| 4750 symbol followed by any number of @dfn{struct options}; each @var{slot} | |
| 4751 is either a slot symbol or a list of the form @samp{(@var{slot-name} | |
| 4752 @var{default-value} @var{slot-options}@dots{})}. The @var{default-value} | |
| 4753 is a Lisp form which is evaluated any time an instance of the | |
| 4754 structure type is created without specifying that slot's value. | |
| 4755 | |
| 4756 Common Lisp defines several slot options, but the only one | |
| 4757 implemented in this package is @code{:read-only}. A non-@code{nil} | |
| 4758 value for this option means the slot should not be @code{setf}-able; | |
| 4759 the slot's value is determined when the object is created and does | |
| 4760 not change afterward. | |
| 4761 | |
| 4762 @example | |
| 4763 (defstruct person | |
| 4764 (name nil :read-only t) | |
| 4765 age | |
| 4766 (sex 'unknown)) | |
| 4767 @end example | |
| 4768 | |
| 4769 Any slot options other than @code{:read-only} are ignored. | |
| 4770 | |
| 4771 For obscure historical reasons, structure options take a different | |
| 4772 form than slot options. A structure option is either a keyword | |
| 4773 symbol, or a list beginning with a keyword symbol possibly followed | |
| 4774 by arguments. (By contrast, slot options are key-value pairs not | |
| 4775 enclosed in lists.) | |
| 4776 | |
| 4777 @example | |
| 4778 (defstruct (person (:constructor create-person) | |
| 4779 (:type list) | |
| 4780 :named) | |
| 4781 name age sex) | |
| 4782 @end example | |
| 4783 | |
| 4784 The following structure options are recognized. | |
| 4785 | |
| 4786 @table @code | |
| 4787 @iftex | |
| 4788 @itemmax=0 in | |
| 4789 @advance@leftskip-.5@tableindent | |
| 4790 @end iftex | |
| 4791 @item :conc-name | |
| 4792 The argument is a symbol whose print name is used as the prefix for | |
| 4793 the names of slot accessor functions. The default is the name of | |
| 4794 the struct type followed by a hyphen. The option @code{(:conc-name p-)} | |
| 4795 would change this prefix to @code{p-}. Specifying @code{nil} as an | |
| 4796 argument means no prefix, so that the slot names themselves are used | |
| 4797 to name the accessor functions. | |
| 4798 | |
| 4799 @item :constructor | |
| 4800 In the simple case, this option takes one argument which is an | |
| 4801 alternate name to use for the constructor function. The default | |
| 4802 is @code{make-@var{name}}, e.g., @code{make-person}. The above | |
| 4803 example changes this to @code{create-person}. Specifying @code{nil} | |
| 4804 as an argument means that no standard constructor should be | |
| 4805 generated at all. | |
| 4806 | |
| 4807 In the full form of this option, the constructor name is followed | |
| 4808 by an arbitrary argument list. @xref{Program Structure}, for a | |
| 4809 description of the format of Common Lisp argument lists. All | |
| 4810 options, such as @code{&rest} and @code{&key}, are supported. | |
| 4811 The argument names should match the slot names; each slot is | |
| 4812 initialized from the corresponding argument. Slots whose names | |
| 4813 do not appear in the argument list are initialized based on the | |
| 4814 @var{default-value} in their slot descriptor. Also, @code{&optional} | |
| 4815 and @code{&key} arguments which don't specify defaults take their | |
| 4816 defaults from the slot descriptor. It is legal to include arguments | |
| 4817 which don't correspond to slot names; these are useful if they are | |
| 4818 referred to in the defaults for optional, keyword, or @code{&aux} | |
| 4819 arguments which @emph{do} correspond to slots. | |
| 4820 | |
| 4821 You can specify any number of full-format @code{:constructor} | |
| 4822 options on a structure. The default constructor is still generated | |
| 4823 as well unless you disable it with a simple-format @code{:constructor} | |
| 4824 option. | |
| 4825 | |
| 4826 @example | |
| 4827 (defstruct | |
| 4828 (person | |
| 4829 (:constructor nil) ; no default constructor | |
| 4830 (:constructor new-person (name sex &optional (age 0))) | |
| 4831 (:constructor new-hound (&key (name "Rover") | |
| 4832 (dog-years 0) | |
| 4833 &aux (age (* 7 dog-years)) | |
| 4834 (sex 'canine)))) | |
| 4835 name age sex) | |
| 4836 @end example | |
| 4837 | |
| 4838 The first constructor here takes its arguments positionally rather | |
| 4839 than by keyword. (In official Common Lisp terminology, constructors | |
| 4840 that work By Order of Arguments instead of by keyword are called | |
| 4841 ``BOA constructors.'' No, I'm not making this up.) For example, | |
| 4842 @code{(new-person "Jane" 'female)} generates a person whose slots | |
| 4843 are @code{"Jane"}, 0, and @code{female}, respectively. | |
| 4844 | |
| 4845 The second constructor takes two keyword arguments, @code{:name}, | |
| 4846 which initializes the @code{name} slot and defaults to @code{"Rover"}, | |
| 4847 and @code{:dog-years}, which does not itself correspond to a slot | |
| 4848 but which is used to initialize the @code{age} slot. The @code{sex} | |
| 4849 slot is forced to the symbol @code{canine} with no syntax for | |
| 4850 overriding it. | |
| 4851 | |
| 4852 @item :copier | |
| 4853 The argument is an alternate name for the copier function for | |
| 4854 this type. The default is @code{copy-@var{name}}. @code{nil} | |
| 4855 means not to generate a copier function. (In this implementation, | |
| 4856 all copier functions are simply synonyms for @code{copy-sequence}.) | |
| 4857 | |
| 4858 @item :predicate | |
| 4859 The argument is an alternate name for the predicate which recognizes | |
| 4860 objects of this type. The default is @code{@var{name}-p}. @code{nil} | |
| 4861 means not to generate a predicate function. (If the @code{:type} | |
| 4862 option is used without the @code{:named} option, no predicate is | |
| 4863 ever generated.) | |
| 4864 | |
| 4865 In true Common Lisp, @code{typep} is always able to recognize a | |
| 4866 structure object even if @code{:predicate} was used. In this | |
| 4867 package, @code{typep} simply looks for a function called | |
| 4868 @code{@var{typename}-p}, so it will work for structure types | |
| 4869 only if they used the default predicate name. | |
| 4870 | |
| 4871 @item :include | |
| 4872 This option implements a very limited form of C++-style inheritance. | |
| 4873 The argument is the name of another structure type previously | |
| 4874 created with @code{defstruct}. The effect is to cause the new | |
| 4875 structure type to inherit all of the included structure's slots | |
| 4876 (plus, of course, any new slots described by this struct's slot | |
| 4877 descriptors). The new structure is considered a ``specialization'' | |
| 4878 of the included one. In fact, the predicate and slot accessors | |
| 4879 for the included type will also accept objects of the new type. | |
| 4880 | |
| 4881 If there are extra arguments to the @code{:include} option after | |
| 4882 the included-structure name, these options are treated as replacement | |
| 4883 slot descriptors for slots in the included structure, possibly with | |
| 4884 modified default values. Borrowing an example from Steele: | |
| 4885 | |
| 4886 @example | |
| 4887 (defstruct person name (age 0) sex) | |
| 4888 @result{} person | |
| 4889 (defstruct (astronaut (:include person (age 45))) | |
| 4890 helmet-size | |
| 4891 (favorite-beverage 'tang)) | |
| 4892 @result{} astronaut | |
| 4893 | |
| 4894 (setq joe (make-person :name "Joe")) | |
| 4895 @result{} [cl-struct-person "Joe" 0 nil] | |
| 4896 (setq buzz (make-astronaut :name "Buzz")) | |
| 4897 @result{} [cl-struct-astronaut "Buzz" 45 nil nil tang] | |
| 4898 | |
| 4899 (list (person-p joe) (person-p buzz)) | |
| 4900 @result{} (t t) | |
| 4901 (list (astronaut-p joe) (astronaut-p buzz)) | |
| 4902 @result{} (nil t) | |
| 4903 | |
| 4904 (person-name buzz) | |
| 4905 @result{} "Buzz" | |
| 4906 (astronaut-name joe) | |
| 4907 @result{} error: "astronaut-name accessing a non-astronaut" | |
| 4908 @end example | |
| 4909 | |
| 4910 Thus, if @code{astronaut} is a specialization of @code{person}, | |
| 4911 then every @code{astronaut} is also a @code{person} (but not the | |
| 4912 other way around). Every @code{astronaut} includes all the slots | |
| 4913 of a @code{person}, plus extra slots that are specific to | |
| 4914 astronauts. Operations that work on people (like @code{person-name}) | |
| 4915 work on astronauts just like other people. | |
| 4916 | |
| 4917 @item :print-function | |
| 4918 In full Common Lisp, this option allows you to specify a function | |
| 4919 which is called to print an instance of the structure type. The | |
| 4920 Emacs Lisp system offers no hooks into the Lisp printer which would | |
| 4921 allow for such a feature, so this package simply ignores | |
| 4922 @code{:print-function}. | |
| 4923 | |
| 4924 @item :type | |
| 4925 The argument should be one of the symbols @code{vector} or @code{list}. | |
| 4926 This tells which underlying Lisp data type should be used to implement | |
| 4927 the new structure type. Vectors are used by default, but | |
| 4928 @code{(:type list)} will cause structure objects to be stored as | |
| 4929 lists instead. | |
| 4930 | |
| 4931 The vector representation for structure objects has the advantage | |
| 4932 that all structure slots can be accessed quickly, although creating | |
| 4933 vectors is a bit slower in Emacs Lisp. Lists are easier to create, | |
| 4934 but take a relatively long time accessing the later slots. | |
| 4935 | |
| 4936 @item :named | |
| 4937 This option, which takes no arguments, causes a characteristic ``tag'' | |
| 4938 symbol to be stored at the front of the structure object. Using | |
| 4939 @code{:type} without also using @code{:named} will result in a | |
| 4940 structure type stored as plain vectors or lists with no identifying | |
| 4941 features. | |
| 4942 | |
| 4943 The default, if you don't specify @code{:type} explicitly, is to | |
| 4944 use named vectors. Therefore, @code{:named} is only useful in | |
| 4945 conjunction with @code{:type}. | |
| 4946 | |
| 4947 @example | |
| 4948 (defstruct (person1) name age sex) | |
| 4949 (defstruct (person2 (:type list) :named) name age sex) | |
| 4950 (defstruct (person3 (:type list)) name age sex) | |
| 4951 | |
| 4952 (setq p1 (make-person1)) | |
| 4953 @result{} [cl-struct-person1 nil nil nil] | |
| 4954 (setq p2 (make-person2)) | |
| 4955 @result{} (person2 nil nil nil) | |
| 4956 (setq p3 (make-person3)) | |
| 4957 @result{} (nil nil nil) | |
| 4958 | |
| 4959 (person1-p p1) | |
| 4960 @result{} t | |
| 4961 (person2-p p2) | |
| 4962 @result{} t | |
| 4963 (person3-p p3) | |
| 4964 @result{} error: function person3-p undefined | |
| 4965 @end example | |
| 4966 | |
| 4967 Since unnamed structures don't have tags, @code{defstruct} is not | |
| 4968 able to make a useful predicate for recognizing them. Also, | |
| 4969 accessors like @code{person3-name} will be generated but they | |
| 4970 will not be able to do any type checking. The @code{person3-name} | |
| 4971 function, for example, will simply be a synonym for @code{car} in | |
| 4972 this case. By contrast, @code{person2-name} is able to verify | |
| 4973 that its argument is indeed a @code{person2} object before | |
| 4974 proceeding. | |
| 4975 | |
| 4976 @item :initial-offset | |
| 4977 The argument must be a nonnegative integer. It specifies a | |
| 4978 number of slots to be left ``empty'' at the front of the | |
| 4979 structure. If the structure is named, the tag appears at the | |
| 4980 specified position in the list or vector; otherwise, the first | |
| 4981 slot appears at that position. Earlier positions are filled | |
| 4982 with @code{nil} by the constructors and ignored otherwise. If | |
| 4983 the type @code{:include}s another type, then @code{:initial-offset} | |
| 4984 specifies a number of slots to be skipped between the last slot | |
| 4985 of the included type and the first new slot. | |
| 4986 @end table | |
| 4987 @end defspec | |
| 4988 | |
| 4989 Except as noted, the @code{defstruct} facility of this package is | |
| 4990 entirely compatible with that of Common Lisp. | |
| 4991 | |
| 4992 @iftex | |
| 4993 @chapno=23 | |
| 4994 @end iftex | |
| 4995 | |
| 4996 @node Assertions, Efficiency Concerns, Structures, Top | |
| 4997 @chapter Assertions and Errors | |
| 4998 | |
| 4999 @noindent | |
| 5000 This section describes two macros that test @dfn{assertions}, i.e., | |
| 5001 conditions which must be true if the program is operating correctly. | |
| 5002 Assertions never add to the behavior of a Lisp program; they simply | |
| 5003 make ``sanity checks'' to make sure everything is as it should be. | |
| 5004 | |
| 5005 If the optimization property @code{speed} has been set to 3, and | |
| 5006 @code{safety} is less than 3, then the byte-compiler will optimize | |
| 5007 away the following assertions. Because assertions might be optimized | |
| 5008 away, it is a bad idea for them to include side-effects. | |
| 5009 | |
| 5010 @defspec assert test-form [show-args string args@dots{}] | |
| 5011 This form verifies that @var{test-form} is true (i.e., evaluates to | |
| 5012 a non-@code{nil} value). If so, it returns @code{nil}. If the test | |
| 5013 is not satisfied, @code{assert} signals an error. | |
| 5014 | |
| 5015 A default error message will be supplied which includes @var{test-form}. | |
| 5016 You can specify a different error message by including a @var{string} | |
| 5017 argument plus optional extra arguments. Those arguments are simply | |
| 5018 passed to @code{error} to signal the error. | |
| 5019 | |
| 5020 If the optional second argument @var{show-args} is @code{t} instead | |
| 5021 of @code{nil}, then the error message (with or without @var{string}) | |
| 5022 will also include all non-constant arguments of the top-level | |
| 5023 @var{form}. For example: | |
| 5024 | |
| 5025 @example | |
| 5026 (assert (> x 10) t "x is too small: %d") | |
| 5027 @end example | |
| 5028 | |
| 446 | 5029 This usage of @var{show-args} is a change to Common Lisp. In |
| 428 | 5030 true Common Lisp, the second argument gives a list of @var{places} |
| 5031 which can be @code{setf}'d by the user before continuing from the | |
| 446 | 5032 error. |
| 428 | 5033 @end defspec |
| 5034 | |
| 446 | 5035 @defspec check-type place type &optional string |
| 5036 This form verifies that @var{place} evaluates to a value of type | |
| 428 | 5037 @var{type}. If so, it returns @code{nil}. If not, @code{check-type} |
| 446 | 5038 signals a continuable @code{wrong-type-argument} error. The default |
| 5039 error message lists the erroneous value along with @var{type} and | |
| 5040 @var{place} themselves. If @var{string} is specified, it is included in | |
| 5041 the error message in place of @var{type}. For example: | |
| 428 | 5042 |
| 5043 @example | |
| 5044 (check-type x (integer 1 *) "a positive integer") | |
| 5045 @end example | |
| 5046 | |
| 5047 @xref{Type Predicates}, for a description of the type specifiers | |
| 5048 that may be used for @var{type}. | |
| 5049 | |
| 446 | 5050 Note that as in Common Lisp, the first argument to @code{check-type} |
| 5051 should be a @var{place} suitable for use by @code{setf}, because | |
| 5052 @code{check-type} signals a continuable error that allows the user to | |
| 5053 modify @var{place}, most simply by returning a value from the debugger. | |
| 428 | 5054 @end defspec |
| 5055 | |
| 5056 The following error-related macro is also defined: | |
| 5057 | |
| 5058 @defspec ignore-errors forms@dots{} | |
| 5059 This executes @var{forms} exactly like a @code{progn}, except that | |
| 5060 errors are ignored during the @var{forms}. More precisely, if | |
| 5061 an error is signalled then @code{ignore-errors} immediately | |
| 5062 aborts execution of the @var{forms} and returns @code{nil}. | |
| 5063 If the @var{forms} complete successfully, @code{ignore-errors} | |
| 5064 returns the result of the last @var{form}. | |
| 5065 @end defspec | |
| 5066 | |
| 5067 @node Efficiency Concerns, Common Lisp Compatibility, Assertions, Top | |
| 5068 @appendix Efficiency Concerns | |
| 5069 | |
| 5070 @appendixsec Macros | |
| 5071 | |
| 5072 @noindent | |
| 5073 Many of the advanced features of this package, such as @code{defun*}, | |
| 5074 @code{loop}, and @code{setf}, are implemented as Lisp macros. In | |
| 5075 byte-compiled code, these complex notations will be expanded into | |
| 5076 equivalent Lisp code which is simple and efficient. For example, | |
| 5077 the forms | |
| 5078 | |
| 5079 @example | |
| 5080 (incf i n) | |
| 5081 (push x (car p)) | |
| 5082 @end example | |
| 5083 | |
| 5084 @noindent | |
| 5085 are expanded at compile-time to the Lisp forms | |
| 5086 | |
| 5087 @example | |
| 5088 (setq i (+ i n)) | |
| 5089 (setcar p (cons x (car p))) | |
| 5090 @end example | |
| 5091 | |
| 5092 @noindent | |
| 5093 which are the most efficient ways of doing these respective operations | |
| 5094 in Lisp. Thus, there is no performance penalty for using the more | |
| 5095 readable @code{incf} and @code{push} forms in your compiled code. | |
| 5096 | |
| 5097 @emph{Interpreted} code, on the other hand, must expand these macros | |
| 5098 every time they are executed. For this reason it is strongly | |
| 5099 recommended that code making heavy use of macros be compiled. | |
| 5100 (The features labelled ``Special Form'' instead of ``Function'' in | |
| 5101 this manual are macros.) A loop using @code{incf} a hundred times | |
| 5102 will execute considerably faster if compiled, and will also | |
| 5103 garbage-collect less because the macro expansion will not have | |
| 5104 to be generated, used, and thrown away a hundred times. | |
| 5105 | |
| 5106 You can find out how a macro expands by using the | |
| 5107 @code{cl-prettyexpand} function. | |
| 5108 | |
| 5109 @defun cl-prettyexpand form &optional full | |
| 5110 This function takes a single Lisp form as an argument and inserts | |
| 5111 a nicely formatted copy of it in the current buffer (which must be | |
| 5112 in Lisp mode so that indentation works properly). It also expands | |
| 5113 all Lisp macros which appear in the form. The easiest way to use | |
| 5114 this function is to go to the @code{*scratch*} buffer and type, say, | |
| 5115 | |
| 5116 @example | |
| 5117 (cl-prettyexpand '(loop for x below 10 collect x)) | |
| 5118 @end example | |
| 5119 | |
| 5120 @noindent | |
| 5121 and type @kbd{C-x C-e} immediately after the closing parenthesis; | |
| 5122 the expansion | |
| 5123 | |
| 5124 @example | |
| 5125 (block nil | |
| 5126 (let* ((x 0) | |
| 5127 (G1004 nil)) | |
| 5128 (while (< x 10) | |
| 5129 (setq G1004 (cons x G1004)) | |
| 5130 (setq x (+ x 1))) | |
| 5131 (nreverse G1004))) | |
| 5132 @end example | |
| 5133 | |
| 5134 @noindent | |
| 5135 will be inserted into the buffer. (The @code{block} macro is | |
| 5136 expanded differently in the interpreter and compiler, so | |
| 5137 @code{cl-prettyexpand} just leaves it alone. The temporary | |
| 5138 variable @code{G1004} was created by @code{gensym}.) | |
| 5139 | |
| 5140 If the optional argument @var{full} is true, then @emph{all} | |
| 5141 macros are expanded, including @code{block}, @code{eval-when}, | |
| 5142 and compiler macros. Expansion is done as if @var{form} were | |
| 5143 a top-level form in a file being compiled. For example, | |
| 5144 | |
| 5145 @example | |
| 5146 (cl-prettyexpand '(pushnew 'x list)) | |
| 5147 @print{} (setq list (adjoin 'x list)) | |
| 5148 (cl-prettyexpand '(pushnew 'x list) t) | |
| 5149 @print{} (setq list (if (memq 'x list) list (cons 'x list))) | |
| 5150 (cl-prettyexpand '(caddr (member* 'a list)) t) | |
| 5151 @print{} (car (cdr (cdr (memq 'a list)))) | |
| 5152 @end example | |
| 5153 | |
| 5154 Note that @code{adjoin}, @code{caddr}, and @code{member*} all | |
| 5155 have built-in compiler macros to optimize them in common cases. | |
| 5156 @end defun | |
| 5157 | |
| 5158 @ifinfo | |
| 5159 @example | |
| 5160 | |
| 5161 @end example | |
| 5162 @end ifinfo | |
| 5163 @appendixsec Error Checking | |
| 5164 | |
| 5165 @noindent | |
| 5166 Common Lisp compliance has in general not been sacrificed for the | |
| 5167 sake of efficiency. A few exceptions have been made for cases | |
| 5168 where substantial gains were possible at the expense of marginal | |
| 5169 incompatibility. One example is the use of @code{memq} (which is | |
| 5170 treated very efficiently by the byte-compiler) to scan for keyword | |
| 5171 arguments; this can become confused in rare cases when keyword | |
| 5172 symbols are used as both keywords and data values at once. This | |
| 5173 is extremely unlikely to occur in practical code, and the use of | |
| 5174 @code{memq} allows functions with keyword arguments to be nearly | |
| 5175 as fast as functions that use @code{&optional} arguments. | |
| 5176 | |
| 5177 The Common Lisp standard (as embodied in Steele's book) uses the | |
| 5178 phrase ``it is an error if'' to indicate a situation which is not | |
| 5179 supposed to arise in complying programs; implementations are strongly | |
| 5180 encouraged but not required to signal an error in these situations. | |
| 5181 This package sometimes omits such error checking in the interest of | |
| 5182 compactness and efficiency. For example, @code{do} variable | |
| 5183 specifiers are supposed to be lists of one, two, or three forms; | |
| 5184 extra forms are ignored by this package rather than signalling a | |
| 5185 syntax error. The @code{endp} function is simply a synonym for | |
| 5186 @code{null} in this package. Functions taking keyword arguments | |
| 5187 will accept an odd number of arguments, treating the trailing | |
| 5188 keyword as if it were followed by the value @code{nil}. | |
| 5189 | |
| 5190 Argument lists (as processed by @code{defun*} and friends) | |
| 5191 @emph{are} checked rigorously except for the minor point just | |
| 5192 mentioned; in particular, keyword arguments are checked for | |
| 5193 validity, and @code{&allow-other-keys} and @code{:allow-other-keys} | |
| 5194 are fully implemented. Keyword validity checking is slightly | |
| 5195 time consuming (though not too bad in byte-compiled code); | |
| 5196 you can use @code{&allow-other-keys} to omit this check. Functions | |
| 5197 defined in this package such as @code{find} and @code{member*} | |
| 5198 do check their keyword arguments for validity. | |
| 5199 | |
| 5200 @ifinfo | |
| 5201 @example | |
| 5202 | |
| 5203 @end example | |
| 5204 @end ifinfo | |
| 5205 @appendixsec Optimizing Compiler | |
| 5206 | |
| 5207 @noindent | |
| 5208 The byte-compiler that comes with Emacs 18 normally fails to expand | |
| 5209 macros that appear in top-level positions in the file (i.e., outside | |
| 5210 of @code{defun}s or other enclosing forms). This would have | |
| 5211 disastrous consequences to programs that used such top-level macros | |
| 5212 as @code{defun*}, @code{eval-when}, and @code{defstruct}. To | |
| 5213 work around this problem, the @dfn{CL} package patches the Emacs | |
| 5214 18 compiler to expand top-level macros. This patch will apply to | |
| 5215 your own macros, too, if they are used in a top-level context. | |
| 5216 The patch will not harm versions of the Emacs 18 compiler which | |
| 5217 have already had a similar patch applied, nor will it affect the | |
| 5218 optimizing Emacs 19 byte-compiler written by Jamie Zawinski and | |
| 5219 Hallvard Furuseth. The patch is applied to the byte compiler's | |
| 5220 code in Emacs' memory, @emph{not} to the @file{bytecomp.elc} file | |
| 5221 stored on disk. | |
| 5222 | |
| 5223 The Emacs 19 compiler (for Emacs 18) is available from various | |
| 5224 Emacs Lisp archive sites such as @code{archive.cis.ohio-state.edu}. | |
| 5225 Its use is highly recommended; many of the Common Lisp macros emit | |
| 5226 code which can be improved by optimization. In particular, | |
| 5227 @code{block}s (whether explicit or implicit in constructs like | |
| 5228 @code{defun*} and @code{loop}) carry a fair run-time penalty; the | |
| 5229 optimizing compiler removes @code{block}s which are not actually | |
| 5230 referenced by @code{return} or @code{return-from} inside the block. | |
| 5231 | |
| 5232 @node Common Lisp Compatibility, Old CL Compatibility, Efficiency Concerns, Top | |
| 5233 @appendix Common Lisp Compatibility | |
| 5234 | |
| 5235 @noindent | |
| 5236 Following is a list of all known incompatibilities between this | |
| 5237 package and Common Lisp as documented in Steele (2nd edition). | |
| 5238 | |
| 5239 Certain function names, such as @code{member}, @code{assoc}, and | |
| 5240 @code{floor}, were already taken by (incompatible) Emacs Lisp | |
| 5241 functions; this package appends @samp{*} to the names of its | |
| 5242 Common Lisp versions of these functions. | |
| 5243 | |
| 5244 The word @code{defun*} is required instead of @code{defun} in order | |
| 5245 to use extended Common Lisp argument lists in a function. Likewise, | |
| 5246 @code{defmacro*} and @code{function*} are versions of those forms | |
| 5247 which understand full-featured argument lists. The @code{&whole} | |
| 5248 keyword does not work in @code{defmacro} argument lists (except | |
| 5249 inside recursive argument lists). | |
| 5250 | |
| 5251 In order to allow an efficient implementation, keyword arguments use | |
| 5252 a slightly cheesy parser which may be confused if a keyword symbol | |
| 5253 is passed as the @emph{value} of another keyword argument. | |
| 5254 (Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})} | |
| 5255 is used to scan for @code{:@var{keyword}} among the supplied | |
| 5256 keyword arguments.) | |
| 5257 | |
| 5258 The @code{eql} and @code{equal} predicates do not distinguish | |
| 5259 between IEEE floating-point plus and minus zero. The @code{equalp} | |
| 5260 predicate has several differences with Common Lisp; @pxref{Predicates}. | |
| 5261 | |
| 5262 The @code{setf} mechanism is entirely compatible, except that | |
| 5263 setf-methods return a list of five values rather than five | |
| 5264 values directly. Also, the new ``@code{setf} function'' concept | |
| 5265 (typified by @code{(defun (setf foo) @dots{})}) is not implemented. | |
| 5266 | |
| 5267 The @code{do-all-symbols} form is the same as @code{do-symbols} | |
| 5268 with no @var{obarray} argument. In Common Lisp, this form would | |
| 5269 iterate over all symbols in all packages. Since Emacs obarrays | |
| 5270 are not a first-class package mechanism, there is no way for | |
| 5271 @code{do-all-symbols} to locate any but the default obarray. | |
| 5272 | |
| 5273 The @code{loop} macro is complete except that @code{loop-finish} | |
| 5274 and type specifiers are unimplemented. | |
| 5275 | |
| 5276 Many Common Lisp declarations are ignored, and others match | |
| 5277 the Common Lisp standard in concept but not in detail. For | |
| 5278 example, local @code{special} declarations, which are purely | |
| 5279 advisory in Emacs Lisp, do not rigorously obey the scoping rules | |
| 5280 set down in Steele's book. | |
| 5281 | |
| 5282 The variable @code{*gensym-counter*} starts out with a pseudo-random | |
| 5283 value rather than with zero. This is to cope with the fact that | |
| 5284 generated symbols become interned when they are written to and | |
| 5285 loaded back from a file. | |
| 5286 | |
| 5287 The @code{defstruct} facility is compatible, except that structures | |
| 5288 are of type @code{:type vector :named} by default rather than some | |
| 5289 special, distinct type. Also, the @code{:type} slot option is ignored. | |
| 5290 | |
| 5291 The second argument of @code{check-type} is treated differently. | |
| 5292 | |
| 5293 @node Old CL Compatibility, Porting Common Lisp, Common Lisp Compatibility, Top | |
| 5294 @appendix Old CL Compatibility | |
| 5295 | |
| 5296 @noindent | |
| 5297 Following is a list of all known incompatibilities between this package | |
| 5298 and the older Quiroz @file{cl.el} package. | |
| 5299 | |
| 5300 The @code{defkeyword} form and @code{keywordp} function are not | |
| 5301 implemented in this package. | |
| 5302 | |
| 5303 The @code{member}, @code{floor}, @code{ceiling}, @code{truncate}, | |
| 5304 @code{round}, @code{mod}, and @code{rem} functions are suffixed | |
| 5305 by @samp{*} in this package to avoid collision with existing | |
| 5306 functions in Emacs 18 or Emacs 19. The older package simply | |
| 5307 redefined these functions, overwriting the built-in meanings and | |
| 5308 causing serious portability problems with Emacs 19. (Some more | |
| 5309 recent versions of the Quiroz package changed the names to | |
| 5310 @code{cl-member}, etc.; this package defines the latter names as | |
| 5311 aliases for @code{member*}, etc.) | |
| 5312 | |
| 5313 Certain functions in the old package which were buggy or inconsistent | |
| 5314 with the Common Lisp standard are incompatible with the conforming | |
| 5315 versions in this package. For example, @code{eql} and @code{member} | |
| 5316 were synonyms for @code{eq} and @code{memq} in that package, @code{setf} | |
| 5317 failed to preserve correct order of evaluation of its arguments, etc. | |
| 5318 | |
| 5319 Finally, unlike the older package, this package is careful to | |
| 5320 prefix all of its internal names with @code{cl-}. Except for a | |
| 5321 few functions which are explicitly defined as additional features | |
| 5322 (such as @code{floatp-safe} and @code{letf}), this package does not | |
| 5323 export any non-@samp{cl-} symbols which are not also part of Common | |
| 5324 Lisp. | |
| 5325 | |
| 5326 @ifinfo | |
| 5327 @example | |
| 5328 | |
| 5329 @end example | |
| 5330 @end ifinfo | |
| 5331 @appendixsec The @code{cl-compat} package | |
| 5332 | |
| 5333 @noindent | |
| 5334 The @dfn{CL} package includes emulations of some features of the | |
| 5335 old @file{cl.el}, in the form of a compatibility package | |
| 5336 @code{cl-compat}. To use it, put @code{(require 'cl-compat)} in | |
| 5337 your program. | |
| 5338 | |
| 5339 The old package defined a number of internal routines without | |
| 5340 @code{cl-} prefixes or other annotations. Call to these routines | |
| 5341 may have crept into existing Lisp code. @code{cl-compat} | |
| 5342 provides emulations of the following internal routines: | |
| 5343 @code{pair-with-newsyms}, @code{zip-lists}, @code{unzip-lists}, | |
| 5344 @code{reassemble-arglists}, @code{duplicate-symbols-p}, | |
| 5345 @code{safe-idiv}. | |
| 5346 | |
| 5347 Some @code{setf} forms translated into calls to internal | |
| 5348 functions that user code might call directly. The functions | |
| 5349 @code{setnth}, @code{setnthcdr}, and @code{setelt} fall in | |
| 5350 this category; they are defined by @code{cl-compat}, but the | |
| 5351 best fix is to change to use @code{setf} properly. | |
| 5352 | |
| 5353 The @code{cl-compat} file defines the keyword functions | |
| 5354 @code{keywordp}, @code{keyword-of}, and @code{defkeyword}, | |
| 5355 which are not defined by the new @dfn{CL} package because the | |
| 5356 use of keywords as data is discouraged. | |
| 5357 | |
| 5358 The @code{build-klist} mechanism for parsing keyword arguments | |
| 5359 is emulated by @code{cl-compat}; the @code{with-keyword-args} | |
| 5360 macro is not, however, and in any case it's best to change to | |
| 5361 use the more natural keyword argument processing offered by | |
| 5362 @code{defun*}. | |
| 5363 | |
| 5364 The functions @code{cl-floor}, @code{cl-ceiling}, @code{cl-truncate}, | |
| 5365 and @code{cl-round} are defined by @code{cl-compat} to use the | |
| 5366 old-style multiple-value mechanism, just as they did in the old | |
| 5367 package. The newer @code{floor*} and friends return their two | |
| 5368 results in a list rather than as multiple values. Note that | |
| 5369 older versions of the old package used the unadorned names | |
| 5370 @code{floor}, @code{ceiling}, etc.; @code{cl-compat} cannot use | |
| 5371 these names because they conflict with Emacs 19 built-ins. | |
| 5372 | |
| 5373 @node Porting Common Lisp, Function Index, Old CL Compatibility, Top | |
| 5374 @appendix Porting Common Lisp | |
| 5375 | |
| 5376 @noindent | |
| 5377 This package is meant to be used as an extension to Emacs Lisp, | |
| 5378 not as an Emacs implementation of true Common Lisp. Some of the | |
| 5379 remaining differences between Emacs Lisp and Common Lisp make it | |
| 5380 difficult to port large Common Lisp applications to Emacs. For | |
| 5381 one, some of the features in this package are not fully compliant | |
| 5382 with ANSI or Steele; @pxref{Common Lisp Compatibility}. But there | |
| 5383 are also quite a few features that this package does not provide | |
| 5384 at all. Here are some major omissions that you will want watch out | |
| 5385 for when bringing Common Lisp code into Emacs. | |
| 5386 | |
| 5387 @itemize @bullet | |
| 5388 @item | |
| 5389 Case-insensitivity. Symbols in Common Lisp are case-insensitive | |
| 5390 by default. Some programs refer to a function or variable as | |
| 5391 @code{foo} in one place and @code{Foo} or @code{FOO} in another. | |
| 5392 Emacs Lisp will treat these as three distinct symbols. | |
| 5393 | |
| 5394 Some Common Lisp code is written in all upper-case. While Emacs | |
| 5395 is happy to let the program's own functions and variables use | |
| 5396 this convention, calls to Lisp builtins like @code{if} and | |
| 5397 @code{defun} will have to be changed to lower-case. | |
| 5398 | |
| 5399 @item | |
| 5400 Lexical scoping. In Common Lisp, function arguments and @code{let} | |
| 5401 bindings apply only to references physically within their bodies | |
| 5402 (or within macro expansions in their bodies). Emacs Lisp, by | |
| 5403 contrast, uses @dfn{dynamic scoping} wherein a binding to a | |
| 5404 variable is visible even inside functions called from the body. | |
| 5405 | |
| 5406 Variables in Common Lisp can be made dynamically scoped by | |
| 5407 declaring them @code{special} or using @code{defvar}. In Emacs | |
| 5408 Lisp it is as if all variables were declared @code{special}. | |
| 5409 | |
| 5410 Often you can use code that was written for lexical scoping | |
| 5411 even in a dynamically scoped Lisp, but not always. Here is | |
| 5412 an example of a Common Lisp code fragment that would fail in | |
| 5413 Emacs Lisp: | |
| 5414 | |
| 5415 @example | |
| 5416 (defun map-odd-elements (func list) | |
| 5417 (loop for x in list | |
| 5418 for flag = t then (not flag) | |
| 5419 collect (if flag x (funcall func x)))) | |
| 5420 | |
| 5421 (defun add-odd-elements (list x) | |
| 5422 (map-odd-elements (function (lambda (a) (+ a x))) list)) | |
| 5423 @end example | |
| 5424 | |
| 5425 @noindent | |
| 5426 In Common Lisp, the two functions' usages of @code{x} are completely | |
| 5427 independent. In Emacs Lisp, the binding to @code{x} made by | |
| 5428 @code{add-odd-elements} will have been hidden by the binding | |
| 5429 in @code{map-odd-elements} by the time the @code{(+ a x)} function | |
| 5430 is called. | |
| 5431 | |
| 5432 (This package avoids such problems in its own mapping functions | |
| 5433 by using names like @code{cl-x} instead of @code{x} internally; | |
| 5434 as long as you don't use the @code{cl-} prefix for your own | |
| 5435 variables no collision can occur.) | |
| 5436 | |
| 5437 @xref{Lexical Bindings}, for a description of the @code{lexical-let} | |
| 5438 form which establishes a Common Lisp-style lexical binding, and some | |
| 5439 examples of how it differs from Emacs' regular @code{let}. | |
| 5440 | |
| 5441 @item | |
| 5442 Common Lisp allows the shorthand @code{#'x} to stand for | |
| 5443 @code{(function x)}, just as @code{'x} stands for @code{(quote x)}. | |
| 5444 In Common Lisp, one traditionally uses @code{#'} notation when | |
| 5445 referring to the name of a function. In Emacs Lisp, it works | |
| 5446 just as well to use a regular quote: | |
| 5447 | |
| 5448 @example | |
| 442 | 5449 (loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp |
| 5450 (loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp | |
| 428 | 5451 @end example |
| 5452 | |
| 5453 When @code{#'} introduces a @code{lambda} form, it is best to | |
| 5454 write out @code{(function ...)} longhand in Emacs Lisp. You can | |
| 5455 use a regular quote, but then the byte-compiler won't know that | |
| 5456 the @code{lambda} expression is code that can be compiled. | |
| 5457 | |
| 5458 @example | |
| 5459 (mapcar #'(lambda (x) (* x 2)) list) ; Common Lisp | |
| 5460 (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp | |
| 5461 @end example | |
| 5462 | |
| 5463 XEmacs supports @code{#'} notation starting with version 19.8. | |
| 5464 | |
| 5465 @item | |
| 5466 Reader macros. Common Lisp includes a second type of macro that | |
| 5467 works at the level of individual characters. For example, Common | |
| 5468 Lisp implements the quote notation by a reader macro called @code{'}, | |
| 5469 whereas Emacs Lisp's parser just treats quote as a special case. | |
| 5470 Some Lisp packages use reader macros to create special syntaxes | |
| 5471 for themselves, which the Emacs parser is incapable of reading. | |
| 5472 | |
| 5473 @item | |
| 5474 Other syntactic features. Common Lisp provides a number of | |
| 5475 notations beginning with @code{#} that the Emacs Lisp parser | |
| 5476 won't understand. For example, @samp{#| ... |#} is an | |
| 5477 alternate comment notation, and @samp{#+lucid (foo)} tells | |
| 5478 the parser to ignore the @code{(foo)} except in Lucid Common | |
| 5479 Lisp. | |
| 5480 | |
| 5481 The number prefixes `#b', `#o', and `#x', however, are supported | |
| 5482 by the Emacs Lisp parser to represent numbers in binary, octal, | |
| 5483 and hexadecimal notation (or radix), just like in Common Lisp. | |
| 5484 | |
| 5485 @item | |
| 5486 Packages. In Common Lisp, symbols are divided into @dfn{packages}. | |
| 5487 Symbols that are Lisp built-ins are typically stored in one package; | |
| 5488 symbols that are vendor extensions are put in another, and each | |
| 5489 application program would have a package for its own symbols. | |
| 5490 Certain symbols are ``exported'' by a package and others are | |
| 5491 internal; certain packages ``use'' or import the exported symbols | |
| 5492 of other packages. To access symbols that would not normally be | |
| 5493 visible due to this importing and exporting, Common Lisp provides | |
| 5494 a syntax like @code{package:symbol} or @code{package::symbol}. | |
| 5495 | |
| 5496 Emacs Lisp has a single namespace for all interned symbols, and | |
| 5497 then uses a naming convention of putting a prefix like @code{cl-} | |
| 5498 in front of the name. Some Emacs packages adopt the Common Lisp-like | |
| 5499 convention of using @code{cl:} or @code{cl::} as the prefix. | |
| 5500 However, the Emacs parser does not understand colons and just | |
| 5501 treats them as part of the symbol name. Thus, while @code{mapcar} | |
| 5502 and @code{lisp:mapcar} may refer to the same symbol in Common | |
| 5503 Lisp, they are totally distinct in Emacs Lisp. Common Lisp | |
| 5504 programs which refer to a symbol by the full name sometimes | |
| 5505 and the short name other times will not port cleanly to Emacs. | |
| 5506 | |
| 5507 Emacs Lisp does have a concept of ``obarrays,'' which are | |
| 5508 package-like collections of symbols, but this feature is not | |
| 5509 strong enough to be used as a true package mechanism. | |
| 5510 | |
| 5511 @item | |
| 5512 Keywords. The notation @code{:test-not} in Common Lisp really | |
| 5513 is a shorthand for @code{keyword:test-not}; keywords are just | |
| 5514 symbols in a built-in @code{keyword} package with the special | |
| 5515 property that all its symbols are automatically self-evaluating. | |
| 5516 Common Lisp programs often use keywords liberally to avoid | |
| 5517 having to use quotes. | |
| 5518 | |
| 5519 In Emacs Lisp a keyword is just a symbol whose name begins with | |
| 5520 a colon; since the Emacs parser does not treat them specially, | |
| 5521 they have to be explicitly made self-evaluating by a statement | |
| 5522 like @code{(setq :test-not ':test-not)}. This package arranges | |
| 5523 to execute such a statement whenever @code{defun*} or some | |
| 5524 other form sees a keyword being used as an argument. Common | |
| 5525 Lisp code that assumes that a symbol @code{:mumble} will be | |
| 5526 self-evaluating even though it was never introduced by a | |
| 5527 @code{defun*} will have to be fixed. | |
| 5528 | |
| 5529 @item | |
| 5530 The @code{format} function is quite different between Common | |
| 5531 Lisp and Emacs Lisp. It takes an additional ``destination'' | |
| 5532 argument before the format string. A destination of @code{nil} | |
| 5533 means to format to a string as in Emacs Lisp; a destination | |
| 5534 of @code{t} means to write to the terminal (similar to | |
| 5535 @code{message} in Emacs). Also, format control strings are | |
| 5536 utterly different; @code{~} is used instead of @code{%} to | |
| 5537 introduce format codes, and the set of available codes is | |
| 5538 much richer. There are no notations like @code{\n} for | |
| 5539 string literals; instead, @code{format} is used with the | |
| 5540 ``newline'' format code, @code{~%}. More advanced formatting | |
| 5541 codes provide such features as paragraph filling, case | |
| 5542 conversion, and even loops and conditionals. | |
| 5543 | |
| 5544 While it would have been possible to implement most of Common | |
| 5545 Lisp @code{format} in this package (under the name @code{format*}, | |
| 5546 of course), it was not deemed worthwhile. It would have required | |
| 5547 a huge amount of code to implement even a decent subset of | |
| 5548 @code{format*}, yet the functionality it would provide over | |
| 5549 Emacs Lisp's @code{format} would rarely be useful. | |
| 5550 | |
| 5551 @item | |
| 5552 Vector constants use square brackets in Emacs Lisp, but | |
| 5553 @code{#(a b c)} notation in Common Lisp. To further complicate | |
| 5554 matters, Emacs 19 introduces its own @code{#(} notation for | |
| 5555 something entirely different---strings with properties. | |
| 5556 | |
| 5557 @item | |
| 5558 Characters are distinct from integers in Common Lisp. The | |
| 5559 notation for character constants is also different: @code{#\A} | |
| 5560 instead of @code{?A}. Also, @code{string=} and @code{string-equal} | |
| 5561 are synonyms in Emacs Lisp whereas the latter is case-insensitive | |
| 5562 in Common Lisp. | |
| 5563 | |
| 5564 @item | |
| 5565 Data types. Some Common Lisp data types do not exist in Emacs | |
| 5566 Lisp. Rational numbers and complex numbers are not present, | |
| 5567 nor are large integers (all integers are ``fixnums''). All | |
| 5568 arrays are one-dimensional. There are no readtables or pathnames; | |
| 5569 streams are a set of existing data types rather than a new data | |
| 5570 type of their own. Hash tables, random-states, structures, and | |
| 5571 packages (obarrays) are built from Lisp vectors or lists rather | |
| 5572 than being distinct types. | |
| 5573 | |
| 5574 @item | |
| 5575 The Common Lisp Object System (CLOS) is not implemented, | |
| 5576 nor is the Common Lisp Condition System. | |
| 5577 | |
| 5578 @item | |
| 5579 Common Lisp features that are completely redundant with Emacs | |
| 5580 Lisp features of a different name generally have not been | |
| 5581 implemented. For example, Common Lisp writes @code{defconstant} | |
| 5582 where Emacs Lisp uses @code{defconst}. Similarly, @code{make-list} | |
| 5583 takes its arguments in different ways in the two Lisps but does | |
| 5584 exactly the same thing, so this package has not bothered to | |
| 5585 implement a Common Lisp-style @code{make-list}. | |
| 5586 | |
| 5587 @item | |
| 5588 A few more notable Common Lisp features not included in this | |
| 5589 package: @code{compiler-let}, @code{tagbody}, @code{prog}, | |
| 5590 @code{ldb/dpb}, @code{parse-integer}, @code{cerror}. | |
| 5591 | |
| 5592 @item | |
| 5593 Recursion. While recursion works in Emacs Lisp just like it | |
| 5594 does in Common Lisp, various details of the Emacs Lisp system | |
| 5595 and compiler make recursion much less efficient than it is in | |
| 5596 most Lisps. Some schools of thought prefer to use recursion | |
| 5597 in Lisp over other techniques; they would sum a list of | |
| 5598 numbers using something like | |
| 5599 | |
| 5600 @example | |
| 5601 (defun sum-list (list) | |
| 5602 (if list | |
| 5603 (+ (car list) (sum-list (cdr list))) | |
| 5604 0)) | |
| 5605 @end example | |
| 5606 | |
| 5607 @noindent | |
| 5608 where a more iteratively-minded programmer might write one of | |
| 5609 these forms: | |
| 5610 | |
| 5611 @example | |
| 5612 (let ((total 0)) (dolist (x my-list) (incf total x)) total) | |
| 5613 (loop for x in my-list sum x) | |
| 5614 @end example | |
| 5615 | |
| 5616 While this would be mainly a stylistic choice in most Common Lisps, | |
| 5617 in Emacs Lisp you should be aware that the iterative forms are | |
| 5618 much faster than recursion. Also, Lisp programmers will want to | |
| 5619 note that the current Emacs Lisp compiler does not optimize tail | |
| 5620 recursion. | |
| 5621 @end itemize | |
| 5622 | |
| 5623 @node Function Index, Variable Index, Porting Common Lisp, Top | |
| 5624 @unnumbered Function Index | |
| 5625 | |
| 5626 @printindex fn | |
| 5627 | |
| 5628 @node Variable Index, , Function Index, Top | |
| 5629 @unnumbered Variable Index | |
| 5630 | |
| 5631 @printindex vr | |
| 5632 | |
| 5633 @contents | |
| 5634 @bye |