# HG changeset patch # User Glenn Morris # Date 1189051926 0 # Node ID 245511e554b102c652004378174b41b28c29ba42 # Parent e9ba15158cdc8fe17b373c3d50919440ba538a15 Move to ../doc/lispref diff -r e9ba15158cdc -r 245511e554b1 lispref/intro.texi --- a/lispref/intro.texi Thu Sep 06 04:11:59 2007 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,560 +0,0 @@ -@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