1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
4 INFO-DIR-SECTION XEmacs Editor
6 * Lispref: (lispref). XEmacs Lisp Reference Manual.
11 GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
12 Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
13 Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
14 XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
15 GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
16 Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
17 Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
18 Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
19 November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
21 Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
22 Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
23 Copyright (C) 1995, 1996 Ben Wing.
25 Permission is granted to make and distribute verbatim copies of this
26 manual provided the copyright notice and this permission notice are
27 preserved on all copies.
29 Permission is granted to copy and distribute modified versions of
30 this manual under the conditions for verbatim copying, provided that the
31 entire resulting derived work is distributed under the terms of a
32 permission notice identical to this one.
34 Permission is granted to copy and distribute translations of this
35 manual into another language, under the above conditions for modified
36 versions, except that this permission notice may be stated in a
37 translation approved by the Foundation.
39 Permission is granted to copy and distribute modified versions of
40 this manual under the conditions for verbatim copying, provided also
41 that the section entitled "GNU General Public License" is included
42 exactly as in the original, and provided that the entire resulting
43 derived work is distributed under the terms of a permission notice
44 identical to this one.
46 Permission is granted to copy and distribute translations of this
47 manual into another language, under the above conditions for modified
48 versions, except that the section entitled "GNU General Public License"
49 may be included in a translation approved by the Free Software
50 Foundation instead of in the original English.
53 File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, Up: Loading
58 The "autoload" facility allows you to make a function or macro known
59 in Lisp, but put off loading the file that defines it. The first call
60 to the function automatically reads the proper file to install the real
61 definition and other associated code, then runs the real definition as
62 if it had been loaded all along.
64 There are two ways to set up an autoloaded function: by calling
65 `autoload', and by writing a special "magic" comment in the source
66 before the real definition. `autoload' is the low-level primitive for
67 autoloading; any Lisp program can call `autoload' at any time. Magic
68 comments do nothing on their own; they serve as a guide for the command
69 `update-file-autoloads', which constructs calls to `autoload' and
70 arranges to execute them when Emacs is built. Magic comments are the
71 most convenient way to make a function autoload, but only for packages
72 installed along with Emacs.
74 - Function: autoload FUNCTION FILENAME &optional DOCSTRING INTERACTIVE
76 This function defines the function (or macro) named FUNCTION so as
77 to load automatically from FILENAME. The string FILENAME
78 specifies the file to load to get the real definition of FUNCTION.
80 The argument DOCSTRING is the documentation string for the
81 function. Normally, this is the identical to the documentation
82 string in the function definition itself. Specifying the
83 documentation string in the call to `autoload' makes it possible
84 to look at the documentation without loading the function's real
87 If INTERACTIVE is non-`nil', then the function can be called
88 interactively. This lets completion in `M-x' work without loading
89 the function's real definition. The complete interactive
90 specification need not be given here; it's not needed unless the
91 user actually calls FUNCTION, and when that happens, it's time to
92 load the real definition.
94 You can autoload macros and keymaps as well as ordinary functions.
95 Specify TYPE as `macro' if FUNCTION is really a macro. Specify
96 TYPE as `keymap' if FUNCTION is really a keymap. Various parts of
97 Emacs need to know this information without loading the real
100 An autoloaded keymap loads automatically during key lookup when a
101 prefix key's binding is the symbol FUNCTION. Autoloading does not
102 occur for other kinds of access to the keymap. In particular, it
103 does not happen when a Lisp program gets the keymap from the value
104 of a variable and calls `define-key'; not even if the variable
105 name is the same symbol FUNCTION.
107 If FUNCTION already has a non-void function definition that is not
108 an autoload object, `autoload' does nothing and returns `nil'. If
109 the function cell of FUNCTION is void, or is already an autoload
110 object, then it is defined as an autoload object like this:
112 (autoload FILENAME DOCSTRING INTERACTIVE TYPE)
116 (symbol-function 'run-prolog)
117 => (autoload "prolog" 169681 t nil)
119 In this case, `"prolog"' is the name of the file to load, 169681
120 refers to the documentation string in the `DOC' file (*note
121 Documentation Basics::.), `t' means the function is interactive,
122 and `nil' that it is not a macro or a keymap.
124 The autoloaded file usually contains other definitions and may
125 require or provide one or more features. If the file is not completely
126 loaded (due to an error in the evaluation of its contents), any function
127 definitions or `provide' calls that occurred during the load are
128 undone. This is to ensure that the next attempt to call any function
129 autoloading from this file will try again to load the file. If not for
130 this, then some of the functions in the file might appear defined, but
131 they might fail to work properly for the lack of certain subroutines
132 defined later in the file and not loaded successfully.
134 XEmacs as distributed comes with many autoloaded functions. The
135 calls to `autoload' are in the file `loaddefs.el'. There is a
136 convenient way of updating them automatically.
138 If the autoloaded file fails to define the desired Lisp function or
139 macro, then an error is signaled with data `"Autoloading failed to
140 define function FUNCTION-NAME"'.
142 A magic autoload comment looks like `;;;###autoload', on a line by
143 itself, just before the real definition of the function in its
144 autoloadable source file. The command `M-x update-file-autoloads'
145 writes a corresponding `autoload' call into `loaddefs.el'. Building
146 Emacs loads `loaddefs.el' and thus calls `autoload'. `M-x
147 update-directory-autoloads' is even more powerful; it updates autoloads
148 for all files in the current directory.
150 The same magic comment can copy any kind of form into `loaddefs.el'.
151 If the form following the magic comment is not a function definition,
152 it is copied verbatim. You can also use a magic comment to execute a
153 form at build time *without* executing it when the file itself is
154 loaded. To do this, write the form "on the same line" as the magic
155 comment. Since it is in a comment, it does nothing when you load the
156 source file; but `update-file-autoloads' copies it to `loaddefs.el',
157 where it is executed while building Emacs.
159 The following example shows how `doctor' is prepared for autoloading
160 with a magic comment:
164 "Switch to *doctor* buffer and start giving psychotherapy."
166 (switch-to-buffer "*doctor*")
169 Here's what that produces in `loaddefs.el':
171 (autoload 'doctor "doctor"
173 Switch to *doctor* buffer and start giving psychotherapy."
176 The backslash and newline immediately following the double-quote are a
177 convention used only in the preloaded Lisp files such as `loaddefs.el';
178 they tell `make-docfile' to put the documentation string in the `DOC'
179 file. *Note Building XEmacs::.
182 File: lispref.info, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading
187 You may load one file more than once in an Emacs session. For
188 example, after you have rewritten and reinstalled a function definition
189 by editing it in a buffer, you may wish to return to the original
190 version; you can do this by reloading the file it came from.
192 When you load or reload files, bear in mind that the `load' and
193 `load-library' functions automatically load a byte-compiled file rather
194 than a non-compiled file of similar name. If you rewrite a file that
195 you intend to save and reinstall, remember to byte-compile it if
196 necessary; otherwise you may find yourself inadvertently reloading the
197 older, byte-compiled file instead of your newer, non-compiled file!
199 When writing the forms in a Lisp library file, keep in mind that the
200 file might be loaded more than once. For example, the choice of
201 `defvar' vs. `defconst' for defining a variable depends on whether it
202 is desirable to reinitialize the variable if the library is reloaded:
203 `defconst' does so, and `defvar' does not. (*Note Defining
206 The simplest way to add an element to an alist is like this:
208 (setq minor-mode-alist
209 (cons '(leif-mode " Leif") minor-mode-alist))
211 But this would add multiple elements if the library is reloaded. To
212 avoid the problem, write this:
214 (or (assq 'leif-mode minor-mode-alist)
215 (setq minor-mode-alist
216 (cons '(leif-mode " Leif") minor-mode-alist)))
218 To add an element to a list just once, use `add-to-list' (*note
219 Setting Variables::.).
221 Occasionally you will want to test explicitly whether a library has
222 already been loaded. Here's one way to test, in a library, whether it
223 has been loaded before:
225 (defvar foo-was-loaded)
227 (if (not (boundp 'foo-was-loaded))
228 EXECUTE-FIRST-TIME-ONLY)
230 (setq foo-was-loaded t)
232 If the library uses `provide' to provide a named feature, you can use
233 `featurep' to test whether the library has been loaded. *Note Named
237 File: lispref.info, Node: Named Features, Next: Unloading, Prev: Repeated Loading, Up: Loading
242 `provide' and `require' are an alternative to `autoload' for loading
243 files automatically. They work in terms of named "features".
244 Autoloading is triggered by calling a specific function, but a feature
245 is loaded the first time another program asks for it by name.
247 A feature name is a symbol that stands for a collection of functions,
248 variables, etc. The file that defines them should "provide" the
249 feature. Another program that uses them may ensure they are defined by
250 "requiring" the feature. This loads the file of definitions if it
251 hasn't been loaded already.
253 To require the presence of a feature, call `require' with the
254 feature name as argument. `require' looks in the global variable
255 `features' to see whether the desired feature has been provided
256 already. If not, it loads the feature from the appropriate file. This
257 file should call `provide' at the top level to add the feature to
258 `features'; if it fails to do so, `require' signals an error.
260 Features are normally named after the files that provide them, so
261 that `require' need not be given the file name.
263 For example, in `emacs/lisp/prolog.el', the definition for
264 `run-prolog' includes the following code:
267 "Run an inferior Prolog process, input and output via buffer *prolog*."
270 (switch-to-buffer (make-comint "prolog" prolog-program-name))
271 (inferior-prolog-mode))
273 The expression `(require 'comint)' loads the file `comint.el' if it has
274 not yet been loaded. This ensures that `make-comint' is defined.
276 The `comint.el' file contains the following top-level expression:
280 This adds `comint' to the global `features' list, so that `(require
281 'comint)' will henceforth know that nothing needs to be done.
283 When `require' is used at top level in a file, it takes effect when
284 you byte-compile that file (*note Byte Compilation::.) as well as when
285 you load it. This is in case the required package contains macros that
286 the byte compiler must know about.
288 Although top-level calls to `require' are evaluated during byte
289 compilation, `provide' calls are not. Therefore, you can ensure that a
290 file of definitions is loaded before it is byte-compiled by including a
291 `provide' followed by a `require' for the same feature, as in the
294 (provide 'my-feature) ; Ignored by byte compiler,
295 ; evaluated by `load'.
296 (require 'my-feature) ; Evaluated by byte compiler.
298 The compiler ignores the `provide', then processes the `require' by
299 loading the file in question. Loading the file does execute the
300 `provide' call, so the subsequent `require' call does nothing while
303 - Function: provide FEATURE
304 This function announces that FEATURE is now loaded, or being
305 loaded, into the current XEmacs session. This means that the
306 facilities associated with FEATURE are or will be available for
309 The direct effect of calling `provide' is to add FEATURE to the
310 front of the list `features' if it is not already in the list.
311 The argument FEATURE must be a symbol. `provide' returns FEATURE.
321 When a file is loaded to satisfy an autoload, and it stops due to
322 an error in the evaluating its contents, any function definitions
323 or `provide' calls that occurred during the load are undone.
326 - Function: require FEATURE &optional FILENAME
327 This function checks whether FEATURE is present in the current
328 XEmacs session (using `(featurep FEATURE)'; see below). If it is
329 not, then `require' loads FILENAME with `load'. If FILENAME is
330 not supplied, then the name of the symbol FEATURE is used as the
333 If loading the file fails to provide FEATURE, `require' signals an
334 error, `Required feature FEATURE was not provided'.
336 - Function: featurep FEXP
337 This function returns `t' if feature FEXP is present in this
338 Emacs. Use this to conditionalize execution of lisp code based on
339 the presence or absence of emacs or environment extensions.
341 FEXP can be a symbol, a number, or a list.
343 If FEXP is a symbol, it is looked up in the `features' variable,
344 and `t' is returned if it is found, `nil' otherwise.
346 If FEXP is a number, the function returns `t' if this Emacs has an
347 equal or greater number than `fexp', `nil' otherwise. Note that
348 minor Emacs version is expected to be 2 decimal places wide, so
349 `(featurep 20.4)' will return `nil' on XEmacs 20.4--you must write
350 `(featurep 20.04)', unless you wish to match for XEmacs 20.40.
352 If FEXP is a list whose car is the symbol `and', the function
353 returns `t' if all the features in its cdr are present, `nil'
356 If FEXP is a list whose car is the symbol `or', the function
357 returns `t' if any the features in its cdr are present, `nil'
360 If FEXP is a list whose car is the symbol `not', the function
361 returns `t' if the feature is not present, `nil' otherwise.
368 (featurep '(and xemacs gnus))
369 => ; t on XEmacs with Gnus loaded.
371 (featurep '(or tty-frames (and emacs 19.30)))
372 => ; t if this Emacs supports TTY frames.
374 (featurep '(or (and xemacs 19.15) (and emacs 19.34)))
375 => ; t on XEmacs 19.15 and later, or on
376 ; FSF Emacs 19.34 and later.
378 *Please note:* The advanced arguments of this function (anything
379 other than a symbol) are not yet supported by FSF Emacs. If you
380 feel they are useful for supporting multiple Emacs variants, lobby
381 Richard Stallman at `<bug-gnu-emacs@prep.ai.mit.edu>'.
384 The value of this variable is a list of symbols that are the
385 features loaded in the current XEmacs session. Each symbol was
386 put in this list with a call to `provide'. The order of the
387 elements in the `features' list is not significant.
390 File: lispref.info, Node: Unloading, Next: Hooks for Loading, Prev: Named Features, Up: Loading
395 You can discard the functions and variables loaded by a library to
396 reclaim memory for other Lisp objects. To do this, use the function
399 - Command: unload-feature FEATURE &optional FORCE
400 This command unloads the library that provided feature FEATURE.
401 It undefines all functions, macros, and variables defined in that
402 library with `defconst', `defvar', `defun', `defmacro',
403 `defsubst', `definf-function' and `defalias'. It then restores
404 any autoloads formerly associated with those symbols. (Loading
405 saves these in the `autoload' property of the symbol.)
407 Ordinarily, `unload-feature' refuses to unload a library on which
408 other loaded libraries depend. (A library A depends on library B
409 if A contains a `require' for B.) If the optional argument FORCE
410 is non-`nil', dependencies are ignored and you can unload any
413 The `unload-feature' function is written in Lisp; its actions are
414 based on the variable `load-history'.
416 - Variable: load-history
417 This variable's value is an alist connecting library names with the
418 names of functions and variables they define, the features they
419 provide, and the features they require.
421 Each element is a list and describes one library. The CAR of the
422 list is the name of the library, as a string. The rest of the
423 list is composed of these kinds of objects:
425 * Symbols that were defined by this library.
427 * Lists of the form `(require . FEATURE)' indicating features
430 * Lists of the form `(provide . FEATURE)' indicating features
433 The value of `load-history' may have one element whose CAR is
434 `nil'. This element describes definitions made with `eval-buffer'
435 on a buffer that is not visiting a file.
437 The command `eval-region' updates `load-history', but does so by
438 adding the symbols defined to the element for the file being visited,
439 rather than replacing that element.
442 File: lispref.info, Node: Hooks for Loading, Prev: Unloading, Up: Loading
447 - Variable: after-load-alist
448 An alist of expressions to evaluate if and when particular
449 libraries are loaded. Each element looks like this:
453 When `load' is run and the file-name argument is FILENAME, the
454 FORMS in the corresponding element are executed at the end of
457 FILENAME must match exactly! Normally FILENAME is the name of a
458 library, with no directory specified, since that is how `load' is
459 normally called. An error in FORMS does not undo the load, but
460 does prevent execution of the rest of the FORMS.
464 File: lispref.info, Node: Byte Compilation, Next: Debugging, Prev: Loading, Up: Top
469 XEmacs Lisp has a "compiler" that translates functions written in
470 Lisp into a special representation called "byte-code" that can be
471 executed more efficiently. The compiler replaces Lisp function
472 definitions with byte-code. When a byte-coded function is called, its
473 definition is evaluated by the "byte-code interpreter".
475 Because the byte-compiled code is evaluated by the byte-code
476 interpreter, instead of being executed directly by the machine's
477 hardware (as true compiled code is), byte-code is completely
478 transportable from machine to machine without recompilation. It is not,
479 however, as fast as true compiled code.
481 In general, any version of Emacs can run byte-compiled code produced
482 by recent earlier versions of Emacs, but the reverse is not true. In
483 particular, if you compile a program with XEmacs 20, the compiled code
484 may not run in earlier versions.
486 The first time a compiled-function object is executed, the byte-code
487 instructions are validated and the byte-code is further optimized. An
488 `invalid-byte-code' error is signaled if the byte-code is invalid, for
489 example if it contains invalid opcodes. This usually means a bug in
492 *Note Compilation Errors::, for how to investigate errors occurring
497 * Speed of Byte-Code:: An example of speedup from byte compilation.
498 * Compilation Functions:: Byte compilation functions.
499 * Docs and Compilation:: Dynamic loading of documentation strings.
500 * Dynamic Loading:: Dynamic loading of individual functions.
501 * Eval During Compile:: Code to be evaluated when you compile.
502 * Compiled-Function Objects:: The data type used for byte-compiled functions.
503 * Disassembly:: Disassembling byte-code; how to read byte-code.
506 File: lispref.info, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation
508 Performance of Byte-Compiled Code
509 =================================
511 A byte-compiled function is not as efficient as a primitive function
512 written in C, but runs much faster than the version written in Lisp.
515 (defun silly-loop (n)
516 "Return time before and after N iterations of a loop."
517 (let ((t1 (current-time-string)))
518 (while (> (setq n (1- n))
520 (list t1 (current-time-string))))
524 => ("Mon Sep 14 15:51:49 1998"
525 "Mon Sep 14 15:52:07 1998") ; 18 seconds
527 (byte-compile 'silly-loop)
528 => #<compiled-function
531 [current-time-string t1 n 0]
533 "Return time before and after N iterations of a loop.">
536 => ("Mon Sep 14 15:53:43 1998"
537 "Mon Sep 14 15:53:49 1998") ; 6 seconds
539 In this example, the interpreted code required 18 seconds to run,
540 whereas the byte-compiled code required 6 seconds. These results are
541 representative, but actual results will vary greatly.
544 File: lispref.info, Node: Compilation Functions, Next: Docs and Compilation, Prev: Speed of Byte-Code, Up: Byte Compilation
546 The Compilation Functions
547 =========================
549 You can byte-compile an individual function or macro definition with
550 the `byte-compile' function. You can compile a whole file with
551 `byte-compile-file', or several files with `byte-recompile-directory'
552 or `batch-byte-compile'.
554 When you run the byte compiler, you may get warnings in a buffer
555 called `*Compile-Log*'. These report things in your program that
556 suggest a problem but are not necessarily erroneous.
558 Be careful when byte-compiling code that uses macros. Macro calls
559 are expanded when they are compiled, so the macros must already be
560 defined for proper compilation. For more details, see *Note Compiling
563 Normally, compiling a file does not evaluate the file's contents or
564 load the file. But it does execute any `require' calls at top level in
565 the file. One way to ensure that necessary macro definitions are
566 available during compilation is to `require' the file that defines them
567 (*note Named Features::.). To avoid loading the macro definition files
568 when someone *runs* the compiled program, write `eval-when-compile'
569 around the `require' calls (*note Eval During Compile::.).
571 - Function: byte-compile SYMBOL
572 This function byte-compiles the function definition of SYMBOL,
573 replacing the previous definition with the compiled one. The
574 function definition of SYMBOL must be the actual code for the
575 function; i.e., the compiler does not follow indirection to
576 another symbol. `byte-compile' returns the new, compiled
577 definition of SYMBOL.
579 If SYMBOL's definition is a compiled-function object,
580 `byte-compile' does nothing and returns `nil'. Lisp records only
581 one function definition for any symbol, and if that is already
582 compiled, non-compiled code is not available anywhere. So there
583 is no way to "compile the same definition again."
585 (defun factorial (integer)
586 "Compute factorial of INTEGER."
588 (* integer (factorial (1- integer)))))
591 (byte-compile 'factorial)
592 => #<compiled-function
595 [integer 1 factorial]
597 "Compute factorial of INTEGER.">
599 The result is a compiled-function object. The string it contains
600 is the actual byte-code; each character in it is an instruction or
601 an operand of an instruction. The vector contains all the
602 constants, variable names and function names used by the function,
603 except for certain primitives that are coded as special
606 - Command: compile-defun &optional ARG
607 This command reads the defun containing point, compiles it, and
608 evaluates the result. If you use this on a defun that is actually
609 a function definition, the effect is to install a compiled version
612 If ARG is non-`nil', the result is inserted in the current buffer
613 after the form; otherwise, it is printed in the minibuffer.
615 - Command: byte-compile-file FILENAME &optional LOAD
616 This function compiles a file of Lisp code named FILENAME into a
617 file of byte-code. The output file's name is made by appending
618 `c' to the end of FILENAME.
620 If `load' is non-`nil', the file is loaded after having been
623 Compilation works by reading the input file one form at a time.
624 If it is a definition of a function or macro, the compiled
625 function or macro definition is written out. Other forms are
626 batched together, then each batch is compiled, and written so that
627 its compiled code will be executed when the file is read. All
628 comments are discarded when the input file is read.
630 This command returns `t'. When called interactively, it prompts
634 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
636 (byte-compile-file "~/emacs/push.el")
640 -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
641 -rw-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
643 - Command: byte-recompile-directory DIRECTORY &optional FLAG
644 This function recompiles every `.el' file in DIRECTORY that needs
645 recompilation. A file needs recompilation if a `.elc' file exists
646 but is older than the `.el' file.
648 When a `.el' file has no corresponding `.elc' file, then FLAG says
649 what to do. If it is `nil', these files are ignored. If it is
650 non-`nil', the user is asked whether to compile each such file.
652 The return value of this command is unpredictable.
654 - Function: batch-byte-compile
655 This function runs `byte-compile-file' on files specified on the
656 command line. This function must be used only in a batch
657 execution of Emacs, as it kills Emacs on completion. An error in
658 one file does not prevent processing of subsequent files. (The
659 file that gets the error will not, of course, produce any compiled
662 % emacs -batch -f batch-byte-compile *.el
664 - Function: batch-byte-recompile-directory
665 This function is similar to `batch-byte-compile' but runs the
666 command `byte-recompile-directory' on the files remaining on the
669 - Variable: byte-recompile-directory-ignore-errors-p
670 If non-`nil', this specifies that `byte-recompile-directory' will
671 continue compiling even when an error occurs in a file. This is
672 normally `nil', but is bound to `t' by
673 `batch-byte-recompile-directory'.
675 - Function: byte-code INSTRUCTIONS CONSTANTS STACK-SIZE
676 This function actually interprets byte-code. Don't call this
677 function yourself. Only the byte compiler knows how to generate
678 valid calls to this function.
680 In newer Emacs versions (19 and up), byte code is usually executed
681 as part of a compiled-function object, and only rarely due to an
682 explicit call to `byte-code'. A byte-compiled function was once
683 actually defined with a body that calls `byte-code', but in recent
684 versions of Emacs `byte-code' is only used to run isolated
685 fragments of lisp code without an associated argument list.
688 File: lispref.info, Node: Docs and Compilation, Next: Dynamic Loading, Prev: Compilation Functions, Up: Byte Compilation
690 Documentation Strings and Compilation
691 =====================================
693 Functions and variables loaded from a byte-compiled file access their
694 documentation strings dynamically from the file whenever needed. This
695 saves space within Emacs, and makes loading faster because the
696 documentation strings themselves need not be processed while loading the
697 file. Actual access to the documentation strings becomes slower as a
698 result, but normally not enough to bother users.
700 Dynamic access to documentation strings does have drawbacks:
702 * If you delete or move the compiled file after loading it, Emacs
703 can no longer access the documentation strings for the functions
704 and variables in the file.
706 * If you alter the compiled file (such as by compiling a new
707 version), then further access to documentation strings in this
708 file will give nonsense results.
710 If your site installs Emacs following the usual procedures, these
711 problems will never normally occur. Installing a new version uses a new
712 directory with a different name; as long as the old version remains
713 installed, its files will remain unmodified in the places where they are
716 However, if you have built Emacs yourself and use it from the
717 directory where you built it, you will experience this problem
718 occasionally if you edit and recompile Lisp files. When it happens, you
719 can cure the problem by reloading the file after recompiling it.
721 Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs
722 19.28 do not support the dynamic docstrings feature, and so will not be
723 able to load bytecode created by more recent Emacs versions. You can
724 turn off the dynamic docstring feature by setting
725 `byte-compile-dynamic-docstrings' to `nil'. Once this is done, you can
726 compile files that will load into older Emacs versions. You can do
727 this globally, or for one source file by specifying a file-local
728 binding for the variable. Here's one way to do that:
730 -*-byte-compile-dynamic-docstrings: nil;-*-
732 - Variable: byte-compile-dynamic-docstrings
733 If this is non-`nil', the byte compiler generates compiled files
734 that are set up for dynamic loading of documentation strings.
736 The dynamic documentation string feature writes compiled files that
737 use a special Lisp reader construct, `#@COUNT'. This construct skips
738 the next COUNT characters. It also uses the `#$' construct, which
739 stands for "the name of this file, as a string." It is best not to use
740 these constructs in Lisp source files.
743 File: lispref.info, Node: Dynamic Loading, Next: Eval During Compile, Prev: Docs and Compilation, Up: Byte Compilation
745 Dynamic Loading of Individual Functions
746 =======================================
748 When you compile a file, you can optionally enable the "dynamic
749 function loading" feature (also known as "lazy loading"). With dynamic
750 function loading, loading the file doesn't fully read the function
751 definitions in the file. Instead, each function definition contains a
752 place-holder which refers to the file. The first time each function is
753 called, it reads the full definition from the file, to replace the
756 The advantage of dynamic function loading is that loading the file
757 becomes much faster. This is a good thing for a file which contains
758 many separate commands, provided that using one of them does not imply
759 you will soon (or ever) use the rest. A specialized mode which provides
760 many keyboard commands often has that usage pattern: a user may invoke
761 the mode, but use only a few of the commands it provides.
763 The dynamic loading feature has certain disadvantages:
765 * If you delete or move the compiled file after loading it, Emacs
766 can no longer load the remaining function definitions not already
769 * If you alter the compiled file (such as by compiling a new
770 version), then trying to load any function not already loaded will
771 get nonsense results.
773 If you compile a new version of the file, the best thing to do is
774 immediately load the new compiled file. That will prevent any future
777 The byte compiler uses the dynamic function loading feature if the
778 variable `byte-compile-dynamic' is non-`nil' at compilation time. Do
779 not set this variable globally, since dynamic loading is desirable only
780 for certain files. Instead, enable the feature for specific source
781 files with file-local variable bindings, like this:
783 -*-byte-compile-dynamic: t;-*-
785 - Variable: byte-compile-dynamic
786 If this is non-`nil', the byte compiler generates compiled files
787 that are set up for dynamic function loading.
789 - Function: fetch-bytecode FUNCTION
790 This immediately finishes loading the definition of FUNCTION from
791 its byte-compiled file, if it is not fully loaded already. The
792 argument FUNCTION may be a compiled-function object or a function
796 File: lispref.info, Node: Eval During Compile, Next: Compiled-Function Objects, Prev: Dynamic Loading, Up: Byte Compilation
798 Evaluation During Compilation
799 =============================
801 These features permit you to write code to be evaluated during
802 compilation of a program.
804 - Special Form: eval-and-compile BODY
805 This form marks BODY to be evaluated both when you compile the
806 containing code and when you run it (whether compiled or not).
808 You can get a similar result by putting BODY in a separate file
809 and referring to that file with `require'. Using `require' is
810 preferable if there is a substantial amount of code to be executed
813 - Special Form: eval-when-compile BODY
814 This form marks BODY to be evaluated at compile time and not when
815 the compiled program is loaded. The result of evaluation by the
816 compiler becomes a constant which appears in the compiled program.
817 When the program is interpreted, not compiled at all, BODY is
820 At top level, this is analogous to the Common Lisp idiom
821 `(eval-when (compile eval) ...)'. Elsewhere, the Common Lisp `#.'
822 reader macro (but not when interpreting) is closer to what
823 `eval-when-compile' does.
826 File: lispref.info, Node: Compiled-Function Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation
828 Compiled-Function Objects
829 =========================
831 Byte-compiled functions have a special data type: they are
832 "compiled-function objects". The evaluator handles this data type
833 specially when it appears as a function to be called.
835 The printed representation for a compiled-function object normally
836 begins with `#<compiled-function' and ends with `>'. However, if the
837 variable `print-readably' is non-`nil', the object is printed beginning
838 with `#[' and ending with `]'. This representation can be read
839 directly by the Lisp reader, and is used in byte-compiled files (those
842 In Emacs version 18, there was no compiled-function object data type;
843 compiled functions used the function `byte-code' to run the byte code.
845 A compiled-function object has a number of different attributes.
849 The list of argument symbols.
852 The string containing the byte-code instructions.
855 The vector of Lisp objects referenced by the byte code. These
856 include symbols used as function names and variable names.
859 The maximum stack size this function needs.
862 The documentation string (if any); otherwise, `nil'. The value may
863 be a number or a list, in case the documentation string is stored
864 in a file. Use the function `documentation' to get the real
865 documentation string (*note Accessing Documentation::.).
868 The interactive spec (if any). This can be a string or a Lisp
869 expression. It is `nil' for a function that isn't interactive.
872 The domain (if any). This is only meaningful if I18N3
873 (message-translation) support was compiled into XEmacs. This is a
874 string defining which domain to find the translation for the
875 documentation string and interactive prompt. *Note Domain
878 Here's an example of a compiled-function object, in printed
879 representation. It is the definition of the command `backward-sexp'.
881 (symbol-function 'backward-sexp)
882 => #<compiled-function
884 "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
886 The primitive way to create a compiled-function object is with
889 - Function: make-byte-code ARGLIST INSTRUCTIONS CONSTANTS STACK-SIZE
890 &optional DOC-STRING INTERACTIVE
891 This function constructs and returns a compiled-function object
892 with the specified attributes.
894 *Please note:* Unlike all other Emacs-lisp functions, calling this
895 with five arguments is *not* the same as calling it with six
896 arguments, the last of which is `nil'. If the INTERACTIVE arg is
897 specified as `nil', then that means that this function was defined
898 with `(interactive)'. If the arg is not specified, then that means
899 the function is not interactive. This is terrible behavior which
900 is retained for compatibility with old `.elc' files which expected
903 You should not try to come up with the elements for a
904 compiled-function object yourself, because if they are inconsistent,
905 XEmacs may crash when you call the function. Always leave it to the
906 byte compiler to create these objects; it makes the elements consistent
909 The following primitives are provided for accessing the elements of
910 a compiled-function object.
912 - Function: compiled-function-arglist FUNCTION
913 This function returns the argument list of compiled-function object
916 - Function: compiled-function-instructions FUNCTION
917 This function returns a string describing the byte-code
918 instructions of compiled-function object FUNCTION.
920 - Function: compiled-function-constants FUNCTION
921 This function returns the vector of Lisp objects referenced by
922 compiled-function object FUNCTION.
924 - Function: compiled-function-stack-size FUNCTION
925 This function returns the maximum stack size needed by
926 compiled-function object FUNCTION.
928 - Function: compiled-function-doc-string FUNCTION
929 This function returns the doc string of compiled-function object
930 FUNCTION, if available.
932 - Function: compiled-function-interactive FUNCTION
933 This function returns the interactive spec of compiled-function
934 object FUNCTION, if any. The return value is `nil' or a
935 two-element list, the first element of which is the symbol
936 `interactive' and the second element is the interactive spec (a
937 string or Lisp form).
939 - Function: compiled-function-domain FUNCTION
940 This function returns the domain of compiled-function object
941 FUNCTION, if any. The result will be a string or `nil'. *Note
942 Domain Specification::.
945 File: lispref.info, Node: Disassembly, Prev: Compiled-Function Objects, Up: Byte Compilation
947 Disassembled Byte-Code
948 ======================
950 People do not write byte-code; that job is left to the byte compiler.
951 But we provide a disassembler to satisfy a cat-like curiosity. The
952 disassembler converts the byte-compiled code into humanly readable form.
954 The byte-code interpreter is implemented as a simple stack machine.
955 It pushes values onto a stack of its own, then pops them off to use them
956 in calculations whose results are themselves pushed back on the stack.
957 When a byte-code function returns, it pops a value off the stack and
958 returns it as the value of the function.
960 In addition to the stack, byte-code functions can use, bind, and set
961 ordinary Lisp variables, by transferring values between variables and
964 - Command: disassemble OBJECT &optional STREAM
965 This function prints the disassembled code for OBJECT. If STREAM
966 is supplied, then output goes there. Otherwise, the disassembled
967 code is printed to the stream `standard-output'. The argument
968 OBJECT can be a function name or a lambda expression.
970 As a special exception, if this function is used interactively, it
971 outputs to a buffer named `*Disassemble*'.
973 Here are two examples of using the `disassemble' function. We have
974 added explanatory comments to help you relate the byte-code to the Lisp
975 source; these do not appear in the output of `disassemble'.
977 (defun factorial (integer)
978 "Compute factorial of an integer."
980 (* integer (factorial (1- integer)))))
986 (disassemble 'factorial)
987 -| byte-code for factorial:
988 doc: Compute factorial of an integer.
991 0 varref integer ; Get value of `integer'
992 ; from the environment
996 1 constant 1 ; Push 1 onto stack.
998 2 eqlsign ; Pop top two values off stack,
1000 ; and push result onto stack.
1002 3 goto-if-nil 1 ; Pop and test top of stack;
1004 ; go to label 1 (which is also byte 7),
1007 5 constant 1 ; Push 1 onto top of stack.
1009 6 return ; Return the top element
1012 7:1 varref integer ; Push value of `integer' onto stack.
1014 8 constant factorial ; Push `factorial' onto stack.
1016 9 varref integer ; Push value of `integer' onto stack.
1018 10 sub1 ; Pop `integer', decrement value,
1019 ; push new value onto stack.
1021 ; Stack now contains:
1022 ; - decremented value of `integer'
1024 ; - value of `integer'
1026 15 call 1 ; Call function `factorial' using
1027 ; the first (i.e., the top) element
1028 ; of the stack as the argument;
1029 ; push returned value onto stack.
1031 ; Stack now contains:
1032 ; - result of recursive
1033 ; call to `factorial'
1034 ; - value of `integer'
1036 12 mult ; Pop top two values off the stack,
1038 ; pushing the result onto the stack.
1040 13 return ; Return the top element
1044 The `silly-loop' function is somewhat more complex:
1046 (defun silly-loop (n)
1047 "Return time before and after N iterations of a loop."
1048 (let ((t1 (current-time-string)))
1049 (while (> (setq n (1- n))
1051 (list t1 (current-time-string))))
1054 (disassemble 'silly-loop)
1055 -| byte-code for silly-loop:
1056 doc: Return time before and after N iterations of a loop.
1059 0 constant current-time-string ; Push
1060 ; `current-time-string'
1061 ; onto top of stack.
1063 1 call 0 ; Call `current-time-string'
1065 ; pushing result onto stack.
1067 2 varbind t1 ; Pop stack and bind `t1'
1070 3:1 varref n ; Get value of `n' from
1071 ; the environment and push
1072 ; the value onto the stack.
1074 4 sub1 ; Subtract 1 from top of stack.
1076 5 dup ; Duplicate the top of the stack;
1077 ; i.e., copy the top of
1078 ; the stack and push the
1079 ; copy onto the stack.
1081 6 varset n ; Pop the top of the stack,
1082 ; and set `n' to the value.
1084 ; In effect, the sequence `dup varset'
1085 ; copies the top of the stack
1086 ; into the value of `n'
1087 ; without popping it.
1089 7 constant 0 ; Push 0 onto stack.
1091 8 gtr ; Pop top two values off stack,
1092 ; test if N is greater than 0
1093 ; and push result onto stack.
1095 9 goto-if-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0
1096 ; (this exits the while loop).
1097 ; else pop top of stack
1100 11 varref t1 ; Push value of `t1' onto stack.
1102 12 constant current-time-string ; Push
1103 ; `current-time-string'
1104 ; onto top of stack.
1106 13 call 0 ; Call `current-time-string' again.
1108 14 unbind 1 ; Unbind `t1' in local environment.
1110 15 list2 ; Pop top two elements off stack,
1111 ; create a list of them,
1112 ; and push list onto stack.
1114 16 return ; Return the top element of the stack.
1119 File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top
1121 Debugging Lisp Programs
1122 ***********************
1124 There are three ways to investigate a problem in an XEmacs Lisp
1125 program, depending on what you are doing with the program when the
1128 * If the problem occurs when you run the program, you can use a Lisp
1129 debugger (either the default debugger or Edebug) to investigate
1130 what is happening during execution.
1132 * If the problem is syntactic, so that Lisp cannot even read the
1133 program, you can use the XEmacs facilities for editing Lisp to
1136 * If the problem occurs when trying to compile the program with the
1137 byte compiler, you need to know how to examine the compiler's
1142 * Debugger:: How the XEmacs Lisp debugger is implemented.
1143 * Syntax Errors:: How to find syntax errors.
1144 * Compilation Errors:: How to find errors that show up in byte compilation.
1145 * Edebug:: A source-level XEmacs Lisp debugger.
1147 Another useful debugging tool is the dribble file. When a dribble
1148 file is open, XEmacs copies all keyboard input characters to that file.
1149 Afterward, you can examine the file to find out what input was used.
1150 *Note Terminal Input::.
1152 For debugging problems in terminal descriptions, the
1153 `open-termscript' function can be useful. *Note Terminal Output::.
1156 File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging
1161 The "Lisp debugger" provides the ability to suspend evaluation of a
1162 form. While evaluation is suspended (a state that is commonly known as
1163 a "break"), you may examine the run time stack, examine the values of
1164 local or global variables, or change those values. Since a break is a
1165 recursive edit, all the usual editing facilities of XEmacs are
1166 available; you can even run programs that will enter the debugger
1167 recursively. *Note Recursive Editing::.
1171 * Error Debugging:: Entering the debugger when an error happens.
1172 * Infinite Loops:: Stopping and debugging a program that doesn't exit.
1173 * Function Debugging:: Entering it when a certain function is called.
1174 * Explicit Debug:: Entering it at a certain point in the program.
1175 * Using Debugger:: What the debugger does; what you see while in it.
1176 * Debugger Commands:: Commands used while in the debugger.
1177 * Invoking the Debugger:: How to call the function `debug'.
1178 * Internals of Debugger:: Subroutines of the debugger, and global variables.
projects / chise / xemacs-chise.git.1 / blob