From: Richard Stallman Date: Sun, 5 Jan 2020 22:21:41 +0000 (-0500) Subject: ; Move the description of define-inline to a different node in functions.texi X-Git-Tag: emacs-27.0.90~180 X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=fd8128f0c18d536cc31578b29f3fd426bbc61630;p=emacs.git ; Move the description of define-inline to a different node in functions.texi --- diff --git a/doc/lispref/functions.texi b/doc/lispref/functions.texi index 8e3e6aefb00..5cf67ba6473 100644 --- a/doc/lispref/functions.texi +++ b/doc/lispref/functions.texi @@ -576,8 +576,9 @@ naming conventions, which are being phased out. @cindex defining a function We usually give a name to a function when it is first created. This -is called @dfn{defining a function}, and it is done with the -@code{defun} macro. +is called @dfn{defining a function}, and we usually do it with the +@code{defun} macro. This section also describes other ways to define +a function. @defmac defun name args [doc] [declare] [interactive] body@dots{} @code{defun} is the usual way to define new Lisp functions. It @@ -682,95 +683,8 @@ definition will have no effect on them. and tells the Lisp compiler to perform inline expansion on it. @xref{Inline Functions}. - Alternatively, you can define a function by providing the code which -will inline it as a compiler macro. The following macros make this -possible. - -@c FIXME: Can define-inline use the interactive spec? -@defmac define-inline name args [doc] [declare] body@dots{} -Define a function @var{name} by providing code that does its inlining, -as a compiler macro. The function will accept the argument list -@var{args} and will have the specified @var{body}. - -If present, @var{doc} should be the function's documentation string -(@pxref{Function Documentation}); @var{declare}, if present, should be -a @code{declare} form (@pxref{Declare Form}) specifying the function's -metadata. -@end defmac - -Functions defined via @code{define-inline} have several advantages -with respect to macros defined by @code{defsubst} or @code{defmacro}: - -@itemize @minus -@item -They can be passed to @code{mapcar} (@pxref{Mapping Functions}). - -@item -They are more efficient. - -@item -They can be used as @dfn{place forms} to store values -(@pxref{Generalized Variables}). - -@item -They behave in a more predictable way than @code{cl-defsubst} -(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs -Lisp}). -@end itemize - -Like @code{defmacro}, a function inlined with @code{define-inline} -inherits the scoping rules, either dynamic or lexical, from the call -site. @xref{Variable Scoping}. - -The following macros should be used in the body of a function defined -by @code{define-inline}. - -@defmac inline-quote expression -Quote @var{expression} for @code{define-inline}. This is similar to -the backquote (@pxref{Backquote}), but quotes code and accepts only -@code{,}, not @code{,@@}. -@end defmac - -@defmac inline-letevals (bindings@dots{}) body@dots{} -This is similar to @code{let} (@pxref{Local Variables}): it sets up -local variables as specified by @var{bindings}, and then evaluates -@var{body} with those bindings in effect. Each element of -@var{bindings} should be either a symbol or a list of the form -@w{@code{(@var{var} @var{expr})}}; the result is to evaluate -@var{expr} and bind @var{var} to the result. The tail of -@var{bindings} can be either @code{nil} or a symbol which should hold -a list of arguments, in which case each argument is evaluated, and the -symbol is bound to the resulting list. -@end defmac - -@defmac inline-const-p expression -Return non-@code{nil} if the value of @var{expression} is already -known. -@end defmac - -@defmac inline-const-val expression -Return the value of @var{expression}. -@end defmac - -@defmac inline-error format &rest args -Signal an error, formatting @var{args} according to @var{format}. -@end defmac - -Here's an example of using @code{define-inline}: - -@lisp -(define-inline myaccessor (obj) - (inline-letevals (obj) - (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2))))) -@end lisp - -@noindent -This is equivalent to - -@lisp -(defsubst myaccessor (obj) - (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2))) -@end lisp + To undefine a function name, use @code{fmakunbound}. +@xref{Function Cells}. @node Calling Functions @section Calling Functions @@ -2155,8 +2069,12 @@ this: 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. To define an inline function, use -@code{defsubst} instead of @code{defun}. +is expanded into the caller. + + The simple way to define an inline function, is to write +@code{defsubst} instead of @code{defun}. The rest of the definition +looks just the same, but using @code{defsubst} says to make it inline +for byte compilation. @defmac defsubst name args [doc] [declare] [interactive] body@dots{} This macro defines an inline function. Its syntax is exactly the same @@ -2194,9 +2112,95 @@ 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. - As an alternative to @code{defsubst}, you can use -@code{define-inline} to define functions via their exhaustive compiler -macro. @xref{Defining Functions, define-inline}. + Alternatively, you can define a function by providing the code which +will inline it as a compiler macro. The following macros make this +possible. + +@c FIXME: Can define-inline use the interactive spec? +@defmac define-inline name args [doc] [declare] body@dots{} +Define a function @var{name} by providing code that does its inlining, +as a compiler macro. The function will accept the argument list +@var{args} and will have the specified @var{body}. + +If present, @var{doc} should be the function's documentation string +(@pxref{Function Documentation}); @var{declare}, if present, should be +a @code{declare} form (@pxref{Declare Form}) specifying the function's +metadata. +@end defmac + +Functions defined via @code{define-inline} have several advantages +with respect to macros defined by @code{defsubst} or @code{defmacro}: + +@itemize @minus +@item +They can be passed to @code{mapcar} (@pxref{Mapping Functions}). + +@item +They are more efficient. + +@item +They can be used as @dfn{place forms} to store values +(@pxref{Generalized Variables}). + +@item +They behave in a more predictable way than @code{cl-defsubst} +(@pxref{Argument Lists,,, cl, Common Lisp Extensions for GNU Emacs +Lisp}). +@end itemize + +Like @code{defmacro}, a function inlined with @code{define-inline} +inherits the scoping rules, either dynamic or lexical, from the call +site. @xref{Variable Scoping}. + +The following macros should be used in the body of a function defined +by @code{define-inline}. + +@defmac inline-quote expression +Quote @var{expression} for @code{define-inline}. This is similar to +the backquote (@pxref{Backquote}), but quotes code and accepts only +@code{,}, not @code{,@@}. +@end defmac + +@defmac inline-letevals (bindings@dots{}) body@dots{} +This is similar to @code{let} (@pxref{Local Variables}): it sets up +local variables as specified by @var{bindings}, and then evaluates +@var{body} with those bindings in effect. Each element of +@var{bindings} should be either a symbol or a list of the form +@w{@code{(@var{var} @var{expr})}}; the result is to evaluate +@var{expr} and bind @var{var} to the result. The tail of +@var{bindings} can be either @code{nil} or a symbol which should hold +a list of arguments, in which case each argument is evaluated, and the +symbol is bound to the resulting list. +@end defmac + +@defmac inline-const-p expression +Return non-@code{nil} if the value of @var{expression} is already +known. +@end defmac + +@defmac inline-const-val expression +Return the value of @var{expression}. +@end defmac + +@defmac inline-error format &rest args +Signal an error, formatting @var{args} according to @var{format}. +@end defmac + +Here's an example of using @code{define-inline}: + +@lisp +(define-inline myaccessor (obj) + (inline-letevals (obj) + (inline-quote (if (foo-p ,obj) (aref (cdr ,obj) 3) (aref ,obj 2))))) +@end lisp + +@noindent +This is equivalent to + +@lisp +(defsubst myaccessor (obj) + (if (foo-p obj) (aref (cdr obj) 3) (aref obj 2))) +@end lisp @node Declare Form @section The @code{declare} Form