-\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.
-