@c -*-texinfo-*-
@c This is part of the XEmacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file lispref.texi for copying conditions.
@setfilename ../../info/functions.info
-@node Functions, Macros, Variables, Top
-@chapter Functions
+@node Functions and Commands, Macros, Variables, Top
+@chapter Functions and Commands
A Lisp program is composed mainly of Lisp functions. This chapter
explains what functions are, how they accept arguments, and how to
* Defining Functions:: Lisp expressions for defining functions.
* Calling Functions:: How to use an existing function.
* Mapping Functions:: Applying a function to each element of a list, etc.
-* Anonymous Functions:: Lambda expressions are functions with no names.
+* Anonymous Functions:: Lambda expressions are functions with no names.
* Function Cells:: Accessing or setting the function definition
of a symbol.
* Inline Functions:: Defining functions that the compiler will open code.
specifically to mean a function written in Lisp. Special forms and
macros are not functions.
+@item command
+@cindex command
+
+A @dfn{command} is a possible definition for a key sequence---we count
+mouse events and menu accesses as key sequences for this purpose. More
+formally, within XEmacs lisp, a command is something that
+@code{command-execute} can invoke.
+
+Some functions are commands; a function written in Lisp is a command if
+it contains an interactive declaration. A trivial interactive
+declaration is a line @code{(interactive)} immediately after the
+documentation string. For more complex examples, with prompting and
+completion, see @xref{Defining Commands}. Such a function can be called
+from Lisp expressions like other functions; in this case, the fact that
+the function is a command makes no difference.
+
+Keyboard macros (strings and vectors) are commands also, even though
+they are not functions. A symbol is a command if its function
+definition is a command; such symbols can be invoked with @kbd{M-x}.
+The symbol is a function as well if the definition is a function.
+
+In the case where you want to call a command in reaction to a
+user-generated event, you'll need to bind it to that event. For how to
+do this, see @xref{Key Binding Commands}.
+@xref{Command Overview}.
+
+@item keystroke command
+@cindex keystroke command
+A @dfn{keystroke command} is a command that is bound to a key sequence
+(typically one to three keystrokes). The distinction is made here
+merely to avoid confusion with the meaning of ``command'' in non-Emacs
+editors; for Lisp programs, the distinction is normally unimportant.
+
@item primitive
@cindex primitive
@cindex subr
things that special forms can do. @xref{Macros}, for how to define and
use macros.
-@item command
-@cindex command
-A @dfn{command} is an object that @code{command-execute} can invoke; it
-is a possible definition for a key sequence. Some functions are
-commands; a function written in Lisp is a command if it contains an
-interactive declaration (@pxref{Defining Commands}). Such a function
-can be called from Lisp expressions like other functions; in this case,
-the fact that the function is a command makes no difference.
-
-Keyboard macros (strings and vectors) are commands also, even though
-they are not functions. A symbol is a command if its function
-definition is a command; such symbols can be invoked with @kbd{M-x}.
-The symbol is a function as well if the definition is a function.
-@xref{Command Overview}.
-
-@item keystroke command
-@cindex keystroke command
-A @dfn{keystroke command} is a command that is bound to a key sequence
-(typically one to three keystrokes). The distinction is made here
-merely to avoid confusion with the meaning of ``command'' in non-Emacs
-editors; for Lisp programs, the distinction is normally unimportant.
-
@item compiled function
A @dfn{compiled function} is a function that has been compiled by the
byte compiler. @xref{Compiled-Function Type}.
This function returns @var{arg} and has no side effects.
@end defun
-@defun ignore &rest args
+@deffn Command ignore &rest args
This function ignores any arguments and returns @code{nil}.
-@end defun
+@end deffn
@node Mapping Functions
@section Mapping Functions
@cindex mapping functions
A @dfn{mapping function} applies a given function to each element of a
-list or other collection. XEmacs Lisp has three such functions;
+list or other collection. XEmacs Lisp has several such functions;
@code{mapcar} and @code{mapconcat}, which scan a list, are described
-here. For the third mapping function, @code{mapatoms}, see
-@ref{Creating Symbols}.
+here. @xref{Creating Symbols}, for the function @code{mapatoms} which
+maps over the symbols in an obarray.
+
+Mapping functions should never modify the sequence being mapped over.
+The results are unpredictable.
@defun mapcar function sequence
@code{mapcar} applies @var{function} to each element of @var{sequence}
in turn, and returns a list of the results.
-The argument @var{sequence} may be a list, a vector, or a string. The
-result is always a list. The length of the result is the same as the
-length of @var{sequence}.
+The argument @var{sequence} can be any kind of sequence; that is, a
+list, a vector, a bit vector, or a string. The result is always a list.
+The length of the result is the same as the length of @var{sequence}.
@smallexample
@group
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
;; @r{If no list is exhausted,}
- (if (not (memq 'nil args))
+ (if (not (memq 'nil args))
;; @r{apply function to @sc{car}s.}
- (cons (apply f (mapcar 'car args))
- (apply 'mapcar* f
+ (cons (apply f (mapcar 'car args))
+ (apply 'mapcar* f
;; @r{Recurse for rest of elements.}
(mapcar 'cdr args)))))
@end group
other suitable punctuation.
The argument @var{function} must be a function that can take one
-argument and return a string.
-
+argument and return a string. The argument @var{sequence} can be any
+kind of sequence; that is, a list, a vector, a bit vector, or a string.
+
@smallexample
@group
(mapconcat 'symbol-name
can make it void once more using @code{fmakunbound}.
@defun fboundp symbol
-This function returns @code{t} if the symbol has an object in its
+This function returns @code{t} if @var{symbol} has an object in its
function cell, @code{nil} otherwise. It does not check that the object
is a legitimate function.
@end defun
@item
Giving a symbol a function definition that is not a list and therefore
cannot be made with @code{defun}. For example, you can use @code{fset}
-to give a symbol @code{s1} a function definition which is another symbol
-@code{s2}; then @code{s1} serves as an alias for whatever definition
-@code{s2} presently has.
+to give a symbol @var{symbol1} a function definition which is another symbol
+@var{symbol2}; then @var{symbol1} serves as an alias for whatever definition
+@var{symbol2} presently has.
@item
In constructs for defining or altering functions. If @code{defun}
projects / chise / xemacs-chise.git.1 / blobdiff