@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 2002, 2003, 2004,
+@c 2005, 2006 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/intro
chapters describe features that are peculiar to Emacs Lisp or relate
specifically to editing.
- This is edition 2.6.
+ 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.
@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
you are criticizing.
@end ifnottex
+@cindex bugs
+@cindex suggestions
Please mail comments and corrections to
@example
@pindex cl
A certain amount of Common Lisp emulation is available via the
-@file{cl} library. @xref{Top,, Common Lisp Extension, cl, Common Lisp
-Extensions}.
+@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
addressed as ``you''. ``The user'' is the person who uses Lisp
programs, including those you write.
-@cindex fonts
+@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}.
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
+ 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}
-(not nil) ; @r{Emphasize the truth value @var{false}}
+(setq foo-flag nil) ; @r{Emphasize the truth value @var{false}}
@end example
-@cindex @code{t} and truth
+@cindex @code{t}, uses of
@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
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. The same is true of
-any symbol whose name starts with a colon (@samp{:}). @xref{Constant
+values results in a @code{setting-constant} error. @xref{Constant
Variables}.
+@defun booleanp object
+Return non-nil iff @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
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.
+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 (print 'foo) (print 'bar))
+(progn (prin1 'foo) (princ "\n") (prin1 'bar))
@print{} foo
@print{} bar
@result{} bar
function, @code{foo}.
* A Sample Variable Description:: A description of an imaginary
variable,
- @code{electric-future-map}.
+ @code{electric-future-map}.
@end menu
@node A Sample Function Description
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
-following argument name will have a value, as a variable, which is a
-list of all these remaining arguments. Do not write @code{&rest} 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}:
@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
+ 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.
These facilities provide information about which version of Emacs is
in use.
-@deffn Command emacs-version
+@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.
@end group
@end smallexample
-Called interactively, the function prints the same information in the
-echo area.
+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 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 three numeric
+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
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