is called @dfn{defining a function}, and it is done with the
@code{defun} special form.
-@defmac defun name argument-list body-forms...
+@defmac defun name args [doc] [declare] [interactive] body@dots{}
@code{defun} is the usual way to define new Lisp functions. It
-defines the symbol @var{name} as a function that looks like this:
+defines the symbol @var{name} as a function with argument list
+@var{args} and body forms given by @var{body}. Neither @var{name} nor
+@var{args} should be quoted.
-@example
-(lambda @var{argument-list} . @var{body-forms})
-@end example
+@var{doc}, if present, should be a string specifying the function's
+documentation string (@pxref{Function Documentation}). @var{declare},
+if present, should be a @code{declare} form specifying function
+metadata (@pxref{Declare Form}). @var{interactive}, if present,
+should be an @code{interactive} form specifying how the function is to
+be called interactively (@pxref{Interactive Call}).
-@code{defun} stores this lambda expression in the function cell of
-@var{name}. Its return value is @emph{undefined}.
-
-As described previously, @var{argument-list} is a list of argument
-names and may include the keywords @code{&optional} and @code{&rest}.
-Also, the first two of the @var{body-forms} may be a documentation
-string and an interactive declaration. @xref{Lambda Components}.
+The return value of @code{defun} is undefined.
Here are some examples:
@end defmac
@cindex function aliases
-@defun defalias name definition &optional docstring
+@defun defalias name definition &optional doc
@anchor{Definition of defalias}
This special form defines the symbol @var{name} as a function, with
definition @var{definition} (which can be any valid Lisp function).
Its return value is @emph{undefined}.
-If @var{docstring} is non-@code{nil}, it becomes the function
-documentation of @var{name}. Otherwise, any documentation provided by
+If @var{doc} is non-@code{nil}, it becomes the function documentation
+of @var{name}. Otherwise, any documentation provided by
@var{definition} is used.
The proper place to use @code{defalias} is where a specific function
But typically you should use the @code{lambda} macro, or the
@code{function} special form, or the @code{#'} read syntax:
-@defmac lambda args body...
-This macro returns an anonymous function with argument list @var{args}
-and body forms given by @var{body}. In effect, this macro makes
-@code{lambda} forms ``self-quoting'': evaluating a form whose @sc{car}
-is @code{lambda} yields the form itself:
+@defmac lambda args [doc] [interactive] body@dots{}
+This macro returns an anonymous function with argument list
+@var{args}, documentation string @var{doc} (if any), interactive spec
+@var{interactive} (if any), and body forms given by @var{body}.
+
+In effect, this macro makes @code{lambda} forms ``self-quoting'':
+evaluating a form whose @sc{car} is @code{lambda} yields the form
+itself:
@example
(lambda (x) (* x x))
was first made obsolete---for example, a date or a release number.
@end defun
-@defmac define-obsolete-function-alias obsolete-name current-name &optional when docstring
+@defmac define-obsolete-function-alias obsolete-name current-name &optional when doc
This convenience macro marks the function @var{obsolete-name} obsolete
and also defines it as an alias for the function @var{current-name}.
It is equivalent to the following:
@example
-(defalias @var{obsolete-name} @var{current-name} @var{docstring})
+(defalias @var{obsolete-name} @var{current-name} @var{doc})
(make-obsolete @var{obsolete-name} @var{current-name} @var{when})
@end example
@end defmac
@section Inline Functions
@cindex inline functions
-@defmac defsubst name argument-list body-forms...
-Define an inline function. The syntax is exactly the same as
-@code{defun} (@pxref{Defining Functions}).
-@end defmac
-
- You can define an @dfn{inline function} by using @code{defsubst}
-instead of @code{defun}. An inline function works just like an
-ordinary function except for one thing: when you byte-compile a call
+ An @dfn{inline function} is a function that works just like an
+ordinary function, except for one thing: when you byte-compile a call
to the function (@pxref{Byte Compilation}), the function's definition
-is expanded into the caller.
+is expanded into the caller. To define an inline function, use
+@code{defsubst} instead of @code{defun}.
+
+@defmac defsubst name args [doc] [declare] [interactive] body@dots{}
+This macro defines an inline function. Its syntax is exactly the same
+as @code{defun} (@pxref{Defining Functions}).
+@end defmac
Making a function inline often makes its function calls run faster.
But it also has disadvantages. For one thing, it reduces flexibility;
@anchor{Definition of declare}
@defmac declare @var{specs}@dots{}
This macro ignores its arguments and evaluates to @code{nil}; it has
-no run-time effect. However, when a @code{declare} form occurs as the
-@emph{very first form} in the body of a @code{defun} function
-definition or a @code{defmacro} macro definition (@pxref{Defining
-Macros}, for a description of @code{defmacro}), it appends the
-properties specified by @var{specs} to the function or macro. This
-work is specially performed by the @code{defun} and @code{defmacro}
-macros.
-
-Note that if you put a @code{declare} form in an interactive function,
-it should go before the @code{interactive} form.
+no run-time effect. However, when a @code{declare} form occurs in the
+@var{declare} argument of a @code{defun} or @code{defsubst} function
+definition (@pxref{Defining Functions}) or a @code{defmacro} macro
+definition (@pxref{Defining Macros}), it appends the properties
+specified by @var{specs} to the function or macro. This work is
+specially performed by @code{defun}, @code{defsubst}, and
+@code{defmacro}.
Each element in @var{specs} should have the form @code{(@var{property}
@var{args}@dots{})}, which should not be quoted. These have the
HCoop / bpt / emacs.git / blobdiff