Reformatted.
[chise/xemacs-chise.git.1] / man / cl.texi
index 7538e51..7e8125a 100644 (file)
@@ -7,6 +7,11 @@
 @end iftex
 
 @ifinfo
 @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.
 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*
 
 @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
 @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
 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
 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}
 @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.
 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
 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
 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
 @end smallexample
 
 @noindent
@@ -1098,44 +1099,44 @@ to standard Common Lisp.
 
 @item
 The following Emacs-specific functions are also @code{setf}-able.
 
 @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
 
 @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
 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
 @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}
 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}
 
 @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{}
 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
 
 @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)))
 @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
 @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
 missing from Emacs Lisp.
 
 @menu
-* Property Lists::       `get*', `remprop', `getf', `remf'
+* Property Lists::       `getf', `remf'
 * Creating Symbols::     `gensym', `gentemp'
 @end menu
 
 * 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}
 
 @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
 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
 
 @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
 
 (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
 
 @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
 @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
 @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
 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.
 
 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
 
 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
 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
 @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
 
 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
 
 @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
 @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.
 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
 
 @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
 
 (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
 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
 
 @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}
 @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")
 
 @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}.
 
 @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:
 @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
 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
 @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
 
 (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
 
 @item
 Reader macros.  Common Lisp includes a second type of macro that