1 This is Info file ../info/cl.info, produced by Makeinfo version 1.68
2 from the input file cl.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Common Lisp: (cl). GNU Emacs Common Lisp emulation package.
9 This file documents the GNU Emacs Common Lisp emulation package.
11 Copyright (C) 1993 Free Software Foundation, Inc.
13 Permission is granted to make and distribute verbatim copies of this
14 manual provided the copyright notice and this permission notice are
15 preserved on all copies.
17 Permission is granted to copy and distribute modified versions of
18 this manual under the conditions for verbatim copying, provided also
19 that the section entitled "GNU General Public License" is included
20 exactly as in the original, and provided that the entire resulting
21 derived work is distributed under the terms of a permission notice
22 identical to this one.
24 Permission is granted to copy and distribute translations of this
25 manual into another language, under the above conditions for modified
26 versions, except that the section entitled "GNU General Public License"
27 may be included in a translation approved by the author instead of in
31 File: cl.info, Node: For Clauses, Next: Iteration Clauses, Prev: Loop Examples, Up: Loop Facility
36 Most loops are governed by one or more `for' clauses. A `for' clause
37 simultaneously describes variables to be bound, how those variables are
38 to be stepped during the loop, and usually an end condition based on
41 The word `as' is a synonym for the word `for'. This word is
42 followed by a variable name, then a word like `from' or `across' that
43 describes the kind of iteration desired. In Common Lisp, the phrase
44 `being the' sometimes precedes the type of iteration; in this package
45 both `being' and `the' are optional. The word `each' is a synonym for
46 `the', and the word that follows it may be singular or plural: `for x
47 being the elements of y' or `for x being each element of y'. Which
48 form you use is purely a matter of style.
50 The variable is bound around the loop as if by `let':
53 (loop for i from 1 to 10 do (do-something-with i))
57 `for VAR from EXPR1 to EXPR2 by EXPR3'
58 This type of `for' clause creates a counting loop. Each of the
59 three sub-terms is optional, though there must be at least one
60 term so that the clause is marked as a counting clause.
62 The three expressions are the starting value, the ending value, and
63 the step value, respectively, of the variable. The loop counts
64 upwards by default (EXPR3 must be positive), from EXPR1 to EXPR2
65 inclusively. If you omit the `from' term, the loop counts from
66 zero; if you omit the `to' term, the loop counts forever without
67 stopping (unless stopped by some other loop clause, of course); if
68 you omit the `by' term, the loop counts in steps of one.
70 You can replace the word `from' with `upfrom' or `downfrom' to
71 indicate the direction of the loop. Likewise, you can replace
72 `to' with `upto' or `downto'. For example, `for x from 5 downto
73 1' executes five times with `x' taking on the integers from 5 down
74 to 1 in turn. Also, you can replace `to' with `below' or `above',
75 which are like `upto' and `downto' respectively except that they
76 are exclusive rather than inclusive limits:
78 (loop for x to 10 collect x)
79 => (0 1 2 3 4 5 6 7 8 9 10)
80 (loop for x below 10 collect x)
81 => (0 1 2 3 4 5 6 7 8 9)
83 The `by' value is always positive, even for downward-counting
84 loops. Some sort of `from' value is required for downward loops;
85 `for x downto 5' is not a legal loop clause all by itself.
87 `for VAR in LIST by FUNCTION'
88 This clause iterates VAR over all the elements of LIST, in turn.
89 If you specify the `by' term, then FUNCTION is used to traverse
90 the list instead of `cdr'; it must be a function taking one
91 argument. For example:
93 (loop for x in '(1 2 3 4 5 6) collect (* x x))
95 (loop for x in '(1 2 3 4 5 6) by 'cddr collect (* x x))
98 `for VAR on LIST by FUNCTION'
99 This clause iterates VAR over all the cons cells of LIST.
101 (loop for x on '(1 2 3 4) collect x)
102 => ((1 2 3 4) (2 3 4) (3 4) (4))
104 With `by', there is no real reason that the `on' expression must
105 be a list. For example:
107 (loop for x on first-animal by 'next-animal collect x)
109 where `(next-animal x)' takes an "animal" X and returns the next
110 in the (assumed) sequence of animals, or `nil' if X was the last
111 animal in the sequence.
113 `for VAR in-ref LIST by FUNCTION'
114 This is like a regular `in' clause, but VAR becomes a `setf'-able
115 "reference" onto the elements of the list rather than just a
116 temporary variable. For example,
118 (loop for x in-ref my-list do (incf x))
120 increments every element of `my-list' in place. This clause is an
121 extension to standard Common Lisp.
123 `for VAR across ARRAY'
124 This clause iterates VAR over all the elements of ARRAY, which may
125 be a vector or a string.
127 (loop for x across "aeiou"
128 do (use-vowel (char-to-string x)))
130 `for VAR across-ref ARRAY'
131 This clause iterates over an array, with VAR a `setf'-able
132 reference onto the elements; see `in-ref' above.
134 `for VAR being the elements of SEQUENCE'
135 This clause iterates over the elements of SEQUENCE, which may be a
136 list, vector, or string. Since the type must be determined at
137 run-time, this is somewhat less efficient than `in' or `across'.
138 The clause may be followed by the additional term `using (index
139 VAR2)' to cause VAR2 to be bound to the successive indices
140 (starting at 0) of the elements.
142 This clause type is taken from older versions of the `loop' macro,
143 and is not present in modern Common Lisp. The `using (sequence
144 ...)' term of the older macros is not supported.
146 `for VAR being the elements of-ref SEQUENCE'
147 This clause iterates over a sequence, with VAR a `setf'-able
148 reference onto the elements; see `in-ref' above.
150 `for VAR being the symbols [of OBARRAY]'
151 This clause iterates over symbols, either over all interned symbols
152 or over all symbols in OBARRAY. The loop is executed with VAR
153 bound to each symbol in turn. The symbols are visited in an
158 (loop for sym being the symbols
160 when (string-match "^map" (symbol-name sym))
163 returns a list of all the functions whose names begin with `map'.
165 The Common Lisp words `external-symbols' and `present-symbols' are
166 also recognized but are equivalent to `symbols' in Emacs Lisp.
168 Due to a minor implementation restriction, it will not work to have
169 more than one `for' clause iterating over symbols, hash tables,
170 keymaps, overlays, or intervals in a given `loop'. Fortunately,
171 it would rarely if ever be useful to do so. It *is* legal to mix
172 one of these types of clauses with other clauses like `for ... to'
175 `for VAR being the hash-keys of HASH-TABLE'
176 This clause iterates over the entries in HASH-TABLE. For each
177 hash table entry, VAR is bound to the entry's key. If you write
178 `the hash-values' instead, VAR is bound to the values of the
179 entries. The clause may be followed by the additional term `using
180 (hash-values VAR2)' (where `hash-values' is the opposite word of
181 the word following `the') to cause VAR and VAR2 to be bound to the
182 two parts of each hash table entry.
184 `for VAR being the key-codes of KEYMAP'
185 This clause iterates over the entries in KEYMAP. In GNU Emacs 18
186 and 19, keymaps are either alists or vectors, and key-codes are
187 integers or symbols. In XEmacs, keymaps are a special new data
188 type, and key-codes are symbols or lists of symbols. The
189 iteration does not enter nested keymaps or inherited (parent)
190 keymaps. You can use `the key-bindings' to access the commands
191 bound to the keys rather than the key codes, and you can add a
192 `using' clause to access both the codes and the bindings together.
194 `for VAR being the key-seqs of KEYMAP'
195 This clause iterates over all key sequences defined by KEYMAP and
196 its nested keymaps, where VAR takes on values which are strings in
197 Emacs 18 or vectors in Emacs 19. The strings or vectors are
198 reused for each iteration, so you must copy them if you wish to
199 keep them permanently. You can add a `using (key-bindings ...)'
200 clause to get the command bindings as well.
202 `for VAR being the overlays [of BUFFER] ...'
203 This clause iterates over the Emacs 19 "overlays" or XEmacs
204 "extents" of a buffer (the clause `extents' is synonymous with
205 `overlays'). Under Emacs 18, this clause iterates zero times. If
206 the `of' term is omitted, the current buffer is used. This clause
207 also accepts optional `from POS' and `to POS' terms, limiting the
208 clause to overlays which overlap the specified region.
210 `for VAR being the intervals [of BUFFER] ...'
211 This clause iterates over all intervals of a buffer with constant
212 text properties. The variable VAR will be bound to conses of
213 start and end positions, where one start position is always equal
214 to the previous end position. The clause allows `of', `from',
215 `to', and `property' terms, where the latter term restricts the
216 search to just the specified property. The `of' term may specify
217 either a buffer or a string. This clause is useful only in GNU
218 Emacs 19; in other versions, all buffers and strings consist of a
221 `for VAR being the frames'
222 This clause iterates over all frames, i.e., X window system windows
223 open on Emacs files. This clause works only under Emacs 19. The
224 clause `screens' is a synonym for `frames'. The frames are
225 visited in `next-frame' order starting from `selected-frame'.
227 `for VAR being the windows [of FRAME]'
228 This clause iterates over the windows (in the Emacs sense) of the
229 current frame, or of the specified FRAME. (In Emacs 18 there is
230 only ever one frame, and the `of' term is not allowed there.)
232 `for VAR being the buffers'
233 This clause iterates over all buffers in Emacs. It is equivalent
234 to `for VAR in (buffer-list)'.
236 `for VAR = EXPR1 then EXPR2'
237 This clause does a general iteration. The first time through the
238 loop, VAR will be bound to EXPR1. On the second and successive
239 iterations it will be set by evaluating EXPR2 (which may refer to
240 the old value of VAR). For example, these two loops are
241 effectively the same:
243 (loop for x on my-list by 'cddr do ...)
244 (loop for x = my-list then (cddr x) while x do ...)
246 Note that this type of `for' clause does not imply any sort of
247 terminating condition; the above example combines it with a
248 `while' clause to tell when to end the loop.
250 If you omit the `then' term, EXPR1 is used both for the initial
251 setting and for successive settings:
253 (loop for x = (random) when (> x 0) return x)
255 This loop keeps taking random numbers from the `(random)' function
256 until it gets a positive one, which it then returns.
258 If you include several `for' clauses in a row, they are treated
259 sequentially (as if by `let*' and `setq'). You can instead use the
260 word `and' to link the clauses, in which case they are processed in
261 parallel (as if by `let' and `psetq').
263 (loop for x below 5 for y = nil then x collect (list x y))
264 => ((0 nil) (1 1) (2 2) (3 3) (4 4))
265 (loop for x below 5 and y = nil then x collect (list x y))
266 => ((0 nil) (1 0) (2 1) (3 2) (4 3))
268 In the first loop, `y' is set based on the value of `x' that was just
269 set by the previous clause; in the second loop, `x' and `y' are set
270 simultaneously so `y' is set based on the value of `x' left over from
271 the previous time through the loop.
273 Another feature of the `loop' macro is "destructuring", similar in
274 concept to the destructuring provided by `defmacro'. The VAR part of
275 any `for' clause can be given as a list of variables instead of a
276 single variable. The values produced during loop execution must be
277 lists; the values in the lists are stored in the corresponding
280 (loop for (x y) in '((2 3) (4 5) (6 7)) collect (+ x y))
283 In loop destructuring, if there are more values than variables the
284 trailing values are ignored, and if there are more variables than
285 values the trailing variables get the value `nil'. If `nil' is used as
286 a variable name, the corresponding values are ignored. Destructuring
287 may be nested, and dotted lists of variables like `(x . y)' are allowed.
290 File: cl.info, Node: Iteration Clauses, Next: Accumulation Clauses, Prev: For Clauses, Up: Loop Facility
295 Aside from `for' clauses, there are several other loop clauses that
296 control the way the loop operates. They might be used by themselves,
297 or in conjunction with one or more `for' clauses.
300 This clause simply counts up to the specified number using an
301 internal temporary variable. The loops
303 (loop repeat n do ...)
304 (loop for temp to n do ...)
306 are identical except that the second one forces you to choose a
307 name for a variable you aren't actually going to use.
310 This clause stops the loop when the specified condition (any Lisp
311 expression) becomes `nil'. For example, the following two loops
312 are equivalent, except for the implicit `nil' block that surrounds
315 (while COND FORMS...)
316 (loop while COND do FORMS...)
319 This clause stops the loop when the specified condition is true,
323 This clause stops the loop when the specified condition is `nil'.
324 Unlike `while', it stops the loop using `return nil' so that the
325 `finally' clauses are not executed. If all the conditions were
326 non-`nil', the loop returns `t':
328 (if (loop for size in size-list always (> size 10))
333 This clause is like `always', except that the loop returns `t' if
334 any conditions were false, or `nil' otherwise.
337 This clause stops the loop when the specified form is non-`nil';
338 in this case, it returns that non-`nil' value. If all the values
339 were `nil', the loop returns `nil'.
342 File: cl.info, Node: Accumulation Clauses, Next: Other Clauses, Prev: Iteration Clauses, Up: Loop Facility
347 These clauses cause the loop to accumulate information about the
348 specified Lisp FORM. The accumulated result is returned from the loop
349 unless overridden, say, by a `return' clause.
352 This clause collects the values of FORM into a list. Several
353 examples of `collect' appear elsewhere in this manual.
355 The word `collecting' is a synonym for `collect', and likewise for
356 the other accumulation clauses.
359 This clause collects lists of values into a result list using
363 This clause collects lists of values into a result list by
364 destructively modifying the lists rather than copying them.
367 This clause concatenates the values of the specified FORM into a
368 string. (It and the following clause are extensions to standard
372 This clause concatenates the values of the specified FORM into a
376 This clause counts the number of times the specified FORM
377 evaluates to a non-`nil' value.
380 This clause accumulates the sum of the values of the specified
381 FORM, which must evaluate to a number.
384 This clause accumulates the maximum value of the specified FORM,
385 which must evaluate to a number. The return value is undefined if
386 `maximize' is executed zero times.
389 This clause accumulates the minimum value of the specified FORM.
391 Accumulation clauses can be followed by `into VAR' to cause the data
392 to be collected into variable VAR (which is automatically `let'-bound
393 during the loop) rather than an unnamed temporary variable. Also,
394 `into' accumulations do not automatically imply a return value. The
395 loop must use some explicit mechanism, such as `finally return', to
396 return the accumulated result.
398 It is legal for several accumulation clauses of the same type to
399 accumulate into the same place. From Steele:
401 (loop for name in '(fred sue alice joe june)
402 for kids in '((bob ken) () () (kris sunshine) ())
405 => (fred bob ken sue alice joe kris sunshine june)
408 File: cl.info, Node: Other Clauses, Prev: Accumulation Clauses, Up: Loop Facility
413 This section describes the remaining loop clauses.
416 This clause binds a variable to a value around the loop, but
417 otherwise leaves the variable alone during the loop. The following
418 loops are basically equivalent:
420 (loop with x = 17 do ...)
421 (let ((x 17)) (loop do ...))
422 (loop for x = 17 then x do ...)
424 Naturally, the variable VAR might be used for some purpose in the
425 rest of the loop. For example:
427 (loop for x in my-list with res = nil do (push x res)
430 This loop inserts the elements of `my-list' at the front of a new
431 list being accumulated in `res', then returns the list `res' at
432 the end of the loop. The effect is similar to that of a `collect'
433 clause, but the list gets reversed by virtue of the fact that
434 elements are being pushed onto the front of `res' rather than the
437 If you omit the `=' term, the variable is initialized to `nil'.
438 (Thus the `= nil' in the above example is unnecessary.)
440 Bindings made by `with' are sequential by default, as if by
441 `let*'. Just like `for' clauses, `with' clauses can be linked
442 with `and' to cause the bindings to be made by `let' instead.
444 `if CONDITION CLAUSE'
445 This clause executes the following loop clause only if the
446 specified condition is true. The following CLAUSE should be an
447 accumulation, `do', `return', `if', or `unless' clause. Several
448 clauses may be linked by separating them with `and'. These
449 clauses may be followed by `else' and a clause or clauses to
450 execute if the condition was false. The whole construct may
451 optionally be followed by the word `end' (which may be used to
452 disambiguate an `else' or `and' in a nested `if').
454 The actual non-`nil' value of the condition form is available by
455 the name `it' in the "then" part. For example:
457 (setq funny-numbers '(6 13 -1))
462 and if (memq x funny-numbers) return (cdr it) end
465 finally return (vector odds evens))
466 => [(1 3 5 7 9) (0 2 4 6 8)]
467 (setq funny-numbers '(6 7 13 -1))
469 (loop <same thing again>)
472 Note the use of `and' to put two clauses into the "then" part, one
473 of which is itself an `if' clause. Note also that `end', while
474 normally optional, was necessary here to make it clear that the
475 `else' refers to the outermost `if' clause. In the first case,
476 the loop returns a vector of lists of the odd and even values of
477 X. In the second case, the odd number 7 is one of the
478 `funny-numbers' so the loop returns early; the actual returned
479 value is based on the result of the `memq' call.
481 `when CONDITION CLAUSE'
482 This clause is just a synonym for `if'.
484 `unless CONDITION CLAUSE'
485 The `unless' clause is just like `if' except that the sense of the
486 condition is reversed.
489 This clause gives a name other than `nil' to the implicit block
490 surrounding the loop. The NAME is the symbol to be used as the
493 `initially [do] FORMS...'
494 This keyword introduces one or more Lisp forms which will be
495 executed before the loop itself begins (but after any variables
496 requested by `for' or `with' have been bound to their initial
497 values). `initially' clauses can appear anywhere; if there are
498 several, they are executed in the order they appear in the loop.
499 The keyword `do' is optional.
501 `finally [do] FORMS...'
502 This introduces Lisp forms which will be executed after the loop
503 finishes (say, on request of a `for' or `while'). `initially' and
504 `finally' clauses may appear anywhere in the loop construct, but
505 they are executed (in the specified order) at the beginning or
506 end, respectively, of the loop.
508 `finally return FORM'
509 This says that FORM should be executed after the loop is done to
510 obtain a return value. (Without this, or some other clause like
511 `collect' or `return', the loop will simply return `nil'.)
512 Variables bound by `for', `with', or `into' will still contain
513 their final values when FORM is executed.
516 The word `do' may be followed by any number of Lisp expressions
517 which are executed as an implicit `progn' in the body of the loop.
518 Many of the examples in this section illustrate the use of `do'.
521 This clause causes the loop to return immediately. The following
522 Lisp form is evaluated to give the return value of the `loop'
523 form. The `finally' clauses, if any, are not executed. Of
524 course, `return' is generally used inside an `if' or `unless', as
525 its use in a top-level loop clause would mean the loop would never
526 get to "loop" more than once.
528 The clause `return FORM' is equivalent to `do (return FORM)' (or
529 `return-from' if the loop was named). The `return' clause is
530 implemented a bit more efficiently, though.
532 While there is no high-level way to add user extensions to `loop'
533 (comparable to `defsetf' for `setf', say), this package does offer two
534 properties called `cl-loop-handler' and `cl-loop-for-handler' which are
535 functions to be called when a given symbol is encountered as a
536 top-level loop clause or `for' clause, respectively. Consult the
537 source code in file `cl-macs.el' for details.
539 This package's `loop' macro is compatible with that of Common Lisp,
540 except that a few features are not implemented: `loop-finish' and
541 data-type specifiers. Naturally, the `for' clauses which iterate over
542 keymaps, overlays, intervals, frames, windows, and buffers are
543 Emacs-specific extensions.
546 File: cl.info, Node: Multiple Values, Prev: Loop Facility, Up: Control Structure
551 Common Lisp functions can return zero or more results. Emacs Lisp
552 functions, by contrast, always return exactly one result. This package
553 makes no attempt to emulate Common Lisp multiple return values; Emacs
554 versions of Common Lisp functions that return more than one value
555 either return just the first value (as in `compiler-macroexpand') or
556 return a list of values (as in `get-setf-method'). This package *does*
557 define placeholders for the Common Lisp functions that work with
558 multiple values, but in Emacs Lisp these functions simply operate on
559 lists instead. The `values' form, for example, is a synonym for `list'
562 - Special Form: multiple-value-bind (VAR...) VALUES-FORM FORMS...
563 This form evaluates VALUES-FORM, which must return a list of
564 values. It then binds the VARs to these respective values, as if
565 by `let', and then executes the body FORMS. If there are more
566 VARs than values, the extra VARs are bound to `nil'. If there are
567 fewer VARs than values, the excess values are ignored.
569 - Special Form: multiple-value-setq (VAR...) FORM
570 This form evaluates FORM, which must return a list of values. It
571 then sets the VARs to these respective values, as if by `setq'.
572 Extra VARs or values are treated the same as in
573 `multiple-value-bind'.
575 The older Quiroz package attempted a more faithful (but still
576 imperfect) emulation of Common Lisp multiple values. The old method
577 "usually" simulated true multiple values quite well, but under certain
578 circumstances would leave spurious return values in memory where a
579 later, unrelated `multiple-value-bind' form would see them.
581 Since a perfect emulation is not feasible in Emacs Lisp, this
582 package opts to keep it as simple and predictable as possible.
585 File: cl.info, Node: Macros, Next: Declarations, Prev: Control Structure, Up: Top
590 This package implements the various Common Lisp features of `defmacro',
591 such as destructuring, `&environment', and `&body'. Top-level `&whole'
592 is not implemented for `defmacro' due to technical difficulties. *Note
595 Destructuring is made available to the user by way of the following
598 - Special Form: destructuring-bind ARGLIST EXPR FORMS...
599 This macro expands to code which executes FORMS, with the
600 variables in ARGLIST bound to the list of values returned by EXPR.
601 The ARGLIST can include all the features allowed for `defmacro'
602 argument lists, including destructuring. (The `&environment'
603 keyword is not allowed.) The macro expansion will signal an error
604 if EXPR returns a list of the wrong number of arguments or with
605 incorrect keyword arguments.
607 This package also includes the Common Lisp `define-compiler-macro'
608 facility, which allows you to define compile-time expansions and
609 optimizations for your functions.
611 - Special Form: define-compiler-macro NAME ARGLIST FORMS...
612 This form is similar to `defmacro', except that it only expands
613 calls to NAME at compile-time; calls processed by the Lisp
614 interpreter are not expanded, nor are they expanded by the
615 `macroexpand' function.
617 The argument list may begin with a `&whole' keyword and a
618 variable. This variable is bound to the macro-call form itself,
619 i.e., to a list of the form `(NAME ARGS...)'. If the macro
620 expander returns this form unchanged, then the compiler treats it
621 as a normal function call. This allows compiler macros to work as
622 optimizers for special cases of a function, leaving complicated
625 For example, here is a simplified version of a definition that
626 appears as a standard part of this package:
628 (define-compiler-macro member* (&whole form a list &rest keys)
630 (eq (car-safe a) 'quote)
631 (not (floatp-safe (cadr a))))
635 This definition causes `(member* A LIST)' to change to a call to
636 the faster `memq' in the common case where A is a
637 non-floating-point constant; if A is anything else, or if there
638 are any keyword arguments in the call, then the original `member*'
639 call is left intact. (The actual compiler macro for `member*'
640 optimizes a number of other cases, including common `:test'
643 - Function: compiler-macroexpand FORM
644 This function is analogous to `macroexpand', except that it
645 expands compiler macros rather than regular macros. It returns
646 FORM unchanged if it is not a call to a function for which a
647 compiler macro has been defined, or if that compiler macro decided
648 to punt by returning its `&whole' argument. Like `macroexpand',
649 it expands repeatedly until it reaches a form for which no further
650 expansion is possible.
652 *Note Macro Bindings::, for descriptions of the `macrolet' and
653 `symbol-macrolet' forms for making "local" macro definitions.
656 File: cl.info, Node: Declarations, Next: Symbols, Prev: Macros, Up: Top
661 Common Lisp includes a complex and powerful "declaration" mechanism
662 that allows you to give the compiler special hints about the types of
663 data that will be stored in particular variables, and about the ways
664 those variables and functions will be used. This package defines
665 versions of all the Common Lisp declaration forms: `declare',
666 `locally', `proclaim', `declaim', and `the'.
668 Most of the Common Lisp declarations are not currently useful in
669 Emacs Lisp, as the byte-code system provides little opportunity to
670 benefit from type information, and `special' declarations are redundant
671 in a fully dynamically-scoped Lisp. A few declarations are meaningful
672 when the optimizing Emacs 19 byte compiler is being used, however.
673 Under the earlier non-optimizing compiler, these declarations will
674 effectively be ignored.
676 - Function: proclaim DECL-SPEC
677 This function records a "global" declaration specified by
678 DECL-SPEC. Since `proclaim' is a function, DECL-SPEC is evaluated
679 and thus should normally be quoted.
681 - Special Form: declaim DECL-SPECS...
682 This macro is like `proclaim', except that it takes any number of
683 DECL-SPEC arguments, and the arguments are unevaluated and
684 unquoted. The `declaim' macro also puts an `(eval-when (compile
685 load eval) ...)' around the declarations so that they will be
686 registered at compile-time as well as at run-time. (This is vital,
687 since normally the declarations are meant to influence the way the
688 compiler treats the rest of the file that contains the `declaim'
691 - Special Form: declare DECL-SPECS...
692 This macro is used to make declarations within functions and other
693 code. Common Lisp allows declarations in various locations,
694 generally at the beginning of any of the many "implicit `progn's"
695 throughout Lisp syntax, such as function bodies, `let' bodies,
696 etc. Currently the only declaration understood by `declare' is
699 - Special Form: locally DECLARATIONS... FORMS...
700 In this package, `locally' is no different from `progn'.
702 - Special Form: the TYPE FORM
703 Type information provided by `the' is ignored in this package; in
704 other words, `(the TYPE FORM)' is equivalent to FORM. Future
705 versions of the optimizing byte-compiler may make use of this
708 For example, `mapcar' can map over both lists and arrays. It is
709 hard for the compiler to expand `mapcar' into an in-line loop
710 unless it knows whether the sequence will be a list or an array
711 ahead of time. With `(mapcar 'car (the vector foo))', a future
712 compiler would have enough information to expand the loop in-line.
713 For now, Emacs Lisp will treat the above code as exactly equivalent
714 to `(mapcar 'car foo)'.
716 Each DECL-SPEC in a `proclaim', `declaim', or `declare' should be a
717 list beginning with a symbol that says what kind of declaration it is.
718 This package currently understands `special', `inline', `notinline',
719 `optimize', and `warn' declarations. (The `warn' declaration is an
720 extension of standard Common Lisp.) Other Common Lisp declarations,
721 such as `type' and `ftype', are silently ignored.
724 Since all variables in Emacs Lisp are "special" (in the Common
725 Lisp sense), `special' declarations are only advisory. They
726 simply tell the optimizing byte compiler that the specified
727 variables are intentionally being referred to without being bound
728 in the body of the function. The compiler normally emits warnings
729 for such references, since they could be typographical errors for
730 references to local variables.
732 The declaration `(declare (special VAR1 VAR2))' is equivalent to
733 `(defvar VAR1) (defvar VAR2)' in the optimizing compiler, or to
734 nothing at all in older compilers (which do not warn for non-local
737 In top-level contexts, it is generally better to write `(defvar
738 VAR)' than `(declaim (special VAR))', since `defvar' makes your
739 intentions clearer. But the older byte compilers can not handle
740 `defvar's appearing inside of functions, while `(declare (special
741 VAR))' takes care to work correctly with all compilers.
744 The `inline' DECL-SPEC lists one or more functions whose bodies
745 should be expanded "in-line" into calling functions whenever the
746 compiler is able to arrange for it. For example, the Common Lisp
747 function `cadr' is declared `inline' by this package so that the
748 form `(cadr X)' will expand directly into `(car (cdr X))' when it
749 is called in user functions, for a savings of one (relatively
750 expensive) function call.
752 The following declarations are all equivalent. Note that the
753 `defsubst' form is a convenient way to define a function and
754 declare it inline all at once, but it is available only in Emacs
757 (declaim (inline foo bar))
758 (eval-when (compile load eval) (proclaim '(inline foo bar)))
759 (proclaim-inline foo bar) ; XEmacs only
760 (defsubst foo (...) ...) ; instead of defun; Emacs 19 only
762 *Please note:* This declaration remains in effect after the
763 containing source file is done. It is correct to use it to
764 request that a function you have defined should be inlined, but it
765 is impolite to use it to request inlining of an external function.
767 In Common Lisp, it is possible to use `(declare (inline ...))'
768 before a particular call to a function to cause just that call to
769 be inlined; the current byte compilers provide no way to implement
770 this, so `(declare (inline ...))' is currently ignored by this
774 The `notinline' declaration lists functions which should not be
775 inlined after all; it cancels a previous `inline' declaration.
778 This declaration controls how much optimization is performed by
779 the compiler. Naturally, it is ignored by the earlier
780 non-optimizing compilers.
782 The word `optimize' is followed by any number of lists like
783 `(speed 3)' or `(safety 2)'. Common Lisp defines several
784 optimization "qualities"; this package ignores all but `speed' and
785 `safety'. The value of a quality should be an integer from 0 to
786 3, with 0 meaning "unimportant" and 3 meaning "very important."
787 The default level for both qualities is 1.
789 In this package, with the Emacs 19 optimizing compiler, the
790 `speed' quality is tied to the `byte-compile-optimize' flag, which
791 is set to `nil' for `(speed 0)' and to `t' for higher settings;
792 and the `safety' quality is tied to the
793 `byte-compile-delete-errors' flag, which is set to `t' for
794 `(safety 3)' and to `nil' for all lower settings. (The latter
795 flag controls whether the compiler is allowed to optimize out code
796 whose only side-effect could be to signal an error, e.g.,
797 rewriting `(progn foo bar)' to `bar' when it is not known whether
798 `foo' will be bound at run-time.)
800 Note that even compiling with `(safety 0)', the Emacs byte-code
801 system provides sufficient checking to prevent real harm from
802 being done. For example, barring serious bugs in Emacs itself,
803 Emacs will not crash with a segmentation fault just because of an
804 error in a fully-optimized Lisp program.
806 The `optimize' declaration is normally used in a top-level
807 `proclaim' or `declaim' in a file; Common Lisp allows it to be
808 used with `declare' to set the level of optimization locally for a
809 given form, but this will not work correctly with the current
810 version of the optimizing compiler. (The `declare' will set the
811 new optimization level, but that level will not automatically be
812 unset after the enclosing form is done.)
815 This declaration controls what sorts of warnings are generated by
816 the byte compiler. Again, only the optimizing compiler generates
817 warnings. The word `warn' is followed by any number of "warning
818 qualities," similar in form to optimization qualities. The
819 currently supported warning types are `redefine', `callargs',
820 `unresolved', and `free-vars'; in the current system, a value of 0
821 will disable these warnings and any higher value will enable them.
822 See the documentation for the optimizing byte compiler for details.
825 File: cl.info, Node: Symbols, Next: Numbers, Prev: Declarations, Up: Top
830 This package defines several symbol-related features that were missing
835 * Property Lists:: `get*', `remprop', `getf', `remf'
836 * Creating Symbols:: `gensym', `gentemp'
839 File: cl.info, Node: Property Lists, Next: Creating Symbols, Prev: Symbols, Up: Symbols
844 These functions augment the standard Emacs Lisp functions `get' and
845 `put' for operating on properties attached to symbols. There are also
846 functions for working with property lists as first-class data
847 structures not attached to particular symbols.
849 - Function: get* SYMBOL PROPERTY &optional DEFAULT
850 This function is like `get', except that if the property is not
851 found, the DEFAULT argument provides the return value. (The Emacs
852 Lisp `get' function always uses `nil' as the default; this
853 package's `get*' is equivalent to Common Lisp's `get'.)
855 The `get*' function is `setf'-able; when used in this fashion, the
856 DEFAULT argument is allowed but ignored.
858 - Function: remprop SYMBOL PROPERTY
859 This function removes the entry for PROPERTY from the property
860 list of SYMBOL. It returns a true value if the property was
861 indeed found and removed, or `nil' if there was no such property.
862 (This function was probably omitted from Emacs originally because,
863 since `get' did not allow a DEFAULT, it was very difficult to
864 distinguish between a missing property and a property whose value
865 was `nil'; thus, setting a property to `nil' was close enough to
866 `remprop' for most purposes.)
868 - Function: getf PLACE PROPERTY &optional DEFAULT
869 This function scans the list PLACE as if it were a property list,
870 i.e., a list of alternating property names and values. If an
871 even-numbered element of PLACE is found which is `eq' to PROPERTY,
872 the following odd-numbered element is returned. Otherwise,
873 DEFAULT is returned (or `nil' if no default is given).
877 (get sym prop) == (getf (symbol-plist sym) prop)
879 It is legal to use `getf' as a `setf' place, in which case its
880 PLACE argument must itself be a legal `setf' place. The DEFAULT
881 argument, if any, is ignored in this context. The effect is to
882 change (via `setcar') the value cell in the list that corresponds
883 to PROPERTY, or to cons a new property-value pair onto the list if
884 the property is not yet present.
886 (put sym prop val) == (setf (getf (symbol-plist sym) prop) val)
888 The `get' and `get*' functions are also `setf'-able. The fact
889 that `default' is ignored can sometimes be useful:
891 (incf (get* 'foo 'usage-count 0))
893 Here, symbol `foo''s `usage-count' property is incremented if it
894 exists, or set to 1 (an incremented 0) otherwise.
896 When not used as a `setf' form, `getf' is just a regular function
897 and its PLACE argument can actually be any Lisp expression.
899 - Special Form: remf PLACE PROPERTY
900 This macro removes the property-value pair for PROPERTY from the
901 property list stored at PLACE, which is any `setf'-able place
902 expression. It returns true if the property was found. Note that
903 if PROPERTY happens to be first on the list, this will effectively
904 do a `(setf PLACE (cddr PLACE))', whereas if it occurs later, this
905 simply uses `setcdr' to splice out the property and value cells.
908 File: cl.info, Node: Creating Symbols, Prev: Property Lists, Up: Symbols
913 These functions create unique symbols, typically for use as temporary
916 - Function: gensym &optional X
917 This function creates a new, uninterned symbol (using
918 `make-symbol') with a unique name. (The name of an uninterned
919 symbol is relevant only if the symbol is printed.) By default,
920 the name is generated from an increasing sequence of numbers,
921 `G1000', `G1001', `G1002', etc. If the optional argument X is a
922 string, that string is used as a prefix instead of `G'.
923 Uninterned symbols are used in macro expansions for temporary
924 variables, to ensure that their names will not conflict with
925 "real" variables in the user's code.
927 - Variable: *gensym-counter*
928 This variable holds the counter used to generate `gensym' names.
929 It is incremented after each use by `gensym'. In Common Lisp this
930 is initialized with 0, but this package initializes it with a
931 random (time-dependent) value to avoid trouble when two files that
932 each used `gensym' in their compilation are loaded together.
934 *XEmacs note:* As of XEmacs 21.0, an uninterned symbol remains
935 uninterned even after being dumped to bytecode. Older versions of
936 Emacs didn't distinguish the printed representation of interned
937 and uninterned symbols, so their names had to be treated more
940 - Function: gentemp &optional X
941 This function is like `gensym', except that it produces a new
942 *interned* symbol. If the symbol that is generated already
943 exists, the function keeps incrementing the counter and trying
944 again until a new symbol is generated.
946 The Quiroz `cl.el' package also defined a `defkeyword' form for
947 creating self-quoting keyword symbols. This package automatically
948 creates all keywords that are called for by `&key' argument specifiers,
949 and discourages the use of keywords as data unrelated to keyword
950 arguments, so the `defkeyword' form has been discontinued.
953 File: cl.info, Node: Numbers, Next: Sequences, Prev: Symbols, Up: Top
958 This section defines a few simple Common Lisp operations on numbers
959 which were left out of Emacs Lisp.
963 * Predicates on Numbers:: `plusp', `oddp', `floatp-safe', etc.
964 * Numerical Functions:: `abs', `expt', `floor*', etc.
965 * Random Numbers:: `random*', `make-random-state'
966 * Implementation Parameters:: `most-positive-fixnum', `most-positive-float'
969 File: cl.info, Node: Predicates on Numbers, Next: Numerical Functions, Prev: Numbers, Up: Numbers
971 Predicates on Numbers
972 =====================
974 These functions return `t' if the specified condition is true of the
975 numerical argument, or `nil' otherwise.
977 - Function: plusp NUMBER
978 This predicate tests whether NUMBER is positive. It is an error
979 if the argument is not a number.
981 - Function: minusp NUMBER
982 This predicate tests whether NUMBER is negative. It is an error
983 if the argument is not a number.
985 - Function: oddp INTEGER
986 This predicate tests whether INTEGER is odd. It is an error if
987 the argument is not an integer.
989 - Function: evenp INTEGER
990 This predicate tests whether INTEGER is even. It is an error if
991 the argument is not an integer.
993 - Function: floatp-safe OBJECT
994 This predicate tests whether OBJECT is a floating-point number.
995 On systems that support floating-point, this is equivalent to
996 `floatp'. On other systems, this always returns `nil'.
999 File: cl.info, Node: Numerical Functions, Next: Random Numbers, Prev: Predicates on Numbers, Up: Numbers
1004 These functions perform various arithmetic operations on numbers.
1006 - Function: abs NUMBER
1007 This function returns the absolute value of NUMBER. (Newer
1008 versions of Emacs provide this as a built-in function; this package
1009 defines `abs' only for Emacs 18 versions which don't provide it as
1012 - Function: expt BASE POWER
1013 This function returns BASE raised to the power of NUMBER. (Newer
1014 versions of Emacs provide this as a built-in function; this
1015 package defines `expt' only for Emacs 18 versions which don't
1016 provide it as a primitive.)
1018 - Function: gcd &rest INTEGERS
1019 This function returns the Greatest Common Divisor of the arguments.
1020 For one argument, it returns the absolute value of that argument.
1021 For zero arguments, it returns zero.
1023 - Function: lcm &rest INTEGERS
1024 This function returns the Least Common Multiple of the arguments.
1025 For one argument, it returns the absolute value of that argument.
1026 For zero arguments, it returns one.
1028 - Function: isqrt INTEGER
1029 This function computes the "integer square root" of its integer
1030 argument, i.e., the greatest integer less than or equal to the true
1031 square root of the argument.
1033 - Function: floor* NUMBER &optional DIVISOR
1034 This function implements the Common Lisp `floor' function. It is
1035 called `floor*' to avoid name conflicts with the simpler `floor'
1036 function built-in to Emacs 19.
1038 With one argument, `floor*' returns a list of two numbers: The
1039 argument rounded down (toward minus infinity) to an integer, and
1040 the "remainder" which would have to be added back to the first
1041 return value to yield the argument again. If the argument is an
1042 integer X, the result is always the list `(X 0)'. If the argument
1043 is an Emacs 19 floating-point number, the first result is a Lisp
1044 integer and the second is a Lisp float between 0 (inclusive) and 1
1047 With two arguments, `floor*' divides NUMBER by DIVISOR, and
1048 returns the floor of the quotient and the corresponding remainder
1049 as a list of two numbers. If `(floor* X Y)' returns `(Q R)', then
1050 `Q*Y + R = X', with R between 0 (inclusive) and R (exclusive).
1051 Also, note that `(floor* X)' is exactly equivalent to `(floor* X
1054 This function is entirely compatible with Common Lisp's `floor'
1055 function, except that it returns the two results in a list since
1056 Emacs Lisp does not support multiple-valued functions.
1058 - Function: ceiling* NUMBER &optional DIVISOR
1059 This function implements the Common Lisp `ceiling' function, which
1060 is analogous to `floor' except that it rounds the argument or
1061 quotient of the arguments up toward plus infinity. The remainder
1062 will be between 0 and minus R.
1064 - Function: truncate* NUMBER &optional DIVISOR
1065 This function implements the Common Lisp `truncate' function,
1066 which is analogous to `floor' except that it rounds the argument
1067 or quotient of the arguments toward zero. Thus it is equivalent
1068 to `floor*' if the argument or quotient is positive, or to
1069 `ceiling*' otherwise. The remainder has the same sign as NUMBER.
1071 - Function: round* NUMBER &optional DIVISOR
1072 This function implements the Common Lisp `round' function, which
1073 is analogous to `floor' except that it rounds the argument or
1074 quotient of the arguments to the nearest integer. In the case of
1075 a tie (the argument or quotient is exactly halfway between two
1076 integers), it rounds to the even integer.
1078 - Function: mod* NUMBER DIVISOR
1079 This function returns the same value as the second return value of
1082 - Function: rem* NUMBER DIVISOR
1083 This function returns the same value as the second return value of
1086 These definitions are compatible with those in the Quiroz `cl.el'
1087 package, except that this package appends `*' to certain function names
1088 to avoid conflicts with existing Emacs 19 functions, and that the
1089 mechanism for returning multiple values is different.
1092 File: cl.info, Node: Random Numbers, Next: Implementation Parameters, Prev: Numerical Functions, Up: Numbers
1097 This package also provides an implementation of the Common Lisp random
1098 number generator. It uses its own additive-congruential algorithm,
1099 which is much more likely to give statistically clean random numbers
1100 than the simple generators supplied by many operating systems.
1102 - Function: random* NUMBER &optional STATE
1103 This function returns a random nonnegative number less than
1104 NUMBER, and of the same type (either integer or floating-point).
1105 The STATE argument should be a `random-state' object which holds
1106 the state of the random number generator. The function modifies
1107 this state object as a side effect. If STATE is omitted, it
1108 defaults to the variable `*random-state*', which contains a
1109 pre-initialized `random-state' object.
1111 - Variable: *random-state*
1112 This variable contains the system "default" `random-state' object,
1113 used for calls to `random*' that do not specify an alternative
1114 state object. Since any number of programs in the Emacs process
1115 may be accessing `*random-state*' in interleaved fashion, the
1116 sequence generated from this variable will be irreproducible for
1117 all intents and purposes.
1119 - Function: make-random-state &optional STATE
1120 This function creates or copies a `random-state' object. If STATE
1121 is omitted or `nil', it returns a new copy of `*random-state*'.
1122 This is a copy in the sense that future sequences of calls to
1123 `(random* N)' and `(random* N S)' (where S is the new random-state
1124 object) will return identical sequences of random numbers.
1126 If STATE is a `random-state' object, this function returns a copy
1127 of that object. If STATE is `t', this function returns a new
1128 `random-state' object seeded from the date and time. As an
1129 extension to Common Lisp, STATE may also be an integer in which
1130 case the new object is seeded from that integer; each different
1131 integer seed will result in a completely different sequence of
1134 It is legal to print a `random-state' object to a buffer or file
1135 and later read it back with `read'. If a program wishes to use a
1136 sequence of pseudo-random numbers which can be reproduced later
1137 for debugging, it can call `(make-random-state t)' to get a new
1138 sequence, then print this sequence to a file. When the program is
1139 later rerun, it can read the original run's random-state from the
1142 - Function: random-state-p OBJECT
1143 This predicate returns `t' if OBJECT is a `random-state' object,
projects / chise / xemacs-chise.git.1 / blob