@c -*-texinfo-*-
@setfilename ../info/intro

@node License, Introduction, Top, Top
@comment  node-name,  next,  previous,  up
@unnumbered GNU Emacs General Public License
@center (Clarified 11 Feb 1988)

  The license agreements of most software companies keep you at the
mercy of those companies.  By contrast, our general public license is
intended to give everyone the right to share GNU Emacs.  To make
sure that you get the rights we want you to have, we need to make
restrictions that forbid anyone to deny you these rights or to ask you
to surrender the rights.  Hence this license agreement.

  Specifically, we want to make sure that you have the right to give
away copies of Emacs, that you receive source code or else can get it
if you want it, that you can change Emacs or use pieces of it in new
free programs, and that you know you can do these things.

  To make sure that everyone has such rights, we have to forbid you to
deprive anyone else of these rights.  For example, if you distribute
copies of Emacs, you must give the recipients all the rights that you
have.  You must make sure that they, too, receive or can get the
source code.  And you must tell them their rights.

  Also, for our own protection, we must make certain that everyone
finds out that there is no warranty for GNU Emacs.  If Emacs is
modified by someone else and passed on, we want its recipients to know
that what they have is not what we distributed, so that any problems
introduced by others will not reflect on our reputation.

  Therefore we (Richard Stallman and the Free Software Foundation, Inc.)@:
make the following terms which say what you must do to be allowed to
distribute or change GNU Emacs.

@unnumberedsec Copying Policies

@enumerate
@item
You may copy and distribute verbatim copies of GNU Emacs source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each file a valid copyright notice ``Copyright
@copyright{} 1988 Free Software Foundation, Inc.'' (or with whatever year
is appropriate); keep intact the notices on all files that
refer to this License Agreement and to the absence of any warranty; and
give any other recipients of the GNU Emacs program a copy of this License
Agreement along with the program.  You may charge a distribution fee
for the physical act of transferring a copy.

@item
You may modify your copy or copies of GNU Emacs source code or
any portion of it, and copy and distribute such modifications under
the terms of Paragraph 1 above, provided that you also do the following:

@itemize @bullet
@item
cause the modified files to carry prominent notices stating
who last changed such files and the date of any change; and

@item
cause the whole of any work that you distribute or publish, that
in whole or in part contains or is a derivative of GNU Emacs or any
part thereof, to be licensed at no charge to all third parties on
terms identical to those contained in this License Agreement
(except that you may choose to grant more extensive warranty
protection to some or all third parties, at your option).

@item
if the modified program serves as a text editor, cause it, when
started running in the simplest and usual way, to print an
announcement including a valid copyright notice ``Copyright
@copyright{} 1988 Free Software Foundation, Inc.'' (or with the
year that is appropriate), saying that there is no warranty (or
else, saying that you provide a warranty) and that users may
redistribute the program under these conditions, and telling the
user how to view a copy of this License Agreement.

@item
You may charge a distribution fee for the physical act of
transferring a copy, and you may at your option offer warranty
protection in exchange for a fee.
@end itemize

Mere aggregation of another unrelated program with this program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other program under the scope of these terms.

@item
You may copy and distribute GNU Emacs (or a portion or derivative of it,
under Paragraph 2) in object code or executable form under the terms
of Paragraphs 1 and 2 above provided that you also do one of the
following:

@itemize @bullet
@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal
shipping charge) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,

@item
accompany it with the information you received as to where the
corresponding source code may be obtained.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
@end itemize

For an executable file, complete source code means all the source code
for all modules it contains; but, as a special exception, it need not
include source code for modules which are standard libraries that
accompany the operating system on which the executable file runs.

@item
You may not copy, sublicense, distribute or transfer GNU Emacs except
as expressly provided under this License Agreement.  Any attempt
otherwise to copy, sublicense, distribute or transfer GNU Emacs is
void and your rights to use GNU Emacs under this License agreement
shall be automatically terminated.  However, parties who have received
computer software programs from you with this License Agreement will
not have their licenses terminated so long as such parties remain in
full compliance.

@item
If you wish to incorporate parts of GNU Emacs into other free programs
whose distribution conditions are different, write to the Free Software
Foundation.  We have not yet worked out a simple rule that can be stated
here, but we will often permit this.  We will be guided by the two goals of
preserving the free status of all derivatives of our free software and of
promoting the sharing and reuse of software.
@end enumerate

Your comments and suggestions about our licensing policies and our
software are welcome!  Please contact the Free Software Foundation, Inc.,
675 Mass Ave, Cambridge, MA 02139.

@iftex
@vfil
@eject
@end iftex
@unnumberedsec NO WARRANTY

  BECAUSE GNU EMACS IS LICENSED FREE OF CHARGE, WE PROVIDE ABSOLUTELY
NO WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
WHEN OTHERWISE STATED IN WRITING, FREE SOFTWARE FOUNDATION, INC,
RICHARD M. STALLMAN AND/OR OTHER PARTIES PROVIDE GNU EMACS ``AS IS''
WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING,
BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY
AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE GNU EMACS
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
SERVICING, REPAIR OR CORRECTION.

 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL FREE SOFTWARE
FOUNDATION, INC., RICHARD M. STALLMAN, AND/OR ANY OTHER PARTY WHO MAY
MODIFY AND REDISTRIBUTE GNU EMACS AS PERMITTED ABOVE, BE LIABLE TO YOU
FOR DAMAGES, INCLUDING ANY LOST PROFITS, LOST MONIES, OR OTHER
SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
INABILITY TO USE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY THIRD PARTIES OR A
FAILURE OF THE PROGRAM TO OPERATE WITH PROGRAMS NOT DISTRIBUTED BY
FREE SOFTWARE FOUNDATION, INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN
ADVISED OF THE POSSIBILITY OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY
OTHER PARTY.

@node Introduction, Types of Lisp Object, License, Top
@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 describes Emacs Lisp, presuming 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 1.02.

@menu
* Caveats::             Flaws and a request for help.
* Lisp History::        Emacs Lisp is descended from Maclisp.
* Conventions::         How the manual is formatted.
* Acknowledgements::    The authors, editors, and sponsors of this manual.
@end menu

@node Caveats, Lisp History, Introduction, Introduction
@section Caveats

  This manual has gone through numerous drafts.  It is nearly complete
but not flawless.  There are a few sections which are not included,
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 references to VMS and
all information relating to X Windows and Sunview.  The functions for
using X Windows will in any case be entirely different in version 19.
(The Free Software Foundation expends no effort on support for Sunview,
since we believe users should use free X Windows rather than
proprietary window systems.)

  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 the manual, we ask that you mark pages with corrections so
you can later look them up and send them in.  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.
@end iftex
@ifinfo

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.
@end ifinfo

Please mail comments and corrections to
@code{lisp-manual-bugs@@prep.ai.mit.edu}.

@noindent
@display
 --Bil Lewis, Dan LaLiberte, Richard Stallman
@end display

@node Lisp History, Conventions, Caveats, Introduction
@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 superior
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 1960's at MIT's Project MAC.  Eventually the
implementors of the descendents of Maclisp came together and developed a
standard for Lisp systems, called Common Lisp.

  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 of the 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.

@node Conventions, Acknowledgements, Lisp History, Introduction
@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 for examples that print output.
* 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, nil and t, Conventions, Conventions
@subsection Some Terms

  Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
printer'' are used to refer to those routines in Lisp that convert
textual representations of Lisp objects into actual objects, and vice
versa.  @xref{Printed Representation}, for more details.  You, the
person reading this manual, are assumed to be ``the programmer'' and are
addressed as ``you''.  ``The user'' is the person who uses the code that
you write.

@cindex fonts
  Examples of Lisp code appear in this font or form: @code{(list 1 2
3)}.  Names that represent arguments or metasyntactic variables appear
in this font or form: @var{first-number}.

@node nil and t, Evaluation Notation, Some Terms, Conventions
@subsection @code{nil} and @code{t}
@cindex @code{nil}, uses of
@cindex truth value
@cindex boolean
@cindex false

  In Lisp, the symbol @code{nil} is overloaded with three 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 use @code{()} when we wish to emphasize that it
means the empty list, and we use @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}
(not nil)                     ; @r{Emphasize the truth value @var{false}}
@end example

@cindex @code{t} and truth
@cindex true
  In context 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 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{Accessing
Variables}.

@node Evaluation Notation, Printing Notation, nil and t, Conventions
@subsection Evaluation Notation
@cindex evaluation notation
@cindex documentation notation

  When you evaluate a piece of Lisp code, it produces a result.  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 actual 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 which
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, Error Messages, Evaluation Notation, Conventions
@subsection Printing Notation
@cindex printing notation

  Many of the examples in this manual print text when they are
evaluated.  If you execute the code from an example in a Lisp
Interaction buffer (such as the buffer @samp{*scratch*}), the printed
text is inserted into the buffer.  If the example is executed by other
means (such as by evaluating the function @code{eval-region}), the text
printed is usually displayed in the echo area.  You should be aware that
text displayed in the echo area is truncated to a single line.

  In examples that print text, the printed text is indicated with
@samp{@print{}}, irrespective of how the form is executed.  The value
returned by evaluating the form (here @code{bar}) follows on a separate
line.

@group
@example
(progn (print 'foo) (print 'bar))
     @print{} foo
     @print{} bar
     @result{} bar
@end example
@end group

@node Error Messages, Buffer Text Notation, Printing Notation, Conventions
@subsection Error Messages
@cindex error message notation

  Some examples cause errors to be signaled.  In them, the error
message (which always appears in the echo area) is shown 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: integer-or-marker-p, x
@end example

@node Buffer Text Notation, Format of Descriptions, Error Messages, Conventions
@subsection Buffer Text Notation
@cindex buffer text notation

  Some examples show modifications to text in a buffer, with ``before''
and ``after'' versions of the text.  In such cases, the entire contents
of the buffer in question are included between two lines of dashes
containing the buffer name.  In addition, the location of point is shown
as @samp{@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 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,  , Buffer Text Notation, Conventions
@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.
@ifinfo
The category---function, variable, or whatever---appears at the
beginning of the line.
@end ifinfo
@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 Sample Variable Description::   
@end menu

@node A Sample Function Description, A Sample Variable Description, Format of Descriptions, Format of Descriptions
@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 parameters.
The names used for the parameters are also used in the body of the
description.

  The appearance of the keyword @code{&optional} in the parameter list
indicates that the arguments for subsequent parameters may be omitted
(omitted parameters default to @code{nil}).  Do not write
@code{&optional} when you call the function.

  The keyword @code{&rest} (which will always be followed by a single
parameter) indicates that any number of arguments can follow.  The value
of the single following parameter will be a list of all these arguments.
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

More generally,

@example
(foo @var{w} @var{x} @var{y}@dots{})
@equiv{}
(+ (- @var{x} @var{w}) @var{y}@dots{})
@end example
@end defun

  Any parameter 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.  Parameters named @var{object} may be of any type.
(@xref{Types of Lisp Object}, for a list of Emacs object types.)
Parameters 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 parameters 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 parameters because they can break the argument
list down into separate arguments in more complicated ways.
@samp{@code{@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 1 (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, then @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,  , A Sample Function Description, Format of Descriptions
@subsubsection A Sample Variable Description
@cindex variable descriptions
@cindex option descriptions

  A @dfn{variable} is a name that can hold a value.  Although any
variable can be set by the user, certain variables that exist
specifically so that users can change them 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 will 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 Acknowledgements,, Conventions, Introduction
@section Acknowledgements

  This manual was written by Robert Krawitz, Bil Lewis, Dan LaLiberte,
Richard M. Stallman and Chris Welty, the volunteers of the GNU manual
group, in an effort extending over several years.  Robert 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
A. Hunt, Jr. of Computational Logic, Inc.

  Corrections were supplied by Karl Berry, Bard Bloom, David Boyes, Alan
Carroll, David A. Duff, Beverly Erlebacher, David Eckelkamp, Eirik
Fuller, Eric Hanchrow, George Hartzell, Nathan Hess, Dan Jacobson, Jak
Kirman, Bob Knighten, Frederick M. Korz, Joe Lammens, K. Richard Magill,
Brian Marick, Roland McGrath, Skip Montanaro, John Gardiner Myers,
Arnold D. Robbins, Raul Rockwell, Shinichirou Sugou, Kimmo Suominen,
Edward Tharp, Bill Trost, Jean White, Matthew Wilding, Carl Witty, Dale
Worley, Rusty Wright, and David D. Zuhn.
