X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Fcl.texi;h=7e8125a4bf8fb20d310746236cbd941d80be3ea4;hb=b516a64aa419c6a06613b1c880db2b9a1605b949;hp=7538e510d5a06d83812387d13c7d5f3de1676e8a;hpb=6883ee56ec887c2c48abe5b06b5e66aa74031910;p=chise%2Fxemacs-chise.git.1 diff --git a/man/cl.texi b/man/cl.texi index 7538e51..7e8125a 100644 --- a/man/cl.texi +++ b/man/cl.texi @@ -7,6 +7,11 @@ @end iftex @ifinfo +@dircategory XEmacs Editor +@direntry +* Common Lisp: (cl). GNU Emacs Common Lisp emulation package. +@end direntry + This file documents the GNU Emacs Common Lisp emulation package. Copyright (C) 1993 Free Software Foundation, Inc. @@ -290,10 +295,10 @@ the Emacs name: @example defun* defsubst* defmacro* function* -member* assoc* rassoc* get* -remove* delete* mapcar* sort* -floor* ceiling* truncate* round* -mod* rem* random* +member* assoc* rassoc* remove* +delete* mapcar* sort* floor* +ceiling* truncate* round* mod* +rem* random* @end example Internal function and variable names in the package are prefixed @@ -947,13 +952,9 @@ it compares numbers without regard to type (so that @code{(equalp 3 objects are compared as if by @code{equal}. This function differs from Common Lisp @code{equalp} in several -respects. First, in keeping with the idea that strings are less +respects. In keeping with the idea that strings are less vector-like in Emacs Lisp, this package's @code{equalp} also will not -compare strings against vectors of integers. Second, Common Lisp's -@code{equalp} compares hash tables without regard to ordering, whereas -this package simply compares hash tables in terms of their underlying -structure (which means vectors for Lucid Emacs 19 hash tables, or lists -for other hash tables). +compare strings against vectors of integers. @end defun Also note that the Common Lisp functions @code{member} and @code{assoc} @@ -1072,7 +1073,7 @@ exactly equivalent to @code{(setq x y)}, and @code{setq} itself is strictly speaking redundant now that @code{setf} exists. Many programmers continue to prefer @code{setq} for setting simple variables, though, purely for stylistic or historical reasons. -The macro @code{(setf x y)} actually expands to @code{(setq x y)}, +The form @code{(setf x y)} actually expands to @code{(setq x y)}, so there is no performance penalty for using it in compiled code. @item @@ -1083,8 +1084,8 @@ car cdr caar .. cddddr nth rest first .. tenth aref elt nthcdr symbol-function symbol-value symbol-plist -get get* getf -gethash subseq +get getf gethash +subseq @end smallexample @noindent @@ -1098,44 +1099,44 @@ to standard Common Lisp. @item The following Emacs-specific functions are also @code{setf}-able. -(Some of these are defined only in Emacs 19 or only in Lucid Emacs.) +(Some of these are defined only in Emacs 19 or only in XEmacs.) @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 @@ -2584,14 +2585,14 @@ is the opposite word of the word following @code{the}) to cause hash table entry. @item for @var{var} being the key-codes of @var{keymap} -This clause iterates over the entries in @var{keymap}. In GNU Emacs -18 and 19, keymaps are either alists or vectors, and key-codes are -integers or symbols. In Lucid Emacs 19, keymaps are a special new -data type, and key-codes are symbols or lists of symbols. The -iteration does not enter nested keymaps or inherited (parent) keymaps. -You can use @samp{the key-bindings} to access the commands bound to -the keys rather than the key codes, and you can add a @code{using} -clause to access both the codes and the bindings together. +This clause iterates over the entries in @var{keymap}. In GNU Emacs 18 +and 19, keymaps are either alists or vectors, and key-codes are integers +or symbols. In XEmacs, keymaps are a special new data type, and +key-codes are symbols or lists of symbols. The iteration does not enter +nested keymaps or inherited (parent) keymaps. You can use @samp{the +key-bindings} to access the commands bound to the keys rather than the +key codes, and you can add a @code{using} clause to access both the +codes and the bindings together. @item for @var{var} being the key-seqs of @var{keymap} This clause iterates over all key sequences defined by @var{keymap} @@ -2602,13 +2603,13 @@ them permanently. You can add a @samp{using (key-bindings ...)} clause to get the command bindings as well. @item for @var{var} being the overlays [of @var{buffer}] @dots{} -This clause iterates over the Emacs 19 ``overlays'' or Lucid -Emacs ``extents'' of a buffer (the clause @code{extents} is synonymous -with @code{overlays}). Under Emacs 18, this clause iterates zero -times. If the @code{of} term is omitted, the current buffer is used. -This clause also accepts optional @samp{from @var{pos}} and -@samp{to @var{pos}} terms, limiting the clause to overlays which -overlap the specified region. +This clause iterates over the Emacs 19 ``overlays'' or XEmacs +``extents'' of a buffer (the clause @code{extents} is synonymous with +@code{overlays}). Under Emacs 18, this clause iterates zero times. If +the @code{of} term is omitted, the current buffer is used. This clause +also accepts optional @samp{from @var{pos}} and @samp{to @var{pos}} +terms, limiting the clause to overlays which overlap the specified +region. @item for @var{var} being the intervals [of @var{buffer}] @dots{} This clause iterates over all intervals of a buffer with constant @@ -3217,8 +3218,8 @@ Emacs 19. @example (declaim (inline foo bar)) (eval-when (compile load eval) (proclaim '(inline foo bar))) -(proclaim-inline foo bar) ; Lucid Emacs only -(defsubst foo (...) ...) ; instead of defun; Emacs 19 only +(proclaim-inline foo bar) ; XEmacs only +(defsubst foo (...) ...) ; instead of defun; Emacs 19 only @end example @strong{Please note:} This declaration remains in effect after the @@ -3296,7 +3297,7 @@ This package defines several symbol-related features that were missing from Emacs Lisp. @menu -* Property Lists:: `get*', `remprop', `getf', `remf' +* Property Lists:: `getf', `remf' * Creating Symbols:: `gensym', `gentemp' @end menu @@ -3305,31 +3306,9 @@ missing from Emacs Lisp. @noindent These functions augment the standard Emacs Lisp functions @code{get} -and @code{put} for operating on properties attached to symbols. +and @code{put} for operating on properties attached to objects. There are also functions for working with property lists as -first-class data structures not attached to particular symbols. - -@defun get* symbol property &optional default -This function is like @code{get}, except that if the property is -not found, the @var{default} argument provides the return value. -(The Emacs Lisp @code{get} function always uses @code{nil} as -the default; this package's @code{get*} is equivalent to Common -Lisp's @code{get}.) - -The @code{get*} function is @code{setf}-able; when used in this -fashion, the @var{default} argument is allowed but ignored. -@end defun - -@defun remprop symbol property -This function removes the entry for @var{property} from the property -list of @var{symbol}. It returns a true value if the property was -indeed found and removed, or @code{nil} if there was no such property. -(This function was probably omitted from Emacs originally because, -since @code{get} did not allow a @var{default}, it was very difficult -to distinguish between a missing property and a property whose value -was @code{nil}; thus, setting a property to @code{nil} was close -enough to @code{remprop} for most purposes.) -@end defun +first-class data structures not attached to particular objects. @defun getf place property &optional default This function scans the list @var{place} as if it were a property @@ -3356,11 +3335,11 @@ pair onto the list if the property is not yet present. (put sym prop val) @equiv{} (setf (getf (symbol-plist sym) prop) val) @end example -The @code{get} and @code{get*} functions are also @code{setf}-able. -The fact that @code{default} is ignored can sometimes be useful: +The @code{get} function is also @code{setf}-able. The fact that +@code{default} is ignored can sometimes be useful: @example -(incf (get* 'foo 'usage-count 0)) +(incf (get 'foo 'usage-count 0)) @end example Here, symbol @code{foo}'s @code{usage-count} property is incremented @@ -4601,6 +4580,10 @@ This is equivalent to @code{(nconc (mapcar* 'cons @var{keys} @var{values}) @chapter Hash Tables @noindent +Hash tables are now implemented directly in the C code and documented in +@ref{Hash Tables,,, lispref, XEmacs Lisp Reference Manual}. + +@ignore A @dfn{hash table} is a data structure that maps ``keys'' onto ``values.'' Keys and values can be arbitrary Lisp data objects. Hash tables have the property that the time to search for a given @@ -4622,14 +4605,14 @@ though if you use something else you should check the details of the hashing function described below to make sure it is suitable for your predicate. -Some versions of Emacs (like Lucid Emacs 19) include a built-in -hash table type; in these versions, @code{make-hash-table} with -a test of @code{eq} will use these built-in hash tables. In all -other cases, it will return a hash-table object which takes the -form of a list with an identifying ``tag'' symbol at the front. -All of the hash table functions in this package can operate on -both types of hash table; normally you will never know which -type is being used. +Some versions of Emacs (like XEmacs) include a built-in hash +table type; in these versions, @code{make-hash-table} with a test of +@code{eq}, @code{eql}, or @code{equal} will use these built-in hash +tables. In all other cases, it will return a hash-table object which +takes the form of a list with an identifying ``tag'' symbol at the +front. All of the hash table functions in this package can operate on +both types of hash table; normally you will never know which type is +being used. This function accepts the additional Common Lisp keywords @code{:rehash-size} and @code{:rehash-threshold}, but it ignores @@ -4648,7 +4631,7 @@ corresponding value is changed to the stored value. If @var{key} does not already exist, a new entry is added to the table and the table is reallocated to a larger size if necessary. The @var{default} argument is allowed but ignored in this case. The situation is -exactly analogous to that of @code{get*}; @pxref{Property Lists}. +exactly analogous to that of @code{get}; @pxref{Property Lists}. @end defun @defun remhash key table @@ -4670,22 +4653,20 @@ of the given entry. The return value of @var{function} is ignored; an alternate way of iterating over hash tables. @end defun -@defun hash-table-count table -This function returns the number of entries in @var{table}. -@strong{Warning:} The current implementation of Lucid Emacs 19 -hash-tables does not decrement the stored @code{count} when -@code{remhash} removes an entry. Therefore, the return value of -this function is not dependable if you have used @code{remhash} -on the table and the table's test is @code{eq}. A slower, but -reliable, way to count the entries is @code{(loop for x being the -hash-keys of @var{table} count t)}. +@defun hash-table-count table This function returns the number of +entries in @var{table}. @strong{Warning:} The current implementation of +XEmacs hash-tables does not decrement the stored @code{count} +when @code{remhash} removes an entry. Therefore, the return value of +this function is not dependable if you have used @code{remhash} on the +table and the table's test is @code{eq}, @code{eql}, or @code{equal}. +A slower, but reliable, way to count the entries is +@code{(loop for x being the hash-keys of @var{table} count t)}. @end defun -@defun hash-table-p object -This function returns @code{t} if @var{object} is a hash table, -@code{nil} otherwise. It recognizes both types of hash tables -(both Lucid Emacs built-in tables and tables implemented with -special lists.) +@defun hash-table-p object This function returns @code{t} if +@var{object} is a hash table, @code{nil} otherwise. It recognizes both +types of hash tables (both XEmacs built-in tables and tables implemented +with special lists.) @end defun Sometimes when dealing with hash tables it is useful to know the @@ -4745,6 +4726,7 @@ structure will be more efficient since lookup does not require converting the key to a string or looking it up in an obarray. However, such tables are guaranteed to take time proportional to their size to do a search. +@end ignore @iftex @chapno=18 @@ -5117,20 +5099,19 @@ will also include all non-constant arguments of the top-level (assert (> x 10) t "x is too small: %d") @end example -This usage of @var{show-args} is an extension to Common Lisp. In +This usage of @var{show-args} is a change to Common Lisp. In true Common Lisp, the second argument gives a list of @var{places} which can be @code{setf}'d by the user before continuing from the -error. Since Emacs Lisp does not support continuable errors, it -makes no sense to specify @var{places}. +error. @end defspec -@defspec check-type form type [string] -This form verifies that @var{form} evaluates to a value of type +@defspec check-type place type &optional string +This form verifies that @var{place} evaluates to a value of type @var{type}. If so, it returns @code{nil}. If not, @code{check-type} -signals a @code{wrong-type-argument} error. The default error message -lists the erroneous value along with @var{type} and @var{form} -themselves. If @var{string} is specified, it is included in the -error message in place of @var{type}. For example: +signals a continuable @code{wrong-type-argument} error. The default +error message lists the erroneous value along with @var{type} and +@var{place} themselves. If @var{string} is specified, it is included in +the error message in place of @var{type}. For example: @example (check-type x (integer 1 *) "a positive integer") @@ -5139,10 +5120,10 @@ error message in place of @var{type}. For example: @xref{Type Predicates}, for a description of the type specifiers that may be used for @var{type}. -Note that in Common Lisp, the first argument to @code{check-type} -must be a @var{place} suitable for use by @code{setf}, because -@code{check-type} signals a continuable error that allows the -user to modify @var{place}. +Note that as in Common Lisp, the first argument to @code{check-type} +should be a @var{place} suitable for use by @code{setf}, because +@code{check-type} signals a continuable error that allows the user to +modify @var{place}, most simply by returning a value from the debugger. @end defspec The following error-related macro is also defined: @@ -5567,8 +5548,8 @@ referring to the name of a function. In Emacs Lisp, it works just as well to use a regular quote: @example -(loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp -(loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp +(loop for x in y by #'cddr collect (mapcar #'plusp x)) ; Common Lisp +(loop for x in y by 'cddr collect (mapcar 'plusp x)) ; Emacs Lisp @end example When @code{#'} introduces a @code{lambda} form, it is best to @@ -5581,7 +5562,7 @@ the @code{lambda} expression is code that can be compiled. (mapcar (function (lambda (x) (* x 2))) list) ; Emacs Lisp @end example -Lucid Emacs supports @code{#'} notation starting with version 19.8. +XEmacs supports @code{#'} notation starting with version 19.8. @item Reader macros. Common Lisp includes a second type of macro that