liberte@B.CS.UIUC.EDU (Daniel LaLiberte) (12/20/86)
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 <ARGS> <DOCUMENTATION> <BODY>)
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 <FUNCTION-NAME> <LAMBDA-LIST> <{DOCUMENTATION}> &rest <BODY-FORMS>
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 <FUNCTION-NAME> <DEFINITION>
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 <function> 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 <LISP-CODE>
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 <FUNCTION> <ARGS>
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 <FUNCTION> &rest <ARGS>
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 <FUNCTION-NAME>
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 <FUNCTION-NAME>
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 <FORM>
X
Xeval evaluates an arbitrary lisp expression and returns its value.
XThis function is rarely useful when writing lisp code; one example of
Xits use is inside the function eval-expression, which reads a Lisp
Xform in the minibuffer and evaluates it.
X
XIf you find yourself using eval frequently, you are almost certainly
Xwriting very poor code. eval is used in tools that operate on Lisp
Xcode itself, rather than in normal applications.
X
X----------------------------------------------------------------
X
Xmapcar <FUNCTION> <LIST>
X
Xmapcar returns a list of the values of FUNCTION applied to each
Xelement of LIST. I. e.
X
X(mapcar 'car '((a b) (c d) (e f)))
X
Xreturns
X
X(a c e)
X
X----------------------------------------------------------------
X
Xvariable-documentation (property)
X
X(get <SYMBOL> 'variable-documentation)
X
XThe variable-documentation property of a symbol holds documentation
Xfor the value, if any, of a symbol.
X
X----------------------------------------------------------------
X
Xdocumentation <FUNCTION>
X
XReturn the documentation string, if any, of FUNCTION.
X
X----------------------------------------------------------------
X
Xsymbol-function <SYMBOL>
X
XReturn the function definition, if any, of SYMBOL. This is how you
Xget at the function definition of a symbol to manipulate it.
X
XIf the symbol does not have a function definition, then this function
Xgets an error. Unless you know that SYMBOL has a function definition,
Xor don't mind the error, it is wise to check first with fboundp.
X
X================================================================
X
XThe remainder of the functions discussed here are specific to Emacs
XLisp.
X
X----------------------------------------------------------------
X
Xinteractive <INTERACTIVE-SPEC>
X
Xinteractive is neither a function nor a special form. It is the way
Xto tell the Lisp interpreter that a function may be called
Xinteractively (i. e. that a function may be used as a command) and in
Xaddition specifies how some or all of its arguments should be read.
X
XThis form (there is no more specific way of describing it) is the only
Xpart of GNU Emacs Lisp that does not follow standard Lisp conventions.
XIt is not difficult to use, and provides a very simple interface for
Xreading arguments.
X
XThe interactive form must be the first form of the body of a function,
Xcoming immediately after the lambda-list or documentation string.
X
XThere are several forms of call to interactive.
X
XThe simplest form of interactive is simply a "call" to interactive:
X
X(interactive)
X
XThis merely tells Emacs that the function so defined can be used as a
Xcommand; it can be called with M-x command-name or bound to a key,
Xcommand-apropos will find it, etc. It does not read any arguments; if
Xthe function requires any, it will get an error.
X
XThe second form is the use of interactive with a control string. The
Xcontrol string specifies how arguments are to be found, any prompts
Xthat may be necessary, and how many arguments are desired. The string
Xconsists of a series of elements consisting of a one-character control
Xspecification, a prompt if appropriate, and a newline if there are
Xmore specifications following the current one (i. e. the newline
Xcharacter delimits interactive specifications). The arguments are
Xassigned to the parameters in the lambda-list in left-to-right order;
Xi. e. the first specification reads an argument for the first
Xparameter, etc. If any required arguments are not specified in this
Xmanner, the function will get an error. In all cases except as noted,
Xthe specifications cause something to be read from the minibuffer, and
Xthus accept a prompt string. The specifications are:
X
Xa -- Function name: symbol with a function definition. This refuses
X to accept a name that does not have a function definition.
Xb -- Name of existing buffer.
XB -- Name of buffer, possibly nonexistent.
Xc -- Single character.
XC -- Command name: symbol with an interactive function definition.
Xd -- Value of point as number. This does not prompt for anything in
X the minibuffer, so supplying a prompt string is meaningless.
XD -- Directory name. Checks to make sure the supplied string is a
X directory.
Xf -- Existing file name.
XF -- Possibly nonexistent file name.
Xk -- Keystroke sequence (string).
Xm -- Value of mark as number. This does not read from the minibuffer.
Xn -- Number. This reads from the minibuffer and converts the result
X into a number.
Xp -- Prefix arg converted to number. A prefix arg is one specified,
X for example, by means of C-u. This does not read from the
X minibuffer. It is meaningful, but not very useful, to use
X this more than once; every argument specified with this option
X receives the same value. This does not use the minibuffer.
XP -- Prefix arg in raw form. This is useful for determining whether
X or not a prefix argument was supplied, because the conversion
X routine defaults prefix arguments to reasonable values (1 for
X a keystroke command, 0 for a M-x command, 4 for C-u, and -4
X for C-u - ). It is also meaningful, but not very useful, to
X use this more than once. It is more useful to use both this
X and "p", since the two arguments are difficult. This form can
X be converted easily into a numerical argument; see
X prefix-numeric-value. This does not use the minibuffer.
Xr -- Region: point and mark as 2 numeric args, smallest first. This
X is the appropriate way to read arguments for a command
X operating on a region; a lisp function calling this function
X should specify the bounds of the region itself. This
X specifies two consecutive arguments. It does not use the minibuffer.
Xs -- Any string.
XS -- Any symbol.
Xv -- User variable name: symbol that is user-variable-p. User
X variables (user options) are defined as variables whose
X documentation strings begin with "*".
Xx -- Lisp expression read but not evaluated.
XX -- Lisp expression read and evaluated.
XIn addition, if the first character of the string is '*' then an error is
X signaled if the buffer is read-only.
X This happens before reading any arguments.
X
XFor example, a function that looks like this:
X
X(lambda (a b c d &optional e)
X (interactive "p\nr\nfFile name to delete: ") nil)
X
Xwhen called interactively, first converts any prefix argument to a
Xnumber and binds a to that number, then binds b to the smaller of the
Xpoint and mark (beginning of region), then binds c to the end of the
Xregion, then prompts in the minibuffer with the string "File name to
Xdelete: ", reading a filename and checking that it exists. e is bound
Xto nil, since it is an optional argument and nothing was specified for
Xit.
X
XThe third way of of using interactive is to pass it a form to
Xevaluate. This form should return a list, and the arguments are
Xassigned from the elements of this list. For example,
X
X(lambda (a b)
X (interactive (list current-prefix-arg
X (completing-read "File to trash: " precious-files))))
X
Xa will be bound to current-prefix-arg (what interactive "P" uses) and
Xb will be bound to a file name read from the keyboard.
X
XWith any form of interactive, calling the function from Lisp does not
Xuse any of interactive's features; you must pass all arguments the
Xusual way. It is possible to call a function interactively from Lisp,
Xthough; see call-interactively.
X
X----------------------------------------------------------------
X
Xcall-interactively <COMMAND>
X
Xcall-interactively calls a command (an interactive function) as if it
Xhad been called from the keyboard. Thus, arguments are found from the
Xinteractive specification of COMMAND. This function is sometimes
Xuseful if you want to call a function from lisp, but wish to treat it
Xas a command.
X
X----------------------------------------------------------------
X
Xinteractive-p
X
Xinteractive-p returns t if the function from which it was called was
Xcalled interactively; that is, from the keyboard or with
Xcall-interactively, and with input from the terminal (i. e.
Xstandard-input's value is t).
X
X----------------------------------------------------------------
X
Xcommandp <FUNCTION>
X
XA FUNCTION satisfies commandp if it can be interactively called. This
Xmeans, either:
X -- that it has an interactive specification;
X -- is a string (which is considered a keyboard macro);
X -- is an interactively autoloadable function (see autoload);
X -- or is an interactively-callable primitive.
X
XA symbol also satisfies commandp if its function definition is
Xcommandp.
X
XThis function is not normally too useful for programmers, since it
Xseldom matters whether a function is a command. However, it may be
Xuseful for determining whether a function can be called with
Xcall-interactively.
X
X----------------------------------------------------------------
X
Xautoload <FUNCTION-NAME> <FILENAME> &optional <DOCUMENTATION> <INTERACTIVE> <MACRO>
X
Xautoload provides a way to specify that if FUNCTION is called, it can
Xbe found in file FILENAME. Thus, an attempt to call FUNCTION will
Xcause FILENAME to be loaded.
X
XDOCUMENTATION is a documentation string; normally it will be the same
Xas the documentation string for the underlying function.
X
XINTERACTIVE specifies that the function may be called interactively.
XThis means that the function name will be included in the completion
Xspace for M-x. Any call to the function, interactive or not, will
Xload the file. What to do will be determined when the true definition
Xis present.
X
XMACRO specifies that the underlying function is really a macro, and
Xnot a function. See the section on macros for more information.
X
X----------------------------------------------------------------
X
Xprefix-numeric-value <RAW-PREFIX-ARG>
X
XTranslates a raw prefix argument, such as that returned by interactive
X"P", into a number. This is the proper way of extracting the numeric
Xvalue of a prefix argument from the raw argument.
X
X----------------------------------------------------------------
X
Xcurrent-prefix-arg (variable)
X
XThe current value of the prefix argument. This variable is reset
Xafter each command.
X
XIt consists of one of the following:
X
Xnil -- no argument given
X- -- (the symbol -) -- C-u - or M-- is the prefix arg
XA number -- C-u followed by a number or M-{number} is the prefix arg
XA list -- One or more C-u's is the prefix arg. (4) means one C-u,
X (16) means 2, etc.
X
XThis can be used instead of interactive "P"; however, interactive "P"
Xis the preferred means of access. current-prefix-arg can be set or
Xbound, and a function then called with call-interactively, to control
Xthe passing of numerical arguments to a command.
X
X----------------------------------------------------------------
X
Xignore &rest <ARGUMENTS>
X
Xignore simply ignores any and all arguments passed it. A typical
Xapplication would be when you are using a standard facility that wants
Xa function that may be called at some point to inform you of some
Xcondition that you are not in fact interested in. You can safely
Xsupply ignore in this situation.
X
X----------------------------------------------------------------
X
Xmapconcat <FUNCTION> <SEQUENCE> <SEPARATOR>
X
Xmapconcat applies FUNCTION to each element of SEQUENCE and
Xconcatenates each result into a string, separated by SEPARATOR. It
Xcan be useful for printing out a list or vector in a preferred format.
XIt is frequently used with identity (see below).
X
X----------------------------------------------------------------
X
Xidentity <FORM>
X
Xidentity is a function that merely returns its argument. It is
Xprimarily useful with mapconcat, for printing out a list.
X
X================================================================
X
XFunctions written in C (primitives)
X
XCertain functions, and all special forms, are written in C. A
Xconvenient interface is provided via a set of macros. The only way to
Xreally understand how to write new C code is to read the source;
Xhowever, some information will be provided here.
X
XAn example of a special form (an ordinary function would have the same
Xgeneral appearance) is the definition of or, from eval.c;
X
X/* NOTE!!! Every function that can call EVAL must protect its args
X and temporaries from garbage collection while it needs them.
X The definition of `For' shows what you have to do. */
X
XDEFUN ("or", For, Sor, 0, UNEVALLED, 0,
X "Eval args until one of them yields non-NIL, then return that value.\n\
XThe remaining args are not evalled at all.\n\
XIf all args return NIL, return NIL.")
X (args)
X Lisp_Object args;
X{
X register Lisp_Object val;
X Lisp_Object args_left;
X struct gcpro gcpro1;
X
X if (NULL(args))
X return Qnil;
X
X args_left = args;
X GCPRO1 (args_left);
X
X do
X {
X val = Feval (Fcar (args_left));
X if (!NULL (val))
X break;
X args_left = Fcdr (args_left);
X }
X while (!NULL(args_left));
X
X UNGCPRO;
X return val;
X}
X
XHere is a precise explanation of the arguments to the DEFUN macro.
X
XThe first argument is the name of the function in Lisp; it will be
Xnamed "or".
X
XThe second argument is the C function name for this function. This is
Xthe name that is used in C code for calling the function. The name
Xis, by convention, F prepended to the Lisp name, with all dashes (-)
Xin the Lisp name changed to underscores. Thus, if your C code wishes
Xto call this function, it will call For(...). Remember that the
Xarguments must be Lisp_Objects; various macros and functions for
Xcreating Lisp_Objects are provided in the file lisp.h.
X
XThe third argument is the name of the C variable representing the Lisp
Xprimitive that this function codes. This name is by convention "S"
Xprepended to the name, in the same manner that the function name is
Xcreated.
X
XThe fourth argument is the minimum number of arguments that must be
Xprovided; i. e. the number of required arguments. In this case, no
Xarguments are required.
X
XThe fifth argument is the maximum number of arguments that can be
Xprovided. This is a special form because this number is the macro
XUNEVALLED, indicating that the arguments are not to be evaluated. A
Xfunction with the equivalent of an &rest argument would have the macro
XMANY in this position. This argument must be one of these macros or a
Xnumber at least as large as the fourth argument.
X
XThe sixth argument is an interactive specification exactly like the
Xone provided in Lisp. In this case it is 0 (a null pointer),
Xindicating that this function cannot be called interactively. A value
Xof "" indicates an interactive function not taking arguments.
X
XThe last argument is the documentation string.
X
XA list of arguments must be provided, and their types (all Lisp
Xobjects) must be declared.
X
XIf you are modifying a file that already has Lisp primitives defined
Xin it, find the function near the end of the file named
Xsyms-of-<something>, and add a line of the form
X
Xdefsubr (&Sname);
X
XIf the file doesn't have this function, or you have created a new
Xfile, add a syms_of_<filename>, e. g. syms_of_eval, and find the spot
Xin emacs.c where all of these functions are called. Add your there.
XThis makes all the subroutines (primitives) available from Lisp.
X
XHere is another function, with more complicated arguments. This comes
Xfrom the code for the X window system, and it demonstrates the use of
Xmacros and functions to manipulate Lisp objects.
X
XDEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
X Scoordinates_in_window_p, 2, 2,
X "xSpecify coordinate pair: \nXExpression which evals to window: ",
X "Return non-nil if POSITIONS (a list, (SCREEN-X SCREEN-Y)) is in WINDOW.\n\
XReturned value is list of positions expressed\n\
Xrelative to window upper left corner.")
X (coordinate, window)
X register Lisp_Object coordinate, window;
X{
X register Lisp_Object xcoord, ycoord;
X
X if (!LISTP (coordinate)) wrong_type_argument (Qlistp, coordinate);
X CHECK_WINDOW (window, 2);
X xcoord = Fcar (coordinate);
X ycoord = Fcar (Fcdr (coordinate));
X CHECK_NUMBER (xcoord, 0);
X CHECK_NUMBER (ycoord, 1);
X if ((XINT (xcoord) < XINT (XWINDOW (window)->left)) ||
X (XINT (xcoord) >= (XINT (XWINDOW (window)->left) +
X XINT (XWINDOW (window)->width))))
X {
X return Qnil;
X }
X XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
X if (XINT (ycoord) == (screen_height - 1))
X return Qnil;
X if ((XINT (ycoord) < XINT (XWINDOW (window)->top)) ||
X (XINT (ycoord) >= (XINT (XWINDOW (window)->top) +
X XINT (XWINDOW (window)->height)) - 1))
X {
X return Qnil;
X }
X XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
X return (Fcons (xcoord, Fcons (ycoord, Qnil)));
X}
X
XThere are similar equivalents for defvar and defconst, as well as a
Xfew others that have no equivalent in the Lisp interpreter.
X
XNote that you cannot directly call functions defined in Lisp as, for
Xexample, Fcons is called above. You must create the appropriate Lisp
Xform, protect everything from garbage collection, and Feval the form,
Xas was done in For above.
X
Xeval.c is a very good file to look through for examples; lisp.h
Xcontains the definitions for some important macros and functions.
X
SHAR_EOF
z=`wc -c < 'functions'`
if test 30546 -ne $z
then
echo shar: error transmitting "'functions'" \($z characters read\)
fi
echo shar: extracting "'numbers'" '(3220 characters)'
if test -f 'numbers'
then
echo shar: over-writing existing file "'numbers'"
fi
sed 's/^X//' << \SHAR_EOF > 'numbers'
XCopyright (C) 1986 Daniel LaLiberte
X
XDoes anyone have an example that might use lots of these numeric functions?
XOr ideas?
X
XI have some questions about machine dependencies. Namely, what
Xare the machine dependencies of integers in Emacs Lisp?
X
X
XDan LaLiberte
Xliberte@b.cs.uiuc.edu
Xliberte@uiuc.csnet
Xihnp4!uiucdcs!liberte
X
X
X------------------------------------------------------------------
XGNU Emacs Lisp supports integer arithmetic. Integers (or "numbers") may
Xhave a different number of significant bits on different machines.
XFor all of the following functions, all the NUMBER arguments must be
Xintegers. An OBJECT may be any Lisp object.
X
X
X
Xintegerp <OBJECT>
X t if OBJECT is an integer.
X
X
Xnatnump <OBJECT>
X t if OBJECT is a natural number, i.e., a nonnegative number.
X
Xinteger-or-marker-p <OBJECT>
X t if OBJECT is an integer or a marker. The function "point"
X returns an integer, but "make-marker" returns a marker.
X
X
Xzerop <NUMBER>
X t if NUMBER is zero.
X
X
Xint-to-string <NUMBER>
X Convert NUMBER to a string by printing it in decimal, with a minus
X sign if it is negative. Also see "format".
X
Xstring-to-int <STRING> &optional <FLAG>
X Convert STRING to an integer by parsing it as a decimal
X number. If the optional second argument FLAG is non-nil this means
X also convert "yes" to 1 and "no" to 0.
X
X
X= <NUMBER1> <NUMBER2>
X t if NUMBER1 = NUMBER2.
X
X< <NUMBER1> <NUMBER2>
X t if NUMBER1 < NUMBER2.
X
X> <NUMBER1> <NUMBER2>
X t if NUMBER1 > NUMBER2.
X
X<= <NUMBER1> <NUMBER2>
X t if NUMBER1 is less than or equal to NUMBER2.
X
X>= <NUMBER1> <NUMBER2>
X t if NUMBER1 is greater than or equal to NUMBER2.
X
X/= <NUMBER1> <NUMBER2>
X t if NUMBER1 is not equal to NUMBER2.
X
X
X+ <{NUMBER}>
X Return the sum of all arguments.
X
X- <{NUMBER}>
X With one argument, negate it. With more than one argument,
X subtract all but the first from the first argument.
X
X* <{NUMBER}>
X Return the product of all arguments.
X
X/ <{NUMBER}>
X Return the first argument divided by all of the rest.
X
X% <NUMBER1> <NUMBER2>
X Return the remainder of NUMBER1 / NUMBER2.
X [What happens when NUMBER1 or NUMBER2 < 0? Is it machine dependent?]
X
X1+ <NUMBER>
X Return NUMBER + 1.
X
X1- <NUMBER>
X Return NUMBER - 1.
X
Xmax <{NUMBER}>
X Return the largest argument.
X
Xmin <{NUMBER}>
X Return the smallest (most negative) argument.
X
X
Xlogand <{NUMBER}>
X Return the bitwise "and" of all the arguments.
X
Xlogior <{NUMBER}>
X Return the bitwise "inclusive-or" of all the arguments.
X
Xlogxor <{NUMBER}>
X Return the bitwise "exclusive-or" of all the arguments.
X
Xlognot <NUMBER>
X Return the bitwise complement of NUMBER.
X
X
Xash <VALUE> <COUNT>
X Arithmetic left or right shift. Return VALUE with its bits shifted
X left by COUNT. If COUNT is negative, shifting is actually to the
X right and the sign bit is duplicated.
X
Xlsh <VALUE> <COUNT>
X Logical left shift. Return VALUE with its bits shifted left
X by COUNT. If COUNT is negative, shifting is actually to the right.
X In either case, zeros are shifted in.
X
X
Xrandom &optional <TIME>
X Return a pseudo-random number. On most systems all integers
Xrepresentable in Lisp are equally likely. This is 24 bits' worth. If
Xthe optional argument TIME is supplied as t, the random number seed is set
Xbased on the current time and pid.
X
X
X
SHAR_EOF
z=`wc -c < 'numbers'`
if test 3220 -ne $z
then
echo shar: error transmitting "'numbers'" \($z characters read\)
fi
# End of shell archive
exit 0