Initial revision
[chise/xemacs-chise.git.1] / info / lispref.info-12
1 This is Info file ../../info/lispref.info, produced by Makeinfo version
2 1.68 from the input file lispref.texi.
3
4 INFO-DIR-SECTION XEmacs Editor
5 START-INFO-DIR-ENTRY
6 * Lispref: (lispref).           XEmacs Lisp Reference Manual.
7 END-INFO-DIR-ENTRY
8
9    Edition History:
10
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
20
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.
24
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.
28
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.
33
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.
38
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.
45
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.
51
52 \1f
53 File: lispref.info,  Node: Autoload,  Next: Repeated Loading,  Prev: How Programs Do Loading,  Up: Loading
54
55 Autoload
56 ========
57
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.
63
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.
73
74  - Function: autoload FUNCTION FILENAME &optional DOCSTRING INTERACTIVE
75           TYPE
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.
79
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
85      definition.
86
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.
93
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
98      definition.
99
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.
106
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:
111
112           (autoload FILENAME DOCSTRING INTERACTIVE TYPE)
113
114      For example,
115
116           (symbol-function 'run-prolog)
117                => (autoload "prolog" 169681 t nil)
118
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.
123
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.
133
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.
137
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"'.
141
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.
149
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.
158
159    The following example shows how `doctor' is prepared for autoloading
160 with a magic comment:
161
162      ;;;###autoload
163      (defun doctor ()
164        "Switch to *doctor* buffer and start giving psychotherapy."
165        (interactive)
166        (switch-to-buffer "*doctor*")
167        (doctor-mode))
168
169 Here's what that produces in `loaddefs.el':
170
171      (autoload 'doctor "doctor"
172        "\
173      Switch to *doctor* buffer and start giving psychotherapy."
174        t)
175
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::.
180
181 \1f
182 File: lispref.info,  Node: Repeated Loading,  Next: Named Features,  Prev: Autoload,  Up: Loading
183
184 Repeated Loading
185 ================
186
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.
191
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!
198
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
204 Variables::.)
205
206    The simplest way to add an element to an alist is like this:
207
208      (setq minor-mode-alist
209            (cons '(leif-mode " Leif") minor-mode-alist))
210
211 But this would add multiple elements if the library is reloaded.  To
212 avoid the problem, write this:
213
214      (or (assq 'leif-mode minor-mode-alist)
215          (setq minor-mode-alist
216                (cons '(leif-mode " Leif") minor-mode-alist)))
217
218    To add an element to a list just once, use `add-to-list' (*note
219 Setting Variables::.).
220
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:
224
225      (defvar foo-was-loaded)
226      
227      (if (not (boundp 'foo-was-loaded))
228          EXECUTE-FIRST-TIME-ONLY)
229      
230      (setq foo-was-loaded t)
231
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
234 Features::.
235
236 \1f
237 File: lispref.info,  Node: Named Features,  Next: Unloading,  Prev: Repeated Loading,  Up: Loading
238
239 Features
240 ========
241
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.
246
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.
252
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.
259
260    Features are normally named after the files that provide them, so
261 that `require' need not be given the file name.
262
263    For example, in `emacs/lisp/prolog.el', the definition for
264 `run-prolog' includes the following code:
265
266      (defun run-prolog ()
267        "Run an inferior Prolog process, input and output via buffer *prolog*."
268        (interactive)
269        (require 'comint)
270        (switch-to-buffer (make-comint "prolog" prolog-program-name))
271        (inferior-prolog-mode))
272
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.
275
276    The `comint.el' file contains the following top-level expression:
277
278      (provide 'comint)
279
280 This adds `comint' to the global `features' list, so that `(require
281 'comint)' will henceforth know that nothing needs to be done.
282
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.
287
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
292 following example.
293
294      (provide 'my-feature)  ; Ignored by byte compiler,
295                             ;   evaluated by `load'.
296      (require 'my-feature)  ; Evaluated by byte compiler.
297
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
301 loading.
302
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
307      other Lisp programs.
308
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.
312
313           features
314                => (bar bish)
315           
316           (provide 'foo)
317                => foo
318           features
319                => (foo bar bish)
320
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.
324      *Note Autoload::.
325
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
331      file name to load.
332
333      If loading the file fails to provide FEATURE, `require' signals an
334      error, `Required feature FEATURE was not provided'.
335
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.
340
341      FEXP can be a symbol, a number, or a list.
342
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.
345
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.
351
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'
354      otherwise.
355
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'
358      otherwise.
359
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.
362
363      Examples:
364
365           (featurep 'xemacs)
366                => ; t on XEmacs.
367           
368           (featurep '(and xemacs gnus))
369                => ; t on XEmacs with Gnus loaded.
370           
371           (featurep '(or tty-frames (and emacs 19.30)))
372                => ; t if this Emacs supports TTY frames.
373           
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.
377
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>'.
382
383  - Variable: features
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.
388
389 \1f
390 File: lispref.info,  Node: Unloading,  Next: Hooks for Loading,  Prev: Named Features,  Up: Loading
391
392 Unloading
393 =========
394
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
397 `unload-feature':
398
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.)
406
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
411      library.
412
413    The `unload-feature' function is written in Lisp; its actions are
414 based on the variable `load-history'.
415
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.
420
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:
424
425         * Symbols that were defined by this library.
426
427         * Lists of the form `(require . FEATURE)' indicating features
428           that were required.
429
430         * Lists of the form `(provide . FEATURE)' indicating features
431           that were provided.
432
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.
436
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.
440
441 \1f
442 File: lispref.info,  Node: Hooks for Loading,  Prev: Unloading,  Up: Loading
443
444 Hooks for Loading
445 =================
446
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:
450
451           (FILENAME FORMS...)
452
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
455      loading.
456
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.
461
462
463 \1f
464 File: lispref.info,  Node: Byte Compilation,  Next: Debugging,  Prev: Loading,  Up: Top
465
466 Byte Compilation
467 ****************
468
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".
474
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.
480
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.
485
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
490 the byte compiler.
491
492    *Note Compilation Errors::, for how to investigate errors occurring
493 in byte compilation.
494
495 * Menu:
496
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.
504
505 \1f
506 File: lispref.info,  Node: Speed of Byte-Code,  Next: Compilation Functions,  Up: Byte Compilation
507
508 Performance of Byte-Compiled Code
509 =================================
510
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.
513 Here is an example:
514
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))
519                    0))
520          (list t1 (current-time-string))))
521      => silly-loop
522      
523      (silly-loop 5000000)
524      => ("Mon Sep 14 15:51:49 1998"
525          "Mon Sep 14 15:52:07 1998")  ; 18 seconds
526      
527      (byte-compile 'silly-loop)
528      => #<compiled-function
529      (n)
530      "...(23)"
531      [current-time-string t1 n 0]
532      2
533      "Return time before and after N iterations of a loop.">
534      
535      (silly-loop 5000000)
536      => ("Mon Sep 14 15:53:43 1998"
537          "Mon Sep 14 15:53:49 1998")  ; 6 seconds
538
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.
542
543 \1f
544 File: lispref.info,  Node: Compilation Functions,  Next: Docs and Compilation,  Prev: Speed of Byte-Code,  Up: Byte Compilation
545
546 The Compilation Functions
547 =========================
548
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'.
553
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.
557
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
561 Macros::.
562
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::.).
570
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.
578
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."
584
585           (defun factorial (integer)
586             "Compute factorial of INTEGER."
587             (if (= 1 integer) 1
588               (* integer (factorial (1- integer)))))
589           => factorial
590           
591           (byte-compile 'factorial)
592           => #<compiled-function
593           (integer)
594           "...(21)"
595           [integer 1 factorial]
596           3
597           "Compute factorial of INTEGER.">
598
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
604      instructions.
605
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
610      of that function.
611
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.
614
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.
619
620      If `load' is non-`nil', the file is loaded after having been
621      compiled.
622
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.
629
630      This command returns `t'.  When called interactively, it prompts
631      for the file name.
632
633           % ls -l push*
634           -rw-r--r--  1 lewis     791 Oct  5 20:31 push.el
635           
636           (byte-compile-file "~/emacs/push.el")
637                => t
638           
639           % ls -l push*
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
642
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.
647
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.
651
652      The return value of this command is unpredictable.
653
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
660      code.)
661
662           % emacs -batch -f batch-byte-compile *.el
663
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
667      command line.
668
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'.
674
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.
679
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.
686
687 \1f
688 File: lispref.info,  Node: Docs and Compilation,  Next: Dynamic Loading,  Prev: Compilation Functions,  Up: Byte Compilation
689
690 Documentation Strings and Compilation
691 =====================================
692
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.
699
700    Dynamic access to documentation strings does have drawbacks:
701
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.
705
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.
709
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
714 expected to be.
715
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.
720
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:
729
730      -*-byte-compile-dynamic-docstrings: nil;-*-
731
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.
735
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.
741
742 \1f
743 File: lispref.info,  Node: Dynamic Loading,  Next: Eval During Compile,  Prev: Docs and Compilation,  Up: Byte Compilation
744
745 Dynamic Loading of Individual Functions
746 =======================================
747
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
754 place-holder.
755
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.
762
763    The dynamic loading feature has certain disadvantages:
764
765    * If you delete or move the compiled file after loading it, Emacs
766      can no longer load the remaining function definitions not already
767      loaded.
768
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.
772
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
775 problems.
776
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:
782
783      -*-byte-compile-dynamic: t;-*-
784
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.
788
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
793      name.
794
795 \1f
796 File: lispref.info,  Node: Eval During Compile,  Next: Compiled-Function Objects,  Prev: Dynamic Loading,  Up: Byte Compilation
797
798 Evaluation During Compilation
799 =============================
800
801    These features permit you to write code to be evaluated during
802 compilation of a program.
803
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).
807
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
811      in this way.
812
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
818      evaluated normally.
819
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.
824
825 \1f
826 File: lispref.info,  Node: Compiled-Function Objects,  Next: Disassembly,  Prev: Eval During Compile,  Up: Byte Compilation
827
828 Compiled-Function Objects
829 =========================
830
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.
834
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
840 ending in `.elc').
841
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.
844
845    A compiled-function object has a number of different attributes.
846 They are:
847
848 ARGLIST
849      The list of argument symbols.
850
851 INSTRUCTIONS
852      The string containing the byte-code instructions.
853
854 CONSTANTS
855      The vector of Lisp objects referenced by the byte code.  These
856      include symbols used as function names and variable names.
857
858 STACK-SIZE
859      The maximum stack size this function needs.
860
861 DOC-STRING
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::.).
866
867 INTERACTIVE
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.
870
871 DOMAIN
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
876      Specification::.
877
878    Here's an example of a compiled-function object, in printed
879 representation.  It is the definition of the command `backward-sexp'.
880
881      (symbol-function 'backward-sexp)
882      => #<compiled-function
883      (&optional arg)
884      "...(15)" [arg 1 forward-sexp] 2 854740 "_p">
885
886    The primitive way to create a compiled-function object is with
887 `make-byte-code':
888
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.
893
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
901      these semantics.
902
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
907 (we hope).
908
909    The following primitives are provided for accessing the elements of
910 a compiled-function object.
911
912  - Function: compiled-function-arglist FUNCTION
913      This function returns the argument list of compiled-function object
914      FUNCTION.
915
916  - Function: compiled-function-instructions FUNCTION
917      This function returns a string describing the byte-code
918      instructions of compiled-function object FUNCTION.
919
920  - Function: compiled-function-constants FUNCTION
921      This function returns the vector of Lisp objects referenced by
922      compiled-function object FUNCTION.
923
924  - Function: compiled-function-stack-size FUNCTION
925      This function returns the maximum stack size needed by
926      compiled-function object FUNCTION.
927
928  - Function: compiled-function-doc-string FUNCTION
929      This function returns the doc string of compiled-function object
930      FUNCTION, if available.
931
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).
938
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::.
943
944 \1f
945 File: lispref.info,  Node: Disassembly,  Prev: Compiled-Function Objects,  Up: Byte Compilation
946
947 Disassembled Byte-Code
948 ======================
949
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.
953
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.
959
960    In addition to the stack, byte-code functions can use, bind, and set
961 ordinary Lisp variables, by transferring values between variables and
962 the stack.
963
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.
969
970      As a special exception, if this function is used interactively, it
971      outputs to a buffer named `*Disassemble*'.
972
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'.
976
977      (defun factorial (integer)
978        "Compute factorial of an integer."
979        (if (= 1 integer) 1
980          (* integer (factorial (1- integer)))))
981           => factorial
982      
983      (factorial 4)
984           => 24
985      
986      (disassemble 'factorial)
987           -| byte-code for factorial:
988       doc: Compute factorial of an integer.
989       args: (integer)
990      
991      0   varref   integer        ; Get value of `integer'
992                                  ;   from the environment
993                                  ;   and push the value
994                                  ;   onto the stack.
995      
996      1   constant 1              ; Push 1 onto stack.
997      
998      2   eqlsign                 ; Pop top two values off stack,
999                                  ;   compare them,
1000                                  ;   and push result onto stack.
1001      
1002      3   goto-if-nil 1           ; Pop and test top of stack;
1003                                  ;   if `nil',
1004                                  ;   go to label 1 (which is also byte 7),
1005                                  ;   else continue.
1006      
1007      5   constant 1              ; Push 1 onto top of stack.
1008      
1009      6   return                  ; Return the top element
1010                                  ;   of the stack.
1011      
1012      7:1 varref   integer        ; Push value of `integer' onto stack.
1013      
1014      8   constant factorial      ; Push `factorial' onto stack.
1015      
1016      9   varref   integer        ; Push value of `integer' onto stack.
1017      
1018      10  sub1                    ; Pop `integer', decrement value,
1019                                  ;   push new value onto stack.
1020      
1021                                  ; Stack now contains:
1022                                  ;   - decremented value of `integer'
1023                                  ;   - `factorial'
1024                                  ;   - value of `integer'
1025      
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.
1030      
1031                                  ; Stack now contains:
1032                                  ;   - result of recursive
1033                                  ;        call to `factorial'
1034                                  ;   - value of `integer'
1035      
1036      12  mult                    ; Pop top two values off the stack,
1037                                  ;   multiply them,
1038                                  ;   pushing the result onto the stack.
1039      
1040      13  return                  ; Return the top element
1041                                  ;   of the stack.
1042           => nil
1043
1044    The `silly-loop' function is somewhat more complex:
1045
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))
1050                    0))
1051          (list t1 (current-time-string))))
1052           => silly-loop
1053      
1054      (disassemble 'silly-loop)
1055           -| byte-code for silly-loop:
1056       doc: Return time before and after N iterations of a loop.
1057       args: (n)
1058      
1059      0   constant current-time-string  ; Push
1060                                        ;   `current-time-string'
1061                                        ;   onto top of stack.
1062      
1063      1   call     0              ; Call `current-time-string'
1064                                  ;    with no argument,
1065                                  ;    pushing result onto stack.
1066      
1067      2   varbind  t1             ; Pop stack and bind `t1'
1068                                  ;   to popped value.
1069      
1070      3:1 varref   n              ; Get value of `n' from
1071                                  ;   the environment and push
1072                                  ;   the value onto the stack.
1073      
1074      4   sub1                    ; Subtract 1 from top of stack.
1075      
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.
1080      
1081      6   varset   n              ; Pop the top of the stack,
1082                                  ;   and set `n' to the value.
1083      
1084                                  ; In effect, the sequence `dup varset'
1085                                  ;   copies the top of the stack
1086                                  ;   into the value of `n'
1087                                  ;   without popping it.
1088      
1089      7   constant 0              ; Push 0 onto stack.
1090      
1091      8   gtr                     ; Pop top two values off stack,
1092                                  ;   test if N is greater than 0
1093                                  ;   and push result onto stack.
1094      
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
1098                                  ;   and continue
1099      
1100      11  varref   t1             ; Push value of `t1' onto stack.
1101      
1102      12  constant current-time-string  ; Push
1103                                        ;   `current-time-string'
1104                                        ;   onto top of stack.
1105      
1106      13  call     0              ; Call `current-time-string' again.
1107      
1108      14  unbind   1              ; Unbind `t1' in local environment.
1109      
1110      15  list2                   ; Pop top two elements off stack,
1111                                  ;   create a list of them,
1112                                  ;   and push list onto stack.
1113      
1114      16  return                  ; Return the top element of the stack.
1115      
1116           => nil
1117
1118 \1f
1119 File: lispref.info,  Node: Debugging,  Next: Read and Print,  Prev: Byte Compilation,  Up: Top
1120
1121 Debugging Lisp Programs
1122 ***********************
1123
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
1126 problem appears.
1127
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.
1131
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
1134      localize it.
1135
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
1138      input buffer.
1139
1140 * Menu:
1141
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.
1146
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::.
1151
1152    For debugging problems in terminal descriptions, the
1153 `open-termscript' function can be useful.  *Note Terminal Output::.
1154
1155 \1f
1156 File: lispref.info,  Node: Debugger,  Next: Syntax Errors,  Up: Debugging
1157
1158 The Lisp Debugger
1159 =================
1160
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::.
1168
1169 * Menu:
1170
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.
1179