@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2012
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2013 Free Software
+@c Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Loading
@chapter Loading
character set translation just as Emacs would do when visiting the file.
@xref{Coding Systems}.
+@c This is referred to from the Macros chapter.
+@c Not sure if it should be the other way round.
+@cindex eager macro expansion
+When loading an uncompiled file, Emacs tries to expand any macros
+that the file contains (@pxref{Macros}). We refer to this as
+@dfn{eager macro expansion}. Doing this (rather than deferring
+the expansion until the relevant code runs) can significantly speed
+up the execution of uncompiled code. Sometimes, this macro expansion
+cannot be done, owing to a cyclic dependency. In the simplest
+example of this, the file you are loading refers to a macro defined
+in another file, and that file in turn requires the file you are
+loading. This is generally harmless. Emacs prints a warning
+(@samp{Eager macro-expansion skipped due to cycle@dots{}})
+giving details of the problem, but it still loads the file, just
+leaving the macro unexpanded for now. You may wish to restructure
+your code so that this does not happen. Loading a compiled file does
+not cause macroexpansion, because this should already have happened
+during compilation. @xref{Compiling Macros}.
+
Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.
symbol @var{function}.
@cindex function cell in autoload
-if @var{function} already has non-void function definition that is not
+If @var{function} already has a non-void function definition that is not
an autoload object, this function does nothing and returns @code{nil}.
Otherwise, it constructs an autoload object (@pxref{Autoload Type}),
and stores it as the function definition for @var{function}. The
@noindent
In this case, @code{"prolog"} is the name of the file to load, 169681
refers to the documentation string in the
-@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
+@file{emacs/etc/DOC} file (@pxref{Documentation Basics}),
@code{t} means the function is interactive, and @code{nil} that it is
not a macro or a keymap.
@end defun
The same magic comment can copy any kind of form into
@file{loaddefs.el}. The form following the magic comment is copied
verbatim, @emph{except} if it is one of the forms which the autoload
-facility handles specially (e.g.@: by conversion into an
+facility handles specially (e.g., by conversion into an
@code{autoload} call). The forms which are not copied verbatim are
the following:
@table @asis
@item Definitions for function or function-like objects:
-@code{defun} and @code{defmacro}; also @code{defun*} and
-@code{defmacro*} (@pxref{Argument Lists,,,cl,CL Manual}), and
-@code{define-overloadable-function} (see the commentary in
+@code{defun} and @code{defmacro}; also @code{cl-defun} and
+@code{cl-defmacro} (@pxref{Argument Lists,,,cl,Common Lisp Extensions}),
+and @code{define-overloadable-function} (see the commentary in
@file{mode-local.el}).
@item Definitions for major or minor modes:
@defun autoload-do-load autoload &optional name macro-only
This function performs the loading specified by @var{autoload}, which
-whould be an autoload object. The optional argument @var{name}, if
+should be an autoload object. The optional argument @var{name}, if
non-@code{nil}, should be a symbol whose function value is
@var{autoload}; in that case, the return value of this function is the
symbol's new function value. If the value of the optional argument
(defun idlwave-complete-filename ()
"Use the comint stuff to complete a file name."
(require 'comint)
- (let* ((comint-file-name-chars "~/A-Za-z0-9+@:_.$#%=@{@}\\-")
+ (let* ((comint-file-name-chars "~/A-Za-z0-9+@@:_.$#%=@{@}\\-")
(comint-completion-addsuffix nil)
...)
(comint-dynamic-complete-filename)))
@defun featurep feature &optional subfeature
This function returns @code{t} if @var{feature} has been provided in
-the current Emacs session (i.e.@:, if @var{feature} is a member of
+the current Emacs session (i.e., if @var{feature} is a member of
@code{features}.) If @var{subfeature} is non-@code{nil}, then the
function returns @code{t} only if that subfeature is provided as well
-(i.e.@: if @var{subfeature} is a member of the @code{subfeature}
+(i.e., if @var{subfeature} is a member of the @code{subfeature}
property of the @var{feature} symbol.)
@end defun
@end defvar
If you want code to be executed when a @emph{particular} library is
-loaded, use the function @code{eval-after-load}:
+loaded, use the macro @code{with-eval-after-load}:
-@defun eval-after-load library form
-This function arranges to evaluate @var{form} at the end of loading
+@defmac with-eval-after-load library body@dots{}
+This macro arranges to evaluate @var{body} at the end of loading
the file @var{library}, each time @var{library} is loaded. If
-@var{library} is already loaded, it evaluates @var{form} right away.
-Don't forget to quote @var{form}!
+@var{library} is already loaded, it evaluates @var{body} right away.
You don't need to give a directory or extension in the file name
@var{library}. Normally, you just give a bare file name, like this:
@example
-(eval-after-load "edebug" '(def-edebug-spec c-point t))
+(with-eval-after-load "edebug" (def-edebug-spec c-point t))
@end example
To restrict which files can trigger the evaluation, include a
@file{my_inst.el}:
@example
-(eval-after-load "foo/bar/my_inst.elc" @dots{})
+(with-eval-after-load "foo/bar/my_inst.elc" @dots{})
@end example
-@var{library} can also be a feature (i.e.@: a symbol), in which case
-@var{form} is evaluated at the end of any file where
+@var{library} can also be a feature (i.e., a symbol), in which case
+@var{body} is evaluated at the end of any file where
@code{(provide @var{library})} is called.
-An error in @var{form} does not undo the load, but does prevent
-execution of the rest of @var{form}.
-@end defun
+An error in @var{body} does not undo the load, but does prevent
+execution of the rest of @var{body}.
+@end defmac
Normally, well-designed Lisp programs should not use
@code{eval-after-load}. If you need to examine and set the variables
it immediately---there is no need to wait until the library is loaded.
If you need to call functions defined by that library, you should load
the library, preferably with @code{require} (@pxref{Named Features}).
-
-@defvar after-load-alist
-This variable stores an alist built by @code{eval-after-load},
-containing the expressions to evaluate when certain libraries are
-loaded. Each element looks like this:
-
-@example
-(@var{regexp-or-feature} @var{forms}@dots{})
-@end example
-
-The key @var{regexp-or-feature} is either a regular expression or a
-symbol, and the value is a list of forms. The forms are evaluated
-when the key matches the absolute true name or feature name of the
-library being loaded.
-@end defvar