* Re: improvement in functions.texi
[not found] ` <E1intAB-0006wF-79@fencepost.gnu.org>
@ 2020-01-05 22:21 ` Richard Stallman
2020-01-11 9:49 ` Eli Zaretskii
[not found] ` <lx7e261g4n.fsf@cochabamba.vanoostrum.org>
1 sibling, 1 reply; 5+ messages in thread
From: Richard Stallman @ 2020-01-05 22:21 UTC (permalink / raw)
To: emacs-devel; +Cc: michael_heerdegen, pieter-l, jidanni
[[[ To any NSA and FBI agents reading my email: please consider ]]]
[[[ whether defending the US Constitution against all enemies, ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]
I propose this improvement in functions.texi. The biggest change
is moving the description of define-inline into the node Inline Functions
where it semantically fits better. But this also adds a cross
reference in Defining Functions to information about undefining.
diff -u /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi.\~2\~ /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi
--- /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi.~2~ 2019-10-26 08:57:05.985082189 -0400
+++ /home/rms/emacs-git/build-oct-2/doc/lispref/functions.texi 2020-01-05 16:12:09.453450858 -0500
@@ -575,8 +575,9 @@
@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
@@ -681,95 +682,8 @@
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
@@ -2154,8 +2068,12 @@
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
@@ -2193,9 +2111,95 @@
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
Diff finished. Sun Jan 5 16:20:31 2020
--
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)
^ permalink raw reply [flat|nested] 5+ messages in thread