+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