X-Git-Url: https://code.delx.au/gnu-emacs/blobdiff_plain/c6ad01e8537f0e25e78b85beba56a673919a5df7..937640a621a4ce2e5e56eaecca37a2a28a584318:/man/cl.texi diff --git a/man/cl.texi b/man/cl.texi index 8788e66a01..455465a27a 100644 --- a/man/cl.texi +++ b/man/cl.texi @@ -2,43 +2,37 @@ @setfilename ../info/cl @settitle Common Lisp Extensions -@dircategory Emacs -@direntry -* CL: (cl). Partial Common Lisp support for Emacs Lisp. -@end direntry +@copying +This file documents the GNU Emacs Common Lisp emulation package. -@iftex -@finalout -@end iftex +Copyright (C) 1993, 2002 Free Software Foundation, Inc. -@ifinfo -This file documents the GNU Emacs Common Lisp emulation package. +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with the Front-Cover texts being ``A GNU +Manual'', and with the Back-Cover Texts as in (a) below. A copy of the +license is included in the section entitled ``GNU Free Documentation +License'' in the Emacs manual. -Copyright (C) 1993 Free Software Foundation, Inc. +(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify +this GNU Manual, like GNU software. Copies published by the Free +Software Foundation raise funds for GNU development.'' -Permission is granted to make and distribute verbatim copies of this -manual provided the copyright notice and this permission notice are -preserved on all copies. +This document is part of a collection distributed under the GNU Free +Documentation License. If you want to distribute this document +separately from the collection, you can do so by adding a copy of the +license to the document, as described in section 6 of the license. +@end quotation +@end copying -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). +@dircategory Emacs +@direntry +* CL: (cl). Partial Common Lisp support for Emacs Lisp. +@end direntry -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the author instead of in the -original English. -@end ifinfo +@finalout @titlepage @sp 6 @@ -51,36 +45,12 @@ original English. @center Dave Gillespie @center daveg@@synaptics.com @page - @vskip 0pt plus 1filll -Copyright @copyright{} 1993 Free Software Foundation, Inc. - -Permission is granted to make and distribute verbatim copies of -this manual provided the copyright notice and this permission notice -are preserved on all copies. - -@ignore -Permission is granted to process this file through TeX and print the -results, provided the printed document carries copying permission notice -identical to this one except for the removal of this paragraph (this -paragraph not being relevant to the printed manual). - -@end ignore -Permission is granted to copy and distribute modified versions of this -manual under the conditions for verbatim copying, provided also that the -section entitled ``GNU General Public License'' is included exactly as -in the original, and provided that the entire resulting derived work is -distributed under the terms of a permission notice identical to this one. - -Permission is granted to copy and distribute translations of this manual -into another language, under the above conditions for modified versions, -except that the section entitled ``GNU General Public License'' may be -included in a translation approved by the author instead of in the -original English. +@insertcopying @end titlepage @node Top, Overview, (dir), (dir) -@chapter Common Lisp Extensions +@chapter Introduction @noindent This document describes a set of Emacs Lisp facilities borrowed from @@ -112,12 +82,9 @@ does assume a basic familiarity with Emacs Lisp. @end menu @node Overview, Program Structure, Top, Top -@ifinfo +@ifnottex @chapter Overview -@end ifinfo -@iftex -@section Overview -@end iftex +@end ifnottex @noindent Common Lisp is a huge language, and Common Lisp systems tend to be @@ -132,6 +99,16 @@ control structures to Emacs Lisp. While not a 100% complete implementation of Common Lisp, @dfn{CL} adds enough functionality to make Emacs Lisp programming significantly more convenient. +@strong{Please note:} the @dfn{CL} functions are not standard parts of +the Emacs Lisp name space, so it is legitimate for users to define +them with other, conflicting meanings. To avoid conflicting with +those user activities, we have a policy that packages installed in +Emacs must not load @dfn{CL} at run time. (It is ok for them to load +@dfn{CL} at compile time only, with @code{eval-when-compile}, and use +the macros it provides.) If you are writing packages that you plan to +distribute and invite widespread use for, you might want to observe +the same rule. + Some Common Lisp features have been omitted from this package for various reasons: @@ -291,7 +268,7 @@ defun* defsubst* defmacro* function* member* assoc* rassoc* get* remove* delete* mapcar* sort* floor* ceiling* truncate* round* -mod* rem* random* last* +mod* rem* random* @end example Internal function and variable names in the package are prefixed @@ -310,7 +287,7 @@ they do not cause other components like @file{cl-extra} to be loaded. @example eql floatp-safe endp evenp oddp plusp minusp -butlast nbutlast caaar .. cddddr +caaar .. cddddr list* ldiff rest first .. tenth copy-list subst mapcar* [2] adjoin [3] acons pairlis pop [4] @@ -509,19 +486,6 @@ accepts other keyword arguments which are passed on to the keep both @code{find-thing} and @code{member*} from complaining about each others' keywords in the arguments. -As a (significant) performance optimization, this package -implements the scan for keyword arguments by calling @code{memq} -to search for keywords in a ``rest'' argument. Technically -speaking, this is incorrect, since @code{memq} looks at the -odd-numbered values as well as the even-numbered keywords. -The net effect is that if you happen to pass a keyword symbol -as the @emph{value} of another keyword argument, where that -keyword symbol happens to equal the name of a valid keyword -argument of the same function, then the keyword parser will -become confused. This minor bug can only affect you if you -use keyword symbols as general-purpose data in your program; -this practice is strongly discouraged in Emacs Lisp. - The fifth section of the argument list consists of @dfn{auxiliary variables}. These are not really arguments at all, but simply variables which are bound to @code{nil} or to the specified @@ -1064,41 +1028,41 @@ to standard Common Lisp. The following Emacs-specific functions are also @code{setf}-able. @smallexample -buffer-file-name marker-position -buffer-modified-p match-data -buffer-name mouse-position -buffer-string overlay-end -buffer-substring overlay-get -current-buffer overlay-start -current-case-table point -current-column point-marker -current-global-map point-max -current-input-mode point-min -current-local-map process-buffer -current-window-configuration process-filter -default-file-modes process-sentinel -default-value read-mouse-position -documentation-property screen-height -extent-data screen-menubar -extent-end-position screen-width -extent-start-position selected-window -face-background selected-screen -face-background-pixmap selected-frame -face-font standard-case-table -face-foreground syntax-table -face-underline-p window-buffer -file-modes window-dedicated-p -frame-height window-display-table -frame-parameters window-height -frame-visible-p window-hscroll -frame-width window-point -get-register window-start -getenv window-width -global-key-binding x-get-cut-buffer -keymap-parent x-get-cutbuffer +buffer-file-name marker-position +buffer-modified-p match-data +buffer-name mouse-position +buffer-string overlay-end +buffer-substring overlay-get +current-buffer overlay-start +current-case-table point +current-column point-marker +current-global-map point-max +current-input-mode point-min +current-local-map process-buffer +current-window-configuration process-filter +default-file-modes process-sentinel +default-value read-mouse-position +documentation-property screen-height +extent-data screen-menubar +extent-end-position screen-width +extent-start-position selected-window +face-background selected-screen +face-background-pixmap selected-frame +face-font standard-case-table +face-foreground syntax-table +face-underline-p window-buffer +file-modes window-dedicated-p +frame-height window-display-table +frame-parameters window-height +frame-visible-p window-hscroll +frame-width window-point +get-register window-start +getenv window-width +global-key-binding x-get-cut-buffer +keymap-parent x-get-cutbuffer local-key-binding x-get-secondary-selection -mark x-get-selection -mark-marker +mark x-get-selection +mark-marker @end smallexample Most of these have directly corresponding ``set'' functions, like @@ -2034,7 +1998,7 @@ just as in Common Lisp. Because they are implemented in terms of Emacs Lisp @code{catch} and @code{throw}, blocks have the same overhead as actual @code{catch} constructs (roughly two function calls). However, -the optimizing byte compiler will optimize away the @code{catch} +the optimizing byte compiler will optimize away the @code{catch} if the block does not in fact contain any @code{return} or @code{return-from} calls that jump to it. This means that @code{do} loops and @code{defun*} @@ -3160,7 +3124,7 @@ and declare it inline all at once. (defsubst foo (...) ...) ; instead of defun @end example -@strong{Note:} This declaration remains in effect after the +@strong{Please note:} this declaration remains in effect after the containing source file is done. It is correct to use it to request that a function you have defined should be inlined, but it is impolite to use it to request inlining of an external @@ -3384,7 +3348,7 @@ which were left out of Emacs Lisp. * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc. * Numerical Functions:: `abs', `floor*', etc. * Random Numbers:: `random*', `make-random-state' -* Implementation Parameters:: `most-positive-fixnum', `most-positive-float' +* Implementation Parameters:: `most-positive-float' @end menu @iftex @@ -3591,16 +3555,6 @@ This predicate returns @code{t} if @var{object} is a @noindent This package defines several useful constants having to with numbers. -@defvar most-positive-fixnum -This constant equals the largest value a Lisp integer can hold. -It is typically @code{2^23-1} or @code{2^25-1}. -@end defvar - -@defvar most-negative-fixnum -This constant equals the smallest (most negative) value a Lisp -integer can hold. -@end defvar - The following parameters have to do with floating-point numbers. This package determines their values by exercising the computer's floating-point arithmetic in various ways. Because this operation @@ -3819,10 +3773,11 @@ that it passes in the list pointers themselves rather than the @end defun @defun mapc function seq &rest more-seqs -This function is like @code{mapcar*}, except that the values -returned by @var{function} are ignored and thrown away rather -than being collected into a list. The return value of @code{mapc} -is @var{seq}, the first sequence. +This function is like @code{mapcar*}, except that the values returned +by @var{function} are ignored and thrown away rather than being +collected into a list. The return value of @code{mapc} is @var{seq}, +the first sequence. This function is more general than the Emacs +primitive @code{mapc}. @end defun @defun mapl function list &rest more-lists @@ -4171,7 +4126,7 @@ a merged sequence which is (stably) sorted according to The functions described here operate on lists. @menu -* List Functions:: `caddr', `first', `last*', `list*', etc. +* List Functions:: `caddr', `first', `list*', etc. * Substitution of Expressions:: `subst', `sublis', etc. * Lists as Sets:: `member*', `adjoin', `union', etc. * Association Lists:: `assoc*', `rassoc*', `acons', `pairlis' @@ -4217,34 +4172,6 @@ with @code{nil}), this function returns @code{nil}. (The regular @code{length} function would get stuck if given a circular list.) @end defun -@defun last* x &optional n -This function returns the last cons, or the @var{n}th-to-last cons, -of the list @var{x}. If @var{n} is omitted it defaults to 1. -The ``last cons'' means the first cons cell of the list whose -@code{cdr} is not another cons cell. (For normal lists, the -@code{cdr} of the last cons will be @code{nil}.) This function -returns @code{nil} if @var{x} is @code{nil} or shorter than -@var{n}. Note that the last @emph{element} of the list is -@code{(car (last @var{x}))}. - -The Emacs function @code{last} does the same thing -except that it does not handle the optional argument @var{n}. -@end defun - -@defun butlast x &optional n -This function returns the list @var{x} with the last element, -or the last @var{n} elements, removed. If @var{n} is greater -than zero it makes a copy of the list so as not to damage the -original list. In general, @code{(append (butlast @var{x} @var{n}) -(last @var{x} @var{n}))} will return a list equal to @var{x}. -@end defun - -@defun nbutlast x &optional n -This is a version of @code{butlast} that works by destructively -modifying the @code{cdr} of the appropriate element, rather than -making a copy of the list. -@end defun - @defun list* arg &rest others This function constructs a list of its arguments. The final argument becomes the @code{cdr} of the last cell constructed. @@ -5002,13 +4929,7 @@ have built-in compiler macros to optimize them in common cases. Common Lisp compliance has in general not been sacrificed for the sake of efficiency. A few exceptions have been made for cases where substantial gains were possible at the expense of marginal -incompatibility. One example is the use of @code{memq} (which is -treated very efficiently by the byte-compiler) to scan for keyword -arguments; this can become confused in rare cases when keyword -symbols are used as both keywords and data values at once. This -is extremely unlikely to occur in practical code, and the use of -@code{memq} allows functions with keyword arguments to be nearly -as fast as functions that use @code{&optional} arguments. +incompatibility. The Common Lisp standard (as embodied in Steele's book) uses the phrase ``it is an error if'' to indicate a situation which is not @@ -5068,13 +4989,6 @@ which understand full-featured argument lists. The @code{&whole} keyword does not work in @code{defmacro} argument lists (except inside recursive argument lists). -In order to allow an efficient implementation, keyword arguments use -a slightly cheesy parser which may be confused if a keyword symbol -is passed as the @emph{value} of another keyword argument. -(Specifically, @code{(memq :@var{keyword} @var{rest-of-arguments})} -is used to scan for @code{:@var{keyword}} among the supplied -keyword arguments.) - The @code{eql} and @code{equal} predicates do not distinguish between IEEE floating-point plus and minus zero. The @code{equalp} predicate has several differences with Common Lisp; @pxref{Predicates}. @@ -5444,3 +5358,7 @@ recursion. @setchapternewpage odd @contents @bye + +@ignore + arch-tag: b61e7200-3bfa-4a70-a9d3-095e152696f8 +@end ignore