This is elisp, produced by makeinfo version 4.0f from ./elisp.texi. INFO-DIR-SECTION Editors START-INFO-DIR-ENTRY * Elisp: (elisp). The Emacs Lisp Reference Manual. END-INFO-DIR-ENTRY This Info file contains edition 2.8 of the GNU Emacs Lisp Reference Manual, corresponding to Emacs version 21.2. Published by the Free Software Foundation 59 Temple Place, Suite 330 Boston, MA 02111-1307 USA Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000, 2001, 2002 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being "Copying", with the Front-Cover texts being "A GNU Manual", and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSF's Back-Cover Text is: "You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development."  File: elisp, Node: Autoload, Next: Repeated Loading, Prev: Loading Non-ASCII, Up: Loading Autoload ======== The "autoload" facility allows you to make a function or macro known in Lisp, but put off loading the file that defines it. The first call to the function automatically reads the proper file to install the real definition and other associated code, then runs the real definition as if it had been loaded all along. There are two ways to set up an autoloaded function: by calling `autoload', and by writing a special "magic" comment in the source before the real definition. `autoload' is the low-level primitive for autoloading; any Lisp program can call `autoload' at any time. Magic comments are the most convenient way to make a function autoload, for packages installed along with Emacs. These comments do nothing on their own, but they serve as a guide for the command `update-file-autoloads', which constructs calls to `autoload' and arranges to execute them when Emacs is built. - Function: autoload function filename &optional docstring interactive type This function defines the function (or macro) named FUNCTION so as to load automatically from FILENAME. The string FILENAME specifies the file to load to get the real definition of FUNCTION. If FILENAME does not contain either a directory name, or the suffix `.el' or `.elc', then `autoload' insists on adding one of these suffixes, and it will not load from a file whose name is just FILENAME with no added suffix. The argument DOCSTRING is the documentation string for the function. Normally, this should be identical to the documentation string in the function definition itself. Specifying the documentation string in the call to `autoload' makes it possible to look at the documentation without loading the function's real definition. If INTERACTIVE is non-`nil', that says FUNCTION can be called interactively. This lets completion in `M-x' work without loading FUNCTION's real definition. The complete interactive specification is not given here; it's not needed unless the user actually calls FUNCTION, and when that happens, it's time to load the real definition. You can autoload macros and keymaps as well as ordinary functions. Specify TYPE as `macro' if FUNCTION is really a macro. Specify TYPE as `keymap' if FUNCTION is really a keymap. Various parts of Emacs need to know this information without loading the real definition. An autoloaded keymap loads automatically during key lookup when a prefix key's binding is the symbol FUNCTION. Autoloading does not occur for other kinds of access to the keymap. In particular, it does not happen when a Lisp program gets the keymap from the value of a variable and calls `define-key'; not even if the variable name is the same symbol FUNCTION. If FUNCTION already has a non-void function definition that is not an autoload object, `autoload' does nothing and returns `nil'. If the function cell of FUNCTION is void, or is already an autoload object, then it is defined as an autoload object like this: (autoload FILENAME DOCSTRING INTERACTIVE TYPE) For example, (symbol-function 'run-prolog) => (autoload "prolog" 169681 t nil) In this case, `"prolog"' is the name of the file to load, 169681 refers to the documentation string in the `emacs/etc/DOC-VERSION' file (*note Documentation Basics::), `t' means the function is interactive, and `nil' that it is not a macro or a keymap. The autoloaded file usually contains other definitions and may require or provide one or more features. If the file is not completely loaded (due to an error in the evaluation of its contents), any function definitions or `provide' calls that occurred during the load are undone. This is to ensure that the next attempt to call any function autoloading from this file will try again to load the file. If not for this, then some of the functions in the file might be defined by the aborted load, but fail to work properly for the lack of certain subroutines not loaded successfully because they come later in the file. If the autoloaded file fails to define the desired Lisp function or macro, then an error is signaled with data `"Autoloading failed to define function FUNCTION-NAME"'. A magic autoload comment consists of `;;;###autoload', on a line by itself, just before the real definition of the function in its autoloadable source file. The command `M-x update-file-autoloads' writes a corresponding `autoload' call into `loaddefs.el'. Building Emacs loads `loaddefs.el' and thus calls `autoload'. `M-x update-directory-autoloads' is even more powerful; it updates autoloads for all files in the current directory. The same magic comment can copy any kind of form into `loaddefs.el'. If the form following the magic comment is not a function-defining form or a `defcustom' form, it is copied verbatim. "Function-defining forms" include `define-skeleton', `define-derived-mode', `define-generic-mode' and `define-minor-mode' as well as `defun' and `defmacro'. To save space, a `defcustom' form is converted to a `defvar' in `loaddefs.el', with some additional information if it uses `:require'. You can also use a magic comment to execute a form at build time _without_ executing it when the file itself is loaded. To do this, write the form _on the same line_ as the magic comment. Since it is in a comment, it does nothing when you load the source file; but `M-x update-file-autoloads' copies it to `loaddefs.el', where it is executed while building Emacs. The following example shows how `doctor' is prepared for autoloading with a magic comment: ;;;###autoload (defun doctor () "Switch to *doctor* buffer and start giving psychotherapy." (interactive) (switch-to-buffer "*doctor*") (doctor-mode)) Here's what that produces in `loaddefs.el': (autoload 'doctor "doctor" "\ Switch to *doctor* buffer and start giving psychotherapy." t) The backslash and newline immediately following the double-quote are a convention used only in the preloaded uncompiled Lisp files such as `loaddefs.el'; they tell `make-docfile' to put the documentation string in the `etc/DOC' file. *Note Building Emacs::. See also the commentary in `lib-src/make-docfile.c'.  File: elisp, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading Repeated Loading ================ You can load a given file more than once in an Emacs session. For example, after you have rewritten and reinstalled a function definition by editing it in a buffer, you may wish to return to the original version; you can do this by reloading the file it came from. When you load or reload files, bear in mind that the `load' and `load-library' functions automatically load a byte-compiled file rather than a non-compiled file of similar name. If you rewrite a file that you intend to save and reinstall, you need to byte-compile the new version; otherwise Emacs will load the older, byte-compiled file instead of your newer, non-compiled file! If that happens, the message displayed when loading the file includes, `(compiled; note, source is newer)', to remind you to recompile it. When writing the forms in a Lisp library file, keep in mind that the file might be loaded more than once. For example, think about whether each variable should be reinitialized when you reload the library; `defvar' does not change the value if the variable is already initialized. (*Note Defining Variables::.) The simplest way to add an element to an alist is like this: (setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist)) But this would add multiple elements if the library is reloaded. To avoid the problem, write this: (or (assq 'leif-mode minor-mode-alist) (setq minor-mode-alist (cons '(leif-mode " Leif") minor-mode-alist))) To add an element to a list just once, you can also use `add-to-list' (*note Setting Variables::). Occasionally you will want to test explicitly whether a library has already been loaded. Here's one way to test, in a library, whether it has been loaded before: (defvar foo-was-loaded nil) (unless foo-was-loaded EXECUTE-FIRST-TIME-ONLY (setq foo-was-loaded t)) If the library uses `provide' to provide a named feature, you can use `featurep' earlier in the file to test whether the `provide' call has been executed before. *Note Named Features::.  File: elisp, Node: Named Features, Next: Unloading, Prev: Repeated Loading, Up: Loading Features ======== `provide' and `require' are an alternative to `autoload' for loading files automatically. They work in terms of named "features". Autoloading is triggered by calling a specific function, but a feature is loaded the first time another program asks for it by name. A feature name is a symbol that stands for a collection of functions, variables, etc. The file that defines them should "provide" the feature. Another program that uses them may ensure they are defined by "requiring" the feature. This loads the file of definitions if it hasn't been loaded already. To require the presence of a feature, call `require' with the feature name as argument. `require' looks in the global variable `features' to see whether the desired feature has been provided already. If not, it loads the feature from the appropriate file. This file should call `provide' at the top level to add the feature to `features'; if it fails to do so, `require' signals an error. For example, in `emacs/lisp/prolog.el', the definition for `run-prolog' includes the following code: (defun run-prolog () "Run an inferior Prolog process, with I/O via buffer *prolog*." (interactive) (require 'comint) (switch-to-buffer (make-comint "prolog" prolog-program-name)) (inferior-prolog-mode)) The expression `(require 'comint)' loads the file `comint.el' if it has not yet been loaded. This ensures that `make-comint' is defined. Features are normally named after the files that provide them, so that `require' need not be given the file name. The `comint.el' file contains the following top-level expression: (provide 'comint) This adds `comint' to the global `features' list, so that `(require 'comint)' will henceforth know that nothing needs to be done. When `require' is used at top level in a file, it takes effect when you byte-compile that file (*note Byte Compilation::) as well as when you load it. This is in case the required package contains macros that the byte compiler must know about. It also avoids byte-compiler warnings for functions and variables defined in the file loaded with `require'. Although top-level calls to `require' are evaluated during byte compilation, `provide' calls are not. Therefore, you can ensure that a file of definitions is loaded before it is byte-compiled by including a `provide' followed by a `require' for the same feature, as in the following example. (provide 'my-feature) ; Ignored by byte compiler, ; evaluated by `load'. (require 'my-feature) ; Evaluated by byte compiler. The compiler ignores the `provide', then processes the `require' by loading the file in question. Loading the file does execute the `provide' call, so the subsequent `require' call does nothing when the file is loaded. - Function: provide feature This function announces that FEATURE is now loaded, or being loaded, into the current Emacs session. This means that the facilities associated with FEATURE are or will be available for other Lisp programs. The direct effect of calling `provide' is to add FEATURE to the front of the list `features' if it is not already in the list. The argument FEATURE must be a symbol. `provide' returns FEATURE. features => (bar bish) (provide 'foo) => foo features => (foo bar bish) When a file is loaded to satisfy an autoload, and it stops due to an error in the evaluating its contents, any function definitions or `provide' calls that occurred during the load are undone. *Note Autoload::. - Function: require feature &optional filename noerror This function checks whether FEATURE is present in the current Emacs session (using `(featurep FEATURE)'; see below). The argument FEATURE must be a symbol. If the feature is not present, then `require' loads FILENAME with `load'. If FILENAME is not supplied, then the name of the symbol FEATURE is used as the base file name to load. However, in this case, `require' insists on finding FEATURE with an added suffix; a file whose name is just FEATURE won't be used. If loading the file fails to provide FEATURE, `require' signals an error, `Required feature FEATURE was not provided', unless NOERROR is non-`nil'. - Function: featurep feature This function returns `t' if FEATURE has been provided in the current Emacs session (i.e., if FEATURE is a member of `features'.) - Variable: features The value of this variable is a list of symbols that are the features loaded in the current Emacs session. Each symbol was put in this list with a call to `provide'. The order of the elements in the `features' list is not significant.  File: elisp, Node: Unloading, Next: Hooks for Loading, Prev: Named Features, Up: Loading Unloading ========= You can discard the functions and variables loaded by a library to reclaim memory for other Lisp objects. To do this, use the function `unload-feature': - Command: unload-feature feature &optional force This command unloads the library that provided feature FEATURE. It undefines all functions, macros, and variables defined in that library with `defun', `defalias', `defsubst', `defmacro', `defconst', `defvar', and `defcustom'. It then restores any autoloads formerly associated with those symbols. (Loading saves these in the `autoload' property of the symbol.) Before restoring the previous definitions, `unload-feature' runs `remove-hook' to remove functions in the library from certain hooks. These hooks include variables whose names end in `hook' or `-hooks', plus those listed in `loadhist-special-hooks'. This is to prevent Emacs from ceasing to function because important hooks refer to functions that are no longer defined. If these measures are not sufficient to prevent malfunction, a library can define an explicit unload hook. If `FEATURE-unload-hook' is defined, it is run as a normal hook before restoring the previous definitions, _instead of_ the usual hook-removing actions. The unload hook ought to undo all the global state changes made by the library that might cease to work once the library is unloaded. `unload-feature' can cause problems with libraries that fail to do this, so it should be used with caution. Ordinarily, `unload-feature' refuses to unload a library on which other loaded libraries depend. (A library A depends on library B if A contains a `require' for B.) If the optional argument FORCE is non-`nil', dependencies are ignored and you can unload any library. The `unload-feature' function is written in Lisp; its actions are based on the variable `load-history'. - Variable: load-history This variable's value is an alist connecting library names with the names of functions and variables they define, the features they provide, and the features they require. Each element is a list and describes one library. The CAR of the list is the name of the library, as a string. The rest of the list is composed of these kinds of objects: * Symbols that were defined by this library. * Cons cells of the form `(require . FEATURE)' indicating features that were required. * Cons cells of the form `(provide . FEATURE)' indicating features that were provided. The value of `load-history' may have one element whose CAR is `nil'. This element describes definitions made with `eval-buffer' on a buffer that is not visiting a file. The command `eval-region' updates `load-history', but does so by adding the symbols defined to the element for the file being visited, rather than replacing that element. *Note Eval::. Preloaded libraries don't contribute initially to `load-history'. Instead, preloading writes information about preloaded libraries into a file, which can be loaded later on to add information to `load-history' describing the preloaded files. This file is installed in `exec-directory' and has a name of the form `fns-EMACSVERSION.el'. See the source for the function `symbol-file', for an example of code that loads this file to find functions in preloaded libraries. - Variable: loadhist-special-hooks This variable holds a list of hooks to be scanned before unloading a library, to remove functions defined in the library.  File: elisp, Node: Hooks for Loading, Prev: Unloading, Up: Loading Hooks for Loading ================= You can ask for code to be executed if and when a particular library is loaded, by calling `eval-after-load'. - Function: eval-after-load library form This function arranges to evaluate FORM at the end of loading the library LIBRARY, if and when LIBRARY is loaded. If LIBRARY is already loaded, it evaluates FORM right away. The library name LIBRARY must exactly match the argument of `load'. To get the proper results when an installed library is found by searching `load-path', you should not include any directory names in LIBRARY. An error in FORM does not undo the load, but does prevent execution of the rest of FORM. In general, well-designed Lisp programs should not use this feature. The clean and modular ways to interact with a Lisp library are (1) examine and set the library's variables (those which are meant for outside use), and (2) call the library's functions. If you wish to do (1), you can do it immediately--there is no need to wait for when the library is loaded. To do (2), you must load the library (preferably with `require'). But it is OK to use `eval-after-load' in your personal customizations if you don't feel they must meet the design standards for programs meant for wider use. - Variable: after-load-alist This variable holds an alist of expressions to evaluate if and when particular libraries are loaded. Each element looks like this: (FILENAME FORMS...) The function `load' checks `after-load-alist' in order to implement `eval-after-load'.  File: elisp, Node: Byte Compilation, Next: Advising Functions, Prev: Loading, Up: Top Byte Compilation **************** Emacs Lisp has a "compiler" that translates functions written in Lisp into a special representation called "byte-code" that can be executed more efficiently. The compiler replaces Lisp function definitions with byte-code. When a byte-code function is called, its definition is evaluated by the "byte-code interpreter". Because the byte-compiled code is evaluated by the byte-code interpreter, instead of being executed directly by the machine's hardware (as true compiled code is), byte-code is completely transportable from machine to machine without recompilation. It is not, however, as fast as true compiled code. Compiling a Lisp file with the Emacs byte compiler always reads the file as multibyte text, even if Emacs was started with `--unibyte', unless the file specifies otherwise. This is so that compilation gives results compatible with running the same file without compilation. *Note Loading Non-ASCII::. In general, any version of Emacs can run byte-compiled code produced by recent earlier versions of Emacs, but the reverse is not true. A major incompatible change was introduced in Emacs version 19.29, and files compiled with versions since that one will definitely not run in earlier versions unless you specify a special option. In addition, the modifier bits in keyboard characters were renumbered in Emacs 19.29; as a result, files compiled in versions before 19.29 will not work in subsequent versions if they contain character constants with modifier bits. *Note Compilation Errors::, for how to investigate errors occurring in byte compilation. * Menu: * Speed of Byte-Code:: An example of speedup from byte compilation. * Compilation Functions:: Byte compilation functions. * Docs and Compilation:: Dynamic loading of documentation strings. * Dynamic Loading:: Dynamic loading of individual functions. * Eval During Compile:: Code to be evaluated when you compile. * Byte-Code Objects:: The data type used for byte-compiled functions. * Disassembly:: Disassembling byte-code; how to read byte-code.  File: elisp, Node: Speed of Byte-Code, Next: Compilation Functions, Up: Byte Compilation Performance of Byte-Compiled Code ================================= A byte-compiled function is not as efficient as a primitive function written in C, but runs much faster than the version written in Lisp. Here is an example: (defun silly-loop (n) "Return time before and after N iterations of a loop." (let ((t1 (current-time-string))) (while (> (setq n (1- n)) 0)) (list t1 (current-time-string)))) => silly-loop (silly-loop 100000) => ("Fri Mar 18 17:25:57 1994" "Fri Mar 18 17:26:28 1994") ; 31 seconds (byte-compile 'silly-loop) => [Compiled code not shown] (silly-loop 100000) => ("Fri Mar 18 17:26:52 1994" "Fri Mar 18 17:26:58 1994") ; 6 seconds In this example, the interpreted code required 31 seconds to run, whereas the byte-compiled code required 6 seconds. These results are representative, but actual results will vary greatly.  File: elisp, Node: Compilation Functions, Next: Docs and Compilation, Prev: Speed of Byte-Code, Up: Byte Compilation The Compilation Functions ========================= You can byte-compile an individual function or macro definition with the `byte-compile' function. You can compile a whole file with `byte-compile-file', or several files with `byte-recompile-directory' or `batch-byte-compile'. The byte compiler produces error messages and warnings about each file in a buffer called `*Compile-Log*'. These report things in your program that suggest a problem but are not necessarily erroneous. Be careful when writing macro calls in files that you may someday byte-compile. Macro calls are expanded when they are compiled, so the macros must already be defined for proper compilation. For more details, see *Note Compiling Macros::. If a program does not work the same way when compiled as it does when interpreted, erroneous macro definitions are one likely cause (*note Problems with Macros::). Normally, compiling a file does not evaluate the file's contents or load the file. But it does execute any `require' calls at top level in the file. One way to ensure that necessary macro definitions are available during compilation is to require the file that defines them (*note Named Features::). To avoid loading the macro definition files when someone _runs_ the compiled program, write `eval-when-compile' around the `require' calls (*note Eval During Compile::). - Function: byte-compile symbol This function byte-compiles the function definition of SYMBOL, replacing the previous definition with the compiled one. The function definition of SYMBOL must be the actual code for the function; i.e., the compiler does not follow indirection to another symbol. `byte-compile' returns the new, compiled definition of SYMBOL. If SYMBOL's definition is a byte-code function object, `byte-compile' does nothing and returns `nil'. Lisp records only one function definition for any symbol, and if that is already compiled, non-compiled code is not available anywhere. So there is no way to "compile the same definition again." (defun factorial (integer) "Compute factorial of INTEGER." (if (= 1 integer) 1 (* integer (factorial (1- integer))))) => factorial (byte-compile 'factorial) => #[(integer) "^H\301U\203^H^@\301\207\302^H\303^HS!\"\207" [integer 1 * factorial] 4 "Compute factorial of INTEGER."] The result is a byte-code function object. The string it contains is the actual byte-code; each character in it is an instruction or an operand of an instruction. The vector contains all the constants, variable names and function names used by the function, except for certain primitives that are coded as special instructions. - Command: compile-defun This command reads the defun containing point, compiles it, and evaluates the result. If you use this on a defun that is actually a function definition, the effect is to install a compiled version of that function. - Command: byte-compile-file filename This function compiles a file of Lisp code named FILENAME into a file of byte-code. The output file's name is made by changing the `.el' suffix into `.elc'; if FILENAME does not end in `.el', it adds `.elc' to the end of FILENAME. Compilation works by reading the input file one form at a time. If it is a definition of a function or macro, the compiled function or macro definition is written out. Other forms are batched together, then each batch is compiled, and written so that its compiled code will be executed when the file is read. All comments are discarded when the input file is read. This command returns `t'. When called interactively, it prompts for the file name. % ls -l push* -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el (byte-compile-file "~/emacs/push.el") => t % ls -l push* -rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el -rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc - Command: byte-recompile-directory directory flag This function recompiles every `.el' file in DIRECTORY that needs recompilation. A file needs recompilation if a `.elc' file exists but is older than the `.el' file. When a `.el' file has no corresponding `.elc' file, FLAG says what to do. If it is `nil', these files are ignored. If it is non-`nil', the user is asked whether to compile each such file. The returned value of this command is unpredictable. - Function: batch-byte-compile This function runs `byte-compile-file' on files specified on the command line. This function must be used only in a batch execution of Emacs, as it kills Emacs on completion. An error in one file does not prevent processing of subsequent files, but no output file will be generated for it, and the Emacs process will terminate with a nonzero status code. % emacs -batch -f batch-byte-compile *.el - Function: byte-code code-string data-vector max-stack This function actually interprets byte-code. A byte-compiled function is actually defined with a body that calls `byte-code'. Don't call this function yourself--only the byte compiler knows how to generate valid calls to this function. In Emacs version 18, byte-code was always executed by way of a call to the function `byte-code'. Nowadays, byte-code is usually executed as part of a byte-code function object, and only rarely through an explicit call to `byte-code'.  File: elisp, Node: Docs and Compilation, Next: Dynamic Loading, Prev: Compilation Functions, Up: Byte Compilation Documentation Strings and Compilation ===================================== Functions and variables loaded from a byte-compiled file access their documentation strings dynamically from the file whenever needed. This saves space within Emacs, and makes loading faster because the documentation strings themselves need not be processed while loading the file. Actual access to the documentation strings becomes slower as a result, but this normally is not enough to bother users. Dynamic access to documentation strings does have drawbacks: * If you delete or move the compiled file after loading it, Emacs can no longer access the documentation strings for the functions and variables in the file. * If you alter the compiled file (such as by compiling a new version), then further access to documentation strings in this file will give nonsense results. If your site installs Emacs following the usual procedures, these problems will never normally occur. Installing a new version uses a new directory with a different name; as long as the old version remains installed, its files will remain unmodified in the places where they are expected to be. However, if you have built Emacs yourself and use it from the directory where you built it, you will experience this problem occasionally if you edit and recompile Lisp files. When it happens, you can cure the problem by reloading the file after recompiling it. Byte-compiled files made with recent versions of Emacs (since 19.29) will not load into older versions because the older versions don't support this feature. You can turn off this feature at compile time by setting `byte-compile-dynamic-docstrings' to `nil'; then you can compile files that will load into older Emacs versions. You can do this globally, or for one source file by specifying a file-local binding for the variable. One way to do that is by adding this string to the file's first line: -*-byte-compile-dynamic-docstrings: nil;-*- - Variable: byte-compile-dynamic-docstrings If this is non-`nil', the byte compiler generates compiled files that are set up for dynamic loading of documentation strings. The dynamic documentation string feature writes compiled files that use a special Lisp reader construct, `#@COUNT'. This construct skips the next COUNT characters. It also uses the `#$' construct, which stands for "the name of this file, as a string." It is usually best not to use these constructs in Lisp source files, since they are not designed to be clear to humans reading the file.  File: elisp, Node: Dynamic Loading, Next: Eval During Compile, Prev: Docs and Compilation, Up: Byte Compilation Dynamic Loading of Individual Functions ======================================= When you compile a file, you can optionally enable the "dynamic function loading" feature (also known as "lazy loading"). With dynamic function loading, loading the file doesn't fully read the function definitions in the file. Instead, each function definition contains a place-holder which refers to the file. The first time each function is called, it reads the full definition from the file, to replace the place-holder. The advantage of dynamic function loading is that loading the file becomes much faster. This is a good thing for a file which contains many separate user-callable functions, if using one of them does not imply you will probably also use the rest. A specialized mode which provides many keyboard commands often has that usage pattern: a user may invoke the mode, but use only a few of the commands it provides. The dynamic loading feature has certain disadvantages: * If you delete or move the compiled file after loading it, Emacs can no longer load the remaining function definitions not already loaded. * If you alter the compiled file (such as by compiling a new version), then trying to load any function not already loaded will yield nonsense results. These problems will never happen in normal circumstances with installed Emacs files. But they are quite likely to happen with Lisp files that you are changing. The easiest way to prevent these problems is to reload the new compiled file immediately after each recompilation. The byte compiler uses the dynamic function loading feature if the variable `byte-compile-dynamic' is non-`nil' at compilation time. Do not set this variable globally, since dynamic loading is desirable only for certain files. Instead, enable the feature for specific source files with file-local variable bindings. For example, you could do it by writing this text in the source file's first line: -*-byte-compile-dynamic: t;-*- - Variable: byte-compile-dynamic If this is non-`nil', the byte compiler generates compiled files that are set up for dynamic function loading. - Function: fetch-bytecode function This immediately finishes loading the definition of FUNCTION from its byte-compiled file, if it is not fully loaded already. The argument FUNCTION may be a byte-code function object or a function name.  File: elisp, Node: Eval During Compile, Next: Byte-Code Objects, Prev: Dynamic Loading, Up: Byte Compilation Evaluation During Compilation ============================= These features permit you to write code to be evaluated during compilation of a program. - Special Form: eval-and-compile body This form marks BODY to be evaluated both when you compile the containing code and when you run it (whether compiled or not). You can get a similar result by putting BODY in a separate file and referring to that file with `require'. That method is preferable when BODY is large. - Special Form: eval-when-compile body This form marks BODY to be evaluated at compile time but not when the compiled program is loaded. The result of evaluation by the compiler becomes a constant which appears in the compiled program. If you load the source file, rather than compiling it, BODY is evaluated normally. *Common Lisp Note:* At top level, this is analogous to the Common Lisp idiom `(eval-when (compile eval) ...)'. Elsewhere, the Common Lisp `#.' reader macro (but not when interpreting) is closer to what `eval-when-compile' does.  File: elisp, Node: Byte-Code Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation Byte-Code Function Objects ========================== Byte-compiled functions have a special data type: they are "byte-code function objects". Internally, a byte-code function object is much like a vector; however, the evaluator handles this data type specially when it appears as a function to be called. The printed representation for a byte-code function object is like that for a vector, with an additional `#' before the opening `['. A byte-code function object must have at least four elements; there is no maximum number, but only the first six elements have any normal use. They are: ARGLIST The list of argument symbols. BYTE-CODE The string containing the byte-code instructions. CONSTANTS The vector of Lisp objects referenced by the byte code. These include symbols used as function names and variable names. STACKSIZE The maximum stack size this function needs. DOCSTRING The documentation string (if any); otherwise, `nil'. The value may be a number or a list, in case the documentation string is stored in a file. Use the function `documentation' to get the real documentation string (*note Accessing Documentation::). INTERACTIVE The interactive spec (if any). This can be a string or a Lisp expression. It is `nil' for a function that isn't interactive. Here's an example of a byte-code function object, in printed representation. It is the definition of the command `backward-sexp'. #[(&optional arg) "^H\204^F^@\301^P\302^H[!\207" [arg 1 forward-sexp] 2 254435 "p"] The primitive way to create a byte-code object is with `make-byte-code': - Function: make-byte-code &rest elements This function constructs and returns a byte-code function object with ELEMENTS as its elements. You should not try to come up with the elements for a byte-code function yourself, because if they are inconsistent, Emacs may crash when you call the function. Always leave it to the byte compiler to create these objects; it makes the elements consistent (we hope). You can access the elements of a byte-code object using `aref'; you can also use `vconcat' to create a vector with the same elements.  File: elisp, Node: Disassembly, Prev: Byte-Code Objects, Up: Byte Compilation Disassembled Byte-Code ====================== People do not write byte-code; that job is left to the byte compiler. But we provide a disassembler to satisfy a cat-like curiosity. The disassembler converts the byte-compiled code into humanly readable form. The byte-code interpreter is implemented as a simple stack machine. It pushes values onto a stack of its own, then pops them off to use them in calculations whose results are themselves pushed back on the stack. When a byte-code function returns, it pops a value off the stack and returns it as the value of the function. In addition to the stack, byte-code functions can use, bind, and set ordinary Lisp variables, by transferring values between variables and the stack. - Command: disassemble object &optional stream This function prints the disassembled code for OBJECT. If STREAM is supplied, then output goes there. Otherwise, the disassembled code is printed to the stream `standard-output'. The argument OBJECT can be a function name or a lambda expression. As a special exception, if this function is used interactively, it outputs to a buffer named `*Disassemble*'. Here are two examples of using the `disassemble' function. We have added explanatory comments to help you relate the byte-code to the Lisp source; these do not appear in the output of `disassemble'. These examples show unoptimized byte-code. Nowadays byte-code is usually optimized, but we did not want to rewrite these examples, since they still serve their purpose. (defun factorial (integer) "Compute factorial of an integer." (if (= 1 integer) 1 (* integer (factorial (1- integer))))) => factorial (factorial 4) => 24 (disassemble 'factorial) -| byte-code for factorial: doc: Compute factorial of an integer. args: (integer) 0 constant 1 ; Push 1 onto stack. 1 varref integer ; Get value of `integer' ; from the environment ; and push the value ; onto the stack. 2 eqlsign ; Pop top two values off stack, ; compare them, ; and push result onto stack. 3 goto-if-nil 10 ; Pop and test top of stack; ; if `nil', go to 10, ; else continue. 6 constant 1 ; Push 1 onto top of stack. 7 goto 17 ; Go to 17 (in this case, 1 will be ; returned by the function). 10 constant * ; Push symbol `*' onto stack. 11 varref integer ; Push value of `integer' onto stack. 12 constant factorial ; Push `factorial' onto stack. 13 varref integer ; Push value of `integer' onto stack. 14 sub1 ; Pop `integer', decrement value, ; push new value onto stack. ; Stack now contains: ; - decremented value of `integer' ; - `factorial' ; - value of `integer' ; - `*' 15 call 1 ; Call function `factorial' using ; the first (i.e., the top) element ; of the stack as the argument; ; push returned value onto stack. ; Stack now contains: ; - result of recursive ; call to `factorial' ; - value of `integer' ; - `*' 16 call 2 ; Using the first two ; (i.e., the top two) ; elements of the stack ; as arguments, ; call the function `*', ; pushing the result onto the stack. 17 return ; Return the top element ; of the stack. => nil The `silly-loop' function is somewhat more complex: (defun silly-loop (n) "Return time before and after N iterations of a loop." (let ((t1 (current-time-string))) (while (> (setq n (1- n)) 0)) (list t1 (current-time-string)))) => silly-loop (disassemble 'silly-loop) -| byte-code for silly-loop: doc: Return time before and after N iterations of a loop. args: (n) 0 constant current-time-string ; Push ; `current-time-string' ; onto top of stack. 1 call 0 ; Call `current-time-string' ; with no argument, ; pushing result onto stack. 2 varbind t1 ; Pop stack and bind `t1' ; to popped value. 3 varref n ; Get value of `n' from ; the environment and push ; the value onto the stack. 4 sub1 ; Subtract 1 from top of stack. 5 dup ; Duplicate the top of the stack; ; i.e., copy the top of ; the stack and push the ; copy onto the stack. 6 varset n ; Pop the top of the stack, ; and bind `n' to the value. ; In effect, the sequence `dup varset' ; copies the top of the stack ; into the value of `n' ; without popping it. 7 constant 0 ; Push 0 onto stack. 8 gtr ; Pop top two values off stack, ; test if N is greater than 0 ; and push result onto stack. 9 goto-if-nil-else-pop 17 ; Goto 17 if `n' <= 0 ; (this exits the while loop). ; else pop top of stack ; and continue 12 constant nil ; Push `nil' onto stack ; (this is the body of the loop). 13 discard ; Discard result of the body ; of the loop (a while loop ; is always evaluated for ; its side effects). 14 goto 3 ; Jump back to beginning ; of while loop. 17 discard ; Discard result of while loop ; by popping top of stack. ; This result is the value `nil' that ; was not popped by the goto at 9. 18 varref t1 ; Push value of `t1' onto stack. 19 constant current-time-string ; Push ; `current-time-string' ; onto top of stack. 20 call 0 ; Call `current-time-string' again. 21 list2 ; Pop top two elements off stack, ; create a list of them, ; and push list onto stack. 22 unbind 1 ; Unbind `t1' in local environment. 23 return ; Return value of the top of stack. => nil  File: elisp, Node: Advising Functions, Next: Debugging, Prev: Byte Compilation, Up: Top Advising Emacs Lisp Functions ***************************** The "advice" feature lets you add to the existing definition of a function, by "advising the function". This is a clean method for a library to customize functions defined by other parts of Emacs--cleaner than redefining the whole function. Each function can have multiple "pieces of advice", separately defined. Each defined piece of advice can be "enabled" or disabled explicitly. All the enabled pieces of advice for any given function actually take effect when you "activate" advice for that function, or when you define or redefine the function. Note that enabling a piece of advice and activating advice for a function are not the same thing. *Usage Note:* Advice is useful for altering the behavior of existing calls to an existing function. If you want the new behavior for new calls, or for key bindings, it is cleaner to define a new function (or a new command) which uses the existing function. * Menu: * Simple Advice:: A simple example to explain the basics of advice. * Defining Advice:: Detailed description of `defadvice'. * Around-Advice:: Wrapping advice around a function's definition. * Computed Advice:: ...is to `defadvice' as `fset' is to `defun'. * Activation of Advice:: Advice doesn't do anything until you activate it. * Enabling Advice:: You can enable or disable each piece of advice. * Preactivation:: Preactivation is a way of speeding up the loading of compiled advice. * Argument Access in Advice:: How advice can access the function's arguments. * Subr Arguments:: Accessing arguments when advising a primitive. * Combined Definition:: How advice is implemented.