-This is Info file ../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref/lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0b from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: Inline Functions, Next: Related Topics, Prev: Function Cells, Up: Functions
+
+Inline Functions
+================
+
+ You can define an "inline function" by using `defsubst' instead of
+`defun'. An inline function works just like an ordinary function
+except for one thing: when you compile a call to the function, the
+function's definition is open-coded into the caller.
+
+ Making a function inline makes explicit calls run faster. But it
+also has disadvantages. For one thing, it reduces flexibility; if you
+change the definition of the function, calls already inlined still use
+the old definition until you recompile them. Since the flexibility of
+redefining functions is an important feature of XEmacs, you should not
+make a function inline unless its speed is really crucial.
+
+ Another disadvantage is that making a large function inline can
+increase the size of compiled code both in files and in memory. Since
+the speed advantage of inline functions is greatest for small
+functions, you generally should not make large functions inline.
+
+ It's possible to define a macro to expand into the same code that an
+inline function would execute. But the macro would have a limitation:
+you can use it only explicitly--a macro cannot be called with `apply',
+`mapcar' and so on. Also, it takes some work to convert an ordinary
+function into a macro. (*Note Macros::.) To convert it into an inline
+function is very easy; simply replace `defun' with `defsubst'. Since
+each argument of an inline function is evaluated exactly once, you
+needn't worry about how many times the body uses the arguments, as you
+do for macros. (*Note Argument Evaluation::.)
+
+ Inline functions can be used and open-coded later on in the same
+file, following the definition, just like macros.
+
+\1f
+File: lispref.info, Node: Related Topics, Prev: Inline Functions, Up: Functions
+
+Other Topics Related to Functions
+=================================
+
+ Here is a table of several functions that do things related to
+function calling and function definitions. They are documented
+elsewhere, but we provide cross references here.
+
+`apply'
+ See *Note Calling Functions::.
+
+`autoload'
+ See *Note Autoload::.
+
+`call-interactively'
+ See *Note Interactive Call::.
+
+`commandp'
+ See *Note Interactive Call::.
+
+`documentation'
+ See *Note Accessing Documentation::.
+
+`eval'
+ See *Note Eval::.
+
+`funcall'
+ See *Note Calling Functions::.
+
+`ignore'
+ See *Note Calling Functions::.
+
+`indirect-function'
+ See *Note Function Indirection::.
+
+`interactive'
+ See *Note Using Interactive::.
+
+`interactive-p'
+ See *Note Interactive Call::.
+
+`mapatoms'
+ See *Note Creating Symbols::.
+
+`mapcar'
+ See *Note Mapping Functions::.
+
+`mapconcat'
+ See *Note Mapping Functions::.
+
+`undefined'
+ See *Note Key Lookup::.
+
+\1f
+File: lispref.info, Node: Macros, Next: Loading, Prev: Functions, Up: Top
+
+Macros
+******
+
+ "Macros" enable you to define new control constructs and other
+language features. A macro is defined much like a function, but instead
+of telling how to compute a value, it tells how to compute another Lisp
+expression which will in turn compute the value. We call this
+expression the "expansion" of the macro.
+
+ Macros can do this because they operate on the unevaluated
+expressions for the arguments, not on the argument values as functions
+do. They can therefore construct an expansion containing these
+argument expressions or parts of them.
+
+ If you are using a macro to do something an ordinary function could
+do, just for the sake of speed, consider using an inline function
+instead. *Note Inline Functions::.
+
+* Menu:
+
+* Simple Macro:: A basic example.
+* Expansion:: How, when and why macros are expanded.
+* Compiling Macros:: How macros are expanded by the compiler.
+* Defining Macros:: How to write a macro definition.
+* Backquote:: Easier construction of list structure.
+* Problems with Macros:: Don't evaluate the macro arguments too many times.
+ Don't hide the user's variables.
+
+\1f
+File: lispref.info, Node: Simple Macro, Next: Expansion, Up: Macros
+
+A Simple Example of a Macro
+===========================
+
+ Suppose we would like to define a Lisp construct to increment a
+variable value, much like the `++' operator in C. We would like to
+write `(inc x)' and have the effect of `(setq x (1+ x))'. Here's a
+macro definition that does the job:
+
+ (defmacro inc (var)
+ (list 'setq var (list '1+ var)))
+
+ When this is called with `(inc x)', the argument `var' has the value
+`x'--_not_ the _value_ of `x'. The body of the macro uses this to
+construct the expansion, which is `(setq x (1+ x))'. Once the macro
+definition returns this expansion, Lisp proceeds to evaluate it, thus
+incrementing `x'.
+
+\1f
+File: lispref.info, Node: Expansion, Next: Compiling Macros, Prev: Simple Macro, Up: Macros
+
+Expansion of a Macro Call
+=========================
+
+ A macro call looks just like a function call in that it is a list
+which starts with the name of the macro. The rest of the elements of
+the list are the arguments of the macro.
+
+ Evaluation of the macro call begins like evaluation of a function
+call except for one crucial difference: the macro arguments are the
+actual expressions appearing in the macro call. They are not evaluated
+before they are given to the macro definition. By contrast, the
+arguments of a function are results of evaluating the elements of the
+function call list.
+
+ Having obtained the arguments, Lisp invokes the macro definition just
+as a function is invoked. The argument variables of the macro are bound
+to the argument values from the macro call, or to a list of them in the
+case of a `&rest' argument. And the macro body executes and returns
+its value just as a function body does.
+
+ The second crucial difference between macros and functions is that
+the value returned by the macro body is not the value of the macro call.
+Instead, it is an alternate expression for computing that value, also
+known as the "expansion" of the macro. The Lisp interpreter proceeds
+to evaluate the expansion as soon as it comes back from the macro.
+
+ Since the expansion is evaluated in the normal manner, it may contain
+calls to other macros. It may even be a call to the same macro, though
+this is unusual.
+
+ You can see the expansion of a given macro call by calling
+`macroexpand'.
+
+ - Function: macroexpand form &optional environment
+ This function expands FORM, if it is a macro call. If the result
+ is another macro call, it is expanded in turn, until something
+ which is not a macro call results. That is the value returned by
+ `macroexpand'. If FORM is not a macro call to begin with, it is
+ returned as given.
+
+ Note that `macroexpand' does not look at the subexpressions of
+ FORM (although some macro definitions may do so). Even if they
+ are macro calls themselves, `macroexpand' does not expand them.
+
+ The function `macroexpand' does not expand calls to inline
+ functions. Normally there is no need for that, since a call to an
+ inline function is no harder to understand than a call to an
+ ordinary function.
+
+ If ENVIRONMENT is provided, it specifies an alist of macro
+ definitions that shadow the currently defined macros. Byte
+ compilation uses this feature.
+
+ (defmacro inc (var)
+ (list 'setq var (list '1+ var)))
+ => inc
+
+ (macroexpand '(inc r))
+ => (setq r (1+ r))
+
+ (defmacro inc2 (var1 var2)
+ (list 'progn (list 'inc var1) (list 'inc var2)))
+ => inc2
+
+ (macroexpand '(inc2 r s))
+ => (progn (inc r) (inc s)) ; `inc' not expanded here.
+
+\1f
+File: lispref.info, Node: Compiling Macros, Next: Defining Macros, Prev: Expansion, Up: Macros
+
+Macros and Byte Compilation
+===========================
+
+ You might ask why we take the trouble to compute an expansion for a
+macro and then evaluate the expansion. Why not have the macro body
+produce the desired results directly? The reason has to do with
+compilation.
+
+ When a macro call appears in a Lisp program being compiled, the Lisp
+compiler calls the macro definition just as the interpreter would, and
+receives an expansion. But instead of evaluating this expansion, it
+compiles the expansion as if it had appeared directly in the program.
+As a result, the compiled code produces the value and side effects
+intended for the macro, but executes at full compiled speed. This would
+not work if the macro body computed the value and side effects
+itself--they would be computed at compile time, which is not useful.
+
+ In order for compilation of macro calls to work, the macros must be
+defined in Lisp when the calls to them are compiled. The compiler has a
+special feature to help you do this: if a file being compiled contains a
+`defmacro' form, the macro is defined temporarily for the rest of the
+compilation of that file. To use this feature, you must define the
+macro in the same file where it is used and before its first use.
+
+ Byte-compiling a file executes any `require' calls at top-level in
+the file. This is in case the file needs the required packages for
+proper compilation. One way to ensure that necessary macro definitions
+are available during compilation is to require the files that define
+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::).
+
+\1f
+File: lispref.info, Node: Defining Macros, Next: Backquote, Prev: Compiling Macros, Up: Macros
+
+Defining Macros
+===============
+
+ A Lisp macro is a list whose CAR is `macro'. Its CDR should be a
+function; expansion of the macro works by applying the function (with
+`apply') to the list of unevaluated argument-expressions from the macro
+call.
+
+ It is possible to use an anonymous Lisp macro just like an anonymous
+function, but this is never done, because it does not make sense to pass
+an anonymous macro to functionals such as `mapcar'. In practice, all
+Lisp macros have names, and they are usually defined with the special
+form `defmacro'.
+
+ - Special Form: defmacro name argument-list body-forms...
+ `defmacro' defines the symbol NAME as a macro that looks like this:
+
+ (macro lambda ARGUMENT-LIST . BODY-FORMS)
+
+ This macro object is stored in the function cell of NAME. The
+ value returned by evaluating the `defmacro' form is NAME, but
+ usually we ignore this value.
+
+ The shape and meaning of ARGUMENT-LIST is the same as in a
+ function, and the keywords `&rest' and `&optional' may be used
+ (*note Argument List::). Macros may have a documentation string,
+ but any `interactive' declaration is ignored since macros cannot be
+ called interactively.
+
+\1f
File: lispref.info, Node: Backquote, Next: Problems with Macros, Prev: Defining Macros, Up: Macros
Backquote
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
-special form `quote' (*note Quoting::.). For example, these two forms
+special form `quote' (*note Quoting::). For example, these two forms
yield identical results:
`(a list of (+ 2 3) elements)
(cons 'while (cons (list '<= var final)
(append body (list (list 'inc var)))))))
=> for
+
(for i from 1 to 3 do
(setq square (* i i))
(princ (format "\n%d %d" i square)))
==>
-
(let ((i 1))
(while (<= i 3)
(setq square (* i i))
(princ (format "%d %d" i square))
(inc i)))
-
-
- -|1 1
+
+ -|1 1
-|2 4
-|3 9
=> nil
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
-
- `(let ((,var ,init)
+ `(let ((,var ,init)
(max ,final))
(while (<= ,var max)
,@body
binding made by `for'.
The way to correct this is to use an uninterned symbol instead of
-`max' (*note Creating Symbols::.). The uninterned symbol can be bound
+`max' (*note Creating Symbols::). The uninterned symbol can be bound
and referred to just like any other symbol, but since it is created by
`for', we know that it cannot already appear in the user's program.
Since it is not interned, there is no way the user can put it into the
Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling
-`eval' (*note Eval::.). If the argument is supposed to refer to the
+`eval' (*note Eval::). If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
variable with the same name as one of the macro arguments. Inside the
macro body, the macro argument binding is the most local binding of this
(defmacro empty-object ()
(list 'quote (cons nil nil)))
-
+
(defun initialize (condition)
(let ((object (empty-object)))
(if condition
The way to declare new customization groups is with `defgroup'.
- - Macro: defgroup GROUP MEMBERS DOC [KEYWORD VALUE]...
+ - Macro: defgroup group members doc [keyword value]...
Declare GROUP as a customization group containing MEMBERS. Do not
quote the symbol GROUP. The argument DOC specifies the
documentation string for the group.
are `custom-variable' for a variable, `custom-face' for a face,
and `custom-group' for a group.
- In addition to the common keywords (*note Common Keywords::.), you
+ In addition to the common keywords (*note Common Keywords::), you
can use this keyword in `defgroup':
`:prefix PREFIX'
Use `defcustom' to declare user-editable variables.
- - Macro: defcustom OPTION DEFAULT DOC [KEYWORD VALUE]...
+ - Macro: defcustom option default doc [keyword value]...
Declare OPTION as a customizable user option variable. Do not
quote OPTION. The argument DOC specifies the documentation string
for the variable.
(defcustom show-paren-mode nil
"Toggle Show Paren mode...."
:set (lambda (symbol value)
- (show-paren-mode (or value 0)))
+ (show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
:type 'boolean
:group 'paren-showing
symbol, one of the customization type names defined in the following
sections. After this symbol come a number of arguments, depending on
the symbol. Between the type symbol and its arguments, you can
-optionally write keyword-value pairs (*note Type Keywords::.).
+optionally write keyword-value pairs (*note Type Keywords::).
Some of the type symbols do not use any arguments; those are called
"simple types". For a simple type, if you do not use any keyword-value
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
-* Unloading:: How to "unload" a library that was loaded.
+* Unloading:: How to ``unload'' a library that was loaded.
* Hooks for Loading:: Providing code to be run when
particular libraries are loaded.
-\1f
-File: lispref.info, Node: How Programs Do Loading, Next: Autoload, Up: Loading
-
-How Programs Do Loading
-=======================
-
- XEmacs Lisp has several interfaces for loading. For example,
-`autoload' creates a placeholder object for a function in a file;
-trying to call the autoloading function loads the file to get the
-function's real definition (*note Autoload::.). `require' loads a file
-if it isn't already loaded (*note Named Features::.). Ultimately, all
-these facilities call the `load' function to do the work.
-
- - Function: load FILENAME &optional MISSING-OK NOMESSAGE NOSUFFIX
- This function finds and opens a file of Lisp code, evaluates all
- the forms in it, and closes the file.
-
- To find the file, `load' first looks for a file named
- `FILENAME.elc', that is, for a file whose name is FILENAME with
- `.elc' appended. If such a file exists, it is loaded. If there
- is no file by that name, then `load' looks for a file named
- `FILENAME.el'. If that file exists, it is loaded. Finally, if
- neither of those names is found, `load' looks for a file named
- FILENAME with nothing appended, and loads it if it exists. (The
- `load' function is not clever about looking at FILENAME. In the
- perverse case of a file named `foo.el.el', evaluation of `(load
- "foo.el")' will indeed find it.)
-
- If the optional argument NOSUFFIX is non-`nil', then the suffixes
- `.elc' and `.el' are not tried. In this case, you must specify
- the precise file name you want.
-
- If FILENAME is a relative file name, such as `foo' or
- `baz/foo.bar', `load' searches for the file using the variable
- `load-path'. It appends FILENAME to each of the directories
- listed in `load-path', and loads the first file it finds whose name
- matches. The current default directory is tried only if it is
- specified in `load-path', where `nil' stands for the default
- directory. `load' tries all three possible suffixes in the first
- directory in `load-path', then all three suffixes in the second
- directory, and so on.
-
- If you get a warning that `foo.elc' is older than `foo.el', it
- means you should consider recompiling `foo.el'. *Note Byte
- Compilation::.
-
- Messages like `Loading foo...' and `Loading foo...done' appear in
- the echo area during loading unless NOMESSAGE is non-`nil'.
-
- Any unhandled errors while loading a file terminate loading. If
- the load was done for the sake of `autoload', any function
- definitions made during the loading are undone.
-
- If `load' can't find the file to load, then normally it signals the
- error `file-error' (with `Cannot open load file FILENAME'). But
- if MISSING-OK is non-`nil', then `load' just returns `nil'.
-
- You can use the variable `load-read-function' to specify a function
- for `load' to use instead of `read' for reading expressions. See
- below.
-
- `load' returns `t' if the file loads successfully.
-
- - User Option: load-path
- The value of this variable is a list of directories to search when
- loading files with `load'. Each element is a string (which must be
- a directory name) or `nil' (which stands for the current working
- directory). The value of `load-path' is initialized from the
- environment variable `EMACSLOADPATH', if that exists; otherwise its
- default value is specified in `emacs/src/paths.h' when XEmacs is
- built.
-
- The syntax of `EMACSLOADPATH' is the same as used for `PATH'; `:'
- (or `;', according to the operating system) separates directory
- names, and `.' is used for the current default directory. Here is
- an example of how to set your `EMACSLOADPATH' variable from a
- `csh' `.login' file:
-
- setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
-
- Here is how to set it using `sh':
-
- export EMACSLOADPATH
- EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
-
- Here is an example of code you can place in a `.emacs' file to add
- several directories to the front of your default `load-path':
-
- (setq load-path
- (append (list nil "/user/bil/emacs"
- "/usr/local/lisplib"
- "~/emacs")
- load-path))
-
- In this example, the path searches the current working directory
- first, followed then by the `/user/bil/emacs' directory, the
- `/usr/local/lisplib' directory, and the `~/emacs' directory, which
- are then followed by the standard directories for Lisp code.
-
- The command line options `-l' or `-load' specify a Lisp library to
- load as part of Emacs startup. Since this file might be in the
- current directory, Emacs 18 temporarily adds the current directory
- to the front of `load-path' so the file can be found there. Newer
- Emacs versions also find such files in the current directory, but
- without altering `load-path'.
-
- Dumping Emacs uses a special value of `load-path'. If the value of
- `load-path' at the end of dumping is unchanged (that is, still the
- same special value), the dumped Emacs switches to the ordinary
- `load-path' value when it starts up, as described above. But if
- `load-path' has any other value at the end of dumping, that value
- is used for execution of the dumped Emacs also.
-
- Therefore, if you want to change `load-path' temporarily for
- loading a few libraries in `site-init.el' or `site-load.el', you
- should bind `load-path' locally with `let' around the calls to
- `load'.
-
- - Function: locate-file FILENAME PATH-LIST &optional SUFFIXES MODE
- This function searches for a file in the same way that `load' does,
- and returns the file found (if any). (In fact, `load' uses this
- function to search through `load-path'.) It searches for FILENAME
- through PATH-LIST, expanded by one of the optional SUFFIXES
- (string of suffixes separated by `:'s), checking for access MODE
- (0|1|2|4 = exists|executable|writeable|readable), default readable.
-
- `locate-file' keeps hash tables of the directories it searches
- through, in order to speed things up. It tries valiantly to not
- get confused in the face of a changing and unpredictable
- environment, but can occasionally get tripped up. In this case,
- you will have to call `locate-file-clear-hashing' to get it back
- on track. See that function for details.
-
- - Function: locate-file-clear-hashing PATH
- This function clears the hash records for the specified list of
- directories. `locate-file' uses a hashing scheme to speed lookup,
- and will correctly track the following environmental changes:
-
- * changes of any sort to the list of directories to be searched.
-
- * addition and deletion of non-shadowing files (see below) from
- the directories in the list.
-
- * byte-compilation of a .el file into a .elc file.
-
- `locate-file' will primarily get confused if you add a file that
- shadows (i.e. has the same name as) another file further down in
- the directory list. In this case, you must call
- `locate-file-clear-hashing'.
-
- - Variable: load-in-progress
- This variable is non-`nil' if Emacs is in the process of loading a
- file, and it is `nil' otherwise.
-
- - Variable: load-read-function
- This variable specifies an alternate expression-reading function
- for `load' and `eval-region' to use instead of `read'. The
- function should accept one argument, just as `read' does.
-
- Normally, the variable's value is `nil', which means those
- functions should use `read'.
-
- - User Option: load-warn-when-source-newer
- This variable specifies whether `load' should check whether the
- source is newer than the binary. If this variable is true, then
- when a `.elc' file is being loaded and the corresponding `.el' is
- newer, a warning message will be printed. The default is `nil',
- but it is bound to `t' during the initial loadup.
-
- - User Option: load-warn-when-source-only
- This variable specifies whether `load' should warn when loading a
- `.el' file instead of an `.elc'. If this variable is true, then
- when `load' is called with a filename without an extension, and
- the `.elc' version doesn't exist but the `.el' version does, then
- a message will be printed. If an explicit extension is passed to
- `load', no warning will be printed. The default is `nil', but it
- is bound to `t' during the initial loadup.
-
- - User Option: load-ignore-elc-files
- This variable specifies whether `load' should ignore `.elc' files
- when a suffix is not given. This is normally used only to
- bootstrap the `.elc' files when building XEmacs, when you use the
- command `make all-elc'. (This forces the `.el' versions to be
- loaded in the process of compiling those same files, so that
- existing out-of-date `.elc' files do not make it mess things up.)
-
- To learn how `load' is used to build XEmacs, see *Note Building
-XEmacs::.
-
projects / chise / xemacs-chise.git- / blobdiff