Merge r21-2-24-utf-2000-0_13-0.

[chise/xemacs-chise.git-] / info / cl.info-3

This is ../info/cl.info, produced by makeinfo version 4.0 from cl.texi.

INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
* Common Lisp: (cl).            GNU Emacs Common Lisp emulation package.
END-INFO-DIR-ENTRY

   This file documents the GNU Emacs Common Lisp emulation package.

   Copyright (C) 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.

   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.

\1f
File: cl.info,  Node: For Clauses,  Next: Iteration Clauses,  Prev: Loop Examples,  Up: Loop Facility

For Clauses
-----------

Most loops are governed by one or more `for' clauses.  A `for' clause
simultaneously describes variables to be bound, how those variables are
to be stepped during the loop, and usually an end condition based on
those variables.

   The word `as' is a synonym for the word `for'.  This word is
followed by a variable name, then a word like `from' or `across' that
describes the kind of iteration desired.  In Common Lisp, the phrase
`being the' sometimes precedes the type of iteration; in this package
both `being' and `the' are optional.  The word `each' is a synonym for
`the', and the word that follows it may be singular or plural:  `for x
being the elements of y' or `for x being each element of y'.  Which
form you use is purely a matter of style.

   The variable is bound around the loop as if by `let':

     (setq i 'happy)
     (loop for i from 1 to 10 do (do-something-with i))
     i
          => happy

`for VAR from EXPR1 to EXPR2 by EXPR3'
     This type of `for' clause creates a counting loop.  Each of the
     three sub-terms is optional, though there must be at least one
     term so that the clause is marked as a counting clause.

     The three expressions are the starting value, the ending value, and
     the step value, respectively, of the variable.  The loop counts
     upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2
     inclusively.  If you omit the `from' term, the loop counts from
     zero; if you omit the `to' term, the loop counts forever without
     stopping (unless stopped by some other loop clause, of course); if
     you omit the `by' term, the loop counts in steps of one.

     You can replace the word `from' with `upfrom' or `downfrom' to
     indicate the direction of the loop.  Likewise, you can replace
     `to' with `upto' or `downto'.  For example, `for x from 5 downto
     1' executes five times with `x' taking on the integers from 5 down
     to 1 in turn.  Also, you can replace `to' with `below' or `above',
     which are like `upto' and `downto' respectively except that they
     are exclusive rather than inclusive limits:

          (loop for x to 10 collect x)
               => (0 1 2 3 4 5 6 7 8 9 10)
          (loop for x below 10 collect x)
               => (0 1 2 3 4 5 6 7 8 9)

     The `by' value is always positive, even for downward-counting
     loops.  Some sort of `from' value is required for downward loops;
     `for x downto 5' is not a legal loop clause all by itself.

`for VAR in LIST by FUNCTION'
     This clause iterates VAR over all the elements of LIST, in turn.
     If you specify the `by' term, then FUNCTION is used to traverse
     the list instead of `cdr'; it must be a function taking one
     argument.  For example:

          (loop for x in '(1 2 3 4 5 6) collect (* x x))
               => (1 4 9 16 25 36)
          (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
               => (1 9 25)

`for VAR on LIST by FUNCTION'
     This clause iterates VAR over all the cons cells of LIST.

          (loop for x on '(1 2 3 4) collect x)
               => ((1 2 3 4) (2 3 4) (3 4) (4))

     With `by', there is no real reason that the `on' expression must
     be a list.  For example:

          (loop for x on first-animal by 'next-animal collect x)

     where `(next-animal x)' takes an "animal" X and returns the next
     in the (assumed) sequence of animals, or `nil' if X was the last
     animal in the sequence.

`for VAR in-ref LIST by FUNCTION'
     This is like a regular `in' clause, but VAR becomes a `setf'-able
     "reference" onto the elements of the list rather than just a
     temporary variable.  For example,

          (loop for x in-ref my-list do (incf x))

     increments every element of `my-list' in place.  This clause is an
     extension to standard Common Lisp.

`for VAR across ARRAY'
     This clause iterates VAR over all the elements of ARRAY, which may
     be a vector or a string.

          (loop for x across "aeiou"
                do (use-vowel (char-to-string x)))

`for VAR across-ref ARRAY'
     This clause iterates over an array, with VAR a `setf'-able
     reference onto the elements; see `in-ref' above.

`for VAR being the elements of SEQUENCE'
     This clause iterates over the elements of SEQUENCE, which may be a
     list, vector, or string.  Since the type must be determined at
     run-time, this is somewhat less efficient than `in' or `across'.
     The clause may be followed by the additional term `using (index
     VAR2)' to cause VAR2 to be bound to the successive indices
     (starting at 0) of the elements.

     This clause type is taken from older versions of the `loop' macro,
     and is not present in modern Common Lisp.  The `using (sequence
     ...)' term of the older macros is not supported.

`for VAR being the elements of-ref SEQUENCE'
     This clause iterates over a sequence, with VAR a `setf'-able
     reference onto the elements; see `in-ref' above.

`for VAR being the symbols [of OBARRAY]'
     This clause iterates over symbols, either over all interned symbols
     or over all symbols in OBARRAY.  The loop is executed with VAR
     bound to each symbol in turn.  The symbols are visited in an
     unspecified order.

     As an example,

          (loop for sym being the symbols
                when (fboundp sym)
                when (string-match "^map" (symbol-name sym))
                collect sym)

     returns a list of all the functions whose names begin with `map'.

     The Common Lisp words `external-symbols' and `present-symbols' are
     also recognized but are equivalent to `symbols' in Emacs Lisp.

     Due to a minor implementation restriction, it will not work to have
     more than one `for' clause iterating over symbols, hash tables,
     keymaps, overlays, or intervals in a given `loop'.  Fortunately,
     it would rarely if ever be useful to do so.  It _is_ legal to mix
     one of these types of clauses with other clauses like `for ... to'
     or `while'.

`for VAR being the hash-keys of HASH-TABLE'
     This clause iterates over the entries in HASH-TABLE.  For each
     hash table entry, VAR is bound to the entry's key.  If you write
     `the hash-values' instead, VAR is bound to the values of the
     entries.  The clause may be followed by the additional term `using
     (hash-values VAR2)' (where `hash-values' is the opposite word of
     the word following `the') to cause VAR and VAR2 to be bound to the
     two parts of each hash table entry.

`for VAR being the key-codes of KEYMAP'
     This clause iterates over the entries in 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 `the key-bindings' to access the commands
     bound to the keys rather than the key codes, and you can add a
     `using' clause to access both the codes and the bindings together.

`for VAR being the key-seqs of KEYMAP'
     This clause iterates over all key sequences defined by KEYMAP and
     its nested keymaps, where VAR takes on values which are strings in
     Emacs 18 or vectors in Emacs 19.  The strings or vectors are
     reused for each iteration, so you must copy them if you wish to
     keep them permanently.  You can add a `using (key-bindings ...)'
     clause to get the command bindings as well.

`for VAR being the overlays [of BUFFER] ...'
     This clause iterates over the Emacs 19 "overlays" or XEmacs
     "extents" of a buffer (the clause `extents' is synonymous with
     `overlays').  Under Emacs 18, this clause iterates zero times.  If
     the `of' term is omitted, the current buffer is used.  This clause
     also accepts optional `from POS' and `to POS' terms, limiting the
     clause to overlays which overlap the specified region.

`for VAR being the intervals [of BUFFER] ...'
     This clause iterates over all intervals of a buffer with constant
     text properties.  The variable VAR will be bound to conses of
     start and end positions, where one start position is always equal
     to the previous end position.  The clause allows `of', `from',
     `to', and `property' terms, where the latter term restricts the
     search to just the specified property.  The `of' term may specify
     either a buffer or a string.  This clause is useful only in GNU
     Emacs 19; in other versions, all buffers and strings consist of a
     single interval.

`for VAR being the frames'
     This clause iterates over all frames, i.e., X window system windows
     open on Emacs files.  This clause works only under Emacs 19.  The
     clause `screens' is a synonym for `frames'.  The frames are
     visited in `next-frame' order starting from `selected-frame'.

`for VAR being the windows [of FRAME]'
     This clause iterates over the windows (in the Emacs sense) of the
     current frame, or of the specified FRAME.  (In Emacs 18 there is
     only ever one frame, and the `of' term is not allowed there.)

`for VAR being the buffers'
     This clause iterates over all buffers in Emacs.  It is equivalent
     to `for VAR in (buffer-list)'.

`for VAR = EXPR1 then EXPR2'
     This clause does a general iteration.  The first time through the
     loop, VAR will be bound to EXPR1.  On the second and successive
     iterations it will be set by evaluating EXPR2 (which may refer to
     the old value of VAR).  For example, these two loops are
     effectively the same:

          (loop for x on my-list by 'cddr do ...)
          (loop for x = my-list then (cddr x) while x do ...)

     Note that this type of `for' clause does not imply any sort of
     terminating condition; the above example combines it with a
     `while' clause to tell when to end the loop.

     If you omit the `then' term, EXPR1 is used both for the initial
     setting and for successive settings:

          (loop for x = (random) when (> x 0) return x)

     This loop keeps taking random numbers from the `(random)' function
     until it gets a positive one, which it then returns.

   If you include several `for' clauses in a row, they are treated
sequentially (as if by `let*' and `setq').  You can instead use the
word `and' to link the clauses, in which case they are processed in
parallel (as if by `let' and `psetq').

     (loop for x below 5 for y = nil then x collect (list x y))
          => ((0 nil) (1 1) (2 2) (3 3) (4 4))
     (loop for x below 5 and y = nil then x collect (list x y))
          => ((0 nil) (1 0) (2 1) (3 2) (4 3))

In the first loop, `y' is set based on the value of `x' that was just
set by the previous clause; in the second loop, `x' and `y' are set
simultaneously so `y' is set based on the value of `x' left over from
the previous time through the loop.

   Another feature of the `loop' macro is "destructuring", similar in
concept to the destructuring provided by `defmacro'.  The VAR part of
any `for' clause can be given as a list of variables instead of a
single variable.  The values produced during loop execution must be
lists; the values in the lists are stored in the corresponding
variables.

     (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
          => (5 9 13)

   In loop destructuring, if there are more values than variables the
trailing values are ignored, and if there are more variables than
values the trailing variables get the value `nil'.  If `nil' is used as
a variable name, the corresponding values are ignored.  Destructuring
may be nested, and dotted lists of variables like `(x . y)' are allowed.

\1f
File: cl.info,  Node: Iteration Clauses,  Next: Accumulation Clauses,  Prev: For Clauses,  Up: Loop Facility

Iteration Clauses
-----------------

Aside from `for' clauses, there are several other loop clauses that
control the way the loop operates.  They might be used by themselves,
or in conjunction with one or more `for' clauses.

`repeat INTEGER'
     This clause simply counts up to the specified number using an
     internal temporary variable.  The loops

          (loop repeat n do ...)
          (loop for temp to n do ...)

     are identical except that the second one forces you to choose a
     name for a variable you aren't actually going to use.

`while CONDITION'
     This clause stops the loop when the specified condition (any Lisp
     expression) becomes `nil'.  For example, the following two loops
     are equivalent, except for the implicit `nil' block that surrounds
     the second one:

          (while COND FORMS...)
          (loop while COND do FORMS...)

`until CONDITION'
     This clause stops the loop when the specified condition is true,
     i.e., non-`nil'.

`always CONDITION'
     This clause stops the loop when the specified condition is `nil'.
     Unlike `while', it stops the loop using `return nil' so that the
     `finally' clauses are not executed.  If all the conditions were
     non-`nil', the loop returns `t':

          (if (loop for size in size-list always (> size 10))
              (some-big-sizes)
            (no-big-sizes))

`never CONDITION'
     This clause is like `always', except that the loop returns `t' if
     any conditions were false, or `nil' otherwise.

`thereis CONDITION'
     This clause stops the loop when the specified form is non-`nil';
     in this case, it returns that non-`nil' value.  If all the values
     were `nil', the loop returns `nil'.

\1f
File: cl.info,  Node: Accumulation Clauses,  Next: Other Clauses,  Prev: Iteration Clauses,  Up: Loop Facility

Accumulation Clauses
--------------------

These clauses cause the loop to accumulate information about the
specified Lisp FORM.  The accumulated result is returned from the loop
unless overridden, say, by a `return' clause.

`collect FORM'
     This clause collects the values of FORM into a list.  Several
     examples of `collect' appear elsewhere in this manual.

     The word `collecting' is a synonym for `collect', and likewise for
     the other accumulation clauses.

`append FORM'
     This clause collects lists of values into a result list using
     `append'.

`nconc FORM'
     This clause collects lists of values into a result list by
     destructively modifying the lists rather than copying them.

`concat FORM'
     This clause concatenates the values of the specified FORM into a
     string.  (It and the following clause are extensions to standard
     Common Lisp.)

`vconcat FORM'
     This clause concatenates the values of the specified FORM into a
     vector.

`count FORM'
     This clause counts the number of times the specified FORM
     evaluates to a non-`nil' value.

`sum FORM'
     This clause accumulates the sum of the values of the specified
     FORM, which must evaluate to a number.

`maximize FORM'
     This clause accumulates the maximum value of the specified FORM,
     which must evaluate to a number.  The return value is undefined if
     `maximize' is executed zero times.

`minimize FORM'
     This clause accumulates the minimum value of the specified FORM.

   Accumulation clauses can be followed by `into VAR' to cause the data
to be collected into variable VAR (which is automatically `let'-bound
during the loop) rather than an unnamed temporary variable.  Also,
`into' accumulations do not automatically imply a return value.  The
loop must use some explicit mechanism, such as `finally return', to
return the accumulated result.

   It is legal for several accumulation clauses of the same type to
accumulate into the same place.  From Steele:

     (loop for name in '(fred sue alice joe june)
           for kids in '((bob ken) () () (kris sunshine) ())
           collect name
           append kids)
          => (fred bob ken sue alice joe kris sunshine june)

\1f
File: cl.info,  Node: Other Clauses,  Prev: Accumulation Clauses,  Up: Loop Facility

Other Clauses
-------------

This section describes the remaining loop clauses.

`with VAR = VALUE'
     This clause binds a variable to a value around the loop, but
     otherwise leaves the variable alone during the loop.  The following
     loops are basically equivalent:

          (loop with x = 17 do ...)
          (let ((x 17)) (loop do ...))
          (loop for x = 17 then x do ...)

     Naturally, the variable VAR might be used for some purpose in the
     rest of the loop.  For example:

          (loop for x in my-list  with res = nil  do (push x res)
                finally return res)

     This loop inserts the elements of `my-list' at the front of a new
     list being accumulated in `res', then returns the list `res' at
     the end of the loop.  The effect is similar to that of a `collect'
     clause, but the list gets reversed by virtue of the fact that
     elements are being pushed onto the front of `res' rather than the
     end.

     If you omit the `=' term, the variable is initialized to `nil'.
     (Thus the `= nil' in the above example is unnecessary.)

     Bindings made by `with' are sequential by default, as if by
     `let*'.  Just like `for' clauses, `with' clauses can be linked
     with `and' to cause the bindings to be made by `let' instead.

`if CONDITION CLAUSE'
     This clause executes the following loop clause only if the
     specified condition is true.  The following CLAUSE should be an
     accumulation, `do', `return', `if', or `unless' clause.  Several
     clauses may be linked by separating them with `and'.  These
     clauses may be followed by `else' and a clause or clauses to
     execute if the condition was false.  The whole construct may
     optionally be followed by the word `end' (which may be used to
     disambiguate an `else' or `and' in a nested `if').

     The actual non-`nil' value of the condition form is available by
     the name `it' in the "then" part.  For example:

          (setq funny-numbers '(6 13 -1))
               => (6 13 -1)
          (loop for x below 10
                if (oddp x)
                  collect x into odds
                  and if (memq x funny-numbers) return (cdr it) end
                else
                  collect x into evens
                finally return (vector odds evens))
               => [(1 3 5 7 9) (0 2 4 6 8)]
          (setq funny-numbers '(6 7 13 -1))
               => (6 7 13 -1)
          (loop <same thing again>)
               => (13 -1)

     Note the use of `and' to put two clauses into the "then" part, one
     of which is itself an `if' clause.  Note also that `end', while
     normally optional, was necessary here to make it clear that the
     `else' refers to the outermost `if' clause.  In the first case,
     the loop returns a vector of lists of the odd and even values of
     X.  In the second case, the odd number 7 is one of the
     `funny-numbers' so the loop returns early; the actual returned
     value is based on the result of the `memq' call.

`when CONDITION CLAUSE'
     This clause is just a synonym for `if'.

`unless CONDITION CLAUSE'
     The `unless' clause is just like `if' except that the sense of the
     condition is reversed.

`named NAME'
     This clause gives a name other than `nil' to the implicit block
     surrounding the loop.  The NAME is the symbol to be used as the
     block name.

`initially [do] FORMS...'
     This keyword introduces one or more Lisp forms which will be
     executed before the loop itself begins (but after any variables
     requested by `for' or `with' have been bound to their initial
     values).  `initially' clauses can appear anywhere; if there are
     several, they are executed in the order they appear in the loop.
     The keyword `do' is optional.

`finally [do] FORMS...'
     This introduces Lisp forms which will be executed after the loop
     finishes (say, on request of a `for' or `while').  `initially' and
     `finally' clauses may appear anywhere in the loop construct, but
     they are executed (in the specified order) at the beginning or
     end, respectively, of the loop.

`finally return FORM'
     This says that FORM should be executed after the loop is done to
     obtain a return value.  (Without this, or some other clause like
     `collect' or `return', the loop will simply return `nil'.)
     Variables bound by `for', `with', or `into' will still contain
     their final values when FORM is executed.

`do FORMS...'
     The word `do' may be followed by any number of Lisp expressions
     which are executed as an implicit `progn' in the body of the loop.
     Many of the examples in this section illustrate the use of `do'.

`return FORM'
     This clause causes the loop to return immediately.  The following
     Lisp form is evaluated to give the return value of the `loop'
     form.  The `finally' clauses, if any, are not executed.  Of
     course, `return' is generally used inside an `if' or `unless', as
     its use in a top-level loop clause would mean the loop would never
     get to "loop" more than once.

     The clause `return FORM' is equivalent to `do (return FORM)' (or
     `return-from' if the loop was named).  The `return' clause is
     implemented a bit more efficiently, though.

   While there is no high-level way to add user extensions to `loop'
(comparable to `defsetf' for `setf', say), this package does offer two
properties called `cl-loop-handler' and `cl-loop-for-handler' which are
functions to be called when a given symbol is encountered as a
top-level loop clause or `for' clause, respectively.  Consult the
source code in file `cl-macs.el' for details.

   This package's `loop' macro is compatible with that of Common Lisp,
except that a few features are not implemented:  `loop-finish' and
data-type specifiers.  Naturally, the `for' clauses which iterate over
keymaps, overlays, intervals, frames, windows, and buffers are
Emacs-specific extensions.

\1f
File: cl.info,  Node: Multiple Values,  Prev: Loop Facility,  Up: Control Structure

Multiple Values
===============

Common Lisp functions can return zero or more results.  Emacs Lisp
functions, by contrast, always return exactly one result.  This package
makes no attempt to emulate Common Lisp multiple return values; Emacs
versions of Common Lisp functions that return more than one value
either return just the first value (as in `compiler-macroexpand') or
return a list of values (as in `get-setf-method').  This package _does_
define placeholders for the Common Lisp functions that work with
multiple values, but in Emacs Lisp these functions simply operate on
lists instead.  The `values' form, for example, is a synonym for `list'
in Emacs.

 - Special Form: multiple-value-bind (var...) values-form forms...
     This form evaluates VALUES-FORM, which must return a list of
     values.  It then binds the VARs to these respective values, as if
     by `let', and then executes the body FORMS.  If there are more
     VARs than values, the extra VARs are bound to `nil'.  If there are
     fewer VARs than values, the excess values are ignored.

 - Special Form: multiple-value-setq (var...) form
     This form evaluates FORM, which must return a list of values.  It
     then sets the VARs to these respective values, as if by `setq'.
     Extra VARs or values are treated the same as in
     `multiple-value-bind'.

   The older Quiroz package attempted a more faithful (but still
imperfect) emulation of Common Lisp multiple values.  The old method
"usually" simulated true multiple values quite well, but under certain
circumstances would leave spurious return values in memory where a
later, unrelated `multiple-value-bind' form would see them.

   Since a perfect emulation is not feasible in Emacs Lisp, this
package opts to keep it as simple and predictable as possible.

\1f
File: cl.info,  Node: Macros,  Next: Declarations,  Prev: Control Structure,  Up: Top

Macros
******

This package implements the various Common Lisp features of `defmacro',
such as destructuring, `&environment', and `&body'.  Top-level `&whole'
is not implemented for `defmacro' due to technical difficulties.  *Note
Argument Lists::.

   Destructuring is made available to the user by way of the following
macro:

 - Special Form: destructuring-bind arglist expr forms...
     This macro expands to code which executes FORMS, with the
     variables in ARGLIST bound to the list of values returned by EXPR.
     The ARGLIST can include all the features allowed for `defmacro'
     argument lists, including destructuring.  (The `&environment'
     keyword is not allowed.)  The macro expansion will signal an error
     if EXPR returns a list of the wrong number of arguments or with
     incorrect keyword arguments.

   This package also includes the Common Lisp `define-compiler-macro'
facility, which allows you to define compile-time expansions and
optimizations for your functions.

 - Special Form: define-compiler-macro name arglist forms...
     This form is similar to `defmacro', except that it only expands
     calls to NAME at compile-time; calls processed by the Lisp
     interpreter are not expanded, nor are they expanded by the
     `macroexpand' function.

     The argument list may begin with a `&whole' keyword and a
     variable.  This variable is bound to the macro-call form itself,
     i.e., to a list of the form `(NAME ARGS...)'.  If the macro
     expander returns this form unchanged, then the compiler treats it
     as a normal function call.  This allows compiler macros to work as
     optimizers for special cases of a function, leaving complicated
     cases alone.

     For example, here is a simplified version of a definition that
     appears as a standard part of this package:

          (define-compiler-macro member* (&whole form a list &rest keys)
            (if (and (null keys)
                     (eq (car-safe a) 'quote)
                     (not (floatp-safe (cadr a))))
                (list 'memq a list)
              form))

     This definition causes `(member* A LIST)' to change to a call to
     the faster `memq' in the common case where A is a
     non-floating-point constant; if A is anything else, or if there
     are any keyword arguments in the call, then the original `member*'
     call is left intact.  (The actual compiler macro for `member*'
     optimizes a number of other cases, including common `:test'
     predicates.)

 - Function: compiler-macroexpand form
     This function is analogous to `macroexpand', except that it
     expands compiler macros rather than regular macros.  It returns
     FORM unchanged if it is not a call to a function for which a
     compiler macro has been defined, or if that compiler macro decided
     to punt by returning its `&whole' argument.  Like `macroexpand',
     it expands repeatedly until it reaches a form for which no further
     expansion is possible.

   *Note Macro Bindings::, for descriptions of the `macrolet' and
`symbol-macrolet' forms for making "local" macro definitions.

\1f
File: cl.info,  Node: Declarations,  Next: Symbols,  Prev: Macros,  Up: Top

Declarations
************

Common Lisp includes a complex and powerful "declaration" mechanism
that allows you to give the compiler special hints about the types of
data that will be stored in particular variables, and about the ways
those variables and functions will be used.  This package defines
versions of all the Common Lisp declaration forms: `declare',
`locally', `proclaim', `declaim', and `the'.

   Most of the Common Lisp declarations are not currently useful in
Emacs Lisp, as the byte-code system provides little opportunity to
benefit from type information, and `special' declarations are redundant
in a fully dynamically-scoped Lisp.  A few declarations are meaningful
when the optimizing Emacs 19 byte compiler is being used, however.
Under the earlier non-optimizing compiler, these declarations will
effectively be ignored.

 - Function: proclaim decl-spec
     This function records a "global" declaration specified by
     DECL-SPEC.  Since `proclaim' is a function, DECL-SPEC is evaluated
     and thus should normally be quoted.

 - Special Form: declaim decl-specs...
     This macro is like `proclaim', except that it takes any number of
     DECL-SPEC arguments, and the arguments are unevaluated and
     unquoted.  The `declaim' macro also puts an `(eval-when (compile
     load eval) ...)' around the declarations so that they will be
     registered at compile-time as well as at run-time.  (This is vital,
     since normally the declarations are meant to influence the way the
     compiler treats the rest of the file that contains the `declaim'
     form.)

 - Special Form: declare decl-specs...
     This macro is used to make declarations within functions and other
     code.  Common Lisp allows declarations in various locations,
     generally at the beginning of any of the many "implicit `progn's"
     throughout Lisp syntax, such as function bodies, `let' bodies,
     etc.  Currently the only declaration understood by `declare' is
     `special'.

 - Special Form: locally declarations... forms...
     In this package, `locally' is no different from `progn'.

 - Special Form: the type form
     Type information provided by `the' is ignored in this package; in
     other words, `(the TYPE FORM)' is equivalent to FORM.  Future
     versions of the optimizing byte-compiler may make use of this
     information.

     For example, `mapcar' can map over both lists and arrays.  It is
     hard for the compiler to expand `mapcar' into an in-line loop
     unless it knows whether the sequence will be a list or an array
     ahead of time.  With `(mapcar 'car (the vector foo))', a future
     compiler would have enough information to expand the loop in-line.
     For now, Emacs Lisp will treat the above code as exactly equivalent
     to `(mapcar 'car foo)'.

   Each DECL-SPEC in a `proclaim', `declaim', or `declare' should be a
list beginning with a symbol that says what kind of declaration it is.
This package currently understands `special', `inline', `notinline',
`optimize', and `warn' declarations.  (The `warn' declaration is an
extension of standard Common Lisp.)  Other Common Lisp declarations,
such as `type' and `ftype', are silently ignored.

`special'
     Since all variables in Emacs Lisp are "special" (in the Common
     Lisp sense), `special' declarations are only advisory.  They
     simply tell the optimizing byte compiler that the specified
     variables are intentionally being referred to without being bound
     in the body of the function.  The compiler normally emits warnings
     for such references, since they could be typographical errors for
     references to local variables.

     The declaration `(declare (special VAR1 VAR2))' is equivalent to
     `(defvar VAR1) (defvar VAR2)' in the optimizing compiler, or to
     nothing at all in older compilers (which do not warn for non-local
     references).

     In top-level contexts, it is generally better to write `(defvar
     VAR)' than `(declaim (special VAR))', since `defvar' makes your
     intentions clearer.  But the older byte compilers can not handle
     `defvar's appearing inside of functions, while `(declare (special
     VAR))' takes care to work correctly with all compilers.

`inline'
     The `inline' DECL-SPEC lists one or more functions whose bodies
     should be expanded "in-line" into calling functions whenever the
     compiler is able to arrange for it.  For example, the Common Lisp
     function `cadr' is declared `inline' by this package so that the
     form `(cadr X)' will expand directly into `(car (cdr X))' when it
     is called in user functions, for a savings of one (relatively
     expensive) function call.

     The following declarations are all equivalent.  Note that the
     `defsubst' form is a convenient way to define a function and
     declare it inline all at once, but it is available only in Emacs
     19.

          (declaim (inline foo bar))
          (eval-when (compile load eval) (proclaim '(inline foo bar)))
          (proclaim-inline foo bar)      ; XEmacs only
          (defsubst foo (...) ...)       ; instead of defun; Emacs 19 only

     *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 function.

     In Common Lisp, it is possible to use `(declare (inline ...))'
     before a particular call to a function to cause just that call to
     be inlined; the current byte compilers provide no way to implement
     this, so `(declare (inline ...))' is currently ignored by this
     package.

`notinline'
     The `notinline' declaration lists functions which should not be
     inlined after all; it cancels a previous `inline' declaration.

`optimize'
     This declaration controls how much optimization is performed by
     the compiler.  Naturally, it is ignored by the earlier
     non-optimizing compilers.

     The word `optimize' is followed by any number of lists like
     `(speed 3)' or `(safety 2)'.  Common Lisp defines several
     optimization "qualities"; this package ignores all but `speed' and
     `safety'.  The value of a quality should be an integer from 0 to
     3, with 0 meaning "unimportant" and 3 meaning "very important."
     The default level for both qualities is 1.

     In this package, with the Emacs 19 optimizing compiler, the
     `speed' quality is tied to the `byte-compile-optimize' flag, which
     is set to `nil' for `(speed 0)' and to `t' for higher settings;
     and the `safety' quality is tied to the
     `byte-compile-delete-errors' flag, which is set to `t' for
     `(safety 3)' and to `nil' for all lower settings.  (The latter
     flag controls whether the compiler is allowed to optimize out code
     whose only side-effect could be to signal an error, e.g.,
     rewriting `(progn foo bar)' to `bar' when it is not known whether
     `foo' will be bound at run-time.)

     Note that even compiling with `(safety 0)', the Emacs byte-code
     system provides sufficient checking to prevent real harm from
     being done.  For example, barring serious bugs in Emacs itself,
     Emacs will not crash with a segmentation fault just because of an
     error in a fully-optimized Lisp program.

     The `optimize' declaration is normally used in a top-level
     `proclaim' or `declaim' in a file; Common Lisp allows it to be
     used with `declare' to set the level of optimization locally for a
     given form, but this will not work correctly with the current
     version of the optimizing compiler.  (The `declare' will set the
     new optimization level, but that level will not automatically be
     unset after the enclosing form is done.)

`warn'
     This declaration controls what sorts of warnings are generated by
     the byte compiler.  Again, only the optimizing compiler generates
     warnings.  The word `warn' is followed by any number of "warning
     qualities," similar in form to optimization qualities.  The
     currently supported warning types are `redefine', `callargs',
     `unresolved', and `free-vars'; in the current system, a value of 0
     will disable these warnings and any higher value will enable them.
     See the documentation for the optimizing byte compiler for details.

\1f
File: cl.info,  Node: Symbols,  Next: Numbers,  Prev: Declarations,  Up: Top

Symbols
*******

This package defines several symbol-related features that were missing
from Emacs Lisp.

* Menu:

* Property Lists::       `get*', `remprop', `getf', `remf'
* Creating Symbols::     `gensym', `gentemp'

\1f
File: cl.info,  Node: Property Lists,  Next: Creating Symbols,  Prev: Symbols,  Up: Symbols

Property Lists
==============

These functions augment the standard Emacs Lisp functions `get' and
`put' for operating on properties attached to symbols.  There are also
functions for working with property lists as first-class data
structures not attached to particular symbols.

 - Function: get* symbol property &optional default
     This function is like `get', except that if the property is not
     found, the DEFAULT argument provides the return value.  (The Emacs
     Lisp `get' function always uses `nil' as the default; this
     package's `get*' is equivalent to Common Lisp's `get'.)

     The `get*' function is `setf'-able; when used in this fashion, the
     DEFAULT argument is allowed but ignored.

 - Function: remprop symbol property
     This function removes the entry for PROPERTY from the property
     list of SYMBOL.  It returns a true value if the property was
     indeed found and removed, or `nil' if there was no such property.
     (This function was probably omitted from Emacs originally because,
     since `get' did not allow a DEFAULT, it was very difficult to
     distinguish between a missing property and a property whose value
     was `nil'; thus, setting a property to `nil' was close enough to
     `remprop' for most purposes.)

 - Function: getf place property &optional default
     This function scans the list PLACE as if it were a property list,
     i.e., a list of alternating property names and values.  If an
     even-numbered element of PLACE is found which is `eq' to PROPERTY,
     the following odd-numbered element is returned.  Otherwise,
     DEFAULT is returned (or `nil' if no default is given).

     In particular,

          (get sym prop)  ==  (getf (symbol-plist sym) prop)

     It is legal to use `getf' as a `setf' place, in which case its
     PLACE argument must itself be a legal `setf' place.  The DEFAULT
     argument, if any, is ignored in this context.  The effect is to
     change (via `setcar') the value cell in the list that corresponds
     to PROPERTY, or to cons a new property-value pair onto the list if
     the property is not yet present.

          (put sym prop val)  ==  (setf (getf (symbol-plist sym) prop) val)

     The `get' and `get*' functions are also `setf'-able.  The fact
     that `default' is ignored can sometimes be useful:

          (incf (get* 'foo 'usage-count 0))

     Here, symbol `foo''s `usage-count' property is incremented if it
     exists, or set to 1 (an incremented 0) otherwise.

     When not used as a `setf' form, `getf' is just a regular function
     and its PLACE argument can actually be any Lisp expression.

 - Special Form: remf place property
     This macro removes the property-value pair for PROPERTY from the
     property list stored at PLACE, which is any `setf'-able place
     expression.  It returns true if the property was found.  Note that
     if PROPERTY happens to be first on the list, this will effectively
     do a `(setf PLACE (cddr PLACE))', whereas if it occurs later, this
     simply uses `setcdr' to splice out the property and value cells.

\1f
File: cl.info,  Node: Creating Symbols,  Prev: Property Lists,  Up: Symbols

Creating Symbols
================

These functions create unique symbols, typically for use as temporary
variables.

 - Function: gensym &optional x
     This function creates a new, uninterned symbol (using
     `make-symbol') with a unique name.  (The name of an uninterned
     symbol is relevant only if the symbol is printed.)  By default,
     the name is generated from an increasing sequence of numbers,
     `G1000', `G1001', `G1002', etc.  If the optional argument X is a
     string, that string is used as a prefix instead of `G'.
     Uninterned symbols are used in macro expansions for temporary
     variables, to ensure that their names will not conflict with
     "real" variables in the user's code.

 - Variable: *gensym-counter*
     This variable holds the counter used to generate `gensym' names.
     It is incremented after each use by `gensym'.  In Common Lisp this
     is initialized with 0, but this package initializes it with a
     random (time-dependent) value to avoid trouble when two files that
     each used `gensym' in their compilation are loaded together.

     *XEmacs note:* As of XEmacs 21.0, an uninterned symbol remains
     uninterned even after being dumped to bytecode.  Older versions of
     Emacs didn't distinguish the printed representation of interned
     and uninterned symbols, so their names had to be treated more
     carefully.

 - Function: gentemp &optional x
     This function is like `gensym', except that it produces a new
     _interned_ symbol.  If the symbol that is generated already
     exists, the function keeps incrementing the counter and trying
     again until a new symbol is generated.

   The Quiroz `cl.el' package also defined a `defkeyword' form for
creating self-quoting keyword symbols.  This package automatically
creates all keywords that are called for by `&key' argument specifiers,
and discourages the use of keywords as data unrelated to keyword
arguments, so the `defkeyword' form has been discontinued.

\1f
File: cl.info,  Node: Numbers,  Next: Sequences,  Prev: Symbols,  Up: Top

Numbers
*******

This section defines a few simple Common Lisp operations on numbers
which were left out of Emacs Lisp.

* Menu:

* Predicates on Numbers::       `plusp', `oddp', `floatp-safe', etc.
* Numerical Functions::         `abs', `expt', `floor*', etc.
* Random Numbers::              `random*', `make-random-state'
* Implementation Parameters::   `most-positive-fixnum', `most-positive-float'

\1f
File: cl.info,  Node: Predicates on Numbers,  Next: Numerical Functions,  Prev: Numbers,  Up: Numbers

Predicates on Numbers
=====================

These functions return `t' if the specified condition is true of the
numerical argument, or `nil' otherwise.

 - Function: plusp number
     This predicate tests whether NUMBER is positive.  It is an error
     if the argument is not a number.

 - Function: minusp number
     This predicate tests whether NUMBER is negative.  It is an error
     if the argument is not a number.

 - Function: oddp integer
     This predicate tests whether INTEGER is odd.  It is an error if
     the argument is not an integer.

 - Function: evenp integer
     This predicate tests whether INTEGER is even.  It is an error if
     the argument is not an integer.

 - Function: floatp-safe object
     This predicate tests whether OBJECT is a floating-point number.
     On systems that support floating-point, this is equivalent to
     `floatp'.  On other systems, this always returns `nil'.

\1f
File: cl.info,  Node: Numerical Functions,  Next: Random Numbers,  Prev: Predicates on Numbers,  Up: Numbers

Numerical Functions
===================

These functions perform various arithmetic operations on numbers.

 - Function: abs number
     This function returns the absolute value of NUMBER.  (Newer
     versions of Emacs provide this as a built-in function; this package
     defines `abs' only for Emacs 18 versions which don't provide it as
     a primitive.)

 - Function: expt base power
     This function returns BASE raised to the power of NUMBER.  (Newer
     versions of Emacs provide this as a built-in function; this
     package defines `expt' only for Emacs 18 versions which don't
     provide it as a primitive.)

 - Function: gcd &rest integers
     This function returns the Greatest Common Divisor of the arguments.
     For one argument, it returns the absolute value of that argument.
     For zero arguments, it returns zero.

 - Function: lcm &rest integers
     This function returns the Least Common Multiple of the arguments.
     For one argument, it returns the absolute value of that argument.
     For zero arguments, it returns one.

 - Function: isqrt integer
     This function computes the "integer square root" of its integer
     argument, i.e., the greatest integer less than or equal to the true
     square root of the argument.

 - Function: floor* number &optional divisor
     This function implements the Common Lisp `floor' function.  It is
     called `floor*' to avoid name conflicts with the simpler `floor'
     function built-in to Emacs 19.

     With one argument, `floor*' returns a list of two numbers: The
     argument rounded down (toward minus infinity) to an integer, and
     the "remainder" which would have to be added back to the first
     return value to yield the argument again.  If the argument is an
     integer X, the result is always the list `(X 0)'.  If the argument
     is an Emacs 19 floating-point number, the first result is a Lisp
     integer and the second is a Lisp float between 0 (inclusive) and 1
     (exclusive).

     With two arguments, `floor*' divides NUMBER by DIVISOR, and
     returns the floor of the quotient and the corresponding remainder
     as a list of two numbers.  If `(floor* X Y)' returns `(Q R)', then
     `Q*Y + R = X', with R between 0 (inclusive) and R (exclusive).
     Also, note that `(floor* X)' is exactly equivalent to `(floor* X
     1)'.

     This function is entirely compatible with Common Lisp's `floor'
     function, except that it returns the two results in a list since
     Emacs Lisp does not support multiple-valued functions.

 - Function: ceiling* number &optional divisor
     This function implements the Common Lisp `ceiling' function, which
     is analogous to `floor' except that it rounds the argument or
     quotient of the arguments up toward plus infinity.  The remainder
     will be between 0 and minus R.

 - Function: truncate* number &optional divisor
     This function implements the Common Lisp `truncate' function,
     which is analogous to `floor' except that it rounds the argument
     or quotient of the arguments toward zero.  Thus it is equivalent
     to `floor*' if the argument or quotient is positive, or to
     `ceiling*' otherwise.  The remainder has the same sign as NUMBER.

 - Function: round* number &optional divisor
     This function implements the Common Lisp `round' function, which
     is analogous to `floor' except that it rounds the argument or
     quotient of the arguments to the nearest integer.  In the case of
     a tie (the argument or quotient is exactly halfway between two
     integers), it rounds to the even integer.

 - Function: mod* number divisor
     This function returns the same value as the second return value of
     `floor'.

 - Function: rem* number divisor
     This function returns the same value as the second return value of
     `truncate'.

   These definitions are compatible with those in the Quiroz `cl.el'
package, except that this package appends `*' to certain function names
to avoid conflicts with existing Emacs 19 functions, and that the
mechanism for returning multiple values is different.

\1f
File: cl.info,  Node: Random Numbers,  Next: Implementation Parameters,  Prev: Numerical Functions,  Up: Numbers

Random Numbers
==============

This package also provides an implementation of the Common Lisp random
number generator.  It uses its own additive-congruential algorithm,
which is much more likely to give statistically clean random numbers
than the simple generators supplied by many operating systems.

 - Function: random* number &optional state
     This function returns a random nonnegative number less than
     NUMBER, and of the same type (either integer or floating-point).
     The STATE argument should be a `random-state' object which holds
     the state of the random number generator.  The function modifies
     this state object as a side effect.  If STATE is omitted, it
     defaults to the variable `*random-state*', which contains a
     pre-initialized `random-state' object.

 - Variable: *random-state*
     This variable contains the system "default" `random-state' object,
     used for calls to `random*' that do not specify an alternative
     state object.  Since any number of programs in the Emacs process
     may be accessing `*random-state*' in interleaved fashion, the
     sequence generated from this variable will be irreproducible for
     all intents and purposes.

 - Function: make-random-state &optional state
     This function creates or copies a `random-state' object.  If STATE
     is omitted or `nil', it returns a new copy of `*random-state*'.
     This is a copy in the sense that future sequences of calls to
     `(random* N)' and `(random* N S)' (where S is the new random-state
     object) will return identical sequences of random numbers.

     If STATE is a `random-state' object, this function returns a copy
     of that object.  If STATE is `t', this function returns a new
     `random-state' object seeded from the date and time.  As an
     extension to Common Lisp, STATE may also be an integer in which
     case the new object is seeded from that integer; each different
     integer seed will result in a completely different sequence of
     random numbers.

     It is legal to print a `random-state' object to a buffer or file
     and later read it back with `read'.  If a program wishes to use a
     sequence of pseudo-random numbers which can be reproduced later
     for debugging, it can call `(make-random-state t)' to get a new
     sequence, then print this sequence to a file.  When the program is
     later rerun, it can read the original run's random-state from the
     file.

 - Function: random-state-p object
     This predicate returns `t' if OBJECT is a `random-state' object,
     or `nil' otherwise.