Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!seismo!husc6!mit-eddie!B.CS.UIUC.EDU!liberte
From: liberte@B.CS.UIUC.EDU (Daniel LaLiberte)
Newsgroups: comp.emacs
Subject: GNU Emacs docs part 2 of 2
Message-ID: <8612200654.AA04518@b.cs.uiuc.edu>
Date: Sat, 20-Dec-86 01:54:07 EST
Article-I.D.: b.8612200654.AA04518
Posted: Sat Dec 20 01:54:07 1986
Date-Received: Sat, 20-Dec-86 06:30:09 EST
Sender: nessus@mit-eddie.MIT.EDU
Lines: 923
This is part 2 of 2 of the GNU Emacs documents prepared so far.
Dan LaLiberte
liberte@b.cs.uiuc.edu
liberte@uiuc.csnet
ihnp4!uiucdcs!liberte
----------------------------------
#! /bin/sh
# This is a shell archive, meaning:
# 1. Remove everything above the #! /bin/sh line.
# 2. Save the resulting text in a file.
# 3. Execute the file with /bin/sh.
# The following files will be created:
# functions
# numbers
# This archive created: Sat Dec 20 00:44:34 1986
export PATH; PATH=/bin:$PATH
echo shar: extracting "'functions'" '(30546 characters)'
if test -f 'functions'
then
echo shar: over-writing existing file "'functions'"
fi
sed 's/^X//' << \SHAR_EOF > 'functions'
X
XCopyright (C) 1986 Robert Krawitz
X
XPermission is granted to make and distribute verbatim copies of
Xthis manual provided the copyright notice and this permission notice
Xare preserved on all copies.
X
X
X Lisp Functions and Emacs Commands
X Robert Krawitz (rlk@ATHENA.MIT.EDU)
X
XThe Lisp language that GNU Emacs uses is, like all Lisp languages,
Xcomprised mainly of a set of functions and variables. This section is
Xconcerned with the definition and manipulation of functions in the
XLisp language and their relationship to editing commands.
X
XFunctions in GNU Emacs Lisp can be defined in one of two basic ways;
Xin the C code that the editor as a whole is written in, or in the Lisp
Xthat is an integral part of the editor. The C-coded functions, of
Xwhich there are approximately 500 defined, provide the very
Xlowest-level interfaces to editing functions or operating system
Xservices, or in a very few cases, to perform certain operations more
Xquickly than they could be performed in Lisp. These can only be
Xmodified by rewriting them and recompiling the editor. This is a
Xfairly complex process, and will be described at the end of this
Xsection.
X
XThe other method, which is the standard method for writing extensions
Xto the editor, is to write new functions in Lisp. If you have ever
Xprogrammed other versions of Emacs you will find writing code
Xfor GNU Emacs very pleasant; the Lisp provided is a true version of
XLisp, and functions that are used as commands do not require any
Xterribly arcane calling sequence.
X
XIt will be helpful to define a few terms first, as the meanings of a
Xfew terms used here differ from the common definitions.
X
XPRIMITIVE -- A primitive is a function callable from Lisp that is
X written in C, such as car and cdr. These are sometimes called
X built-in functions.
X
XFUNCTION -- A function in general is anything that can be called in
X Lisp code. In this text, function will normally be used to
X mean code written in Lisp. The exceptions should be easy to
X spot.
X
XCOMMAND -- A command is something that is advertised to the user and
X can be invoked by the user either by M-x command-name or by
X means of a keystroke. From the programmer's point of view, it
X is a function with an interactive specification (see
X interactive, below).
X
XKEYSTROKE COMMAND -- A keystroke command is a command that can be
X executed with a short sequence of keystrokes, as opposed to a
X command that is not bound to a keystroke. The distinction is
X made here merely to avoid confusion with the meaning of
X command in non-Emacs editors; for programmers, the distinction
X is normally unimportant.
X
XSince many people have not programmed in Lisp before, it may be
Xhelpful to review just what a function is before discussing some of
Xthe particular facilities provided for manipulating functions. If you
Xare a Lisp programmer, you can skim this section, but there are some
Xpoints that are specific to the GNU Emacs Lisp language.
X
XA Lisp function is a list that looks like this:
X
X(lambda )
X
X(This sort of Lisp expression is known as a "Lambda-expression" for
Xmainly historical reasons.)
X
XThe first element of this list is the symbol ``lambda''; the second
Xelement of this list is a list of arguments; the third element is an
Xoptional string documenting the function, and all other elements of
Xthe list comprise Lisp code to execute, or, as a Lisp programmer would
Xsay, "are a list of Lisp forms to evaluate". The value returned by
Xthe function is the value returned by the last element of the body.
X
XThe list of arguments, called the lambda-list, is a list of variable
Xnames. When a lisp function is called, the arguments provided are
Xmatched up against the names in the lambda-list, and those variables
Xare bound to the values provided.
X
XThus, if the function foo looked like this:
X
X(lambda (a b c) "Test" (+ a b c))
X
Xand was called as follows:
X
X(foo 1 2 3)
X
Xfoo would be evaluated with the variable a bound to 1, b bound to 2,
Xand c bound to 3. Note that the arguments could have been the results
Xof other functions; i. e.
X
X(foo 1 (* 2 3) (- 5 4))
X
Xall the arguments to foo (1, (* 2 3), and (- 5 4)) would be evaluated,
Xleft to right. Then foo would be applied to these arguments.
X
XThe function that calls our example here must provide all three
Xarguments. If you attempted to call foo with only two arguments, you
Xwould get a Lisp error. However, it is often convenient not to have
Xto specify certain arguments, allowing them to default in some way,
Xsuch as the function rmail, which will default to a predetermined
Xfilename if not passed a specific filename; or to be able to provide
Xan indefinite number of arguments; functions such as and, or, and +
Xfall into this category. If optional or rest arguments are not
Xprovided, they are bound to nil.
X
XGNU Emacs Lisp has a way to allow you to specify optional and extra
X(commonly known as "rest") arguments. Simply include the keyword
X&optional before the optional arguments and the keyword &rest before
Xone final argument that will be a list of all extra arguments.
X
XThus, a lambda list that looks like this:
X
X(a b &optional c d &rest e)
X
Xbinds a and b to the first two arguments, which are required. If one
Xor two more arguments are included, c and d are bound to them
Xrespectively; any arguments after that are collected into a list and e
Xis bound to that list. After the arguments provided by the caller are
Xused up, any remianing optional or rest variables are bound to nil.
X
X[The concept of binding should be explained clearly in the section on
Xdynamic scoping. That should come BEFORE this section!]
X
XAll arguments after the &optional are optional arguments, and only one
Xargument is meaningful after &rest. To see why this must be so,
Xsuppose that c in the example is optional and d is required. Suppose
Xthree arguments are given; then what should be bound to the third
Xargument? If c is bound to it, then d is left unbound, which is an
Xerror. If d is bound to it, then any fourth argument would be bound
Xto c, changing the order of the list. It should be clear that a
Xrequired argument following an optional argument in this scheme is
Xmeaningless. Similarly, multiple &rest arguments have no meaning
Xsince all extra arguments are collected into a list; if you do not
Xwant this behavior you should use &optional arguments. [This is very
Xmessy; anyone want to clean it up?]
X
XOne minor problem with this is that if the last argument provided is
Xnil, and it is an optional argument, then the function cannot tell if
Xthe argument was provided or not.
X
XThe documentation string is completely optional as far as the language
Xis concerned; if provided, it is a literal string that is used by a
Xfew functions for the user's benefit. It is a good idea to provide
Xdocumentation strings for all commands and functions, and it should
Xexplain what the function does and all its arguments in order.
X
XYou may wonder how the documentation string could be optional, since
Xthere are required components of the function that follow it (the
Xbody). Since evaluation of a string returns that string, without any
Xside effects, it has no effect if it is not the last form in the body.
XThus, in practice, there is no confusion between the first form of the
Xbody and the documentation string; if the only body form is a string
Xthen it serves as both the return value and the documentation.
X
XThe rest of the function definition is simply a list of lisp forms to
Xbe evaluated in order, and the value of the last form is returned.
X
XFunctions and special forms provided to create and manipulate
Xfunctions:
X
X----------------------------------------------------------------
X
Xdefun <{DOCUMENTATION}> &rest
X
Xdefun is the basic special form for defining new lisp functions. A
Xspecial form is a function whose arguments are not evaluated. As
Xmentioned above, the arguments to functions are normally evaluated
Xbefore the function is called. With a special form, this is not true.
XThis is necessary in this case because defun must be able to see
Xexactly what its arguments look like. All special forms will be noted
Xas such in the description of the appropriate function, otherwise you
Xmay assume that the function is an ordinary function. This can be
Xmildly confusing.
X
XFUNCTION-NAME should be the name of the symbol that will be the name
Xof the new function. This can be the name of a pre-existing variable,
Xsince variable values are stored in a different place (the "value
Xcell" of the symbol) than the function definition (the "function
Xcell").
X
XWhat defun does is set the contents of the function cell of the symbol
XFUNCTION-NAME to the lambda-expression specified by the rest of the
Xarguments. Thus, if we evaluate this expression:
X
X(defun test-function (a b)
X "This is a sample Lisp function definition"
X (setq c (+ a b))
X (* c 2))
X
Xthe function cell of the symbol test-function will be given the
Xfollowing value:
X
X(lambda (a b) "This is a sample Lisp function definition"
X (setq c (+ a b)) (* c 2))
X
XIf a function is already defined, and you wish to redefine it, you
Xmerely need evaluate a new defun with the new function definition.
X
X----------------------------------------------------------------
X
Xfset
X
Xfset is a primitive for creating or modifying functions. The
Xdifference between fset and defun, aside from the fact that fset takes
Xdifferent arguments, is that fset is a function, and thus its
Xarguments are evaluated. This can be useful, for example, if you wish
Xto define a function whose name you don't know when you are writing
Xcode, but that you intend to find out at runtime, or if you have code
Xthat will generate a legal function definition. Thus, any constant
Xarguments (i. e. if you know the function name or function definition
Xin advance) will have to be quoted. See below.
X
Xfset is for use in tools that operate on Lisp functions themselves,
Xnot for defining particular functions with particular definitions.
XFor example, named keyboard macros are created by means of fset; the
Xname of the function and its definition are supplied by the user and
Xnot fixed in the code for the keyboard macro facility.
X
X----------------------------------------------------------------
X
Xfunction
X
Xfunction is a special form very similar to the quote form that is used
Xin the Lisp interpreter. The quote special form is normally implied
Xby the "'" syntax; thus, the syntax 'list is completely equivalent to
Xthe form (quote list). The difference between the two forms is that
Xwith quote you might be planning to use the actual Lisp value of the
Xconstant (quoted Lisp forms). You should use function only if you do
Xnot intend to use the value for anything except to apply it to
Xarguments, since the byte compiler will compile forms inside function,
Xbut not touch forms inside quote.
X
XI. e., you might use
X
X(setq text-mode-hook (function (lambda () (auto-fill-mode 1))))
X
X----------------------------------------------------------------
X
Xapply
X
Xapply calls FUNCTION with the elements of ARGS. This is very handy
Xwhen you don't know how many arguments you wish to call a function
Xwith, or don't know what function you want to call, or just want to
Xapply an arbitrary lambda-expression which may not have any symbol
Xbound to it to a list of arguments. Thus, you might want to use apply
Xto do the following:
X
X(defvar magic-op 0 "Magic operation to be applied to a list of numbers")
X
X(apply (nth magic-op '(+ - * /)) list-of-numbers)
X
XOr, if you already know the operation, and just wanted to apply it to
Xa list of arguments:
X
X(apply '+ list-of-numbers)
X
X----------------------------------------------------------------
X
Xfuncall &rest
X
Xfuncall is similar to apply, except that the arguments are specified
Xindividually rather than collected into a list. For example, you
Xmight know what arguments you want to call a function with, but you
Xmight not know what function you need. Example:
X
X(defconst divide-by-zero-hook '(lambda (x) 8388607))
X
X(defun /-safe (num denom)
X "Divide NUM by DENOM, checking that DENOM is not zero. If DENOM is
Xzero, then the value of divide-by-zero-hook is called with NUM as the only
Xargument."
X (if (zerop denom)
X (if (and (boundp divide-by-zero-hook)
X divide-by-zero-hook)
X (funcall divide-by-zero-hook num)
X (error "Dividing by zero"))
X (/ x y)))
X
XThis is the technique used to call the various hooks (i. e.
Xdivide-by-zero-hook). After checking that the hook does indeed exist,
Xthe hook is called with no arguments using funcall. You can't just
Xevaluate the form (divide-by-zero-hook num) because the actual
Xfunction is the value of divide-by-zero-hook, not the function
Xdefinition of that symbol.
X
X(funcall function a b c)
X
Xis completely equivalent to
X
X(apply function (list a b c)).
X
X----------------------------------------------------------------
X
Xfboundp
X
Xfboundp checks whether the function cell of FUNCTION is bound to
Xanything, returning t if it is, or nil if it isn't. This can be
Xuseful before attempting to funcall something that may or may not
Xexist, since attempting to call a void function results in a Lisp
Xerror.
X
X----------------------------------------------------------------
X
Xfmakunbound
X
Xfmakunbound removes any function definition of the symbol
XFUNCTION-NAME. This function is rarely used, since there is seldom a
Xreason for simply removing the function cell of a symbol (making a
Xfunction undefined).
X
X----------------------------------------------------------------
X
Xeval