+++ /dev/null
-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
-
-INFO-DIR-SECTION XEmacs Editor
-START-INFO-DIR-ENTRY
-* Lispref: (lispref). XEmacs Lisp Reference Manual.
-END-INFO-DIR-ENTRY
-
- Edition History:
-
- GNU Emacs Lisp Reference Manual Second Edition (v2.01), May 1993 GNU
-Emacs Lisp Reference Manual Further Revised (v2.02), August 1993 Lucid
-Emacs Lisp Reference Manual (for 19.10) First Edition, March 1994
-XEmacs Lisp Programmer's Manual (for 19.12) Second Edition, April 1995
-GNU Emacs Lisp Reference Manual v2.4, June 1995 XEmacs Lisp
-Programmer's Manual (for 19.13) Third Edition, July 1995 XEmacs Lisp
-Reference Manual (for 19.14 and 20.0) v3.1, March 1996 XEmacs Lisp
-Reference Manual (for 19.15 and 20.1, 20.2, 20.3) v3.2, April, May,
-November 1997 XEmacs Lisp Reference Manual (for 21.0) v3.3, April 1998
-
- Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software
-Foundation, Inc. Copyright (C) 1994, 1995 Sun Microsystems, Inc.
-Copyright (C) 1995, 1996 Ben Wing.
-
- Permission is granted to make and distribute verbatim copies of this
-manual provided the copyright notice and this permission notice are
-preserved on all copies.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided that the
-entire resulting derived work is distributed under the terms of a
-permission notice identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that this permission notice may be stated in a
-translation approved by the Foundation.
-
- Permission is granted to copy and distribute modified versions of
-this manual under the conditions for verbatim copying, provided also
-that the section entitled "GNU General Public License" is included
-exactly as in the original, and provided that the entire resulting
-derived work is distributed under the terms of a permission notice
-identical to this one.
-
- Permission is granted to copy and distribute translations of this
-manual into another language, under the above conditions for modified
-versions, except that the section entitled "GNU General Public License"
-may be included in a translation approved by the Free Software
-Foundation instead of in the original English.
-
-\1f
-File: lispref.info, Node: Autoload, Next: Repeated Loading, Prev: How Programs Do Loading, 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 do nothing on their own; 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. Magic comments are the
-most convenient way to make a function autoload, but only for packages
-installed along with Emacs.
-
- - 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.
-
- The argument DOCSTRING is the documentation string for the
- function. Normally, this is the 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', then the function can be called
- interactively. This lets completion in `M-x' work without loading
- the function's real definition. The complete interactive
- specification need not be 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 `DOC' 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 appear defined, but
-they might fail to work properly for the lack of certain subroutines
-defined later in the file and not loaded successfully.
-
- XEmacs as distributed comes with many autoloaded functions. The
-calls to `autoload' are in the file `loaddefs.el'. There is a
-convenient way of updating them automatically.
-
- 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 looks like `;;;###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 definition,
-it is copied verbatim. 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 `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 Lisp files such as `loaddefs.el';
-they tell `make-docfile' to put the documentation string in the `DOC'
-file. *Note Building XEmacs::.
-
-\1f
-File: lispref.info, Node: Repeated Loading, Next: Named Features, Prev: Autoload, Up: Loading
-
-Repeated Loading
-================
-
- You may load one 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, remember to byte-compile it if
-necessary; otherwise you may find yourself inadvertently reloading the
-older, byte-compiled file instead of your newer, non-compiled file!
-
- When writing the forms in a Lisp library file, keep in mind that the
-file might be loaded more than once. For example, the choice of
-`defvar' vs. `defconst' for defining a variable depends on whether it
-is desirable to reinitialize the variable if the library is reloaded:
-`defconst' does so, and `defvar' does not. (*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, 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)
-
- (if (not (boundp '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' to test whether the library has been loaded. *Note Named
-Features::.
-
-\1f
-File: lispref.info, 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.
-
- Features are normally named after the files that provide them, so
-that `require' need not be given the file name.
-
- For example, in `emacs/lisp/prolog.el', the definition for
-`run-prolog' includes the following code:
-
- (defun run-prolog ()
- "Run an inferior Prolog process, input and output 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.
-
- 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.
-
- 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 while
-loading.
-
- - Function: provide FEATURE
- This function announces that FEATURE is now loaded, or being
- loaded, into the current XEmacs 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
- This function checks whether FEATURE is present in the current
- XEmacs session (using `(featurep FEATURE)'; see below). If it is
- not, then `require' loads FILENAME with `load'. If FILENAME is
- not supplied, then the name of the symbol FEATURE is used as the
- file name to load.
-
- If loading the file fails to provide FEATURE, `require' signals an
- error, `Required feature FEATURE was not provided'.
-
- - Function: featurep FEXP
- This function returns `t' if feature FEXP is present in this
- Emacs. Use this to conditionalize execution of lisp code based on
- the presence or absence of emacs or environment extensions.
-
- FEXP can be a symbol, a number, or a list.
-
- If FEXP is a symbol, it is looked up in the `features' variable,
- and `t' is returned if it is found, `nil' otherwise.
-
- If FEXP is a number, the function returns `t' if this Emacs has an
- equal or greater number than `fexp', `nil' otherwise. Note that
- minor Emacs version is expected to be 2 decimal places wide, so
- `(featurep 20.4)' will return `nil' on XEmacs 20.4--you must write
- `(featurep 20.04)', unless you wish to match for XEmacs 20.40.
-
- If FEXP is a list whose car is the symbol `and', the function
- returns `t' if all the features in its cdr are present, `nil'
- otherwise.
-
- If FEXP is a list whose car is the symbol `or', the function
- returns `t' if any the features in its cdr are present, `nil'
- otherwise.
-
- If FEXP is a list whose car is the symbol `not', the function
- returns `t' if the feature is not present, `nil' otherwise.
-
- Examples:
-
- (featurep 'xemacs)
- => ; t on XEmacs.
-
- (featurep '(and xemacs gnus))
- => ; t on XEmacs with Gnus loaded.
-
- (featurep '(or tty-frames (and emacs 19.30)))
- => ; t if this Emacs supports TTY frames.
-
- (featurep '(or (and xemacs 19.15) (and emacs 19.34)))
- => ; t on XEmacs 19.15 and later, or on
- ; FSF Emacs 19.34 and later.
-
- *Please note:* The advanced arguments of this function (anything
- other than a symbol) are not yet supported by FSF Emacs. If you
- feel they are useful for supporting multiple Emacs variants, lobby
- Richard Stallman at `<bug-gnu-emacs@prep.ai.mit.edu>'.
-
- - Variable: features
- The value of this variable is a list of symbols that are the
- features loaded in the current XEmacs 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.
-
-\1f
-File: lispref.info, 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 `defconst', `defvar', `defun', `defmacro',
- `defsubst', `definf-function' and `defalias'. It then restores
- any autoloads formerly associated with those symbols. (Loading
- saves these in the `autoload' property of the symbol.)
-
- 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.
-
- * Lists of the form `(require . FEATURE)' indicating features
- that were required.
-
- * Lists 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.
-
-\1f
-File: lispref.info, Node: Hooks for Loading, Prev: Unloading, Up: Loading
-
-Hooks for Loading
-=================
-
- - Variable: after-load-alist
- An alist of expressions to evaluate if and when particular
- libraries are loaded. Each element looks like this:
-
- (FILENAME FORMS...)
-
- When `load' is run and the file-name argument is FILENAME, the
- FORMS in the corresponding element are executed at the end of
- loading.
-
- FILENAME must match exactly! Normally FILENAME is the name of a
- library, with no directory specified, since that is how `load' is
- normally called. An error in FORMS does not undo the load, but
- does prevent execution of the rest of the FORMS.
-
-
-\1f
-File: lispref.info, Node: Byte Compilation, Next: Debugging, Prev: Loading, Up: Top
-
-Byte Compilation
-****************
-
- XEmacs 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-coded 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.
-
- In general, any version of Emacs can run byte-compiled code produced
-by recent earlier versions of Emacs, but the reverse is not true. In
-particular, if you compile a program with XEmacs 20, the compiled code
-may not run in earlier versions.
-
- The first time a compiled-function object is executed, the byte-code
-instructions are validated and the byte-code is further optimized. An
-`invalid-byte-code' error is signaled if the byte-code is invalid, for
-example if it contains invalid opcodes. This usually means a bug in
-the byte compiler.
-
- *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.
-* Compiled-Function Objects:: The data type used for byte-compiled functions.
-* Disassembly:: Disassembling byte-code; how to read byte-code.
-
-\1f
-File: lispref.info, 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 5000000)
- => ("Mon Sep 14 15:51:49 1998"
- "Mon Sep 14 15:52:07 1998") ; 18 seconds
-
- (byte-compile 'silly-loop)
- => #<compiled-function
- (n)
- "...(23)"
- [current-time-string t1 n 0]
- 2
- "Return time before and after N iterations of a loop.">
-
- (silly-loop 5000000)
- => ("Mon Sep 14 15:53:43 1998"
- "Mon Sep 14 15:53:49 1998") ; 6 seconds
-
- In this example, the interpreted code required 18 seconds to run,
-whereas the byte-compiled code required 6 seconds. These results are
-representative, but actual results will vary greatly.
-
-\1f
-File: lispref.info, 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'.
-
- When you run the byte compiler, you may get warnings in a buffer
-called `*Compile-Log*'. These report things in your program that
-suggest a problem but are not necessarily erroneous.
-
- Be careful when byte-compiling code that uses macros. 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::.
-
- 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 compiled-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)
- => #<compiled-function
- (integer)
- "...(21)"
- [integer 1 factorial]
- 3
- "Compute factorial of INTEGER.">
-
- The result is a compiled-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 &optional ARG
- 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.
-
- If ARG is non-`nil', the result is inserted in the current buffer
- after the form; otherwise, it is printed in the minibuffer.
-
- - Command: byte-compile-file FILENAME &optional LOAD
- This function compiles a file of Lisp code named FILENAME into a
- file of byte-code. The output file's name is made by appending
- `c' to the end of FILENAME.
-
- If `load' is non-`nil', the file is loaded after having been
- compiled.
-
- 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-r--r-- 1 lewis 638 Oct 8 20:25 push.elc
-
- - Command: byte-recompile-directory DIRECTORY &optional 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, then 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 return 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. (The
- file that gets the error will not, of course, produce any compiled
- code.)
-
- % emacs -batch -f batch-byte-compile *.el
-
- - Function: batch-byte-recompile-directory
- This function is similar to `batch-byte-compile' but runs the
- command `byte-recompile-directory' on the files remaining on the
- command line.
-
- - Variable: byte-recompile-directory-ignore-errors-p
- If non-`nil', this specifies that `byte-recompile-directory' will
- continue compiling even when an error occurs in a file. This is
- normally `nil', but is bound to `t' by
- `batch-byte-recompile-directory'.
-
- - Function: byte-code INSTRUCTIONS CONSTANTS STACK-SIZE
- This function actually interprets byte-code. Don't call this
- function yourself. Only the byte compiler knows how to generate
- valid calls to this function.
-
- In newer Emacs versions (19 and up), byte code is usually executed
- as part of a compiled-function object, and only rarely due to an
- explicit call to `byte-code'. A byte-compiled function was once
- actually defined with a body that calls `byte-code', but in recent
- versions of Emacs `byte-code' is only used to run isolated
- fragments of lisp code without an associated argument list.
-
-\1f
-File: lispref.info, 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 normally 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.
-
- Versions of Emacs up to and including XEmacs 19.14 and FSF Emacs
-19.28 do not support the dynamic docstrings feature, and so will not be
-able to load bytecode created by more recent Emacs versions. You can
-turn off the dynamic docstring feature by setting
-`byte-compile-dynamic-docstrings' to `nil'. Once this is done, 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. Here's one way to do that:
-
- -*-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 best not to use
-these constructs in Lisp source files.
-
-\1f
-File: lispref.info, 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 commands, provided that using one of them does not imply
-you will soon (or ever) 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
- get nonsense results.
-
- If you compile a new version of the file, the best thing to do is
-immediately load the new compiled file. That will prevent any future
-problems.
-
- 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, like this:
-
- -*-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 compiled-function object or a function
- name.
-
-\1f
-File: lispref.info, Node: Eval During Compile, Next: Compiled-Function 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'. Using `require' is
- preferable if there is a substantial amount of code to be executed
- in this way.
-
- - Special Form: eval-when-compile BODY
- This form marks BODY to be evaluated at compile time and not when
- the compiled program is loaded. The result of evaluation by the
- compiler becomes a constant which appears in the compiled program.
- When the program is interpreted, not compiled at all, BODY is
- evaluated normally.
-
- 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.
-
-\1f
-File: lispref.info, Node: Compiled-Function Objects, Next: Disassembly, Prev: Eval During Compile, Up: Byte Compilation
-
-Compiled-Function Objects
-=========================
-
- Byte-compiled functions have a special data type: they are
-"compiled-function objects". The evaluator handles this data type
-specially when it appears as a function to be called.
-
- The printed representation for a compiled-function object normally
-begins with `#<compiled-function' and ends with `>'. However, if the
-variable `print-readably' is non-`nil', the object is printed beginning
-with `#[' and ending with `]'. This representation can be read
-directly by the Lisp reader, and is used in byte-compiled files (those
-ending in `.elc').
-
- In Emacs version 18, there was no compiled-function object data type;
-compiled functions used the function `byte-code' to run the byte code.
-
- A compiled-function object has a number of different attributes.
-They are:
-
-ARGLIST
- The list of argument symbols.
-
-INSTRUCTIONS
- 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.
-
-STACK-SIZE
- The maximum stack size this function needs.
-
-DOC-STRING
- 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.
-
-DOMAIN
- The domain (if any). This is only meaningful if I18N3
- (message-translation) support was compiled into XEmacs. This is a
- string defining which domain to find the translation for the
- documentation string and interactive prompt. *Note Domain
- Specification::.
-
- Here's an example of a compiled-function object, in printed
-representation. It is the definition of the command `backward-sexp'.
-
- (symbol-function 'backward-sexp)
- => #<compiled-function
- (&optional arg)
- "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
-
- The primitive way to create a compiled-function object is with
-`make-byte-code':
-
- - Function: make-byte-code ARGLIST INSTRUCTIONS CONSTANTS STACK-SIZE
- &optional DOC-STRING INTERACTIVE
- This function constructs and returns a compiled-function object
- with the specified attributes.
-
- *Please note:* Unlike all other Emacs-lisp functions, calling this
- with five arguments is *not* the same as calling it with six
- arguments, the last of which is `nil'. If the INTERACTIVE arg is
- specified as `nil', then that means that this function was defined
- with `(interactive)'. If the arg is not specified, then that means
- the function is not interactive. This is terrible behavior which
- is retained for compatibility with old `.elc' files which expected
- these semantics.
-
- You should not try to come up with the elements for a
-compiled-function object yourself, because if they are inconsistent,
-XEmacs 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).
-
- The following primitives are provided for accessing the elements of
-a compiled-function object.
-
- - Function: compiled-function-arglist FUNCTION
- This function returns the argument list of compiled-function object
- FUNCTION.
-
- - Function: compiled-function-instructions FUNCTION
- This function returns a string describing the byte-code
- instructions of compiled-function object FUNCTION.
-
- - Function: compiled-function-constants FUNCTION
- This function returns the vector of Lisp objects referenced by
- compiled-function object FUNCTION.
-
- - Function: compiled-function-stack-size FUNCTION
- This function returns the maximum stack size needed by
- compiled-function object FUNCTION.
-
- - Function: compiled-function-doc-string FUNCTION
- This function returns the doc string of compiled-function object
- FUNCTION, if available.
-
- - Function: compiled-function-interactive FUNCTION
- This function returns the interactive spec of compiled-function
- object FUNCTION, if any. The return value is `nil' or a
- two-element list, the first element of which is the symbol
- `interactive' and the second element is the interactive spec (a
- string or Lisp form).
-
- - Function: compiled-function-domain FUNCTION
- This function returns the domain of compiled-function object
- FUNCTION, if any. The result will be a string or `nil'. *Note
- Domain Specification::.
-
-\1f
-File: lispref.info, Node: Disassembly, Prev: Compiled-Function 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'.
-
- (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 varref integer ; Get value of `integer'
- ; from the environment
- ; and push the value
- ; onto the stack.
-
- 1 constant 1 ; Push 1 onto stack.
-
- 2 eqlsign ; Pop top two values off stack,
- ; compare them,
- ; and push result onto stack.
-
- 3 goto-if-nil 1 ; Pop and test top of stack;
- ; if `nil',
- ; go to label 1 (which is also byte 7),
- ; else continue.
-
- 5 constant 1 ; Push 1 onto top of stack.
-
- 6 return ; Return the top element
- ; of the stack.
-
- 7:1 varref integer ; Push value of `integer' onto stack.
-
- 8 constant factorial ; Push `factorial' onto stack.
-
- 9 varref integer ; Push value of `integer' onto stack.
-
- 10 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'
-
- 12 mult ; Pop top two values off the stack,
- ; multiply them,
- ; pushing the result onto the stack.
-
- 13 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:1 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 set `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-not-nil 1 ; Goto label 1 (byte 3) if `n' <= 0
- ; (this exits the while loop).
- ; else pop top of stack
- ; and continue
-
- 11 varref t1 ; Push value of `t1' onto stack.
-
- 12 constant current-time-string ; Push
- ; `current-time-string'
- ; onto top of stack.
-
- 13 call 0 ; Call `current-time-string' again.
-
- 14 unbind 1 ; Unbind `t1' in local environment.
-
- 15 list2 ; Pop top two elements off stack,
- ; create a list of them,
- ; and push list onto stack.
-
- 16 return ; Return the top element of the stack.
-
- => nil
-
-\1f
-File: lispref.info, Node: Debugging, Next: Read and Print, Prev: Byte Compilation, Up: Top
-
-Debugging Lisp Programs
-***********************
-
- There are three ways to investigate a problem in an XEmacs Lisp
-program, depending on what you are doing with the program when the
-problem appears.
-
- * If the problem occurs when you run the program, you can use a Lisp
- debugger (either the default debugger or Edebug) to investigate
- what is happening during execution.
-
- * If the problem is syntactic, so that Lisp cannot even read the
- program, you can use the XEmacs facilities for editing Lisp to
- localize it.
-
- * If the problem occurs when trying to compile the program with the
- byte compiler, you need to know how to examine the compiler's
- input buffer.
-
-* Menu:
-
-* Debugger:: How the XEmacs Lisp debugger is implemented.
-* Syntax Errors:: How to find syntax errors.
-* Compilation Errors:: How to find errors that show up in byte compilation.
-* Edebug:: A source-level XEmacs Lisp debugger.
-
- Another useful debugging tool is the dribble file. When a dribble
-file is open, XEmacs copies all keyboard input characters to that file.
-Afterward, you can examine the file to find out what input was used.
-*Note Terminal Input::.
-
- For debugging problems in terminal descriptions, the
-`open-termscript' function can be useful. *Note Terminal Output::.
-
-\1f
-File: lispref.info, Node: Debugger, Next: Syntax Errors, Up: Debugging
-
-The Lisp Debugger
-=================
-
- The "Lisp debugger" provides the ability to suspend evaluation of a
-form. While evaluation is suspended (a state that is commonly known as
-a "break"), you may examine the run time stack, examine the values of
-local or global variables, or change those values. Since a break is a
-recursive edit, all the usual editing facilities of XEmacs are
-available; you can even run programs that will enter the debugger
-recursively. *Note Recursive Editing::.
-
-* Menu:
-
-* Error Debugging:: Entering the debugger when an error happens.
-* Infinite Loops:: Stopping and debugging a program that doesn't exit.
-* Function Debugging:: Entering it when a certain function is called.
-* Explicit Debug:: Entering it at a certain point in the program.
-* Using Debugger:: What the debugger does; what you see while in it.
-* Debugger Commands:: Commands used while in the debugger.
-* Invoking the Debugger:: How to call the function `debug'.
-* Internals of Debugger:: Subroutines of the debugger, and global variables.
-
projects / chise / xemacs-chise.git.1 / blobdiff