X-Git-Url: http://git.chise.org/gitweb/?a=blobdiff_plain;f=man%2Flispref%2Ffunctions.texi;h=59cf6534e5847219554c3d2f0b50bc5dd769ec08;hb=dd92ac670f8f1af7134c4c74351fb1e696af8a40;hp=63b964abf3fba0534a53eaf8563d6bb509fb5085;hpb=afa9772e3fcbb4e80e3e4cfd1a40b4fccc6d08b8;p=chise%2Fxemacs-chise.git diff --git a/man/lispref/functions.texi b/man/lispref/functions.texi index 63b964a..59cf653 100644 --- a/man/lispref/functions.texi +++ b/man/lispref/functions.texi @@ -1,10 +1,10 @@ @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 @@ -17,7 +17,7 @@ define them. * 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. @@ -45,6 +45,39 @@ arguments in a Lisp program. In some cases, we use it more 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 @@ -84,28 +117,6 @@ original expression. Macros enable Lisp programmers to do the sorts of 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}. @@ -671,27 +682,30 @@ function: 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 @@ -715,10 +729,10 @@ length of @var{sequence}. "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 @@ -738,8 +752,9 @@ Between each pair of result strings, @code{mapconcat} inserts the string 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 @@ -927,7 +942,7 @@ and can be stored into a function cell just as any other object can be 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 @@ -972,9 +987,9 @@ making an alternate name for a function.) @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}