# HG changeset patch # User Glenn Morris # Date 1189052460 0 # Node ID efcba214fdbb4b1444ab4e0860ac113c31f6d9be # Parent 0463db10a14b51ee00fa6256b673ea49940aa91c Move here from ../../lispref diff -r 0463db10a14b -r efcba214fdbb doc/lispref/intro.texi --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/lispref/intro.texi Thu Sep 06 04:21:00 2007 +0000 @@ -0,0 +1,560 @@ +@c -*-texinfo-*- +@c This is part of the GNU Emacs Lisp Reference Manual. +@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2001, 2002, 2003, 2004, +@c 2005, 2006, 2007 Free Software Foundation, Inc. +@c See the file elisp.texi for copying conditions. +@setfilename ../info/intro + +@node Introduction, Lisp Data Types, Top, Top +@comment node-name, next, previous, up +@chapter Introduction + + Most of the GNU Emacs text editor is written in the programming +language called Emacs Lisp. You can write new code in Emacs Lisp and +install it as an extension to the editor. However, Emacs Lisp is more +than a mere ``extension language''; it is a full computer programming +language in its own right. You can use it as you would any other +programming language. + + Because Emacs Lisp is designed for use in an editor, it has special +features for scanning and parsing text as well as features for handling +files, buffers, displays, subprocesses, and so on. Emacs Lisp is +closely integrated with the editing facilities; thus, editing commands +are functions that can also conveniently be called from Lisp programs, +and parameters for customization are ordinary Lisp variables. + + This manual attempts to be a full description of Emacs Lisp. For a +beginner's introduction to Emacs Lisp, see @cite{An Introduction to +Emacs Lisp Programming}, by Bob Chassell, also published by the Free +Software Foundation. This manual presumes considerable familiarity with +the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this +basic information. + + Generally speaking, the earlier chapters describe features of Emacs +Lisp that have counterparts in many programming languages, and later +chapters describe features that are peculiar to Emacs Lisp or relate +specifically to editing. + + This is edition @value{VERSION} of the GNU Emacs Lisp Reference +Manual, corresponding to Emacs version @value{EMACSVER}. + +@menu +* Caveats:: Flaws and a request for help. +* Lisp History:: Emacs Lisp is descended from Maclisp. +* Conventions:: How the manual is formatted. +* Version Info:: Which Emacs version is running? +* Acknowledgements:: The authors, editors, and sponsors of this manual. +@end menu + +@node Caveats +@section Caveats +@cindex bugs in this manual + + This manual has gone through numerous drafts. It is nearly complete +but not flawless. There are a few topics that are not covered, either +because we consider them secondary (such as most of the individual +modes) or because they are yet to be written. Because we are not able +to deal with them completely, we have left out several parts +intentionally. This includes most information about usage on VMS. + + The manual should be fully correct in what it does cover, and it is +therefore open to criticism on anything it says---from specific examples +and descriptive text, to the ordering of chapters and sections. If +something is confusing, or you find that you have to look at the sources +or experiment to learn something not covered in the manual, then perhaps +the manual should be fixed. Please let us know. + +@iftex + As you use this manual, we ask that you mark pages with corrections so +you can later look them up and send them to us. If you think of a simple, +real-life example for a function or group of functions, please make an +effort to write it up and send it in. Please reference any comments to +the chapter name, section name, and function name, as appropriate, since +page numbers and chapter and section numbers will change and we may have +trouble finding the text you are talking about. Also state the number +of the edition you are criticizing. +@end iftex +@ifnottex + +As you use this manual, we ask that you send corrections as soon as you +find them. If you think of a simple, real life example for a function +or group of functions, please make an effort to write it up and send it +in. Please reference any comments to the node name and function or +variable name, as appropriate. Also state the number of the edition +you are criticizing. +@end ifnottex + +@cindex bugs +@cindex suggestions +Please mail comments and corrections to + +@example +bug-lisp-manual@@gnu.org +@end example + +@noindent +We let mail to this list accumulate unread until someone decides to +apply the corrections. Months, and sometimes years, go by between +updates. So please attach no significance to the lack of a reply---your +mail @emph{will} be acted on in due time. If you want to contact the +Emacs maintainers more quickly, send mail to +@code{bug-gnu-emacs@@gnu.org}. + +@node Lisp History +@section Lisp History +@cindex Lisp history + + Lisp (LISt Processing language) was first developed in the late 1950s +at the Massachusetts Institute of Technology for research in artificial +intelligence. The great power of the Lisp language makes it ideal +for other purposes as well, such as writing editing commands. + +@cindex Maclisp +@cindex Common Lisp + Dozens of Lisp implementations have been built over the years, each +with its own idiosyncrasies. Many of them were inspired by Maclisp, +which was written in the 1960s at MIT's Project MAC. Eventually the +implementors of the descendants of Maclisp came together and developed a +standard for Lisp systems, called Common Lisp. In the meantime, Gerry +Sussman and Guy Steele at MIT developed a simplified but very powerful +dialect of Lisp, called Scheme. + + GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common +Lisp. If you know Common Lisp, you will notice many similarities. +However, many features of Common Lisp have been omitted or +simplified in order to reduce the memory requirements of GNU Emacs. +Sometimes the simplifications are so drastic that a Common Lisp user +might be very confused. We will occasionally point out how GNU Emacs +Lisp differs from Common Lisp. If you don't know Common Lisp, don't +worry about it; this manual is self-contained. + +@pindex cl + A certain amount of Common Lisp emulation is available via the +@file{cl} library. @inforef{Top, Overview, cl}. + + Emacs Lisp is not at all influenced by Scheme; but the GNU project has +an implementation of Scheme, called Guile. We use Guile in all new GNU +software that calls for extensibility. + +@node Conventions +@section Conventions + +This section explains the notational conventions that are used in this +manual. You may want to skip this section and refer back to it later. + +@menu +* Some Terms:: Explanation of terms we use in this manual. +* nil and t:: How the symbols @code{nil} and @code{t} are used. +* Evaluation Notation:: The format we use for examples of evaluation. +* Printing Notation:: The format we use when examples print text. +* Error Messages:: The format we use for examples of errors. +* Buffer Text Notation:: The format we use for buffer contents in examples. +* Format of Descriptions:: Notation for describing functions, variables, etc. +@end menu + +@node Some Terms +@subsection Some Terms + + Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp +printer'' refer to those routines in Lisp that convert textual +representations of Lisp objects into actual Lisp objects, and vice +versa. @xref{Printed Representation}, for more details. You, the +person reading this manual, are thought of as ``the programmer'' and are +addressed as ``you.'' ``The user'' is the person who uses Lisp +programs, including those you write. + +@cindex fonts in this manual + Examples of Lisp code are formatted like this: @code{(list 1 2 3)}. +Names that represent metasyntactic variables, or arguments to a function +being described, are formatted like this: @var{first-number}. + +@node nil and t +@subsection @code{nil} and @code{t} +@cindex truth value +@cindex boolean + +@cindex @code{nil} +@cindex false + In Lisp, the symbol @code{nil} has three separate meanings: it +is a symbol with the name @samp{nil}; it is the logical truth value +@var{false}; and it is the empty list---the list of zero elements. +When used as a variable, @code{nil} always has the value @code{nil}. + + As far as the Lisp reader is concerned, @samp{()} and @samp{nil} are +identical: they stand for the same object, the symbol @code{nil}. The +different ways of writing the symbol are intended entirely for human +readers. After the Lisp reader has read either @samp{()} or @samp{nil}, +there is no way to determine which representation was actually written +by the programmer. + + In this manual, we write @code{()} when we wish to emphasize that it +means the empty list, and we write @code{nil} when we wish to emphasize +that it means the truth value @var{false}. That is a good convention to use +in Lisp programs also. + +@example +(cons 'foo ()) ; @r{Emphasize the empty list} +(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}} +@end example + +@cindex @code{t} +@cindex true + In contexts where a truth value is expected, any non-@code{nil} value +is considered to be @var{true}. However, @code{t} is the preferred way +to represent the truth value @var{true}. When you need to choose a +value which represents @var{true}, and there is no other basis for +choosing, use @code{t}. The symbol @code{t} always has the value +@code{t}. + + In Emacs Lisp, @code{nil} and @code{t} are special symbols that always +evaluate to themselves. This is so that you do not need to quote them +to use them as constants in a program. An attempt to change their +values results in a @code{setting-constant} error. @xref{Constant +Variables}. + +@defun booleanp object +Return non-nil if @var{object} is one of the two canonical boolean +values: @code{t} or @code{nil}. +@end defun + +@node Evaluation Notation +@subsection Evaluation Notation +@cindex evaluation notation +@cindex documentation notation +@cindex notation + + A Lisp expression that you can evaluate is called a @dfn{form}. +Evaluating a form always produces a result, which is a Lisp object. In +the examples in this manual, this is indicated with @samp{@result{}}: + +@example +(car '(1 2)) + @result{} 1 +@end example + +@noindent +You can read this as ``@code{(car '(1 2))} evaluates to 1.'' + + When a form is a macro call, it expands into a new form for Lisp to +evaluate. We show the result of the expansion with +@samp{@expansion{}}. We may or may not show the result of the +evaluation of the expanded form. + +@example +(third '(a b c)) + @expansion{} (car (cdr (cdr '(a b c)))) + @result{} c +@end example + + Sometimes to help describe one form we show another form that +produces identical results. The exact equivalence of two forms is +indicated with @samp{@equiv{}}. + +@example +(make-sparse-keymap) @equiv{} (list 'keymap) +@end example + +@node Printing Notation +@subsection Printing Notation +@cindex printing notation + + Many of the examples in this manual print text when they are +evaluated. If you execute example code in a Lisp Interaction buffer +(such as the buffer @samp{*scratch*}), the printed text is inserted into +the buffer. If you execute the example by other means (such as by +evaluating the function @code{eval-region}), the printed text is +displayed in the echo area. + + Examples in this manual indicate printed text with @samp{@print{}}, +irrespective of where that text goes. The value returned by +evaluating the form (here @code{bar}) follows on a separate line with +@samp{@result{}}. + +@example +@group +(progn (prin1 'foo) (princ "\n") (prin1 'bar)) + @print{} foo + @print{} bar + @result{} bar +@end group +@end example + +@node Error Messages +@subsection Error Messages +@cindex error message notation + + Some examples signal errors. This normally displays an error message +in the echo area. We show the error message on a line starting with +@samp{@error{}}. Note that @samp{@error{}} itself does not appear in +the echo area. + +@example +(+ 23 'x) +@error{} Wrong type argument: number-or-marker-p, x +@end example + +@node Buffer Text Notation +@subsection Buffer Text Notation +@cindex buffer text notation + + Some examples describe modifications to the contents of a buffer, by +showing the ``before'' and ``after'' versions of the text. These +examples show the contents of the buffer in question between two lines +of dashes containing the buffer name. In addition, @samp{@point{}} +indicates the location of point. (The symbol for point, of course, is +not part of the text in the buffer; it indicates the place +@emph{between} two characters where point is currently located.) + +@example +---------- Buffer: foo ---------- +This is the @point{}contents of foo. +---------- Buffer: foo ---------- + +(insert "changed ") + @result{} nil +---------- Buffer: foo ---------- +This is the changed @point{}contents of foo. +---------- Buffer: foo ---------- +@end example + +@node Format of Descriptions +@subsection Format of Descriptions +@cindex description format + + Functions, variables, macros, commands, user options, and special +forms are described in this manual in a uniform format. The first +line of a description contains the name of the item followed by its +arguments, if any. +@ifnottex +The category---function, variable, or whatever---appears at the +beginning of the line. +@end ifnottex +@iftex +The category---function, variable, or whatever---is printed next to the +right margin. +@end iftex +The description follows on succeeding lines, sometimes with examples. + +@menu +* A Sample Function Description:: A description of an imaginary + function, @code{foo}. +* A Sample Variable Description:: A description of an imaginary + variable, + @code{electric-future-map}. +@end menu + +@node A Sample Function Description +@subsubsection A Sample Function Description +@cindex function descriptions +@cindex command descriptions +@cindex macro descriptions +@cindex special form descriptions + + In a function description, the name of the function being described +appears first. It is followed on the same line by a list of argument +names. These names are also used in the body of the description, to +stand for the values of the arguments. + + The appearance of the keyword @code{&optional} in the argument list +indicates that the subsequent arguments may be omitted (omitted +arguments default to @code{nil}). Do not write @code{&optional} when +you call the function. + + The keyword @code{&rest} (which must be followed by a single +argument name) indicates that any number of arguments can follow. The +single argument name following @code{&rest} will receive, as its +value, a list of all the remaining arguments passed to the function. +Do not write @code{&rest} when you call the function. + + Here is a description of an imaginary function @code{foo}: + +@defun foo integer1 &optional integer2 &rest integers +The function @code{foo} subtracts @var{integer1} from @var{integer2}, +then adds all the rest of the arguments to the result. If @var{integer2} +is not supplied, then the number 19 is used by default. + +@example +(foo 1 5 3 9) + @result{} 16 +(foo 5) + @result{} 14 +@end example + +@need 1500 +More generally, + +@example +(foo @var{w} @var{x} @var{y}@dots{}) +@equiv{} +(+ (- @var{x} @var{w}) @var{y}@dots{}) +@end example +@end defun + + Any argument whose name contains the name of a type (e.g., +@var{integer}, @var{integer1} or @var{buffer}) is expected to be of that +type. A plural of a type (such as @var{buffers}) often means a list of +objects of that type. Arguments named @var{object} may be of any type. +(@xref{Lisp Data Types}, for a list of Emacs object types.) Arguments +with other sorts of names (e.g., @var{new-file}) are discussed +specifically in the description of the function. In some sections, +features common to the arguments of several functions are described at +the beginning. + + @xref{Lambda Expressions}, for a more complete description of optional +and rest arguments. + + Command, macro, and special form descriptions have the same format, +but the word `Function' is replaced by `Command', `Macro', or `Special +Form', respectively. Commands are simply functions that may be called +interactively; macros process their arguments differently from functions +(the arguments are not evaluated), but are presented the same way. + + Special form descriptions use a more complex notation to specify +optional and repeated arguments because they can break the argument +list down into separate arguments in more complicated ways. +@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is +optional and @samp{@var{repeated-args}@dots{}} stands for zero or more +arguments. Parentheses are used when several arguments are grouped into +additional levels of list structure. Here is an example: + +@defspec count-loop (@var{var} [@var{from} @var{to} [@var{inc}]]) @var{body}@dots{} +This imaginary special form implements a loop that executes the +@var{body} forms and then increments the variable @var{var} on each +iteration. On the first iteration, the variable has the value +@var{from}; on subsequent iterations, it is incremented by one (or by +@var{inc} if that is given). The loop exits before executing @var{body} +if @var{var} equals @var{to}. Here is an example: + +@example +(count-loop (i 0 10) + (prin1 i) (princ " ") + (prin1 (aref vector i)) + (terpri)) +@end example + +If @var{from} and @var{to} are omitted, @var{var} is bound to +@code{nil} before the loop begins, and the loop exits if @var{var} is +non-@code{nil} at the beginning of an iteration. Here is an example: + +@example +(count-loop (done) + (if (pending) + (fixit) + (setq done t))) +@end example + +In this special form, the arguments @var{from} and @var{to} are +optional, but must both be present or both absent. If they are present, +@var{inc} may optionally be specified as well. These arguments are +grouped with the argument @var{var} into a list, to distinguish them +from @var{body}, which includes all remaining elements of the form. +@end defspec + +@node A Sample Variable Description +@subsubsection A Sample Variable Description +@cindex variable descriptions +@cindex option descriptions + + A @dfn{variable} is a name that can hold a value. Although nearly +all variables can be set by the user, certain variables exist +specifically so that users can change them; these are called @dfn{user +options}. Ordinary variables and user options are described using a +format like that for functions except that there are no arguments. + + Here is a description of the imaginary @code{electric-future-map} +variable.@refill + +@defvar electric-future-map +The value of this variable is a full keymap used by Electric Command +Future mode. The functions in this map allow you to edit commands you +have not yet thought about executing. +@end defvar + + User option descriptions have the same format, but `Variable' is +replaced by `User Option'. + +@node Version Info +@section Version Information + + These facilities provide information about which version of Emacs is +in use. + +@deffn Command emacs-version &optional here +This function returns a string describing the version of Emacs that is +running. It is useful to include this string in bug reports. + +@smallexample +@group +(emacs-version) + @result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit) + of Sat Feb 14 1998 on psilocin.gnu.org" +@end group +@end smallexample + +If @var{here} is non-@code{nil}, it inserts the text in the buffer +before point, and returns @code{nil}. Called interactively, the +function prints the same information in the echo area, but giving a +prefix argument makes @var{here} non-@code{nil}. +@end deffn + +@defvar emacs-build-time +The value of this variable indicates the time at which Emacs was built +at the local site. It is a list of three integers, like the value +of @code{current-time} (@pxref{Time of Day}). + +@example +@group +emacs-build-time + @result{} (13623 62065 344633) +@end group +@end example +@end defvar + +@defvar emacs-version +The value of this variable is the version of Emacs being run. It is a +string such as @code{"20.3.1"}. The last number in this string is not +really part of the Emacs release version number; it is incremented each +time you build Emacs in any given directory. A value with four numeric +components, such as @code{"20.3.9.1"}, indicates an unreleased test +version. +@end defvar + + The following two variables have existed since Emacs version 19.23: + +@defvar emacs-major-version +The major version number of Emacs, as an integer. For Emacs version +20.3, the value is 20. +@end defvar + +@defvar emacs-minor-version +The minor version number of Emacs, as an integer. For Emacs version +20.3, the value is 3. +@end defvar + +@node Acknowledgements +@section Acknowledgements + + This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte, +Richard@tie{}M. Stallman and Chris Welty, the volunteers of the GNU +manual group, in an effort extending over several years. +Robert@tie{}J. Chassell helped to review and edit the manual, with the +support of the Defense Advanced Research Projects Agency, ARPA Order +6082, arranged by Warren@tie{}A. Hunt, Jr.@: of Computational Logic, +Inc. + + Corrections were supplied by Karl Berry, Jim Blandy, Bard Bloom, +Stephane Boucher, David Boyes, Alan Carroll, Richard Davis, Lawrence +R. Dodd, Peter Doornbosch, David A. Duff, Chris Eich, Beverly +Erlebacher, David Eckelkamp, Ralf Fassel, Eirik Fuller, Stephen Gildea, +Bob Glickstein, Eric Hanchrow, George Hartzell, Nathan Hess, Masayuki +Ida, Dan Jacobson, Jak Kirman, Bob Knighten, Frederick M. Korz, Joe +Lammens, Glenn M. Lewis, K. Richard Magill, Brian Marick, Roland +McGrath, Skip Montanaro, John Gardiner Myers, Thomas A. Peterson, +Francesco Potorti, Friedrich Pukelsheim, Arnold D. Robbins, Raul +Rockwell, Per Starb@"ack, Shinichirou Sugou, Kimmo Suominen, Edward Tharp, +Bill Trost, Rickard Westman, Jean White, Matthew Wilding, Carl Witty, +Dale Worley, Rusty Wright, and David D. Zuhn. + +@ignore + arch-tag: d156593f-82f8-4708-a844-204e48f7f2aa +@end ignore