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