procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Move here from ../../lispref

Browse source
This commit is contained in:
Glenn Morris 2007-09-06 04:25:08 +00:00
parent f69340d750
commit b8d4c8d0e9
72 changed files with 83477 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
doc/lispref/.arch-inventory Normal file
View file

@ -0,0 +1,4 @@
# Generated files
precious ^(config\.status|config\.cache)$
# arch-tag: dde817a2-94ff-4c6e-838c-bb5b33e7f0df

17
doc/lispref/.gitignore vendored Normal file
View file

@ -0,0 +1,17 @@
texput.log
elisp.??
elisp.???
configure
config.log
config.cache
config.status
Makefile
makefile
index.texi
elisp
elisp-?
elisp-??
vol1.*
vol2.*
elisp1*
elisp2*

6291
doc/lispref/ChangeLog Normal file
View file

File diff suppressed because it is too large Load diff

144
doc/lispref/Makefile.in Normal file
View file

@ -0,0 +1,144 @@
# Makefile for the GNU Emacs Lisp Reference Manual.
# Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999, 2000,
# 2001, 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
# This file is part of GNU Emacs.
# GNU Emacs is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
# GNU Emacs is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with GNU Emacs; see the file COPYING. If not, write to
# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
# Standard configure variables.
srcdir = @srcdir@
# Tell make where to find source files; this is needed for the makefiles.
VPATH=@srcdir@
infodir = ../info
usermanualdir = $(srcdir)/../man
TEXI2DVI = texi2dvi
SHELL = /bin/sh
INSTALL_INFO = install-info
MAKEINFO = makeinfo --force
# The name of the manual:
VERSION=2.9
manual = elisp-manual-21-$(VERSION)
# List of all the texinfo files in the manual:
srcs = \
$(srcdir)/abbrevs.texi \
$(srcdir)/advice.texi \
$(srcdir)/anti.texi \
$(srcdir)/back.texi \
$(srcdir)/backups.texi \
$(srcdir)/buffers.texi \
$(srcdir)/commands.texi \
$(srcdir)/compile.texi \
$(srcdir)/control.texi \
$(srcdir)/customize.texi \
$(srcdir)/debugging.texi \
$(srcdir)/display.texi \
$(srcdir)/edebug.texi \
$(srcdir)/elisp.texi \
$(srcdir)/errors.texi \
$(srcdir)/eval.texi \
$(srcdir)/files.texi \
$(srcdir)/frames.texi \
$(srcdir)/functions.texi \
$(srcdir)/hash.texi \
$(srcdir)/help.texi \
$(srcdir)/hooks.texi \
$(srcdir)/internals.texi \
$(srcdir)/intro.texi \
$(srcdir)/keymaps.texi \
$(srcdir)/lists.texi \
$(srcdir)/loading.texi \
$(srcdir)/locals.texi \
$(srcdir)/macros.texi \
$(srcdir)/maps.texi \
$(srcdir)/markers.texi \
$(srcdir)/minibuf.texi \
$(srcdir)/modes.texi \
$(srcdir)/nonascii.texi \
$(srcdir)/numbers.texi \
$(srcdir)/objects.texi \
$(srcdir)/os.texi \
$(srcdir)/positions.texi \
$(srcdir)/processes.texi \
$(srcdir)/searching.texi \
$(srcdir)/sequences.texi \
$(srcdir)/streams.texi \
$(srcdir)/strings.texi \
$(srcdir)/symbols.texi \
$(srcdir)/syntax.texi \
$(srcdir)/text.texi \
$(srcdir)/tips.texi \
$(srcdir)/variables.texi \
$(srcdir)/windows.texi \
$(srcdir)/index.texi \
$(srcdir)/gpl.texi \
$(srcdir)/doclicense.texi
.PHONY: clean
# The info file is named `elisp'.
info: $(infodir)/elisp
$(infodir)/elisp: $(srcs)
cd $(srcdir); $(MAKEINFO) -I. -I$(infodir) elisp.texi -o $(infodir)/elisp
elisp.dvi: $(srcs)
$(TEXI2DVI) -I $(srcdir) -I $(usermanualdir) $(srcdir)/elisp.texi
# This is for use in a separate distro of the Emacs Lisp manual.
install: elisp
$(srcdir)/mkinstalldirs $(infodir)
cp elisp elisp-[1-9] elisp-[1-9][0-9] $(infodir)
${INSTALL_INFO} --info-dir=${infodir} ${infodir}/elisp
# This is for use in a separate distro of the Emacs Lisp manual.
elisp: $(srcs)
$(MAKEINFO) -I. -I$(srcdir) $(srcdir)/elisp.texi
clean:
rm -f *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
*.vr *.vrs *.pg *.pgs *.ky *.kys
rm -f make.out core
distclean: clean
maintainer-clean: clean
rm -f elisp.dvi elisp.oaux
cd $(infodir); rm -f elisp elisp-[1-9] elisp-[1-9][0-9]
dist: $(infodir)/elisp elisp.dvi
-rm -rf temp
-mkdir temp
-mkdir temp/$(manual)
-ln $(srcdir)/README $(srcdir)/configure.in $(srcdir)/configure \
$(srcdir)/Makefile.in $(srcs) \
$(srcdir)/../man/texinfo.tex \
elisp.dvi elisp.aux elisp.??s \
$(infodir)/elisp $(infodir)/elisp-[1-9] $(infodir)/elisp-[1-9][0-9] \
temp/$(manual)
-(cd temp/$(manual); rm -f mkinstalldirs)
cp $(srcdir)/mkinstalldirs temp/$(manual)
(cd temp/$(manual); rm -f *~)
(cd temp; tar chf - $(manual)) | gzip > $(manual).tar.gz
-rm -rf temp

72
doc/lispref/README Normal file
View file

@ -0,0 +1,72 @@
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
Free Software Foundation, Inc.
See the end of the file for license conditions.
README for Edition 2.9 of the Emacs Lisp Reference Manual.
* This directory contains the texinfo source files for the Reference
Manual, make-permuted-index, and the latest version of texinfo.tex,
which handles forms that cannot be handled by the older versions of
texinfo.tex.
* Report Lisp Manual bugs to bug-lisp-manual@gnu.org. We don't read
these bug reports until it's time for a new edition. To report other
Emacs bugs, use bug-gnu-emacs@gnu.org. To ask questions, use the
newsgroup gnu.emacs.help.
* The Emacs Lisp Reference Manual is quite large. It totals around
1100 pages in smallbook format; the info files total over
2.5 megabytes.
* You can format this manual either for Info or for printing hardcopy
using TeX.
* You can buy nicely printed copies from the Free Software Foundation.
For info, send mail to gnu@gnu.org or phone 617-542-5942. Buying a
manual from the Free Software Foundation helps support our GNU
development work.
** This distribution contains a Makefile that you can use with GNU Make.
Otherwise, here are detailed instructions:
** HARDCOPY: A copy of the version of `texinfo.tex' that formats this
manual is included in this distribution.
The master file for formatting this manual for Tex is called
`elisp.texi'. It contains @include commands to include all the
chapters that make up the manual. In addition, `elisp.texi' has
the title page in a new format designed by Karl Berry, using the
@titlespec command.
To create a DVI file with a sorted index, execute the following
commands in the shell:
% ./configure
% make index.texi
% make elisp.dvi
*** To create a DVI file with a permuted index, you may experiment
with `make-permuted-index'.
** To make an Info file, you need to install Texinfo, then run
`./configure' and `make info'. To install the Info files, run
`make install'.
This file is part of GNU Emacs.
GNU Emacs is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3, or (at your option)
any later version.
GNU Emacs is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Emacs; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.

411
doc/lispref/abbrevs.texi Normal file
View file

@ -0,0 +1,411 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1999, 2001, 2002, 2003,
@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/abbrevs
@node Abbrevs, Processes, Syntax Tables, Top
@chapter Abbrevs and Abbrev Expansion
@cindex abbrev
@c @cindex abbrev table Redundant with "abbrev".
An abbreviation or @dfn{abbrev} is a string of characters that may be
expanded to a longer string. The user can insert the abbrev string and
find it replaced automatically with the expansion of the abbrev. This
saves typing.
The set of abbrevs currently in effect is recorded in an @dfn{abbrev
table}. Each buffer has a local abbrev table, but normally all buffers
in the same major mode share one abbrev table. There is also a global
abbrev table. Normally both are used.
An abbrev table is represented as an obarray containing a symbol for
each abbreviation. The symbol's name is the abbreviation; its value
is the expansion; its function definition is the hook function to do
the expansion (@pxref{Defining Abbrevs}); its property list cell
typically contains the use count, the number of times the abbreviation
has been expanded. Alternatively, the use count is on the
@code{count} property and the system-abbrev flag is on the
@code{system-type} property. Abbrevs with a non-@code{nil}
@code{system-type} property are called ``system'' abbrevs. They are
usually defined by modes or packages, instead of by the user, and are
treated specially in certain respects.
Because the symbols used for abbrevs are not interned in the usual
obarray, they will never appear as the result of reading a Lisp
expression; in fact, normally they are never used except by the code
that handles abbrevs. Therefore, it is safe to use them in an
extremely nonstandard way. @xref{Creating Symbols}.
For the user-level commands for abbrevs, see @ref{Abbrevs,, Abbrev
Mode, emacs, The GNU Emacs Manual}.
@menu
* Abbrev Mode:: Setting up Emacs for abbreviation.
* Tables: Abbrev Tables. Creating and working with abbrev tables.
* Defining Abbrevs:: Specifying abbreviations and their expansions.
* Files: Abbrev Files. Saving abbrevs in files.
* Expansion: Abbrev Expansion. Controlling expansion; expansion subroutines.
* Standard Abbrev Tables:: Abbrev tables used by various major modes.
@end menu
@node Abbrev Mode, Abbrev Tables, Abbrevs, Abbrevs
@comment node-name, next, previous, up
@section Setting Up Abbrev Mode
Abbrev mode is a minor mode controlled by the value of the variable
@code{abbrev-mode}.
@defvar abbrev-mode
A non-@code{nil} value of this variable turns on the automatic expansion
of abbrevs when their abbreviations are inserted into a buffer.
If the value is @code{nil}, abbrevs may be defined, but they are not
expanded automatically.
This variable automatically becomes buffer-local when set in any fashion.
@end defvar
@defvar default-abbrev-mode
This is the value of @code{abbrev-mode} for buffers that do not override it.
This is the same as @code{(default-value 'abbrev-mode)}.
@end defvar
@node Abbrev Tables, Defining Abbrevs, Abbrev Mode, Abbrevs
@section Abbrev Tables
This section describes how to create and manipulate abbrev tables.
@defun make-abbrev-table
This function creates and returns a new, empty abbrev table---an obarray
containing no symbols. It is a vector filled with zeros.
@end defun
@defun clear-abbrev-table table
This function undefines all the abbrevs in abbrev table @var{table},
leaving it empty. It always returns @code{nil}.
@end defun
@defun copy-abbrev-table table
This function returns a copy of abbrev table @var{table}---a new
abbrev table that contains the same abbrev definitions. The only
difference between @var{table} and the returned copy is that this
function sets the property lists of all copied abbrevs to 0.
@end defun
@defun define-abbrev-table tabname definitions
This function defines @var{tabname} (a symbol) as an abbrev table
name, i.e., as a variable whose value is an abbrev table. It defines
abbrevs in the table according to @var{definitions}, a list of
elements of the form @code{(@var{abbrevname} @var{expansion}
@var{hook} @var{usecount} @var{system-flag})}. If an element of
@var{definitions} has length less than five, omitted elements default
to @code{nil}. A value of @code{nil} for @var{usecount} is equivalent
to zero. The return value is always @code{nil}.
If this function is called more than once for the same @var{tabname},
subsequent calls add the definitions in @var{definitions} to
@var{tabname}, rather than overriding the entire original contents.
(A subsequent call only overrides abbrevs explicitly redefined or
undefined in @var{definitions}.)
@end defun
@defvar abbrev-table-name-list
This is a list of symbols whose values are abbrev tables.
@code{define-abbrev-table} adds the new abbrev table name to this list.
@end defvar
@defun insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev table
named @var{name}. The argument @var{name} is a symbol whose value is an
abbrev table. The return value is always @code{nil}.
If @var{human} is non-@code{nil}, the description is human-oriented.
System abbrevs are listed and identified as such. Otherwise the
description is a Lisp expression---a call to @code{define-abbrev-table}
that would define @var{name} as it is currently defined, but without
the system abbrevs. (The mode or package using @var{name} is supposed
to add these to @var{name} separately.)
@end defun
@node Defining Abbrevs, Abbrev Files, Abbrev Tables, Abbrevs
@comment node-name, next, previous, up
@section Defining Abbrevs
@code{define-abbrev} is the low-level basic function for defining an
abbrev in a specified abbrev table. When major modes predefine standard
abbrevs, they should call @code{define-abbrev} and specify @code{t} for
@var{system-flag}. Be aware that any saved non-``system'' abbrevs are
restored at startup, i.e. before some major modes are loaded. Major modes
should therefore not assume that when they are first loaded their abbrev
tables are empty.
@defun define-abbrev table name expansion &optional hook count system-flag
This function defines an abbrev named @var{name}, in @var{table}, to
expand to @var{expansion} and call @var{hook}. The return value is
@var{name}.
The value of @var{count}, if specified, initializes the abbrev's
usage-count. If @var{count} is not specified or @code{nil}, the use
count is initialized to zero.
The argument @var{name} should be a string. The argument
@var{expansion} is normally the desired expansion (a string), or
@code{nil} to undefine the abbrev. If it is anything but a string or
@code{nil}, then the abbreviation ``expands'' solely by running
@var{hook}.
The argument @var{hook} is a function or @code{nil}. If @var{hook} is
non-@code{nil}, then it is called with no arguments after the abbrev is
replaced with @var{expansion}; point is located at the end of
@var{expansion} when @var{hook} is called.
@cindex @code{no-self-insert} property
If @var{hook} is a non-@code{nil} symbol whose @code{no-self-insert}
property is non-@code{nil}, @var{hook} can explicitly control whether
to insert the self-inserting input character that triggered the
expansion. If @var{hook} returns non-@code{nil} in this case, that
inhibits insertion of the character. By contrast, if @var{hook}
returns @code{nil}, @code{expand-abbrev} also returns @code{nil}, as
if expansion had not really occurred.
If @var{system-flag} is non-@code{nil}, that marks the abbrev as a
``system'' abbrev with the @code{system-type} property. Unless
@var{system-flag} has the value @code{force}, a ``system'' abbrev will
not overwrite an existing definition for a non-``system'' abbrev of the
same name.
Normally the function @code{define-abbrev} sets the variable
@code{abbrevs-changed} to @code{t}, if it actually changes the abbrev.
(This is so that some commands will offer to save the abbrevs.) It
does not do this for a ``system'' abbrev, since those won't be saved
anyway.
@end defun
@defopt only-global-abbrevs
If this variable is non-@code{nil}, it means that the user plans to use
global abbrevs only. This tells the commands that define mode-specific
abbrevs to define global ones instead. This variable does not alter the
behavior of the functions in this section; it is examined by their
callers.
@end defopt
@node Abbrev Files, Abbrev Expansion, Defining Abbrevs, Abbrevs
@section Saving Abbrevs in Files
A file of saved abbrev definitions is actually a file of Lisp code.
The abbrevs are saved in the form of a Lisp program to define the same
abbrev tables with the same contents. Therefore, you can load the file
with @code{load} (@pxref{How Programs Do Loading}). However, the
function @code{quietly-read-abbrev-file} is provided as a more
convenient interface.
User-level facilities such as @code{save-some-buffers} can save
abbrevs in a file automatically, under the control of variables
described here.
@defopt abbrev-file-name
This is the default file name for reading and saving abbrevs.
@end defopt
@defun quietly-read-abbrev-file &optional filename
This function reads abbrev definitions from a file named @var{filename},
previously written with @code{write-abbrev-file}. If @var{filename} is
omitted or @code{nil}, the file specified in @code{abbrev-file-name} is
used. @code{save-abbrevs} is set to @code{t} so that changes will be
saved.
This function does not display any messages. It returns @code{nil}.
@end defun
@defopt save-abbrevs
A non-@code{nil} value for @code{save-abbrevs} means that Emacs should
offer the user to save abbrevs when files are saved. If the value is
@code{silently}, Emacs saves the abbrevs without asking the user.
@code{abbrev-file-name} specifies the file to save the abbrevs in.
@end defopt
@defvar abbrevs-changed
This variable is set non-@code{nil} by defining or altering any
abbrevs (except ``system'' abbrevs). This serves as a flag for
various Emacs commands to offer to save your abbrevs.
@end defvar
@deffn Command write-abbrev-file &optional filename
Save all abbrev definitions (except ``system'' abbrevs), for all abbrev
tables listed in @code{abbrev-table-name-list}, in the file
@var{filename}, in the form of a Lisp program that when loaded will
define the same abbrevs. If @var{filename} is @code{nil} or omitted,
@code{abbrev-file-name} is used. This function returns @code{nil}.
@end deffn
@node Abbrev Expansion, Standard Abbrev Tables, Abbrev Files, Abbrevs
@comment node-name, next, previous, up
@section Looking Up and Expanding Abbreviations
Abbrevs are usually expanded by certain interactive commands,
including @code{self-insert-command}. This section describes the
subroutines used in writing such commands, as well as the variables they
use for communication.
@defun abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named
@var{abbrev}. The value returned is @code{nil} if that abbrev is not
defined. The optional second argument @var{table} is the abbrev table
to look it up in. If @var{table} is @code{nil}, this function tries
first the current buffer's local abbrev table, and second the global
abbrev table.
@end defun
@defun abbrev-expansion abbrev &optional table
This function returns the string that @var{abbrev} would expand into (as
defined by the abbrev tables used for the current buffer). If
@var{abbrev} is not a valid abbrev, the function returns @code{nil}.
The optional argument @var{table} specifies the abbrev table to use,
as in @code{abbrev-symbol}.
@end defun
@deffn Command expand-abbrev
This command expands the abbrev before point, if any. If point does not
follow an abbrev, this command does nothing. The command returns the
abbrev symbol if it did expansion, @code{nil} otherwise.
If the abbrev symbol has a hook function which is a symbol whose
@code{no-self-insert} property is non-@code{nil}, and if the hook
function returns @code{nil} as its value, then @code{expand-abbrev}
returns @code{nil} even though expansion did occur.
@end deffn
@deffn Command abbrev-prefix-mark &optional arg
This command marks the current location of point as the beginning of
an abbrev. The next call to @code{expand-abbrev} will use the text
from here to point (where it is then) as the abbrev to expand, rather
than using the previous word as usual.
First, this command expands any abbrev before point, unless @var{arg}
is non-@code{nil}. (Interactively, @var{arg} is the prefix argument.)
Then it inserts a hyphen before point, to indicate the start of the
next abbrev to be expanded. The actual expansion removes the hyphen.
@end deffn
@defopt abbrev-all-caps
When this is set non-@code{nil}, an abbrev entered entirely in upper
case is expanded using all upper case. Otherwise, an abbrev entered
entirely in upper case is expanded by capitalizing each word of the
expansion.
@end defopt
@defvar abbrev-start-location
The value of this variable is a buffer position (an integer or a marker)
for @code{expand-abbrev} to use as the start of the next abbrev to be
expanded. The value can also be @code{nil}, which means to use the
word before point instead. @code{abbrev-start-location} is set to
@code{nil} each time @code{expand-abbrev} is called. This variable is
also set by @code{abbrev-prefix-mark}.
@end defvar
@defvar abbrev-start-location-buffer
The value of this variable is the buffer for which
@code{abbrev-start-location} has been set. Trying to expand an abbrev
in any other buffer clears @code{abbrev-start-location}. This variable
is set by @code{abbrev-prefix-mark}.
@end defvar
@defvar last-abbrev
This is the @code{abbrev-symbol} of the most recent abbrev expanded. This
information is left by @code{expand-abbrev} for the sake of the
@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
Abbrevs, emacs, The GNU Emacs Manual}).
@end defvar
@defvar last-abbrev-location
This is the location of the most recent abbrev expanded. This contains
information left by @code{expand-abbrev} for the sake of the
@code{unexpand-abbrev} command.
@end defvar
@defvar last-abbrev-text
This is the exact expansion text of the most recent abbrev expanded,
after case conversion (if any). Its value is @code{nil} if the abbrev
has already been unexpanded. This contains information left by
@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
@end defvar
@c Emacs 19 feature
@defvar pre-abbrev-expand-hook
This is a normal hook whose functions are executed, in sequence, just
before any expansion of an abbrev. @xref{Hooks}. Since it is a normal
hook, the hook functions receive no arguments. However, they can find
the abbrev to be expanded by looking in the buffer before point.
Running the hook is the first thing that @code{expand-abbrev} does, and
so a hook function can be used to change the current abbrev table before
abbrev lookup happens. (Although you have to do this carefully. See
the example below.)
@end defvar
The following sample code shows a simple use of
@code{pre-abbrev-expand-hook}. It assumes that @code{foo-mode} is a
mode for editing certain files in which lines that start with @samp{#}
are comments. You want to use Text mode abbrevs for those lines. The
regular local abbrev table, @code{foo-mode-abbrev-table} is
appropriate for all other lines. Then you can put the following code
in your @file{.emacs} file. @xref{Standard Abbrev Tables}, for the
definitions of @code{local-abbrev-table} and @code{text-mode-abbrev-table}.
@smallexample
(defun foo-mode-pre-abbrev-expand ()
(when (save-excursion (forward-line 0) (eq (char-after) ?#))
(let ((local-abbrev-table text-mode-abbrev-table)
;; Avoid infinite loop.
(pre-abbrev-expand-hook nil))
(expand-abbrev))
;; We have already called `expand-abbrev' in this hook.
;; Hence we want the "actual" call following this hook to be a no-op.
(setq abbrev-start-location (point-max)
abbrev-start-location-buffer (current-buffer))))
(add-hook 'foo-mode-hook
#'(lambda ()
(add-hook 'pre-abbrev-expand-hook
'foo-mode-pre-abbrev-expand
nil t)))
@end smallexample
Note that @code{foo-mode-pre-abbrev-expand} just returns @code{nil}
without doing anything for lines not starting with @samp{#}. Hence
abbrevs expand normally using @code{foo-mode-abbrev-table} as local
abbrev table for such lines.
@node Standard Abbrev Tables, , Abbrev Expansion, Abbrevs
@comment node-name, next, previous, up
@section Standard Abbrev Tables
Here we list the variables that hold the abbrev tables for the
preloaded major modes of Emacs.
@defvar global-abbrev-table
This is the abbrev table for mode-independent abbrevs. The abbrevs
defined in it apply to all buffers. Each buffer may also have a local
abbrev table, whose abbrev definitions take precedence over those in the
global table.
@end defvar
@defvar local-abbrev-table
The value of this buffer-local variable is the (mode-specific)
abbreviation table of the current buffer.
@end defvar
@defvar fundamental-mode-abbrev-table
This is the local abbrev table used in Fundamental mode; in other words,
it is the local abbrev table in all buffers in Fundamental mode.
@end defvar
@defvar text-mode-abbrev-table
This is the local abbrev table used in Text mode.
@end defvar
@defvar lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
@end defvar
@ignore
arch-tag: 5ffdbe08-2cd4-48ec-a5a8-080f95756eec
@end ignore

773
doc/lispref/advice.texi Normal file
View file

@ -0,0 +1,773 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1998, 1999, 2001, 2002, 2003, 2004,
@c 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/advising
@node Advising Functions, Debugging, Byte Compilation, Top
@chapter Advising Emacs Lisp Functions
@cindex advising functions
The @dfn{advice} feature lets you add to the existing definition of
a function, by @dfn{advising the function}. This is a cleaner method
for a library to customize functions defined within Emacs---cleaner
than redefining the whole function.
@cindex piece of advice
Each function can have multiple @dfn{pieces of advice}, separately
defined. Each defined piece of advice can be @dfn{enabled} or
@dfn{disabled} explicitly. All the enabled pieces of advice for any given
function actually take effect when you @dfn{activate} advice for that
function, or when you define or redefine the function. Note that
enabling a piece of advice and activating advice for a function
are not the same thing.
@strong{Usage Note:} Advice is useful for altering the behavior of
existing calls to an existing function. If you want the new behavior
for new calls, or for key bindings, you should define a new function
(or a new command) which uses the existing function.
@strong{Usage note:} Advising a function can cause confusion in
debugging, since people who debug calls to the original function may
not notice that it has been modified with advice. Therefore, if you
have the possibility to change the code of that function (or ask
someone to do so) to run a hook, please solve the problem that way.
Advice should be reserved for the cases where you cannot get the
function changed.
In particular, this means that a file in Emacs should not put advice
on a function in Emacs. There are currently a few exceptions to this
convention, but we aim to correct them.
@menu
* Simple Advice:: A simple example to explain the basics of advice.
* Defining Advice:: Detailed description of @code{defadvice}.
* Around-Advice:: Wrapping advice around a function's definition.
* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
* Activation of Advice:: Advice doesn't do anything until you activate it.
* Enabling Advice:: You can enable or disable each piece of advice.
* Preactivation:: Preactivation is a way of speeding up the
loading of compiled advice.
* Argument Access in Advice:: How advice can access the function's arguments.
* Advising Primitives:: Accessing arguments when advising a primitive.
* Combined Definition:: How advice is implemented.
@end menu
@node Simple Advice
@section A Simple Advice Example
The command @code{next-line} moves point down vertically one or more
lines; it is the standard binding of @kbd{C-n}. When used on the last
line of the buffer, this command inserts a newline to create a line to
move to if @code{next-line-add-newlines} is non-@code{nil} (its default
is @code{nil}.)
Suppose you wanted to add a similar feature to @code{previous-line},
which would insert a new line at the beginning of the buffer for the
command to move to (when @code{next-line-add-newlines} is
non-@code{nil}). How could you do this?
You could do it by redefining the whole function, but that is not
modular. The advice feature provides a cleaner alternative: you can
effectively add your code to the existing function definition, without
actually changing or even seeing that definition. Here is how to do
this:
@example
(defadvice previous-line (before next-line-at-end
(&optional arg try-vscroll))
"Insert an empty line when moving up from the top line."
(if (and next-line-add-newlines (= arg 1)
(save-excursion (beginning-of-line) (bobp)))
(progn
(beginning-of-line)
(newline))))
@end example
This expression defines a @dfn{piece of advice} for the function
@code{previous-line}. This piece of advice is named
@code{next-line-at-end}, and the symbol @code{before} says that it is
@dfn{before-advice} which should run before the regular definition of
@code{previous-line}. @code{(&optional arg try-vscroll)} specifies
how the advice code can refer to the function's arguments.
When this piece of advice runs, it creates an additional line, in the
situation where that is appropriate, but does not move point to that
line. This is the correct way to write the advice, because the normal
definition will run afterward and will move back to the newly inserted
line.
Defining the advice doesn't immediately change the function
@code{previous-line}. That happens when you @dfn{activate} the advice,
like this:
@example
(ad-activate 'previous-line)
@end example
@noindent
This is what actually begins to use the advice that has been defined so
far for the function @code{previous-line}. Henceforth, whenever that
function is run, whether invoked by the user with @kbd{C-p} or
@kbd{M-x}, or called from Lisp, it runs the advice first, and its
regular definition second.
This example illustrates before-advice, which is one @dfn{class} of
advice: it runs before the function's base definition. There are two
other advice classes: @dfn{after-advice}, which runs after the base
definition, and @dfn{around-advice}, which lets you specify an
expression to wrap around the invocation of the base definition.
@node Defining Advice
@section Defining Advice
@cindex defining advice
@cindex advice, defining
To define a piece of advice, use the macro @code{defadvice}. A call
to @code{defadvice} has the following syntax, which is based on the
syntax of @code{defun} and @code{defmacro}, but adds more:
@findex defadvice
@example
(defadvice @var{function} (@var{class} @var{name}
@r{[}@var{position}@r{]} @r{[}@var{arglist}@r{]}
@var{flags}...)
@r{[}@var{documentation-string}@r{]}
@r{[}@var{interactive-form}@r{]}
@var{body-forms}...)
@end example
@noindent
Here, @var{function} is the name of the function (or macro or special
form) to be advised. From now on, we will write just ``function'' when
describing the entity being advised, but this always includes macros and
special forms.
In place of the argument list in an ordinary definition, an advice
definition calls for several different pieces of information.
@cindex class of advice
@cindex before-advice
@cindex after-advice
@cindex around-advice
@var{class} specifies the @dfn{class} of the advice---one of @code{before},
@code{after}, or @code{around}. Before-advice runs before the function
itself; after-advice runs after the function itself; around-advice is
wrapped around the execution of the function itself. After-advice and
around-advice can override the return value by setting
@code{ad-return-value}.
@defvar ad-return-value
While advice is executing, after the function's original definition has
been executed, this variable holds its return value, which will
ultimately be returned to the caller after finishing all the advice.
After-advice and around-advice can arrange to return some other value
by storing it in this variable.
@end defvar
The argument @var{name} is the name of the advice, a non-@code{nil}
symbol. The advice name uniquely identifies one piece of advice, within all
the pieces of advice in a particular class for a particular
@var{function}. The name allows you to refer to the piece of
advice---to redefine it, or to enable or disable it.
The optional @var{position} specifies where, in the current list of
advice of the specified @var{class}, this new advice should be placed.
It should be either @code{first}, @code{last} or a number that specifies
a zero-based position (@code{first} is equivalent to 0). If no position
is specified, the default is @code{first}. Position values outside the
range of existing positions in this class are mapped to the beginning or
the end of the range, whichever is closer. The @var{position} value is
ignored when redefining an existing piece of advice.
The optional @var{arglist} can be used to define the argument list for
the sake of advice. This becomes the argument list of the combined
definition that is generated in order to run the advice (@pxref{Combined
Definition}). Therefore, the advice expressions can use the argument
variables in this list to access argument values.
The argument list used in advice need not be the same as the argument
list used in the original function, but must be compatible with it, so
that it can handle the ways the function is actually called. If two
pieces of advice for a function both specify an argument list, they must
specify the same argument list.
@xref{Argument Access in Advice}, for more information about argument
lists and advice, and a more flexible way for advice to access the
arguments.
The remaining elements, @var{flags}, are symbols that specify further
information about how to use this piece of advice. Here are the valid
symbols and their meanings:
@table @code
@item activate
Activate the advice for @var{function} now. Changes in a function's
advice always take effect the next time you activate advice for the
function; this flag says to do so, for @var{function}, immediately after
defining this piece of advice.
@cindex forward advice
This flag has no immediate effect if @var{function} itself is not defined yet (a
situation known as @dfn{forward advice}), because it is impossible to
activate an undefined function's advice. However, defining
@var{function} will automatically activate its advice.
@item protect
Protect this piece of advice against non-local exits and errors in
preceding code and advice. Protecting advice places it as a cleanup in
an @code{unwind-protect} form, so that it will execute even if the
previous code gets an error or uses @code{throw}. @xref{Cleanups}.
@item compile
Compile the combined definition that is used to run the advice. This
flag is ignored unless @code{activate} is also specified.
@xref{Combined Definition}.
@item disable
Initially disable this piece of advice, so that it will not be used
unless subsequently explicitly enabled. @xref{Enabling Advice}.
@item preactivate
Activate advice for @var{function} when this @code{defadvice} is
compiled or macroexpanded. This generates a compiled advised definition
according to the current advice state, which will be used during
activation if appropriate. @xref{Preactivation}.
This is useful only if this @code{defadvice} is byte-compiled.
@end table
The optional @var{documentation-string} serves to document this piece of
advice. When advice is active for @var{function}, the documentation for
@var{function} (as returned by @code{documentation}) combines the
documentation strings of all the advice for @var{function} with the
documentation string of its original function definition.
The optional @var{interactive-form} form can be supplied to change the
interactive behavior of the original function. If more than one piece
of advice has an @var{interactive-form}, then the first one (the one
with the smallest position) found among all the advice takes precedence.
The possibly empty list of @var{body-forms} specifies the body of the
advice. The body of an advice can access or change the arguments, the
return value, the binding environment, and perform any other kind of
side effect.
@strong{Warning:} When you advise a macro, keep in mind that macros are
expanded when a program is compiled, not when a compiled program is run.
All subroutines used by the advice need to be available when the byte
compiler expands the macro.
@deffn Command ad-unadvise function
This command deletes the advice from @var{function}.
@end deffn
@deffn Command ad-unadvise-all
This command deletes all pieces of advice from all functions.
@end deffn
@node Around-Advice
@section Around-Advice
Around-advice lets you ``wrap'' a Lisp expression ``around'' the
original function definition. You specify where the original function
definition should go by means of the special symbol @code{ad-do-it}.
Where this symbol occurs inside the around-advice body, it is replaced
with a @code{progn} containing the forms of the surrounded code. Here
is an example:
@example
(defadvice foo (around foo-around)
"Ignore case in `foo'."
(let ((case-fold-search t))
ad-do-it))
@end example
@noindent
Its effect is to make sure that case is ignored in
searches when the original definition of @code{foo} is run.
@defvar ad-do-it
This is not really a variable, rather a place-holder that looks like a
variable. You use it in around-advice to specify the place to run the
function's original definition and other ``earlier'' around-advice.
@end defvar
If the around-advice does not use @code{ad-do-it}, then it does not run
the original function definition. This provides a way to override the
original definition completely. (It also overrides lower-positioned
pieces of around-advice).
If the around-advice uses @code{ad-do-it} more than once, the original
definition is run at each place. In this way, around-advice can execute
the original definition (and lower-positioned pieces of around-advice)
several times. Another way to do that is by using @code{ad-do-it}
inside of a loop.
@node Computed Advice
@section Computed Advice
The macro @code{defadvice} resembles @code{defun} in that the code for
the advice, and all other information about it, are explicitly stated in
the source code. You can also create advice whose details are computed,
using the function @code{ad-add-advice}.
@defun ad-add-advice function advice class position
Calling @code{ad-add-advice} adds @var{advice} as a piece of advice to
@var{function} in class @var{class}. The argument @var{advice} has
this form:
@example
(@var{name} @var{protected} @var{enabled} @var{definition})
@end example
Here @var{protected} and @var{enabled} are flags, and @var{definition}
is the expression that says what the advice should do. If @var{enabled}
is @code{nil}, this piece of advice is initially disabled
(@pxref{Enabling Advice}).
If @var{function} already has one or more pieces of advice in the
specified @var{class}, then @var{position} specifies where in the list
to put the new piece of advice. The value of @var{position} can either
be @code{first}, @code{last}, or a number (counting from 0 at the
beginning of the list). Numbers outside the range are mapped to the
beginning or the end of the range, whichever is closer. The
@var{position} value is ignored when redefining an existing piece of
advice.
If @var{function} already has a piece of @var{advice} with the same
name, then the position argument is ignored and the old advice is
replaced with the new one.
@end defun
@node Activation of Advice
@section Activation of Advice
@cindex activating advice
@cindex advice, activating
By default, advice does not take effect when you define it---only when
you @dfn{activate} advice for the function that was advised. However,
the advice will be activated automatically if you define or redefine
the function later. You can request the activation of advice for a
function when you define the advice, by specifying the @code{activate}
flag in the @code{defadvice}. But normally you activate the advice
for a function by calling the function @code{ad-activate} or one of
the other activation commands listed below.
Separating the activation of advice from the act of defining it permits
you to add several pieces of advice to one function efficiently, without
redefining the function over and over as each advice is added. More
importantly, it permits defining advice for a function before that
function is actually defined.
When a function's advice is first activated, the function's original
definition is saved, and all enabled pieces of advice for that function
are combined with the original definition to make a new definition.
(Pieces of advice that are currently disabled are not used; see
@ref{Enabling Advice}.) This definition is installed, and optionally
byte-compiled as well, depending on conditions described below.
In all of the commands to activate advice, if @var{compile} is
@code{t} (or anything but @code{nil} or a negative number), the
command also compiles the combined definition which implements the
advice. If it is @code{nil} or a negative number, what happens
depends on @code{ad-default-compilation-action} as described below.
@deffn Command ad-activate function &optional compile
This command activates all the advice defined for @var{function}.
@end deffn
Activating advice does nothing if @var{function}'s advice is already
active. But if there is new advice, added since the previous time you
activated advice for @var{function}, it activates the new advice.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
@cindex deactivating advice
@c @cindex advice, deactivating "advice, activating" is just above
@end deffn
@deffn Command ad-update function &optional compile
This command activates the advice for @var{function}
if its advice is already activated. This is useful
if you change the advice.
@end deffn
@deffn Command ad-activate-all &optional compile
This command activates the advice for all functions.
@end deffn
@deffn Command ad-deactivate-all
This command deactivates the advice for all functions.
@end deffn
@deffn Command ad-update-all &optional compile
This command activates the advice for all functions
whose advice is already activated. This is useful
if you change the advice of some functions.
@end deffn
@deffn Command ad-activate-regexp regexp &optional compile
This command activates all pieces of advice whose names match
@var{regexp}. More precisely, it activates all advice for any function
which has at least one piece of advice that matches @var{regexp}.
@end deffn
@deffn Command ad-deactivate-regexp regexp
This command deactivates all pieces of advice whose names match
@var{regexp}. More precisely, it deactivates all advice for any
function which has at least one piece of advice that matches
@var{regexp}.
@end deffn
@deffn Command ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match @var{regexp},
but only those for functions whose advice is already activated.
@cindex reactivating advice
Reactivating a function's advice is useful for putting into effect all
the changes that have been made in its advice (including enabling and
disabling specific pieces of advice; @pxref{Enabling Advice}) since the
last time it was activated.
@end deffn
@deffn Command ad-start-advice
Turn on automatic advice activation when a function is defined or
redefined. This is the default mode.
@end deffn
@deffn Command ad-stop-advice
Turn off automatic advice activation when a function is defined or
redefined.
@end deffn
@defopt ad-default-compilation-action
This variable controls whether to compile the combined definition
that results from activating advice for a function.
A value of @code{always} specifies to compile unconditionally.
A value of @code{never} specifies never compile the advice.
A value of @code{maybe} specifies to compile if the byte-compiler is
already loaded. A value of @code{like-original} specifies to compile
the advice if the original definition of the advised function is
compiled or a built-in function.
This variable takes effect only if the @var{compile} argument of
@code{ad-activate} (or any of the above functions) did not force
compilation.
@end defopt
If the advised definition was constructed during ``preactivation''
(@pxref{Preactivation}), then that definition must already be compiled,
because it was constructed during byte-compilation of the file that
contained the @code{defadvice} with the @code{preactivate} flag.
@node Enabling Advice
@section Enabling and Disabling Advice
@cindex enabling advice
@cindex advice, enabling and disabling
@cindex disabling advice
Each piece of advice has a flag that says whether it is enabled or
not. By enabling or disabling a piece of advice, you can turn it on
and off without having to undefine and redefine it. For example, here is
how to disable a particular piece of advice named @code{my-advice} for
the function @code{foo}:
@example
(ad-disable-advice 'foo 'before 'my-advice)
@end example
This function by itself only changes the enable flag for a piece of
advice. To make the change take effect in the advised definition, you
must activate the advice for @code{foo} again:
@example
(ad-activate 'foo)
@end example
@deffn Command ad-disable-advice function class name
This command disables the piece of advice named @var{name} in class
@var{class} on @var{function}.
@end deffn
@deffn Command ad-enable-advice function class name
This command enables the piece of advice named @var{name} in class
@var{class} on @var{function}.
@end deffn
You can also disable many pieces of advice at once, for various
functions, using a regular expression. As always, the changes take real
effect only when you next reactivate advice for the functions in
question.
@deffn Command ad-disable-regexp regexp
This command disables all pieces of advice whose names match
@var{regexp}, in all classes, on all functions.
@end deffn
@deffn Command ad-enable-regexp regexp
This command enables all pieces of advice whose names match
@var{regexp}, in all classes, on all functions.
@end deffn
@node Preactivation
@section Preactivation
@cindex preactivating advice
@cindex advice, preactivating
Constructing a combined definition to execute advice is moderately
expensive. When a library advises many functions, this can make loading
the library slow. In that case, you can use @dfn{preactivation} to
construct suitable combined definitions in advance.
To use preactivation, specify the @code{preactivate} flag when you
define the advice with @code{defadvice}. This @code{defadvice} call
creates a combined definition which embodies this piece of advice
(whether enabled or not) plus any other currently enabled advice for the
same function, and the function's own definition. If the
@code{defadvice} is compiled, that compiles the combined definition
also.
When the function's advice is subsequently activated, if the enabled
advice for the function matches what was used to make this combined
definition, then the existing combined definition is used, thus avoiding
the need to construct one. Thus, preactivation never causes wrong
results---but it may fail to do any good, if the enabled advice at the
time of activation doesn't match what was used for preactivation.
Here are some symptoms that can indicate that a preactivation did not
work properly, because of a mismatch.
@itemize @bullet
@item
Activation of the advised
function takes longer than usual.
@item
The byte-compiler gets
loaded while an advised function gets activated.
@item
@code{byte-compile} is included in the value of @code{features} even
though you did not ever explicitly use the byte-compiler.
@end itemize
Compiled preactivated advice works properly even if the function itself
is not defined until later; however, the function needs to be defined
when you @emph{compile} the preactivated advice.
There is no elegant way to find out why preactivated advice is not being
used. What you can do is to trace the function
@code{ad-cache-id-verification-code} (with the function
@code{trace-function-background}) before the advised function's advice
is activated. After activation, check the value returned by
@code{ad-cache-id-verification-code} for that function: @code{verified}
means that the preactivated advice was used, while other values give
some information about why they were considered inappropriate.
@strong{Warning:} There is one known case that can make preactivation
fail, in that a preconstructed combined definition is used even though
it fails to match the current state of advice. This can happen when two
packages define different pieces of advice with the same name, in the
same class, for the same function. But you should avoid that anyway.
@node Argument Access in Advice
@section Argument Access in Advice
The simplest way to access the arguments of an advised function in the
body of a piece of advice is to use the same names that the function
definition uses. To do this, you need to know the names of the argument
variables of the original function.
While this simple method is sufficient in many cases, it has a
disadvantage: it is not robust, because it hard-codes the argument names
into the advice. If the definition of the original function changes,
the advice might break.
Another method is to specify an argument list in the advice itself.
This avoids the need to know the original function definition's argument
names, but it has a limitation: all the advice on any particular
function must use the same argument list, because the argument list
actually used for all the advice comes from the first piece of advice
for that function.
A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the
advised definition. Access macros access actual arguments by position
regardless of how these actual arguments get distributed onto the
argument variables of a function. This is robust because in Emacs Lisp
the meaning of an argument is strictly determined by its position in the
argument list.
@defmac ad-get-arg position
This returns the actual argument that was supplied at @var{position}.
@end defmac
@defmac ad-get-args position
This returns the list of actual arguments supplied starting at
@var{position}.
@end defmac
@defmac ad-set-arg position value
This sets the value of the actual argument at @var{position} to
@var{value}
@end defmac
@defmac ad-set-args position value-list
This sets the list of actual arguments starting at @var{position} to
@var{value-list}.
@end defmac
Now an example. Suppose the function @code{foo} is defined as
@example
(defun foo (x y &optional z &rest r) ...)
@end example
@noindent
and is then called with
@example
(foo 0 1 2 3 4 5 6)
@end example
@noindent
which means that @var{x} is 0, @var{y} is 1, @var{z} is 2 and @var{r} is
@code{(3 4 5 6)} within the body of @code{foo}. Here is what
@code{ad-get-arg} and @code{ad-get-args} return in this case:
@example
(ad-get-arg 0) @result{} 0
(ad-get-arg 1) @result{} 1
(ad-get-arg 2) @result{} 2
(ad-get-arg 3) @result{} 3
(ad-get-args 2) @result{} (2 3 4 5 6)
(ad-get-args 4) @result{} (4 5 6)
@end example
Setting arguments also makes sense in this example:
@example
(ad-set-arg 5 "five")
@end example
@noindent
has the effect of changing the sixth argument to @code{"five"}. If this
happens in advice executed before the body of @code{foo} is run, then
@var{r} will be @code{(3 4 "five" 6)} within that body.
Here is an example of setting a tail of the argument list:
@example
(ad-set-args 0 '(5 4 3 2 1 0))
@end example
@noindent
If this happens in advice executed before the body of @code{foo} is run,
then within that body, @var{x} will be 5, @var{y} will be 4, @var{z}
will be 3, and @var{r} will be @code{(2 1 0)} inside the body of
@code{foo}.
These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism.
@node Advising Primitives
@section Advising Primitives
@cindex advising primitives
Advising a primitive function (also called a ``subr'') is risky.
Some primitive functions are used by the advice mechanism; advising
them could cause an infinite recursion. Also, many primitive
functions are called directly from C code. Calls to the primitive
from Lisp code will take note of the advice, but calls from C code
will ignore the advice.
When the advice facility constructs the combined definition, it needs
to know the argument list of the original function. This is not
always possible for primitive functions. When advice cannot determine
the argument list, it uses @code{(&rest ad-subr-args)}, which always
works but is inefficient because it constructs a list of the argument
values. You can use @code{ad-define-subr-args} to declare the proper
argument names for a primitive function:
@defun ad-define-subr-args function arglist
This function specifies that @var{arglist} should be used as the
argument list for function @var{function}.
@end defun
For example,
@example
(ad-define-subr-args 'fset '(sym newdef))
@end example
@noindent
specifies the argument list for the function @code{fset}.
@node Combined Definition
@section The Combined Definition
Suppose that a function has @var{n} pieces of before-advice
(numbered from 0 through @var{n}@minus{}1), @var{m} pieces of
around-advice and @var{k} pieces of after-advice. Assuming no piece
of advice is protected, the combined definition produced to implement
the advice for a function looks like this:
@example
(lambda @var{arglist}
@r{[} @r{[}@var{advised-docstring}@r{]} @r{[}(interactive ...)@r{]} @r{]}
(let (ad-return-value)
@r{before-0-body-form}...
....
@r{before-@var{n}@minus{}1-body-form}...
@r{around-0-body-form}...
@r{around-1-body-form}...
....
@r{around-@var{m}@minus{}1-body-form}...
(setq ad-return-value
@r{apply original definition to @var{arglist}})
@r{end-of-around-@var{m}@minus{}1-body-form}...
....
@r{end-of-around-1-body-form}...
@r{end-of-around-0-body-form}...
@r{after-0-body-form}...
....
@r{after-@var{k}@minus{}1-body-form}...
ad-return-value))
@end example
Macros are redefined as macros, which means adding @code{macro} to
the beginning of the combined definition.
The interactive form is present if the original function or some piece
of advice specifies one. When an interactive primitive function is
advised, advice uses a special method: it calls the primitive with
@code{call-interactively} so that it will read its own arguments.
In this case, the advice cannot access the arguments.
The body forms of the various advice in each class are assembled
according to their specified order. The forms of around-advice @var{l}
are included in one of the forms of around-advice @var{l} @minus{} 1.
The innermost part of the around advice onion is
@display
apply original definition to @var{arglist}
@end display
@noindent
whose form depends on the type of the original function. The variable
@code{ad-return-value} is set to whatever this returns. The variable is
visible to all pieces of advice, which can access and modify it before
it is actually returned from the advised function.
The semantic structure of advised functions that contain protected
pieces of advice is the same. The only difference is that
@code{unwind-protect} forms ensure that the protected advice gets
executed even if some previous piece of advice had an error or a
non-local exit. If any around-advice is protected, then the whole
around-advice onion is protected as a result.
@ignore
arch-tag: 80c135c2-f1c3-4f8d-aa85-f8d8770d307f
@end ignore

453
doc/lispref/anti.texi Normal file
View file

@ -0,0 +1,453 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1999, 2002, 2003, 2004, 2005,
@c 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c This node must have no pointers.
@node Antinews, GNU Free Documentation License, System Interface, Top
@appendix Emacs 21 Antinews
For those users who live backwards in time, here is information about
downgrading to Emacs version 21.4. We hope you will enjoy the greater
simplicity that results from the absence of many Emacs @value{EMACSVER}
features.
@section Old Lisp Features in Emacs 21
@itemize @bullet
@item
Many unnecessary features of redisplay have been eliminated. (The
earlier major release, Emacs 20, will have a completely rewritten
redisplay engine, which will be even simpler.)
@itemize @minus
@item
The function @code{redisplay} has been removed. To update the display
without delay, call @code{(sit-for 0)}. Since it is generally
considered wasteful to update the display if there are any pending
input events, no replacement for @code{(redisplay t)} is provided.
@item
The function @code{force-window-update} has been removed. It
shouldn't be needed, since changes in window contents are detected
automatically. In case they aren't, call @code{redraw-display} to
redraw everything.
@item
Point no longer moves out from underneath invisible text at the end of
each command. This allows the user to detect invisible text by moving
the cursor around---if the cursor gets stuck, there is something
invisible in the way. If you really want cursor motion to ignore the
text, try marking it as intangible.
@item
Support for image maps and image slices has been removed. Emacs was
always meant for editing text, anyway.
@item
The mode line now accepts all text properties, as well as
@code{:propertize} and @code{:eval} forms, regardless of the
@code{risky-local-variable} property.
@item
The @code{line-height} and @code{line-spacing} properties no longer
have any meaning for newline characters. Such properties wouldn't
make sense, since newlines are not really characters; they just tell
you where to break a line.
@item
Considerable simplifications have been made to the display
specification @code{(space . @var{props})}, which is used for
displaying a space of specified width and height. Pixel-based
specifications and Lisp expressions are no longer accepted.
@item
Many features associated with the fringe areas have been removed, to
encourage people to concentrate on the main editing area (the fringe
will be completely removed in Emacs 20.) Arbitrary bitmaps can no
longer be displayed in the fringe; an overlay arrow can still be
displayed, but there can only be one overlay arrow at a time (any more
would be confusing.) The fringe widths cannot be adjusted, and
individual windows cannot have their own fringe settings. A mouse
click on the fringe no longer generates a special event.
@item
Individual windows cannot have their own scroll-bar settings.
@item
You can no longer use @samp{default} in a @code{defface} to specify
defaults for subsequent faces.
@item
The function @code{display-supports-face-attributes-p} has been
removed. In @code{defface} specifications, the @code{supports}
predicate is no longer supported.
@item
The functions @code{merge-face-attribute} and
@code{face-attribute-relative-p} have been removed.
@item
The priority of faces in a list supplied by the @code{:inherit} face
attribute has been reversed. We like to make changes like this once
in a while, to keep Emacs Lisp programmers on their toes.
@item
The @code{min-colors} face attribute, used for tailoring faces to
limited-color displays, does not exist. If in doubt, use colors like
``white'' and ``black,'' which ought to be defined everywhere.
@item
The @code{tty-color-mode} frame parameter does not exist. You should
just trust the terminal capabilities database.
@end itemize
@item
Several simplifications have been made to mouse support:
@itemize @minus
@item
Clicking @kbd{mouse-1} won't follow links, as that is alien to the
spirit of Emacs. Therefore, the @code{follow-link} property doesn't
have any special meaning, and the function @code{mouse-on-link-p} has
been removed.
@item
The variable @code{void-text-area-pointer} has been removed, so the
mouse pointer shape remains unchanged when moving between valid text
areas and void text areas. The @code{pointer} image and text
properties are no longer supported.
@item
Mouse events will no longer specify the timestamp, the object clicked,
equivalent buffer positions (for marginal or fringe areas), glyph
coordinates, or relative pixel coordinates.
@end itemize
@item
Simplifications have also been made to the way Emacs handles keymaps
and key sequences:
@itemize @minus
@item
The @code{kbd} macro is now obsolete and is no longer documented.
It isn't that difficult to write key sequences using the string and
vector representations, and we want to encourage users to learn.
@item
Emacs no longer supports key remapping. You can do pretty much the
same thing with @code{substitute-key-definition}, or by advising the
relevant command.
@item
The @code{keymap} text and overlay property is now overridden by minor
mode keymaps, and will not work at the ends of text properties and
overlays.
@item
The functions @code{map-keymap}, @code{keymap-prompt}, and
@code{current-active-maps} have been removed.
@end itemize
@item
Process support has been pared down to a functional minimum. The
functions @code{call-process-shell-command} and @code{process-file}
have been deleted. Processes no longer maintain property lists, and
they won't ask any questions when the user tries to exit Emacs (which
would simply be rude.) The function @code{signal-process} won't
accept a process object, only the process id; determining the process
id from a process object is left as an exercise to the programmer.
@item
Networking has also been simplified: @code{make-network-process} and
its various associated function have all been replaced with a single
easy-to-use function, @code{open-network-stream}, which can't use UDP,
can't act as a server, and can't set up non-blocking connections.
Also, deleting a network process with @code{delete-process} won't call
the sentinel.
@item
Many programming shortcuts have been deleted, to provide you with the
enjoyment of ``rolling your own.'' The macros @code{while-no-input},
@code{with-local-quit}, and @code{with-selected-window}, along with
@code{dynamic-completion-table} and @code{lazy-completion-table} no
longer exist. Also, there are no built-in progress reporters;
with Emacs, you can take progress for granted.
@item
Variable aliases are no longer supported. Aliases are for functions,
not for variables.
@item
The variables @code{most-positive-fixnum} and
@code{most-negative-fixnum} do not exist. On 32 bit machines, the
most positive integer is probably 134217727, and the most negative
integer is probably -134217728.
@item
The functions @code{eql} and @code{macroexpand-all} are no longer
available. However, you can find similar functions in the @code{cl}
package.
@item
The list returned by @code{split-string} won't include null substrings
for separators at the beginning or end of a string. If you want to
check for such separators, do it separately.
@item
The function @code{assoc-string} has been removed. Use
@code{assoc-ignore-case} or @code{assoc-ignore-representation} (which
are no longer obsolete.)
@item
The escape sequence @samp{\s} is always interpreted as a super
modifier, never a space.
@item
The variable @code{buffer-save-without-query} has been removed, to
prevent Emacs from sneakily saving buffers. Also, the hook
@code{before-save-hook} has been removed, so if you want something to
be done before saving, advise or redefine @code{basic-save-buffer}.
@item
The variable @code{buffer-auto-save-file-format} has been renamed to
@code{auto-save-file-format}, and is no longer a permanent local.
@item
The function @code{visited-file-modtime} now returns a cons, instead
of a list of two integers. The primitive @code{set-file-times} has
been eliminated.
@item
The function @code{file-remote-p} is no longer available.
@item
When determining the filename extension, a leading dot in a filename
is no longer ignored. Thus, @file{.emacs} is considered to have
extension @file{emacs}, rather than being extensionless.
@item
Emacs looks for special file handlers in a more efficient manner: it
will choose the first matching handler in
@code{file-name-handler-alist}, rather than trying to figure out which
provides the closest match.
@item
The @code{predicate} argument for @code{read-file-name} has been
removed, and so have the variables @code{read-file-name-function} and
@code{read-file-name-completion-ignore-case}. The function
@code{read-directory-name} has also been removed.
@item
The functions @code{all-completions} and @code{try-completion} will no
longer accept lists of strings or hash tables (it will still accept
alists, obarrays, and functions.) In addition, the function
@code{test-completion} is no longer available.
@item
The @samp{G} interactive code character is no longer supported.
Use @samp{F} instead.
@item
Arbitrary Lisp functions can no longer be recorded into
@code{buffer-undo-list}. As a consequence, @code{yank-undo-function}
is obsolete, and has been removed.
@item
Emacs will never complain about commands that accumulate too much undo
information, so you no longer have to worry about binding
@code{buffer-undo-list} to @code{t} for such commands (though you may
want to do that anyway, to avoid taking up unnecessary memory space.)
@item
Atomic change groups are no longer supported.
@item
The list returned by @code{(match-data t)} no longer records the
buffer as a final element.
@item
The function @code{looking-back} has been removed, so we no longer
have the benefit of hindsight.
@item
The variable @code{search-spaces-regexp} does not exist. Spaces
always stand for themselves in regular expression searches.
@item
The functions @code{skip-chars-forward} and @code{skip-chars-backward}
no longer accepts character classes such as @samp{[:alpha:]}. All
characters are created equal.
@item
The @code{yank-handler} text property no longer has any meaning.
Also, @code{yank-excluded-properties}, @code{insert-for-yank}, and
@code{insert-buffer-substring-as-yank} have all been removed.
@item
The variable @code{char-property-alias-alist} has been deleted.
Aliases are for functions, not for properties.
@item
The function @code{get-char-property-and-overlay} has been deleted.
If you want the properties at a point, find the text properties at the
point; then, find the overlays at the point, and find the properties
on those overlays.
@item
Font Lock mode only manages @code{face} properties; you can't use
font-lock keywords to specify arbitrary text properties for it to
manage. After all, it is called Font Lock mode, not Arbitrary
Properties Lock mode.
@item
The arguments to @code{remove-overlays} are no longer optional.
@item
In @code{replace-match}, the replacement text now inherits properties
from the surrounding text.
@item
The variable @code{mode-line-format} no longer supports the @code{:propertize},
@code{%i}, and @code{%I} constructs. The function
@code{format-mode-line} has been removed.
@item
The functions @code{window-inside-edges} and @code{window-body-height}
have been removed. You should do the relevant calculations yourself,
starting with @code{window-width} and @code{window-height}.
@item
The functions @code{window-pixel-edges} and
@code{window-inside-pixel-edges} have been removed. We prefer to
think in terms of lines and columns, not pixel coordinates. (Sometime
in the distant past, we will do away with graphical terminals
entirely, in favor of text terminals.) For similar reasons, the
functions @code{posn-at-point}, @code{posn-at-x-y}, and
@code{window-line-height} have been removed, and
@code{pos-visible-in-window-p} no longer worries about partially
visible rows.
@item
The macro @code{save-selected-window} only saves the selected window
of the selected frame, so don't try selecting windows in other frames.
@item
The function @code{minibufferp} is no longer available.
@item
The function @code{modify-all-frames-parameters} has been removed (we
always suspected the name was ungrammatical, anyway.)
@item
The @code{line-spacing} variable no longer accepts float values.
@item
The function @code{tool-bar-local-item-from-menu} has been deleted.
If you need to make an entry in the tool bar, you can still use
@code{tool-bar-add-item-from-menu}, but that modifies the binding in
the source keymap instead of copying it into the local keymap.
@item
When determining the major mode, the file name takes precedence over
the interpreter magic line. The variable @code{magic-mode-alist},
which associates certain buffer beginnings with major modes, has been
eliminated.
@item
The hook @code{after-change-major-mode-hook} is not defined, and
neither are @code{run-mode-hooks} and @code{delay-mode-hooks}.
@item
The variable @code{minor-mode-list} has been removed.
@item
@code{define-derived-mode} will copy abbrevs from the parent mode's
abbrev table, instead of creating a new, empty abbrev table.
@item
There are no ``system'' abbrevs. When the user saves into the abbrevs
file, all abbrevs are saved.
@item
The Warnings facility has been removed. Just use @code{error}.
@item
Several hook variables have been renamed to flout the Emacs naming
conventions. We feel that consistency is boring, and having
non-standard hook names encourages users to check the documentation
before using a hook. For instance, the normal hook
@code{find-file-hook} has been renamed to @code{find-file-hooks}, and
the abnormal hook @code{delete-frame-functions} has been renamed to
@code{delete-frame-hook}.
@item
The function @code{symbol-file} does not exist. If you want to know
which file defined a function or variable, try grepping for it.
@item
The variable @code{load-history} records function definitions just
like variable definitions, instead of indicating which functions were
previously autoloaded.
@item
There is a new variable, @code{recursive-load-depth-limit}, which
specifies how many times files can recursively load themselves; it is
50 by default, and @code{nil} means infinity. Previously, Emacs signaled an
error after just 3 recursive loads, which was boring.
@item
Byte-compiler warnings and error messages will leave out the line and
character positions, in order to exercise your debugging skills.
Also, there is no @code{with-no-warnings} macro---instead of
suppressing compiler warnings, fix your code to avoid them!
@item
The function @code{unsafep} has been removed.
@item
File local variables can now specify a string with text properties.
Since arbitrary Lisp expressions can be embedded in text properties,
this can provide you with a great deal of flexibility and power. On
the other hand, @code{safe-local-eval-forms} and the
@code{safe-local-eval-function} function property have no special
meaning.
@item
You can no longer use @code{char-displayable-p} to test if Emacs can
display a certain character.
@item
The function @code{string-to-multibyte} is no longer available.
@item
The @code{translation-table-for-input} translation table has been
removed. Also, translation hash tables are no longer available, so we
don't need the functions @code{lookup-character} and
@code{lookup-integer}.
@item
The @code{table} argument to @code{translate-region} can no longer be
a char-table; it has to be a string.
@item
The variable @code{auto-coding-functions} and the two functions
@code{merge-coding-systems} and @code{decode-coding-inserted-region}
have been deleted. The coding system property
@code{mime-text-unsuitable} no longer has any special meaning.
@item
If pure storage overflows while dumping, Emacs won't tell you how much
additional pure storage it needs. Try adding in increments of 20000,
until you have enough.
@item
The variables @code{gc-elapsed}, @code{gcs-done}, and
@code{post-gc-hook} have been garbage-collected.
@end itemize
@ignore
arch-tag: 1d0ef137-2bad-430e-ae8e-d820d569b5a6
@end ignore

42
doc/lispref/back.texi Normal file
View file

@ -0,0 +1,42 @@
\input /home/gd/gnu/doc/texinfo.tex @c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c
@c %**start of header
@setfilename back-cover
@settitle GNU Emacs Lisp Reference Manual
@c %**end of header
.
@sp 7
@center @titlefont {GNU Emacs Lisp}
@sp 1
@quotation
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. 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.
@end quotation
@hfil
@bye
@ignore
arch-tag: ac7694c8-1f02-4b42-9531-33ba13b179e1
@end ignore

756
doc/lispref/backups.texi Normal file
View file

@ -0,0 +1,756 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1999, 2001, 2002, 2003,
@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/backups
@node Backups and Auto-Saving, Buffers, Files, Top
@chapter Backups and Auto-Saving
@cindex backups and auto-saving
Backup files and auto-save files are two methods by which Emacs tries
to protect the user from the consequences of crashes or of the user's
own errors. Auto-saving preserves the text from earlier in the current
editing session; backup files preserve file contents prior to the
current session.
@menu
* Backup Files:: How backup files are made; how their names are chosen.
* Auto-Saving:: How auto-save files are made; how their names are chosen.
* Reverting:: @code{revert-buffer}, and how to customize what it does.
@end menu
@node Backup Files
@section Backup Files
@cindex backup file
A @dfn{backup file} is a copy of the old contents of a file you are
editing. Emacs makes a backup file the first time you save a buffer
into its visited file. Thus, normally, the backup file contains the
contents of the file as it was before the current editing session.
The contents of the backup file normally remain unchanged once it
exists.
Backups are usually made by renaming the visited file to a new name.
Optionally, you can specify that backup files should be made by copying
the visited file. This choice makes a difference for files with
multiple names; it also can affect whether the edited file remains owned
by the original owner or becomes owned by the user editing it.
By default, Emacs makes a single backup file for each file edited.
You can alternatively request numbered backups; then each new backup
file gets a new name. You can delete old numbered backups when you
don't want them any more, or Emacs can delete them automatically.
@menu
* Making Backups:: How Emacs makes backup files, and when.
* Rename or Copy:: Two alternatives: renaming the old file or copying it.
* Numbered Backups:: Keeping multiple backups for each source file.
* Backup Names:: How backup file names are computed; customization.
@end menu
@node Making Backups
@subsection Making Backup Files
@defun backup-buffer
This function makes a backup of the file visited by the current
buffer, if appropriate. It is called by @code{save-buffer} before
saving the buffer the first time.
If a backup was made by renaming, the return value is a cons cell of
the form (@var{modes} . @var{backupname}), where @var{modes} are the
mode bits of the original file, as returned by @code{file-modes}
(@pxref{File Attributes,, Other Information about Files}), and
@var{backupname} is the name of the backup. In all other cases, that
is, if a backup was made by copying or if no backup was made, this
function returns @code{nil}.
@end defun
@defvar buffer-backed-up
This buffer-local variable says whether this buffer's file has
been backed up on account of this buffer. If it is non-@code{nil},
the backup file has been written. Otherwise, the file should be backed
up when it is next saved (if backups are enabled). This is a
permanent local; @code{kill-all-local-variables} does not alter@tie{}it.
@end defvar
@defopt make-backup-files
This variable determines whether or not to make backup files. If it
is non-@code{nil}, then Emacs creates a backup of each file when it is
saved for the first time---provided that @code{backup-inhibited}
is @code{nil} (see below).
The following example shows how to change the @code{make-backup-files}
variable only in the Rmail buffers and not elsewhere. Setting it
@code{nil} stops Emacs from making backups of these files, which may
save disk space. (You would put this code in your init file.)
@smallexample
@group
(add-hook 'rmail-mode-hook
(function (lambda ()
(make-local-variable
'make-backup-files)
(setq make-backup-files nil))))
@end group
@end smallexample
@end defopt
@defvar backup-enable-predicate
This variable's value is a function to be called on certain occasions to
decide whether a file should have backup files. The function receives
one argument, an absolute file name to consider. If the function returns
@code{nil}, backups are disabled for that file. Otherwise, the other
variables in this section say whether and how to make backups.
@findex normal-backup-enable-predicate
The default value is @code{normal-backup-enable-predicate}, which checks
for files in @code{temporary-file-directory} and
@code{small-temporary-file-directory}.
@end defvar
@defvar backup-inhibited
If this variable is non-@code{nil}, backups are inhibited. It records
the result of testing @code{backup-enable-predicate} on the visited file
name. It can also coherently be used by other mechanisms that inhibit
backups based on which file is visited. For example, VC sets this
variable non-@code{nil} to prevent making backups for files managed
with a version control system.
This is a permanent local, so that changing the major mode does not lose
its value. Major modes should not set this variable---they should set
@code{make-backup-files} instead.
@end defvar
@defvar backup-directory-alist
This variable's value is an alist of filename patterns and backup
directory names. Each element looks like
@smallexample
(@var{regexp} . @var{directory})
@end smallexample
@noindent
Backups of files with names matching @var{regexp} will be made in
@var{directory}. @var{directory} may be relative or absolute. If it is
absolute, so that all matching files are backed up into the same
directory, the file names in this directory will be the full name of the
file backed up with all directory separators changed to @samp{!} to
prevent clashes. This will not work correctly if your filesystem
truncates the resulting name.
For the common case of all backups going into one directory, the alist
should contain a single element pairing @samp{"."} with the appropriate
directory name.
If this variable is @code{nil}, or it fails to match a filename, the
backup is made in the original file's directory.
On MS-DOS filesystems without long names this variable is always
ignored.
@end defvar
@defvar make-backup-file-name-function
This variable's value is a function to use for making backups instead
of the default @code{make-backup-file-name}. A value of @code{nil}
gives the default @code{make-backup-file-name} behavior.
@xref{Backup Names,, Naming Backup Files}.
This could be buffer-local to do something special for specific
files. If you define it, you may need to change
@code{backup-file-name-p} and @code{file-name-sans-versions} too.
@end defvar
@node Rename or Copy
@subsection Backup by Renaming or by Copying?
@cindex backup files, rename or copy
There are two ways that Emacs can make a backup file:
@itemize @bullet
@item
Emacs can rename the original file so that it becomes a backup file, and
then write the buffer being saved into a new file. After this
procedure, any other names (i.e., hard links) of the original file now
refer to the backup file. The new file is owned by the user doing the
editing, and its group is the default for new files written by the user
in that directory.
@item
Emacs can copy the original file into a backup file, and then overwrite
the original file with new contents. After this procedure, any other
names (i.e., hard links) of the original file continue to refer to the
current (updated) version of the file. The file's owner and group will
be unchanged.
@end itemize
The first method, renaming, is the default.
The variable @code{backup-by-copying}, if non-@code{nil}, says to use
the second method, which is to copy the original file and overwrite it
with the new buffer contents. The variable @code{file-precious-flag},
if non-@code{nil}, also has this effect (as a sideline of its main
significance). @xref{Saving Buffers}.
@defopt backup-by-copying
If this variable is non-@code{nil}, Emacs always makes backup files by
copying.
@end defopt
The following three variables, when non-@code{nil}, cause the second
method to be used in certain special cases. They have no effect on the
treatment of files that don't fall into the special cases.
@defopt backup-by-copying-when-linked
If this variable is non-@code{nil}, Emacs makes backups by copying for
files with multiple names (hard links).
This variable is significant only if @code{backup-by-copying} is
@code{nil}, since copying is always used when that variable is
non-@code{nil}.
@end defopt
@defopt backup-by-copying-when-mismatch
If this variable is non-@code{nil}, Emacs makes backups by copying in cases
where renaming would change either the owner or the group of the file.
The value has no effect when renaming would not alter the owner or
group of the file; that is, for files which are owned by the user and
whose group matches the default for a new file created there by the
user.
This variable is significant only if @code{backup-by-copying} is
@code{nil}, since copying is always used when that variable is
non-@code{nil}.
@end defopt
@defopt backup-by-copying-when-privileged-mismatch
This variable, if non-@code{nil}, specifies the same behavior as
@code{backup-by-copying-when-mismatch}, but only for certain user-id
values: namely, those less than or equal to a certain number. You set
this variable to that number.
Thus, if you set @code{backup-by-copying-when-privileged-mismatch}
to 0, backup by copying is done for the superuser only,
when necessary to prevent a change in the owner of the file.
The default is 200.
@end defopt
@node Numbered Backups
@subsection Making and Deleting Numbered Backup Files
If a file's name is @file{foo}, the names of its numbered backup
versions are @file{foo.~@var{v}~}, for various integers @var{v}, like
this: @file{foo.~1~}, @file{foo.~2~}, @file{foo.~3~}, @dots{},
@file{foo.~259~}, and so on.
@defopt version-control
This variable controls whether to make a single non-numbered backup
file or multiple numbered backups.
@table @asis
@item @code{nil}
Make numbered backups if the visited file already has numbered backups;
otherwise, do not. This is the default.
@item @code{never}
Do not make numbered backups.
@item @var{anything else}
Make numbered backups.
@end table
@end defopt
The use of numbered backups ultimately leads to a large number of
backup versions, which must then be deleted. Emacs can do this
automatically or it can ask the user whether to delete them.
@defopt kept-new-versions
The value of this variable is the number of newest versions to keep
when a new numbered backup is made. The newly made backup is included
in the count. The default value is@tie{}2.
@end defopt
@defopt kept-old-versions
The value of this variable is the number of oldest versions to keep
when a new numbered backup is made. The default value is@tie{}2.
@end defopt
If there are backups numbered 1, 2, 3, 5, and 7, and both of these
variables have the value 2, then the backups numbered 1 and 2 are kept
as old versions and those numbered 5 and 7 are kept as new versions;
backup version 3 is excess. The function @code{find-backup-file-name}
(@pxref{Backup Names}) is responsible for determining which backup
versions to delete, but does not delete them itself.
@defopt delete-old-versions
If this variable is @code{t}, then saving a file deletes excess
backup versions silently. If it is @code{nil}, that means
to ask for confirmation before deleting excess backups.
Otherwise, they are not deleted at all.
@end defopt
@defopt dired-kept-versions
This variable specifies how many of the newest backup versions to keep
in the Dired command @kbd{.} (@code{dired-clean-directory}). That's the
same thing @code{kept-new-versions} specifies when you make a new backup
file. The default is@tie{}2.
@end defopt
@node Backup Names
@subsection Naming Backup Files
The functions in this section are documented mainly because you can
customize the naming conventions for backup files by redefining them.
If you change one, you probably need to change the rest.
@defun backup-file-name-p filename
This function returns a non-@code{nil} value if @var{filename} is a
possible name for a backup file. It just checks the name, not whether
a file with the name @var{filename} exists.
@smallexample
@group
(backup-file-name-p "foo")
@result{} nil
@end group
@group
(backup-file-name-p "foo~")
@result{} 3
@end group
@end smallexample
The standard definition of this function is as follows:
@smallexample
@group
(defun backup-file-name-p (file)
"Return non-nil if FILE is a backup file \
name (numeric or not)..."
(string-match "~\\'" file))
@end group
@end smallexample
@noindent
Thus, the function returns a non-@code{nil} value if the file name ends
with a @samp{~}. (We use a backslash to split the documentation
string's first line into two lines in the text, but produce just one
line in the string itself.)
This simple expression is placed in a separate function to make it easy
to redefine for customization.
@end defun
@defun make-backup-file-name filename
This function returns a string that is the name to use for a
non-numbered backup file for file @var{filename}. On Unix, this is just
@var{filename} with a tilde appended.
The standard definition of this function, on most operating systems, is
as follows:
@smallexample
@group
(defun make-backup-file-name (file)
"Create the non-numeric backup file name for FILE..."
(concat file "~"))
@end group
@end smallexample
You can change the backup-file naming convention by redefining this
function. The following example redefines @code{make-backup-file-name}
to prepend a @samp{.} in addition to appending a tilde:
@smallexample
@group
(defun make-backup-file-name (filename)
(expand-file-name
(concat "." (file-name-nondirectory filename) "~")
(file-name-directory filename)))
@end group
@group
(make-backup-file-name "backups.texi")
@result{} ".backups.texi~"
@end group
@end smallexample
Some parts of Emacs, including some Dired commands, assume that backup
file names end with @samp{~}. If you do not follow that convention, it
will not cause serious problems, but these commands may give
less-than-desirable results.
@end defun
@defun find-backup-file-name filename
This function computes the file name for a new backup file for
@var{filename}. It may also propose certain existing backup files for
deletion. @code{find-backup-file-name} returns a list whose @sc{car} is
the name for the new backup file and whose @sc{cdr} is a list of backup
files whose deletion is proposed. The value can also be @code{nil},
which means not to make a backup.
Two variables, @code{kept-old-versions} and @code{kept-new-versions},
determine which backup versions should be kept. This function keeps
those versions by excluding them from the @sc{cdr} of the value.
@xref{Numbered Backups}.
In this example, the value says that @file{~rms/foo.~5~} is the name
to use for the new backup file, and @file{~rms/foo.~3~} is an ``excess''
version that the caller should consider deleting now.
@smallexample
@group
(find-backup-file-name "~rms/foo")
@result{} ("~rms/foo.~5~" "~rms/foo.~3~")
@end group
@end smallexample
@end defun
@c Emacs 19 feature
@defun file-newest-backup filename
This function returns the name of the most recent backup file for
@var{filename}, or @code{nil} if that file has no backup files.
Some file comparison commands use this function so that they can
automatically compare a file with its most recent backup.
@end defun
@node Auto-Saving
@section Auto-Saving
@c @cindex auto-saving Lots of symbols starting with auto-save here.
Emacs periodically saves all files that you are visiting; this is
called @dfn{auto-saving}. Auto-saving prevents you from losing more
than a limited amount of work if the system crashes. By default,
auto-saves happen every 300 keystrokes, or after around 30 seconds of
idle time. @xref{Auto Save, Auto Save, Auto-Saving: Protection Against
Disasters, emacs, The GNU Emacs Manual}, for information on auto-save
for users. Here we describe the functions used to implement auto-saving
and the variables that control them.
@defvar buffer-auto-save-file-name
This buffer-local variable is the name of the file used for
auto-saving the current buffer. It is @code{nil} if the buffer
should not be auto-saved.
@example
@group
buffer-auto-save-file-name
@result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example
@end defvar
@deffn Command auto-save-mode arg
When used interactively without an argument, this command is a toggle
switch: it turns on auto-saving of the current buffer if it is off, and
vice versa. With an argument @var{arg}, the command turns auto-saving
on if the value of @var{arg} is @code{t}, a nonempty list, or a positive
integer. Otherwise, it turns auto-saving off.
@end deffn
@defun auto-save-file-name-p filename
This function returns a non-@code{nil} value if @var{filename} is a
string that could be the name of an auto-save file. It assumes
the usual naming convention for auto-save files: a name that
begins and ends with hash marks (@samp{#}) is a possible auto-save file
name. The argument @var{filename} should not contain a directory part.
@example
@group
(make-auto-save-file-name)
@result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@group
(auto-save-file-name-p "#backups.texi#")
@result{} 0
@end group
@group
(auto-save-file-name-p "backups.texi")
@result{} nil
@end group
@end example
The standard definition of this function is as follows:
@example
@group
(defun auto-save-file-name-p (filename)
"Return non-nil if FILENAME can be yielded by..."
(string-match "^#.*#$" filename))
@end group
@end example
This function exists so that you can customize it if you wish to
change the naming convention for auto-save files. If you redefine it,
be sure to redefine the function @code{make-auto-save-file-name}
correspondingly.
@end defun
@defun make-auto-save-file-name
This function returns the file name to use for auto-saving the current
buffer. This is just the file name with hash marks (@samp{#}) prepended
and appended to it. This function does not look at the variable
@code{auto-save-visited-file-name} (described below); callers of this
function should check that variable first.
@example
@group
(make-auto-save-file-name)
@result{} "/xcssun/users/rms/lewis/#backups.texi#"
@end group
@end example
Here is a simplified version of the standard definition of this
function:
@example
@group
(defun make-auto-save-file-name ()
"Return file name to use for auto-saves \
of current buffer.."
(if buffer-file-name
@end group
@group
(concat
(file-name-directory buffer-file-name)
"#"
(file-name-nondirectory buffer-file-name)
"#")
(expand-file-name
(concat "#%" (buffer-name) "#"))))
@end group
@end example
This exists as a separate function so that you can redefine it to
customize the naming convention for auto-save files. Be sure to
change @code{auto-save-file-name-p} in a corresponding way.
@end defun
@defopt auto-save-visited-file-name
If this variable is non-@code{nil}, Emacs auto-saves buffers in
the files they are visiting. That is, the auto-save is done in the same
file that you are editing. Normally, this variable is @code{nil}, so
auto-save files have distinct names that are created by
@code{make-auto-save-file-name}.
When you change the value of this variable, the new value does not take
effect in an existing buffer until the next time auto-save mode is
reenabled in it. If auto-save mode is already enabled, auto-saves
continue to go in the same file name until @code{auto-save-mode} is
called again.
@end defopt
@defun recent-auto-save-p
This function returns @code{t} if the current buffer has been
auto-saved since the last time it was read in or saved.
@end defun
@defun set-buffer-auto-saved
This function marks the current buffer as auto-saved. The buffer will
not be auto-saved again until the buffer text is changed again. The
function returns @code{nil}.
@end defun
@defopt auto-save-interval
The value of this variable specifies how often to do auto-saving, in
terms of number of input events. Each time this many additional input
events are read, Emacs does auto-saving for all buffers in which that is
enabled. Setting this to zero disables autosaving based on the
number of characters typed.
@end defopt
@defopt auto-save-timeout
The value of this variable is the number of seconds of idle time that
should cause auto-saving. Each time the user pauses for this long,
Emacs does auto-saving for all buffers in which that is enabled. (If
the current buffer is large, the specified timeout is multiplied by a
factor that increases as the size increases; for a million-byte
buffer, the factor is almost 4.)
If the value is zero or @code{nil}, then auto-saving is not done as a
result of idleness, only after a certain number of input events as
specified by @code{auto-save-interval}.
@end defopt
@defvar auto-save-hook
This normal hook is run whenever an auto-save is about to happen.
@end defvar
@defopt auto-save-default
If this variable is non-@code{nil}, buffers that are visiting files
have auto-saving enabled by default. Otherwise, they do not.
@end defopt
@deffn Command do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved. It
saves all buffers for which auto-saving is enabled and that have been
changed since the previous auto-save.
If any buffers are auto-saved, @code{do-auto-save} normally displays a
message saying @samp{Auto-saving...} in the echo area while
auto-saving is going on. However, if @var{no-message} is
non-@code{nil}, the message is inhibited.
If @var{current-only} is non-@code{nil}, only the current buffer
is auto-saved.
@end deffn
@defun delete-auto-save-file-if-necessary &optional force
This function deletes the current buffer's auto-save file if
@code{delete-auto-save-files} is non-@code{nil}. It is called every
time a buffer is saved.
Unless @var{force} is non-@code{nil}, this function only deletes the
file if it was written by the current Emacs session since the last
true save.
@end defun
@defopt delete-auto-save-files
This variable is used by the function
@code{delete-auto-save-file-if-necessary}. If it is non-@code{nil},
Emacs deletes auto-save files when a true save is done (in the visited
file). This saves disk space and unclutters your directory.
@end defopt
@defun rename-auto-save-file
This function adjusts the current buffer's auto-save file name if the
visited file name has changed. It also renames an existing auto-save
file, if it was made in the current Emacs session. If the visited
file name has not changed, this function does nothing.
@end defun
@defvar buffer-saved-size
The value of this buffer-local variable is the length of the current
buffer, when it was last read in, saved, or auto-saved. This is
used to detect a substantial decrease in size, and turn off auto-saving
in response.
If it is @minus{}1, that means auto-saving is temporarily shut off in
this buffer due to a substantial decrease in size. Explicitly saving
the buffer stores a positive value in this variable, thus reenabling
auto-saving. Turning auto-save mode off or on also updates this
variable, so that the substantial decrease in size is forgotten.
@end defvar
@defvar auto-save-list-file-name
This variable (if non-@code{nil}) specifies a file for recording the
names of all the auto-save files. Each time Emacs does auto-saving, it
writes two lines into this file for each buffer that has auto-saving
enabled. The first line gives the name of the visited file (it's empty
if the buffer has none), and the second gives the name of the auto-save
file.
When Emacs exits normally, it deletes this file; if Emacs crashes, you
can look in the file to find all the auto-save files that might contain
work that was otherwise lost. The @code{recover-session} command uses
this file to find them.
The default name for this file specifies your home directory and starts
with @samp{.saves-}. It also contains the Emacs process @acronym{ID} and the
host name.
@end defvar
@defvar auto-save-list-file-prefix
After Emacs reads your init file, it initializes
@code{auto-save-list-file-name} (if you have not already set it
non-@code{nil}) based on this prefix, adding the host name and process
ID. If you set this to @code{nil} in your init file, then Emacs does
not initialize @code{auto-save-list-file-name}.
@end defvar
@node Reverting
@section Reverting
If you have made extensive changes to a file and then change your mind
about them, you can get rid of them by reading in the previous version
of the file with the @code{revert-buffer} command. @xref{Reverting, ,
Reverting a Buffer, emacs, The GNU Emacs Manual}.
@deffn Command revert-buffer &optional ignore-auto noconfirm preserve-modes
This command replaces the buffer text with the text of the visited
file on disk. This action undoes all changes since the file was visited
or saved.
By default, if the latest auto-save file is more recent than the visited
file, and the argument @var{ignore-auto} is @code{nil},
@code{revert-buffer} asks the user whether to use that auto-save
instead. When you invoke this command interactively, @var{ignore-auto}
is @code{t} if there is no numeric prefix argument; thus, the
interactive default is not to check the auto-save file.
Normally, @code{revert-buffer} asks for confirmation before it changes
the buffer; but if the argument @var{noconfirm} is non-@code{nil},
@code{revert-buffer} does not ask for confirmation.
Normally, this command reinitializes the buffer's major and minor modes
using @code{normal-mode}. But if @var{preserve-modes} is
non-@code{nil}, the modes remain unchanged.
Reverting tries to preserve marker positions in the buffer by using the
replacement feature of @code{insert-file-contents}. If the buffer
contents and the file contents are identical before the revert
operation, reverting preserves all the markers. If they are not
identical, reverting does change the buffer; in that case, it preserves
the markers in the unchanged text (if any) at the beginning and end of
the buffer. Preserving any additional markers would be problematical.
@end deffn
You can customize how @code{revert-buffer} does its work by setting
the variables described in the rest of this section.
@defopt revert-without-query
This variable holds a list of files that should be reverted without
query. The value is a list of regular expressions. If the visited file
name matches one of these regular expressions, and the file has changed
on disk but the buffer is not modified, then @code{revert-buffer}
reverts the file without asking the user for confirmation.
@end defopt
Some major modes customize @code{revert-buffer} by making
buffer-local bindings for these variables:
@defvar revert-buffer-function
@anchor{Definition of revert-buffer-function}
The value of this variable is the function to use to revert this
buffer. If non-@code{nil}, it should be a function with two optional
arguments to do the work of reverting. The two optional arguments,
@var{ignore-auto} and @var{noconfirm}, are the arguments that
@code{revert-buffer} received. If the value is @code{nil}, reverting
works the usual way.
Modes such as Dired mode, in which the text being edited does not
consist of a file's contents but can be regenerated in some other
fashion, can give this variable a buffer-local value that is a function to
regenerate the contents.
@end defvar
@defvar revert-buffer-insert-file-contents-function
The value of this variable, if non-@code{nil}, specifies the function to use to
insert the updated contents when reverting this buffer. The function
receives two arguments: first the file name to use; second, @code{t} if
the user has asked to read the auto-save file.
The reason for a mode to set this variable instead of
@code{revert-buffer-function} is to avoid duplicating or replacing the
rest of what @code{revert-buffer} does: asking for confirmation,
clearing the undo list, deciding the proper major mode, and running the
hooks listed below.
@end defvar
@defvar before-revert-hook
This normal hook is run by @code{revert-buffer} before
inserting the modified contents---but only if
@code{revert-buffer-function} is @code{nil}.
@end defvar
@defvar after-revert-hook
This normal hook is run by @code{revert-buffer} after inserting
the modified contents---but only if @code{revert-buffer-function} is
@code{nil}.
@end defvar
@ignore
arch-tag: 295a6321-e5ab-46d5-aef5-0bb4f447a67f
@end ignore

29
doc/lispref/book-spine.texinfo Normal file
View file

@ -0,0 +1,29 @@
\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename book-spine
@settitle book-spine
@c %**end of header
@c need dot in text so first space command works!
.
@sp 7
@center @titlefont{GNU Emacs Lisp Reference Manual}
@sp 5
@center GNU
@center Emacs Version 22.1
@center for Unix Users
@sp 5
@center by
@center Bil Lewis,
@center Dan LaLiberte,
@center and the
@center GNU Manual Group
@sp 5
@center Free Software Foundation
@bye
@ignore
arch-tag: 4466c7ca-e549-4119-948c-6eed34e1ff87
@end ignore

1165
doc/lispref/buffers.texi Normal file
View file

File diff suppressed because it is too large Load diff

3290
doc/lispref/commands.texi Normal file
View file

File diff suppressed because it is too large Load diff

886
doc/lispref/compile.texi Normal file
View file

@ -0,0 +1,886 @@
@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/compile
@node Byte Compilation, Advising Functions, Loading, Top
@chapter Byte Compilation
@cindex byte compilation
@cindex byte-code
@cindex compilation (Emacs Lisp)
Emacs Lisp has a @dfn{compiler} that translates functions written
in Lisp into a special representation called @dfn{byte-code} that can be
executed more efficiently. The compiler replaces Lisp function
definitions with byte-code. When a byte-code function is called, its
definition is evaluated by the @dfn{byte-code interpreter}.
Because the byte-compiled code is evaluated by the byte-code
interpreter, instead of being executed directly by the machine's
hardware (as true compiled code is), byte-code is completely
transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
Compiling a Lisp file with the Emacs byte compiler always reads the
file as multibyte text, even if Emacs was started with @samp{--unibyte},
unless the file specifies otherwise. This is so that compilation gives
results compatible with running the same file without compilation.
@xref{Loading Non-ASCII}.
In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true.
@vindex no-byte-compile
If you do not want a Lisp file to be compiled, ever, put a file-local
variable binding for @code{no-byte-compile} into it, like this:
@example
;; -*-no-byte-compile: t; -*-
@end example
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
@menu
* Speed of Byte-Code:: An example of speedup from byte compilation.
* Compilation Functions:: Byte compilation functions.
* Docs and Compilation:: Dynamic loading of documentation strings.
* Dynamic Loading:: Dynamic loading of individual functions.
* Eval During Compile:: Code to be evaluated when you compile.
* Compiler Errors:: Handling compiler error messages.
* Byte-Code Objects:: The data type used for byte-compiled functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
@end menu
@node Speed of Byte-Code
@section Performance of Byte-Compiled Code
A byte-compiled function is not as efficient as a primitive function
written in C, but runs much faster than the version written in Lisp.
Here is an example:
@example
@group
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
@result{} silly-loop
@end group
@group
(silly-loop 100000)
@result{} ("Fri Mar 18 17:25:57 1994"
"Fri Mar 18 17:26:28 1994") ; @r{31 seconds}
@end group
@group
(byte-compile 'silly-loop)
@result{} @r{[Compiled code not shown]}
@end group
@group
(silly-loop 100000)
@result{} ("Fri Mar 18 17:26:52 1994"
"Fri Mar 18 17:26:58 1994") ; @r{6 seconds}
@end group
@end example
In this example, the interpreted code required 31 seconds to run,
whereas the byte-compiled code required 6 seconds. These results are
representative, but actual results will vary greatly.
@node Compilation Functions
@comment node-name, next, previous, up
@section The Compilation Functions
@cindex compilation functions
You can byte-compile an individual function or macro definition with
the @code{byte-compile} function. You can compile a whole file with
@code{byte-compile-file}, or several files with
@code{byte-recompile-directory} or @code{batch-byte-compile}.
The byte compiler produces error messages and warnings about each file
in a buffer called @samp{*Compile-Log*}. These report things in your
program that suggest a problem but are not necessarily erroneous.
@cindex macro compilation
Be careful when writing macro calls in files that you may someday
byte-compile. Macro calls are expanded when they are compiled, so the
macros must already be defined for proper compilation. For more
details, see @ref{Compiling Macros}. If a program does not work the
same way when compiled as it does when interpreted, erroneous macro
definitions are one likely cause (@pxref{Problems with Macros}).
Inline (@code{defsubst}) functions are less troublesome; if you
compile a call to such a function before its definition is known, the
call will still work right, it will just run slower.
Normally, compiling a file does not evaluate the file's contents or
load the file. But it does execute any @code{require} calls at top
level in the file. One way to ensure that necessary macro definitions
are available during compilation is to require the file that defines
them (@pxref{Named Features}). To avoid loading the macro definition files
when someone @emph{runs} the compiled program, write
@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
During Compile}).
@defun byte-compile symbol
This function byte-compiles the function definition of @var{symbol},
replacing the previous definition with the compiled one. The function
definition of @var{symbol} must be the actual code for the function;
i.e., the compiler does not follow indirection to another symbol.
@code{byte-compile} returns the new, compiled definition of
@var{symbol}.
If @var{symbol}'s definition is a byte-code function object,
@code{byte-compile} does nothing and returns @code{nil}. Lisp records
only one function definition for any symbol, and if that is already
compiled, non-compiled code is not available anywhere. So there is no
way to ``compile the same definition again.''
@example
@group
(defun factorial (integer)
"Compute factorial of INTEGER."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
@result{} factorial
@end group
@group
(byte-compile 'factorial)
@result{}
#[(integer)
"^H\301U\203^H^@@\301\207\302^H\303^HS!\"\207"
[integer 1 * factorial]
4 "Compute factorial of INTEGER."]
@end group
@end example
@noindent
The result is a byte-code function object. The string it contains is
the actual byte-code; each character in it is an instruction or an
operand of an instruction. The vector contains all the constants,
variable names and function names used by the function, except for
certain primitives that are coded as special instructions.
If the argument to @code{byte-compile} is a @code{lambda} expression,
it returns the corresponding compiled code, but does not store
it anywhere.
@end defun
@deffn Command compile-defun &optional arg
This command reads the defun containing point, compiles it, and
evaluates the result. If you use this on a defun that is actually a
function definition, the effect is to install a compiled version of that
function.
@code{compile-defun} normally displays the result of evaluation in the
echo area, but if @var{arg} is non-@code{nil}, it inserts the result
in the current buffer after the form it compiled.
@end deffn
@deffn Command byte-compile-file filename &optional load
This function compiles a file of Lisp code named @var{filename} into a
file of byte-code. The output file's name is made by changing the
@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
Compilation works by reading the input file one form at a time. If it
is a definition of a function or macro, the compiled function or macro
definition is written out. Other forms are batched together, then each
batch is compiled, and written so that its compiled code will be
executed when the file is read. All comments are discarded when the
input file is read.
This command returns @code{t} if there were no errors and @code{nil}
otherwise. When called interactively, it prompts for the file name.
If @var{load} is non-@code{nil}, this command loads the compiled file
after compiling it. Interactively, @var{load} is the prefix argument.
@example
@group
% ls -l push*
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
@end group
@group
(byte-compile-file "~/emacs/push.el")
@result{} t
@end group
@group
% ls -l push*
-rw-r--r-- 1 lewis 791 Oct 5 20:31 push.el
-rw-rw-rw- 1 lewis 638 Oct 8 20:25 push.elc
@end group
@end example
@end deffn
@deffn Command byte-recompile-directory directory &optional flag force
@cindex library compilation
This command recompiles every @samp{.el} file in @var{directory} (or
its subdirectories) that needs recompilation. A file needs
recompilation if a @samp{.elc} file exists but is older than the
@samp{.el} file.
When a @samp{.el} file has no corresponding @samp{.elc} file,
@var{flag} says what to do. If it is @code{nil}, this command ignores
these files. If @var{flag} is 0, it compiles them. If it is neither
@code{nil} nor 0, it asks the user whether to compile each such file,
and asks about each subdirectory as well.
Interactively, @code{byte-recompile-directory} prompts for
@var{directory} and @var{flag} is the prefix argument.
If @var{force} is non-@code{nil}, this command recompiles every
@samp{.el} file that has a @samp{.elc} file.
The returned value is unpredictable.
@end deffn
@defun batch-byte-compile &optional noforce
This function runs @code{byte-compile-file} on files specified on the
command line. This function must be used only in a batch execution of
Emacs, as it kills Emacs on completion. An error in one file does not
prevent processing of subsequent files, but no output file will be
generated for it, and the Emacs process will terminate with a nonzero
status code.
If @var{noforce} is non-@code{nil}, this function does not recompile
files that have an up-to-date @samp{.elc} file.
@example
% emacs -batch -f batch-byte-compile *.el
@end example
@end defun
@defun byte-code code-string data-vector max-stack
@cindex byte-code interpreter
This function actually interprets byte-code. A byte-compiled function
is actually defined with a body that calls @code{byte-code}. Don't call
this function yourself---only the byte compiler knows how to generate
valid calls to this function.
In Emacs version 18, byte-code was always executed by way of a call to
the function @code{byte-code}. Nowadays, byte-code is usually executed
as part of a byte-code function object, and only rarely through an
explicit call to @code{byte-code}.
@end defun
@node Docs and Compilation
@section Documentation Strings and Compilation
@cindex dynamic loading of documentation
Functions and variables loaded from a byte-compiled file access their
documentation strings dynamically from the file whenever needed. This
saves space within Emacs, and makes loading faster because the
documentation strings themselves need not be processed while loading the
file. Actual access to the documentation strings becomes slower as a
result, but this normally is not enough to bother users.
Dynamic access to documentation strings does have drawbacks:
@itemize @bullet
@item
If you delete or move the compiled file after loading it, Emacs can no
longer access the documentation strings for the functions and variables
in the file.
@item
If you alter the compiled file (such as by compiling a new version),
then further access to documentation strings in this file will
probably give nonsense results.
@end itemize
If your site installs Emacs following the usual procedures, these
problems will never normally occur. Installing a new version uses a new
directory with a different name; as long as the old version remains
installed, its files will remain unmodified in the places where they are
expected to be.
However, if you have built Emacs yourself and use it from the
directory where you built it, you will experience this problem
occasionally if you edit and recompile Lisp files. When it happens, you
can cure the problem by reloading the file after recompiling it.
You can turn off this feature at compile time by setting
@code{byte-compile-dynamic-docstrings} to @code{nil}; this is useful
mainly if you expect to change the file, and you want Emacs processes
that have already loaded it to keep working when the file changes.
You can do this globally, or for one source file by specifying a
file-local binding for the variable. One way to do that is by adding
this string to the file's first line:
@example
-*-byte-compile-dynamic-docstrings: nil;-*-
@end example
@defvar byte-compile-dynamic-docstrings
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic loading of documentation strings.
@end defvar
@cindex @samp{#@@@var{count}}
@cindex @samp{#$}
The dynamic documentation string feature writes compiled files that
use a special Lisp reader construct, @samp{#@@@var{count}}. This
construct skips the next @var{count} characters. It also uses the
@samp{#$} construct, which stands for ``the name of this file, as a
string.'' It is usually best not to use these constructs in Lisp source
files, since they are not designed to be clear to humans reading the
file.
@node Dynamic Loading
@section Dynamic Loading of Individual Functions
@cindex dynamic loading of functions
@cindex lazy loading
When you compile a file, you can optionally enable the @dfn{dynamic
function loading} feature (also known as @dfn{lazy loading}). With
dynamic function loading, loading the file doesn't fully read the
function definitions in the file. Instead, each function definition
contains a place-holder which refers to the file. The first time each
function is called, it reads the full definition from the file, to
replace the place-holder.
The advantage of dynamic function loading is that loading the file
becomes much faster. This is a good thing for a file which contains
many separate user-callable functions, if using one of them does not
imply you will probably also use the rest. A specialized mode which
provides many keyboard commands often has that usage pattern: a user may
invoke the mode, but use only a few of the commands it provides.
The dynamic loading feature has certain disadvantages:
@itemize @bullet
@item
If you delete or move the compiled file after loading it, Emacs can no
longer load the remaining function definitions not already loaded.
@item
If you alter the compiled file (such as by compiling a new version),
then trying to load any function not already loaded will usually yield
nonsense results.
@end itemize
These problems will never happen in normal circumstances with
installed Emacs files. But they are quite likely to happen with Lisp
files that you are changing. The easiest way to prevent these problems
is to reload the new compiled file immediately after each recompilation.
The byte compiler uses the dynamic function loading feature if the
variable @code{byte-compile-dynamic} is non-@code{nil} at compilation
time. Do not set this variable globally, since dynamic loading is
desirable only for certain files. Instead, enable the feature for
specific source files with file-local variable bindings. For example,
you could do it by writing this text in the source file's first line:
@example
-*-byte-compile-dynamic: t;-*-
@end example
@defvar byte-compile-dynamic
If this is non-@code{nil}, the byte compiler generates compiled files
that are set up for dynamic function loading.
@end defvar
@defun fetch-bytecode function
If @var{function} is a byte-code function object, this immediately
finishes loading the byte code of @var{function} from its
byte-compiled file, if it is not fully loaded already. Otherwise,
it does nothing. It always returns @var{function}.
@end defun
@node Eval During Compile
@section Evaluation During Compilation
These features permit you to write code to be evaluated during
compilation of a program.
@defspec eval-and-compile body@dots{}
This form marks @var{body} to be evaluated both when you compile the
containing code and when you run it (whether compiled or not).
You can get a similar result by putting @var{body} in a separate file
and referring to that file with @code{require}. That method is
preferable when @var{body} is large. Effectively @code{require} is
automatically @code{eval-and-compile}, the package is loaded both when
compiling and executing.
@code{autoload} is also effectively @code{eval-and-compile} too. It's
recognized when compiling, so uses of such a function don't produce
``not known to be defined'' warnings.
Most uses of @code{eval-and-compile} are fairly sophisticated.
If a macro has a helper function to build its result, and that macro
is used both locally and outside the package, then
@code{eval-and-compile} should be used to get the helper both when
compiling and then later when running.
If functions are defined programmatically (with @code{fset} say), then
@code{eval-and-compile} can be used to have that done at compile-time
as well as run-time, so calls to those functions are checked (and
warnings about ``not known to be defined'' suppressed).
@end defspec
@defspec eval-when-compile body@dots{}
This form marks @var{body} to be evaluated at compile time but not when
the compiled program is loaded. The result of evaluation by the
compiler becomes a constant which appears in the compiled program. If
you load the source file, rather than compiling it, @var{body} is
evaluated normally.
@cindex compile-time constant
If you have a constant that needs some calculation to produce,
@code{eval-when-compile} can do that at compile-time. For example,
@lisp
(defvar my-regexp
(eval-when-compile (regexp-opt '("aaa" "aba" "abb"))))
@end lisp
@cindex macros, at compile time
If you're using another package, but only need macros from it (the
byte compiler will expand those), then @code{eval-when-compile} can be
used to load it for compiling, but not executing. For example,
@lisp
(eval-when-compile
(require 'my-macro-package)) ;; only macros needed from this
@end lisp
The same sort of thing goes for macros and @code{defsubst} functions
defined locally and only for use within the file. They are needed for
compiling the file, but in most cases they are not needed for
execution of the compiled file. For example,
@lisp
(eval-when-compile
(unless (fboundp 'some-new-thing)
(defmacro 'some-new-thing ()
(compatibility code))))
@end lisp
@noindent
This is often good for code that's only a fallback for compatibility
with other versions of Emacs.
@strong{Common Lisp Note:} At top level, @code{eval-when-compile} is analogous to the Common
Lisp idiom @code{(eval-when (compile eval) @dots{})}. Elsewhere, the
Common Lisp @samp{#.} reader macro (but not when interpreting) is closer
to what @code{eval-when-compile} does.
@end defspec
@node Compiler Errors
@section Compiler Errors
@cindex compiler errors
Byte compilation outputs all errors and warnings into the buffer
@samp{*Compile-Log*}. The messages include file names and line
numbers that identify the location of the problem. The usual Emacs
commands for operating on compiler diagnostics work properly on
these messages.
However, the warnings about functions that were used but not
defined are always ``located'' at the end of the file, so these
commands won't find the places they are really used. To do that,
you must search for the function names.
You can suppress the compiler warning for calling an undefined
function @var{func} by conditionalizing the function call on an
@code{fboundp} test, like this:
@example
(if (fboundp '@var{func}) ...(@var{func} ...)...)
@end example
@noindent
The call to @var{func} must be in the @var{then-form} of the
@code{if}, and @var{func} must appear quoted in the call to
@code{fboundp}. (This feature operates for @code{cond} as well.)
Likewise, you can suppress a compiler warning for an unbound variable
@var{variable} by conditionalizing its use on a @code{boundp} test,
like this:
@example
(if (boundp '@var{variable}) ...@var{variable}...)
@end example
@noindent
The reference to @var{variable} must be in the @var{then-form} of the
@code{if}, and @var{variable} must appear quoted in the call to
@code{boundp}.
You can suppress any compiler warnings using the construct
@code{with-no-warnings}:
@c This is implemented with a defun, but conceptually it is
@c a special form.
@defspec with-no-warnings body@dots{}
In execution, this is equivalent to @code{(progn @var{body}...)},
but the compiler does not issue warnings for anything that occurs
inside @var{body}.
We recommend that you use this construct around the smallest
possible piece of code.
@end defspec
@node Byte-Code Objects
@section Byte-Code Function Objects
@cindex compiled function
@cindex byte-code function
Byte-compiled functions have a special data type: they are
@dfn{byte-code function objects}.
Internally, a byte-code function object is much like a vector;
however, the evaluator handles this data type specially when it appears
as a function to be called. The printed representation for a byte-code
function object is like that for a vector, with an additional @samp{#}
before the opening @samp{[}.
A byte-code function object must have at least four elements; there is
no maximum number, but only the first six elements have any normal use.
They are:
@table @var
@item arglist
The list of argument symbols.
@item byte-code
The string containing the byte-code instructions.
@item constants
The vector of Lisp objects referenced by the byte code. These include
symbols used as function names and variable names.
@item stacksize
The maximum stack size this function needs.
@item docstring
The documentation string (if any); otherwise, @code{nil}. The value may
be a number or a list, in case the documentation string is stored in a
file. Use the function @code{documentation} to get the real
documentation string (@pxref{Accessing Documentation}).
@item interactive
The interactive spec (if any). This can be a string or a Lisp
expression. It is @code{nil} for a function that isn't interactive.
@end table
Here's an example of a byte-code function object, in printed
representation. It is the definition of the command
@code{backward-sexp}.
@example
#[(&optional arg)
"^H\204^F^@@\301^P\302^H[!\207"
[arg 1 forward-sexp]
2
254435
"p"]
@end example
The primitive way to create a byte-code object is with
@code{make-byte-code}:
@defun make-byte-code &rest elements
This function constructs and returns a byte-code function object
with @var{elements} as its elements.
@end defun
You should not try to come up with the elements for a byte-code
function yourself, because if they are inconsistent, Emacs may crash
when you call the function. Always leave it to the byte compiler to
create these objects; it makes the elements consistent (we hope).
You can access the elements of a byte-code object using @code{aref};
you can also use @code{vconcat} to create a vector with the same
elements.
@node Disassembly
@section Disassembled Byte-Code
@cindex disassembled byte-code
People do not write byte-code; that job is left to the byte compiler.
But we provide a disassembler to satisfy a cat-like curiosity. The
disassembler converts the byte-compiled code into humanly readable
form.
The byte-code interpreter is implemented as a simple stack machine.
It pushes values onto a stack of its own, then pops them off to use them
in calculations whose results are themselves pushed back on the stack.
When a byte-code function returns, it pops a value off the stack and
returns it as the value of the function.
In addition to the stack, byte-code functions can use, bind, and set
ordinary Lisp variables, by transferring values between variables and
the stack.
@deffn Command disassemble object &optional buffer-or-name
This command displays the disassembled code for @var{object}. In
interactive use, or if @var{buffer-or-name} is @code{nil} or omitted,
the output goes in a buffer named @samp{*Disassemble*}. If
@var{buffer-or-name} is non-@code{nil}, it must be a buffer or the
name of an existing buffer. Then the output goes there, at point, and
point is left before the output.
The argument @var{object} can be a function name, a lambda expression
or a byte-code object. If it is a lambda expression, @code{disassemble}
compiles it and disassembles the resulting compiled code.
@end deffn
Here are two examples of using the @code{disassemble} function. We
have added explanatory comments to help you relate the byte-code to the
Lisp source; these do not appear in the output of @code{disassemble}.
These examples show unoptimized byte-code. Nowadays byte-code is
usually optimized, but we did not want to rewrite these examples, since
they still serve their purpose.
@example
@group
(defun factorial (integer)
"Compute factorial of an integer."
(if (= 1 integer) 1
(* integer (factorial (1- integer)))))
@result{} factorial
@end group
@group
(factorial 4)
@result{} 24
@end group
@group
(disassemble 'factorial)
@print{} byte-code for factorial:
doc: Compute factorial of an integer.
args: (integer)
@end group
@group
0 constant 1 ; @r{Push 1 onto stack.}
1 varref integer ; @r{Get value of @code{integer}}
; @r{from the environment}
; @r{and push the value}
; @r{onto the stack.}
@end group
@group
2 eqlsign ; @r{Pop top two values off stack,}
; @r{compare them,}
; @r{and push result onto stack.}
@end group
@group
3 goto-if-nil 10 ; @r{Pop and test top of stack;}
; @r{if @code{nil}, go to 10,}
; @r{else continue.}
@end group
@group
6 constant 1 ; @r{Push 1 onto top of stack.}
7 goto 17 ; @r{Go to 17 (in this case, 1 will be}
; @r{returned by the function).}
@end group
@group
10 constant * ; @r{Push symbol @code{*} onto stack.}
11 varref integer ; @r{Push value of @code{integer} onto stack.}
@end group
@group
12 constant factorial ; @r{Push @code{factorial} onto stack.}
13 varref integer ; @r{Push value of @code{integer} onto stack.}
14 sub1 ; @r{Pop @code{integer}, decrement value,}
; @r{push new value onto stack.}
@end group
@group
; @r{Stack now contains:}
; @minus{} @r{decremented value of @code{integer}}
; @minus{} @r{@code{factorial}}
; @minus{} @r{value of @code{integer}}
; @minus{} @r{@code{*}}
@end group
@group
15 call 1 ; @r{Call function @code{factorial} using}
; @r{the first (i.e., the top) element}
; @r{of the stack as the argument;}
; @r{push returned value onto stack.}
@end group
@group
; @r{Stack now contains:}
; @minus{} @r{result of recursive}
; @r{call to @code{factorial}}
; @minus{} @r{value of @code{integer}}
; @minus{} @r{@code{*}}
@end group
@group
16 call 2 ; @r{Using the first two}
; @r{(i.e., the top two)}
; @r{elements of the stack}
; @r{as arguments,}
; @r{call the function @code{*},}
; @r{pushing the result onto the stack.}
@end group
@group
17 return ; @r{Return the top element}
; @r{of the stack.}
@result{} nil
@end group
@end example
The @code{silly-loop} function is somewhat more complex:
@example
@group
(defun silly-loop (n)
"Return time before and after N iterations of a loop."
(let ((t1 (current-time-string)))
(while (> (setq n (1- n))
0))
(list t1 (current-time-string))))
@result{} silly-loop
@end group
@group
(disassemble 'silly-loop)
@print{} byte-code for silly-loop:
doc: Return time before and after N iterations of a loop.
args: (n)
0 constant current-time-string ; @r{Push}
; @r{@code{current-time-string}}
; @r{onto top of stack.}
@end group
@group
1 call 0 ; @r{Call @code{current-time-string}}
; @r{ with no argument,}
; @r{ pushing result onto stack.}
@end group
@group
2 varbind t1 ; @r{Pop stack and bind @code{t1}}
; @r{to popped value.}
@end group
@group
3 varref n ; @r{Get value of @code{n} from}
; @r{the environment and push}
; @r{the value onto the stack.}
@end group
@group
4 sub1 ; @r{Subtract 1 from top of stack.}
@end group
@group
5 dup ; @r{Duplicate the top of the stack;}
; @r{i.e., copy the top of}
; @r{the stack and push the}
; @r{copy onto the stack.}
@end group
@group
6 varset n ; @r{Pop the top of the stack,}
; @r{and bind @code{n} to the value.}
; @r{In effect, the sequence @code{dup varset}}
; @r{copies the top of the stack}
; @r{into the value of @code{n}}
; @r{without popping it.}
@end group
@group
7 constant 0 ; @r{Push 0 onto stack.}
@end group
@group
8 gtr ; @r{Pop top two values off stack,}
; @r{test if @var{n} is greater than 0}
; @r{and push result onto stack.}
@end group
@group
9 goto-if-nil-else-pop 17 ; @r{Goto 17 if @code{n} <= 0}
; @r{(this exits the while loop).}
; @r{else pop top of stack}
; @r{and continue}
@end group
@group
12 constant nil ; @r{Push @code{nil} onto stack}
; @r{(this is the body of the loop).}
@end group
@group
13 discard ; @r{Discard result of the body}
; @r{of the loop (a while loop}
; @r{is always evaluated for}
; @r{its side effects).}
@end group
@group
14 goto 3 ; @r{Jump back to beginning}
; @r{of while loop.}
@end group
@group
17 discard ; @r{Discard result of while loop}
; @r{by popping top of stack.}
; @r{This result is the value @code{nil} that}
; @r{was not popped by the goto at 9.}
@end group
@group
18 varref t1 ; @r{Push value of @code{t1} onto stack.}
@end group
@group
19 constant current-time-string ; @r{Push}
; @r{@code{current-time-string}}
; @r{onto top of stack.}
@end group
@group
20 call 0 ; @r{Call @code{current-time-string} again.}
@end group
@group
21 list2 ; @r{Pop top two elements off stack,}
; @r{create a list of them,}
; @r{and push list onto stack.}
@end group
@group
22 unbind 1 ; @r{Unbind @code{t1} in local environment.}
23 return ; @r{Return value of the top of stack.}
@result{} nil
@end group
@end example
@ignore
arch-tag: f78e3050-2f0a-4dee-be27-d9979a0a2289
@end ignore

775
doc/lispref/configure vendored Executable file
View file

@ -0,0 +1,775 @@
#! /bin/sh
# Guess values for system-dependent variables and create Makefiles.
# Generated automatically using autoconf version 2.13
# Copyright (C) 1992, 1993, 1994, 1995, 1996, 2001, 2002, 2003, 2004,
# 2005, 2006, 2007 Free Software Foundation, Inc.
#
# This configure script is free software; the Free Software Foundation
# gives unlimited permission to copy, distribute and modify it.
# Defaults:
ac_help=
ac_default_prefix=/usr/local
# Any additions from configure.in:
# Initialize some variables set by options.
# The variables have the same names as the options, with
# dashes changed to underlines.
build=NONE
cache_file=./config.cache
exec_prefix=NONE
host=NONE
no_create=
nonopt=NONE
no_recursion=
prefix=NONE
program_prefix=NONE
program_suffix=NONE
program_transform_name=s,x,x,
silent=
site=
srcdir=
target=NONE
verbose=
x_includes=NONE
x_libraries=NONE
bindir='${exec_prefix}/bin'
sbindir='${exec_prefix}/sbin'
libexecdir='${exec_prefix}/libexec'
datadir='${prefix}/share'
sysconfdir='${prefix}/etc'
sharedstatedir='${prefix}/com'
localstatedir='${prefix}/var'
libdir='${exec_prefix}/lib'
includedir='${prefix}/include'
oldincludedir='/usr/include'
infodir='${prefix}/info'
mandir='${prefix}/man'
# Initialize some other variables.
subdirs=
MFLAGS= MAKEFLAGS=
SHELL=${CONFIG_SHELL-/bin/sh}
# Maximum number of lines to put in a shell here document.
ac_max_here_lines=12
ac_prev=
for ac_option
do
# If the previous option needs an argument, assign it.
if test -n "$ac_prev"; then
eval "$ac_prev=\$ac_option"
ac_prev=
continue
fi
case "$ac_option" in
-*=*) ac_optarg=`echo "$ac_option" | sed 's/[-_a-zA-Z0-9]*=//'` ;;
*) ac_optarg= ;;
esac
# Accept the important Cygnus configure options, so we can diagnose typos.
case "$ac_option" in
-bindir | --bindir | --bindi | --bind | --bin | --bi)
ac_prev=bindir ;;
-bindir=* | --bindir=* | --bindi=* | --bind=* | --bin=* | --bi=*)
bindir="$ac_optarg" ;;
-build | --build | --buil | --bui | --bu)
ac_prev=build ;;
-build=* | --build=* | --buil=* | --bui=* | --bu=*)
build="$ac_optarg" ;;
-cache-file | --cache-file | --cache-fil | --cache-fi \
| --cache-f | --cache- | --cache | --cach | --cac | --ca | --c)
ac_prev=cache_file ;;
-cache-file=* | --cache-file=* | --cache-fil=* | --cache-fi=* \
| --cache-f=* | --cache-=* | --cache=* | --cach=* | --cac=* | --ca=* | --c=*)
cache_file="$ac_optarg" ;;
-datadir | --datadir | --datadi | --datad | --data | --dat | --da)
ac_prev=datadir ;;
-datadir=* | --datadir=* | --datadi=* | --datad=* | --data=* | --dat=* \
| --da=*)
datadir="$ac_optarg" ;;
-disable-* | --disable-*)
ac_feature=`echo $ac_option|sed -e 's/-*disable-//'`
# Reject names that are not valid shell variable names.
if test -n "`echo $ac_feature| sed 's/[-a-zA-Z0-9_]//g'`"; then
{ echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
fi
ac_feature=`echo $ac_feature| sed 's/-/_/g'`
eval "enable_${ac_feature}=no" ;;
-enable-* | --enable-*)
ac_feature=`echo $ac_option|sed -e 's/-*enable-//' -e 's/=.*//'`
# Reject names that are not valid shell variable names.
if test -n "`echo $ac_feature| sed 's/[-_a-zA-Z0-9]//g'`"; then
{ echo "configure: error: $ac_feature: invalid feature name" 1>&2; exit 1; }
fi
ac_feature=`echo $ac_feature| sed 's/-/_/g'`
case "$ac_option" in
*=*) ;;
*) ac_optarg=yes ;;
esac
eval "enable_${ac_feature}='$ac_optarg'" ;;
-exec-prefix | --exec_prefix | --exec-prefix | --exec-prefi \
| --exec-pref | --exec-pre | --exec-pr | --exec-p | --exec- \
| --exec | --exe | --ex)
ac_prev=exec_prefix ;;
-exec-prefix=* | --exec_prefix=* | --exec-prefix=* | --exec-prefi=* \
| --exec-pref=* | --exec-pre=* | --exec-pr=* | --exec-p=* | --exec-=* \
| --exec=* | --exe=* | --ex=*)
exec_prefix="$ac_optarg" ;;
-gas | --gas | --ga | --g)
# Obsolete; use --with-gas.
with_gas=yes ;;
-help | --help | --hel | --he)
# Omit some internal or obsolete options to make the list less imposing.
# This message is too long to be a string in the A/UX 3.1 sh.
cat << EOF
Usage: configure [options] [host]
Options: [defaults in brackets after descriptions]
Configuration:
--cache-file=FILE cache test results in FILE
--help print this message
--no-create do not create output files
--quiet, --silent do not print \`checking...' messages
--version print the version of autoconf that created configure
Directory and file names:
--prefix=PREFIX install architecture-independent files in PREFIX
[$ac_default_prefix]
--exec-prefix=EPREFIX install architecture-dependent files in EPREFIX
[same as prefix]
--bindir=DIR user executables in DIR [EPREFIX/bin]
--sbindir=DIR system admin executables in DIR [EPREFIX/sbin]
--libexecdir=DIR program executables in DIR [EPREFIX/libexec]
--datadir=DIR read-only architecture-independent data in DIR
[PREFIX/share]
--sysconfdir=DIR read-only single-machine data in DIR [PREFIX/etc]
--sharedstatedir=DIR modifiable architecture-independent data in DIR
[PREFIX/com]
--localstatedir=DIR modifiable single-machine data in DIR [PREFIX/var]
--libdir=DIR object code libraries in DIR [EPREFIX/lib]
--includedir=DIR C header files in DIR [PREFIX/include]
--oldincludedir=DIR C header files for non-gcc in DIR [/usr/include]
--infodir=DIR info documentation in DIR [PREFIX/info]
--mandir=DIR man documentation in DIR [PREFIX/man]
--srcdir=DIR find the sources in DIR [configure dir or ..]
--program-prefix=PREFIX prepend PREFIX to installed program names
--program-suffix=SUFFIX append SUFFIX to installed program names
--program-transform-name=PROGRAM
run sed PROGRAM on installed program names
EOF
cat << EOF
Host type:
--build=BUILD configure for building on BUILD [BUILD=HOST]
--host=HOST configure for HOST [guessed]
--target=TARGET configure for TARGET [TARGET=HOST]
Features and packages:
--disable-FEATURE do not include FEATURE (same as --enable-FEATURE=no)
--enable-FEATURE[=ARG] include FEATURE [ARG=yes]
--with-PACKAGE[=ARG] use PACKAGE [ARG=yes]
--without-PACKAGE do not use PACKAGE (same as --with-PACKAGE=no)
--x-includes=DIR X include files are in DIR
--x-libraries=DIR X library files are in DIR
EOF
if test -n "$ac_help"; then
echo "--enable and --with options recognized:$ac_help"
fi
exit 0 ;;
-host | --host | --hos | --ho)
ac_prev=host ;;
-host=* | --host=* | --hos=* | --ho=*)
host="$ac_optarg" ;;
-includedir | --includedir | --includedi | --included | --include \
| --includ | --inclu | --incl | --inc)
ac_prev=includedir ;;
-includedir=* | --includedir=* | --includedi=* | --included=* | --include=* \
| --includ=* | --inclu=* | --incl=* | --inc=*)
includedir="$ac_optarg" ;;
-infodir | --infodir | --infodi | --infod | --info | --inf)
ac_prev=infodir ;;
-infodir=* | --infodir=* | --infodi=* | --infod=* | --info=* | --inf=*)
infodir="$ac_optarg" ;;
-libdir | --libdir | --libdi | --libd)
ac_prev=libdir ;;
-libdir=* | --libdir=* | --libdi=* | --libd=*)
libdir="$ac_optarg" ;;
-libexecdir | --libexecdir | --libexecdi | --libexecd | --libexec \
| --libexe | --libex | --libe)
ac_prev=libexecdir ;;
-libexecdir=* | --libexecdir=* | --libexecdi=* | --libexecd=* | --libexec=* \
| --libexe=* | --libex=* | --libe=*)
libexecdir="$ac_optarg" ;;
-localstatedir | --localstatedir | --localstatedi | --localstated \
| --localstate | --localstat | --localsta | --localst \
| --locals | --local | --loca | --loc | --lo)
ac_prev=localstatedir ;;
-localstatedir=* | --localstatedir=* | --localstatedi=* | --localstated=* \
| --localstate=* | --localstat=* | --localsta=* | --localst=* \
| --locals=* | --local=* | --loca=* | --loc=* | --lo=*)
localstatedir="$ac_optarg" ;;
-mandir | --mandir | --mandi | --mand | --man | --ma | --m)
ac_prev=mandir ;;
-mandir=* | --mandir=* | --mandi=* | --mand=* | --man=* | --ma=* | --m=*)
mandir="$ac_optarg" ;;
-nfp | --nfp | --nf)
# Obsolete; use --without-fp.
with_fp=no ;;
-no-create | --no-create | --no-creat | --no-crea | --no-cre \
| --no-cr | --no-c)
no_create=yes ;;
-no-recursion | --no-recursion | --no-recursio | --no-recursi \
| --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r)
no_recursion=yes ;;
-oldincludedir | --oldincludedir | --oldincludedi | --oldincluded \
| --oldinclude | --oldinclud | --oldinclu | --oldincl | --oldinc \
| --oldin | --oldi | --old | --ol | --o)
ac_prev=oldincludedir ;;
-oldincludedir=* | --oldincludedir=* | --oldincludedi=* | --oldincluded=* \
| --oldinclude=* | --oldinclud=* | --oldinclu=* | --oldincl=* | --oldinc=* \
| --oldin=* | --oldi=* | --old=* | --ol=* | --o=*)
oldincludedir="$ac_optarg" ;;
-prefix | --prefix | --prefi | --pref | --pre | --pr | --p)
ac_prev=prefix ;;
-prefix=* | --prefix=* | --prefi=* | --pref=* | --pre=* | --pr=* | --p=*)
prefix="$ac_optarg" ;;
-program-prefix | --program-prefix | --program-prefi | --program-pref \
| --program-pre | --program-pr | --program-p)
ac_prev=program_prefix ;;
-program-prefix=* | --program-prefix=* | --program-prefi=* \
| --program-pref=* | --program-pre=* | --program-pr=* | --program-p=*)
program_prefix="$ac_optarg" ;;
-program-suffix | --program-suffix | --program-suffi | --program-suff \
| --program-suf | --program-su | --program-s)
ac_prev=program_suffix ;;
-program-suffix=* | --program-suffix=* | --program-suffi=* \
| --program-suff=* | --program-suf=* | --program-su=* | --program-s=*)
program_suffix="$ac_optarg" ;;
-program-transform-name | --program-transform-name \
| --program-transform-nam | --program-transform-na \
| --program-transform-n | --program-transform- \
| --program-transform | --program-transfor \
| --program-transfo | --program-transf \
| --program-trans | --program-tran \
| --progr-tra | --program-tr | --program-t)
ac_prev=program_transform_name ;;
-program-transform-name=* | --program-transform-name=* \
| --program-transform-nam=* | --program-transform-na=* \
| --program-transform-n=* | --program-transform-=* \
| --program-transform=* | --program-transfor=* \
| --program-transfo=* | --program-transf=* \
| --program-trans=* | --program-tran=* \
| --progr-tra=* | --program-tr=* | --program-t=*)
program_transform_name="$ac_optarg" ;;
-q | -quiet | --quiet | --quie | --qui | --qu | --q \
| -silent | --silent | --silen | --sile | --sil)
silent=yes ;;
-sbindir | --sbindir | --sbindi | --sbind | --sbin | --sbi | --sb)
ac_prev=sbindir ;;
-sbindir=* | --sbindir=* | --sbindi=* | --sbind=* | --sbin=* \
| --sbi=* | --sb=*)
sbindir="$ac_optarg" ;;
-sharedstatedir | --sharedstatedir | --sharedstatedi \
| --sharedstated | --sharedstate | --sharedstat | --sharedsta \
| --sharedst | --shareds | --shared | --share | --shar \
| --sha | --sh)
ac_prev=sharedstatedir ;;
-sharedstatedir=* | --sharedstatedir=* | --sharedstatedi=* \
| --sharedstated=* | --sharedstate=* | --sharedstat=* | --sharedsta=* \
| --sharedst=* | --shareds=* | --shared=* | --share=* | --shar=* \
| --sha=* | --sh=*)
sharedstatedir="$ac_optarg" ;;
-site | --site | --sit)
ac_prev=site ;;
-site=* | --site=* | --sit=*)
site="$ac_optarg" ;;
-srcdir | --srcdir | --srcdi | --srcd | --src | --sr)
ac_prev=srcdir ;;
-srcdir=* | --srcdir=* | --srcdi=* | --srcd=* | --src=* | --sr=*)
srcdir="$ac_optarg" ;;
-sysconfdir | --sysconfdir | --sysconfdi | --sysconfd | --sysconf \
| --syscon | --sysco | --sysc | --sys | --sy)
ac_prev=sysconfdir ;;
-sysconfdir=* | --sysconfdir=* | --sysconfdi=* | --sysconfd=* | --sysconf=* \
| --syscon=* | --sysco=* | --sysc=* | --sys=* | --sy=*)
sysconfdir="$ac_optarg" ;;
-target | --target | --targe | --targ | --tar | --ta | --t)
ac_prev=target ;;
-target=* | --target=* | --targe=* | --targ=* | --tar=* | --ta=* | --t=*)
target="$ac_optarg" ;;
-v | -verbose | --verbose | --verbos | --verbo | --verb)
verbose=yes ;;
-version | --version | --versio | --versi | --vers)
echo "configure generated by autoconf version 2.13"
exit 0 ;;
-with-* | --with-*)
ac_package=`echo $ac_option|sed -e 's/-*with-//' -e 's/=.*//'`
# Reject names that are not valid shell variable names.
if test -n "`echo $ac_package| sed 's/[-_a-zA-Z0-9]//g'`"; then
{ echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
fi
ac_package=`echo $ac_package| sed 's/-/_/g'`
case "$ac_option" in
*=*) ;;
*) ac_optarg=yes ;;
esac
eval "with_${ac_package}='$ac_optarg'" ;;
-without-* | --without-*)
ac_package=`echo $ac_option|sed -e 's/-*without-//'`
# Reject names that are not valid shell variable names.
if test -n "`echo $ac_package| sed 's/[-a-zA-Z0-9_]//g'`"; then
{ echo "configure: error: $ac_package: invalid package name" 1>&2; exit 1; }
fi
ac_package=`echo $ac_package| sed 's/-/_/g'`
eval "with_${ac_package}=no" ;;
--x)
# Obsolete; use --with-x.
with_x=yes ;;
-x-includes | --x-includes | --x-include | --x-includ | --x-inclu \
| --x-incl | --x-inc | --x-in | --x-i)
ac_prev=x_includes ;;
-x-includes=* | --x-includes=* | --x-include=* | --x-includ=* | --x-inclu=* \
| --x-incl=* | --x-inc=* | --x-in=* | --x-i=*)
x_includes="$ac_optarg" ;;
-x-libraries | --x-libraries | --x-librarie | --x-librari \
| --x-librar | --x-libra | --x-libr | --x-lib | --x-li | --x-l)
ac_prev=x_libraries ;;
-x-libraries=* | --x-libraries=* | --x-librarie=* | --x-librari=* \
| --x-librar=* | --x-libra=* | --x-libr=* | --x-lib=* | --x-li=* | --x-l=*)
x_libraries="$ac_optarg" ;;
-*) { echo "configure: error: $ac_option: invalid option; use --help to show usage" 1>&2; exit 1; }
;;
*)
if test -n "`echo $ac_option| sed 's/[-a-z0-9.]//g'`"; then
echo "configure: warning: $ac_option: invalid host type" 1>&2
fi
if test "x$nonopt" != xNONE; then
{ echo "configure: error: can only configure for one host and one target at a time" 1>&2; exit 1; }
fi
nonopt="$ac_option"
;;
esac
done
if test -n "$ac_prev"; then
{ echo "configure: error: missing argument to --`echo $ac_prev | sed 's/_/-/g'`" 1>&2; exit 1; }
fi
trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
# File descriptor usage:
# 0 standard input
# 1 file creation
# 2 errors and warnings
# 3 some systems may open it to /dev/tty
# 4 used on the Kubota Titan
# 6 checking for... messages and results
# 5 compiler messages saved in config.log
if test "$silent" = yes; then
exec 6>/dev/null
else
exec 6>&1
fi
exec 5>./config.log
echo "\
This file contains any messages produced by compilers while
running configure, to aid debugging if configure makes a mistake.
" 1>&5
# Strip out --no-create and --no-recursion so they do not pile up.
# Also quote any args containing shell metacharacters.
ac_configure_args=
for ac_arg
do
case "$ac_arg" in
-no-create | --no-create | --no-creat | --no-crea | --no-cre \
| --no-cr | --no-c) ;;
-no-recursion | --no-recursion | --no-recursio | --no-recursi \
| --no-recurs | --no-recur | --no-recu | --no-rec | --no-re | --no-r) ;;
*" "*|*" "*|*[\[\]\~\#\$\^\&\*\(\)\{\}\\\|\;\<\>\?]*)
ac_configure_args="$ac_configure_args '$ac_arg'" ;;
*) ac_configure_args="$ac_configure_args $ac_arg" ;;
esac
done
# NLS nuisances.
# Only set these to C if already set. These must not be set unconditionally
# because not all systems understand e.g. LANG=C (notably SCO).
# Fixing LC_MESSAGES prevents Solaris sh from translating var values in `set'!
# Non-C LC_CTYPE values break the ctype check.
if test "${LANG+set}" = set; then LANG=C; export LANG; fi
if test "${LC_ALL+set}" = set; then LC_ALL=C; export LC_ALL; fi
if test "${LC_MESSAGES+set}" = set; then LC_MESSAGES=C; export LC_MESSAGES; fi
if test "${LC_CTYPE+set}" = set; then LC_CTYPE=C; export LC_CTYPE; fi
# confdefs.h avoids OS command line length limits that DEFS can exceed.
rm -rf conftest* confdefs.h
# AIX cpp loses on an empty file, so make sure it contains at least a newline.
echo > confdefs.h
# A filename unique to this package, relative to the directory that
# configure is in, which we can look for to find out if srcdir is correct.
ac_unique_file=elisp.texi
# Find the source files, if location was not specified.
if test -z "$srcdir"; then
ac_srcdir_defaulted=yes
# Try the directory containing this script, then its parent.
ac_prog=$0
ac_confdir=`echo $ac_prog|sed 's%/[^/][^/]*$%%'`
test "x$ac_confdir" = "x$ac_prog" && ac_confdir=.
srcdir=$ac_confdir
if test ! -r $srcdir/$ac_unique_file; then
srcdir=..
fi
else
ac_srcdir_defaulted=no
fi
if test ! -r $srcdir/$ac_unique_file; then
if test "$ac_srcdir_defaulted" = yes; then
{ echo "configure: error: can not find sources in $ac_confdir or .." 1>&2; exit 1; }
else
{ echo "configure: error: can not find sources in $srcdir" 1>&2; exit 1; }
fi
fi
srcdir=`echo "${srcdir}" | sed 's%\([^/]\)/*$%\1%'`
# Prefer explicitly selected file to automatically selected ones.
if test -z "$CONFIG_SITE"; then
if test "x$prefix" != xNONE; then
CONFIG_SITE="$prefix/share/config.site $prefix/etc/config.site"
else
CONFIG_SITE="$ac_default_prefix/share/config.site $ac_default_prefix/etc/config.site"
fi
fi
for ac_site_file in $CONFIG_SITE; do
if test -r "$ac_site_file"; then
echo "loading site script $ac_site_file"
. "$ac_site_file"
fi
done
if test -r "$cache_file"; then
echo "loading cache $cache_file"
. $cache_file
else
echo "creating cache $cache_file"
> $cache_file
fi
ac_ext=c
# CFLAGS is not in ac_cpp because -g, -O, etc. are not valid cpp options.
ac_cpp='$CPP $CPPFLAGS'
ac_compile='${CC-cc} -c $CFLAGS $CPPFLAGS conftest.$ac_ext 1>&5'
ac_link='${CC-cc} -o conftest${ac_exeext} $CFLAGS $CPPFLAGS $LDFLAGS conftest.$ac_ext $LIBS 1>&5'
cross_compiling=$ac_cv_prog_cc_cross
ac_exeext=
ac_objext=o
if (echo "testing\c"; echo 1,2,3) | grep c >/dev/null; then
# Stardent Vistra SVR4 grep lacks -e, says ghazi@caip.rutgers.edu.
if (echo -n testing; echo 1,2,3) | sed s/-n/xn/ | grep xn >/dev/null; then
ac_n= ac_c='
' ac_t=' '
else
ac_n=-n ac_c= ac_t=
fi
else
ac_n= ac_c='\c' ac_t=
fi
trap '' 1 2 15
cat > confcache <<\EOF
# This file is a shell script that caches the results of configure
# tests run on this system so they can be shared between configure
# scripts and configure runs. It is not useful on other systems.
# If it contains results you don't want to keep, you may remove or edit it.
#
# By default, configure uses ./config.cache as the cache file,
# creating it if it does not exist already. You can give configure
# the --cache-file=FILE option to use a different cache file; that is
# what configure does when it calls configure scripts in
# subdirectories, so they share the cache.
# Giving --cache-file=/dev/null disables caching, for debugging configure.
# config.status only pays attention to the cache file if you give it the
# --recheck option to rerun configure.
#
EOF
# The following way of writing the cache mishandles newlines in values,
# but we know of no workaround that is simple, portable, and efficient.
# So, don't put newlines in cache variables' values.
# Ultrix sh set writes to stderr and can't be redirected directly,
# and sets the high bit in the cache file unless we assign to the vars.
(set) 2>&1 |
case `(ac_space=' '; set | grep ac_space) 2>&1` in
*ac_space=\ *)
# `set' does not quote correctly, so add quotes (double-quote substitution
# turns \\\\ into \\, and sed turns \\ into \).
sed -n \
-e "s/'/'\\\\''/g" \
-e "s/^\\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\\)=\\(.*\\)/\\1=\${\\1='\\2'}/p"
;;
*)
# `set' quotes correctly as required by POSIX, so do not add quotes.
sed -n -e 's/^\([a-zA-Z0-9_]*_cv_[a-zA-Z0-9_]*\)=\(.*\)/\1=${\1=\2}/p'
;;
esac >> confcache
if cmp -s $cache_file confcache; then
:
else
if test -w $cache_file; then
echo "updating cache $cache_file"
cat confcache > $cache_file
else
echo "not updating unwritable cache $cache_file"
fi
fi
rm -f confcache
trap 'rm -fr conftest* confdefs* core core.* *.core $ac_clean_files; exit 1' 1 2 15
test "x$prefix" = xNONE && prefix=$ac_default_prefix
# Let make expand exec_prefix.
test "x$exec_prefix" = xNONE && exec_prefix='${prefix}'
# Any assignment to VPATH causes Sun make to only execute
# the first set of double-colon rules, so remove it if not needed.
# If there is a colon in the path, we need to keep it.
if test "x$srcdir" = x.; then
ac_vpsub='/^[ ]*VPATH[ ]*=[^:]*$/d'
fi
trap 'rm -f $CONFIG_STATUS conftest*; exit 1' 1 2 15
# Transform confdefs.h into DEFS.
# Protect against shell expansion while executing Makefile rules.
# Protect against Makefile macro expansion.
cat > conftest.defs <<\EOF
s%#define \([A-Za-z_][A-Za-z0-9_]*\) *\(.*\)%-D\1=\2%g
s%[ `~#$^&*(){}\\|;'"<>?]%\\&%g
s%\[%\\&%g
s%\]%\\&%g
s%\$%$$%g
EOF
DEFS=`sed -f conftest.defs confdefs.h | tr '\012' ' '`
rm -f conftest.defs
# Without the "./", some shells look in PATH for config.status.
: ${CONFIG_STATUS=./config.status}
echo creating $CONFIG_STATUS
rm -f $CONFIG_STATUS
cat > $CONFIG_STATUS <<EOF
#! /bin/sh
# Generated automatically by configure.
# Run this file to recreate the current configuration.
# This directory was configured as follows,
# on host `(hostname || uname -n) 2>/dev/null | sed 1q`:
#
# $0 $ac_configure_args
#
# Compiler output produced by configure, useful for debugging
# configure, is in ./config.log if it exists.
ac_cs_usage="Usage: $CONFIG_STATUS [--recheck] [--version] [--help]"
for ac_option
do
case "\$ac_option" in
-recheck | --recheck | --rechec | --reche | --rech | --rec | --re | --r)
echo "running \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion"
exec \${CONFIG_SHELL-/bin/sh} $0 $ac_configure_args --no-create --no-recursion ;;
-version | --version | --versio | --versi | --vers | --ver | --ve | --v)
echo "$CONFIG_STATUS generated by autoconf version 2.13"
exit 0 ;;
-help | --help | --hel | --he | --h)
echo "\$ac_cs_usage"; exit 0 ;;
*) echo "\$ac_cs_usage"; exit 1 ;;
esac
done
ac_given_srcdir=$srcdir
trap 'rm -fr `echo "Makefile" | sed "s/:[^ ]*//g"` conftest*; exit 1' 1 2 15
EOF
cat >> $CONFIG_STATUS <<EOF
# Protect against being on the right side of a sed subst in config.status.
sed 's/%@/@@/; s/@%/@@/; s/%g\$/@g/; /@g\$/s/[\\\\&%]/\\\\&/g;
s/@@/%@/; s/@@/@%/; s/@g\$/%g/' > conftest.subs <<\\CEOF
$ac_vpsub
$extrasub
s%@SHELL@%$SHELL%g
s%@CFLAGS@%$CFLAGS%g
s%@CPPFLAGS@%$CPPFLAGS%g
s%@CXXFLAGS@%$CXXFLAGS%g
s%@FFLAGS@%$FFLAGS%g
s%@DEFS@%$DEFS%g
s%@LDFLAGS@%$LDFLAGS%g
s%@LIBS@%$LIBS%g
s%@exec_prefix@%$exec_prefix%g
s%@prefix@%$prefix%g
s%@program_transform_name@%$program_transform_name%g
s%@bindir@%$bindir%g
s%@sbindir@%$sbindir%g
s%@libexecdir@%$libexecdir%g
s%@datadir@%$datadir%g
s%@sysconfdir@%$sysconfdir%g
s%@sharedstatedir@%$sharedstatedir%g
s%@localstatedir@%$localstatedir%g
s%@libdir@%$libdir%g
s%@includedir@%$includedir%g
s%@oldincludedir@%$oldincludedir%g
s%@infodir@%$infodir%g
s%@mandir@%$mandir%g
CEOF
EOF
cat >> $CONFIG_STATUS <<\EOF
# Split the substitutions into bite-sized pieces for seds with
# small command number limits, like on Digital OSF/1 and HP-UX.
ac_max_sed_cmds=90 # Maximum number of lines to put in a sed script.
ac_file=1 # Number of current file.
ac_beg=1 # First line for current file.
ac_end=$ac_max_sed_cmds # Line after last line for current file.
ac_more_lines=:
ac_sed_cmds=""
while $ac_more_lines; do
if test $ac_beg -gt 1; then
sed "1,${ac_beg}d; ${ac_end}q" conftest.subs > conftest.s$ac_file
else
sed "${ac_end}q" conftest.subs > conftest.s$ac_file
fi
if test ! -s conftest.s$ac_file; then
ac_more_lines=false
rm -f conftest.s$ac_file
else
if test -z "$ac_sed_cmds"; then
ac_sed_cmds="sed -f conftest.s$ac_file"
else
ac_sed_cmds="$ac_sed_cmds | sed -f conftest.s$ac_file"
fi
ac_file=`expr $ac_file + 1`
ac_beg=$ac_end
ac_end=`expr $ac_end + $ac_max_sed_cmds`
fi
done
if test -z "$ac_sed_cmds"; then
ac_sed_cmds=cat
fi
EOF
cat >> $CONFIG_STATUS <<EOF
CONFIG_FILES=\${CONFIG_FILES-"Makefile"}
EOF
cat >> $CONFIG_STATUS <<\EOF
for ac_file in .. $CONFIG_FILES; do if test "x$ac_file" != x..; then
# Support "outfile[:infile[:infile...]]", defaulting infile="outfile.in".
case "$ac_file" in
*:*) ac_file_in=`echo "$ac_file"|sed 's%[^:]*:%%'`
ac_file=`echo "$ac_file"|sed 's%:.*%%'` ;;
*) ac_file_in="${ac_file}.in" ;;
esac
# Adjust a relative srcdir, top_srcdir, and INSTALL for subdirectories.
# Remove last slash and all that follows it. Not all systems have dirname.
ac_dir=`echo $ac_file|sed 's%/[^/][^/]*$%%'`
if test "$ac_dir" != "$ac_file" && test "$ac_dir" != .; then
# The file is in a subdirectory.
test ! -d "$ac_dir" && mkdir "$ac_dir"
ac_dir_suffix="/`echo $ac_dir|sed 's%^\./%%'`"
# A "../" for each directory in $ac_dir_suffix.
ac_dots=`echo $ac_dir_suffix|sed 's%/[^/]*%../%g'`
else
ac_dir_suffix= ac_dots=
fi
case "$ac_given_srcdir" in
.) srcdir=.
if test -z "$ac_dots"; then top_srcdir=.
else top_srcdir=`echo $ac_dots|sed 's%/$%%'`; fi ;;
/*) srcdir="$ac_given_srcdir$ac_dir_suffix"; top_srcdir="$ac_given_srcdir" ;;
*) # Relative path.
srcdir="$ac_dots$ac_given_srcdir$ac_dir_suffix"
top_srcdir="$ac_dots$ac_given_srcdir" ;;
esac
echo creating "$ac_file"
rm -f "$ac_file"
configure_input="Generated automatically from `echo $ac_file_in|sed 's%.*/%%'` by configure."
case "$ac_file" in
*Makefile*) ac_comsub="1i\\
# $configure_input" ;;
*) ac_comsub= ;;
esac
ac_file_inputs=`echo $ac_file_in|sed -e "s%^%$ac_given_srcdir/%" -e "s%:% $ac_given_srcdir/%g"`
sed -e "$ac_comsub
s%@configure_input@%$configure_input%g
s%@srcdir@%$srcdir%g
s%@top_srcdir@%$top_srcdir%g
" $ac_file_inputs | (eval "$ac_sed_cmds") > $ac_file
fi; done
rm -f conftest.s*
EOF
cat >> $CONFIG_STATUS <<EOF
EOF
cat >> $CONFIG_STATUS <<\EOF
exit 0
EOF
chmod +x $CONFIG_STATUS
rm -fr confdefs* $ac_clean_files
test "$no_create" = yes || ${CONFIG_SHELL-/bin/sh} $CONFIG_STATUS || exit 1

7
doc/lispref/configure.in Normal file
View file

@ -0,0 +1,7 @@
dnl Process this file with autoconf to produce a configure script.
AC_INIT(elisp.texi)
AC_OUTPUT(Makefile)
m4_if(dnl Do not change this comment
arch-tag: 61db4227-0d2b-4c4d-ad54-ca9a1ee518ea
)dnl

1291
doc/lispref/control.texi Normal file
View file

File diff suppressed because it is too large Load diff

1253
doc/lispref/customize.texi Normal file
View file

File diff suppressed because it is too large Load diff

834
doc/lispref/debugging.texi Normal file
View file

@ -0,0 +1,834 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002, 2003,
@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Advising Functions, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
depending on what you are doing with the program when the problem appears.
@itemize @bullet
@item
If the problem occurs when you run the program, you can use a Lisp
debugger to investigate what is happening during execution. In addition
to the ordinary debugger, Emacs comes with a source-level debugger,
Edebug. This chapter describes both of them.
@item
If the problem is syntactic, so that Lisp cannot even read the program,
you can use the Emacs facilities for editing Lisp to localize it.
@item
If the problem occurs when trying to compile the program with the byte
compiler, you need to know how to examine the compiler's input buffer.
@end itemize
@menu
* Debugger:: How the Emacs Lisp debugger is implemented.
* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Test Coverage:: Ensuring you have tested all branches in your code.
* Compilation Errors:: How to find errors that show up in byte compilation.
@end menu
Another useful debugging tool is the dribble file. When a dribble
file is open, Emacs copies all keyboard input characters to that file.
Afterward, you can examine the file to find out what input was used.
@xref{Terminal Input}.
For debugging problems in terminal descriptions, the
@code{open-termscript} function can be useful. @xref{Terminal Output}.
@node Debugger
@section The Lisp Debugger
@cindex debugger for Emacs Lisp
@cindex Lisp debugger
@cindex break
The ordinary @dfn{Lisp debugger} provides the ability to suspend
evaluation of a form. While evaluation is suspended (a state that is
commonly known as a @dfn{break}), you may examine the run time stack,
examine the values of local or global variables, or change those values.
Since a break is a recursive edit, all the usual editing facilities of
Emacs are available; you can even run programs that will enter the
debugger recursively. @xref{Recursive Editing}.
@menu
* Error Debugging:: Entering the debugger when an error happens.
* Infinite Loops:: Stopping and debugging a program that doesn't exit.
* Function Debugging:: Entering it when a certain function is called.
* Explicit Debug:: Entering it at a certain point in the program.
* Using Debugger:: What the debugger does; what you see while in it.
* Debugger Commands:: Commands used while in the debugger.
* Invoking the Debugger:: How to call the function @code{debug}.
* Internals of Debugger:: Subroutines of the debugger, and global variables.
@end menu
@node Error Debugging
@subsection Entering the Debugger on an Error
@cindex error debugging
@cindex debugging errors
The most important time to enter the debugger is when a Lisp error
happens. This allows you to investigate the immediate causes of the
error.
However, entry to the debugger is not a normal consequence of an
error. Many commands frequently cause Lisp errors when invoked
inappropriately (such as @kbd{C-f} at the end of the buffer), and during
ordinary editing it would be very inconvenient to enter the debugger
each time this happens. So if you want errors to enter the debugger, set
the variable @code{debug-on-error} to non-@code{nil}. (The command
@code{toggle-debug-on-error} provides an easy way to do this.)
@defopt debug-on-error
This variable determines whether the debugger is called when an error is
signaled and not handled. If @code{debug-on-error} is @code{t}, all
kinds of errors call the debugger (except those listed in
@code{debug-ignored-errors}). If it is @code{nil}, none call the
debugger.
The value can also be a list of error conditions that should call the
debugger. For example, if you set it to the list
@code{(void-variable)}, then only errors about a variable that has no
value invoke the debugger.
When this variable is non-@code{nil}, Emacs does not create an error
handler around process filter functions and sentinels. Therefore,
errors in these functions also invoke the debugger. @xref{Processes}.
@end defopt
@defopt debug-ignored-errors
This variable specifies certain kinds of errors that should not enter
the debugger. Its value is a list of error condition symbols and/or
regular expressions. If the error has any of those condition symbols,
or if the error message matches any of the regular expressions, then
that error does not enter the debugger, regardless of the value of
@code{debug-on-error}.
The normal value of this variable lists several errors that happen often
during editing but rarely result from bugs in Lisp programs. However,
``rarely'' is not ``never''; if your program fails with an error that
matches this list, you will need to change this list in order to debug
the error. The easiest way is usually to set
@code{debug-ignored-errors} to @code{nil}.
@end defopt
@defopt eval-expression-debug-on-error
If this variable has a non-@code{nil} value, then
@code{debug-on-error} is set to @code{t} when evaluating with the
command @code{eval-expression}. If
@code{eval-expression-debug-on-error} is @code{nil}, then the value of
@code{debug-on-error} is not changed. @xref{Lisp Eval,, Evaluating
Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}.
@end defopt
@defopt debug-on-signal
Normally, errors that are caught by @code{condition-case} never run the
debugger, even if @code{debug-on-error} is non-@code{nil}. In other
words, @code{condition-case} gets a chance to handle the error before
the debugger gets a chance.
If you set @code{debug-on-signal} to a non-@code{nil} value, then the
debugger gets the first chance at every error; an error will invoke the
debugger regardless of any @code{condition-case}, if it fits the
criteria specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medicine! Various parts of
Emacs handle errors in the normal course of affairs, and you may not
even realize that errors happen there. If you set
@code{debug-on-signal} to a non-@code{nil} value, those errors will
enter the debugger.
@strong{Warning:} @code{debug-on-signal} has no effect when
@code{debug-on-error} is @code{nil}.
@end defopt
To debug an error that happens during loading of the init
file, use the option @samp{--debug-init}. This binds
@code{debug-on-error} to @code{t} while loading the init file, and
bypasses the @code{condition-case} which normally catches errors in the
init file.
If your init file sets @code{debug-on-error}, the effect may
not last past the end of loading the init file. (This is an undesirable
byproduct of the code that implements the @samp{--debug-init} command
line option.) The best way to make the init file set
@code{debug-on-error} permanently is with @code{after-init-hook}, like
this:
@example
(add-hook 'after-init-hook
(lambda () (setq debug-on-error t)))
@end example
@node Infinite Loops
@subsection Debugging Infinite Loops
@cindex infinite loops
@cindex loops, infinite
@cindex quitting from infinite loop
@cindex stopping an infinite loop
When a program loops infinitely and fails to return, your first
problem is to stop the loop. On most operating systems, you can do this
with @kbd{C-g}, which causes a @dfn{quit}.
Ordinary quitting gives no information about why the program was
looping. To get more information, you can set the variable
@code{debug-on-quit} to non-@code{nil}. Quitting with @kbd{C-g} is not
considered an error, and @code{debug-on-error} has no effect on the
handling of @kbd{C-g}. Likewise, @code{debug-on-quit} has no effect on
errors.
Once you have the debugger running in the middle of the infinite loop,
you can proceed from the debugger using the stepping commands. If you
step through the entire loop, you will probably get enough information
to solve the problem.
@defopt debug-on-quit
This variable determines whether the debugger is called when @code{quit}
is signaled and not handled. If @code{debug-on-quit} is non-@code{nil},
then the debugger is called whenever you quit (that is, type @kbd{C-g}).
If @code{debug-on-quit} is @code{nil}, then the debugger is not called
when you quit. @xref{Quitting}.
@end defopt
@node Function Debugging
@subsection Entering the Debugger on a Function Call
@cindex function call debugging
@cindex debugging specific functions
To investigate a problem that happens in the middle of a program, one
useful technique is to enter the debugger whenever a certain function is
called. You can do this to the function in which the problem occurs,
and then step through the function, or you can do this to a function
called shortly before the problem, step quickly over the call to that
function, and then step through its caller.
@deffn Command debug-on-entry function-name
This function requests @var{function-name} to invoke the debugger each
time it is called. It works by inserting the form
@code{(implement-debug-on-entry)} into the function definition as the
first form.
Any function or macro defined as Lisp code may be set to break on
entry, regardless of whether it is interpreted code or compiled code.
If the function is a command, it will enter the debugger when called
from Lisp and when called interactively (after the reading of the
arguments). You can also set debug-on-entry for primitive functions
(i.e., those written in C) this way, but it only takes effect when the
primitive is called from Lisp code. Debug-on-entry is not allowed for
special forms.
When @code{debug-on-entry} is called interactively, it prompts for
@var{function-name} in the minibuffer. If the function is already set
up to invoke the debugger on entry, @code{debug-on-entry} does nothing.
@code{debug-on-entry} always returns @var{function-name}.
@strong{Warning:} if you redefine a function after using
@code{debug-on-entry} on it, the code to enter the debugger is
discarded by the redefinition. In effect, redefining the function
cancels the break-on-entry feature for that function.
Here's an example to illustrate use of this function:
@example
@group
(defun fact (n)
(if (zerop n) 1
(* n (fact (1- n)))))
@result{} fact
@end group
@group
(debug-on-entry 'fact)
@result{} fact
@end group
@group
(fact 3)
@end group
@group
------ Buffer: *Backtrace* ------
Debugger entered--entering a function:
* fact(3)
eval((fact 3))
eval-last-sexp-1(nil)
eval-last-sexp(nil)
call-interactively(eval-last-sexp)
------ Buffer: *Backtrace* ------
@end group
@group
(symbol-function 'fact)
@result{} (lambda (n)
(debug (quote debug))
(if (zerop n) 1 (* n (fact (1- n)))))
@end group
@end example
@end deffn
@deffn Command cancel-debug-on-entry &optional function-name
This function undoes the effect of @code{debug-on-entry} on
@var{function-name}. When called interactively, it prompts for
@var{function-name} in the minibuffer. If @var{function-name} is
omitted or @code{nil}, it cancels break-on-entry for all functions.
Calling @code{cancel-debug-on-entry} does nothing to a function which is
not currently set up to break on entry.
@end deffn
@node Explicit Debug
@subsection Explicit Entry to the Debugger
You can cause the debugger to be called at a certain point in your
program by writing the expression @code{(debug)} at that point. To do
this, visit the source file, insert the text @samp{(debug)} at the
proper place, and type @kbd{C-M-x} (@code{eval-defun}, a Lisp mode key
binding). @strong{Warning:} if you do this for temporary debugging
purposes, be sure to undo this insertion before you save the file!
The place where you insert @samp{(debug)} must be a place where an
additional form can be evaluated and its value ignored. (If the value
of @code{(debug)} isn't ignored, it will alter the execution of the
program!) The most common suitable places are inside a @code{progn} or
an implicit @code{progn} (@pxref{Sequencing}).
@node Using Debugger
@subsection Using the Debugger
When the debugger is entered, it displays the previously selected
buffer in one window and a buffer named @samp{*Backtrace*} in another
window. The backtrace buffer contains one line for each level of Lisp
function execution currently going on. At the beginning of this buffer
is a message describing the reason that the debugger was invoked (such
as the error message and associated data, if it was invoked due to an
error).
The backtrace buffer is read-only and uses a special major mode,
Debugger mode, in which letters are defined as debugger commands. The
usual Emacs editing commands are available; thus, you can switch windows
to examine the buffer that was being edited at the time of the error,
switch buffers, visit files, or do any other sort of editing. However,
the debugger is a recursive editing level (@pxref{Recursive Editing})
and it is wise to go back to the backtrace buffer and exit the debugger
(with the @kbd{q} command) when you are finished with it. Exiting
the debugger gets out of the recursive edit and kills the backtrace
buffer.
@cindex current stack frame
The backtrace buffer shows you the functions that are executing and
their argument values. It also allows you to specify a stack frame by
moving point to the line describing that frame. (A stack frame is the
place where the Lisp interpreter records information about a particular
invocation of a function.) The frame whose line point is on is
considered the @dfn{current frame}. Some of the debugger commands
operate on the current frame. If a line starts with a star, that means
that exiting that frame will call the debugger again. This is useful
for examining the return value of a function.
If a function name is underlined, that means the debugger knows
where its source code is located. You can click @kbd{Mouse-2} on that
name, or move to it and type @key{RET}, to visit the source code.
The debugger itself must be run byte-compiled, since it makes
assumptions about how many stack frames are used for the debugger
itself. These assumptions are false if the debugger is running
interpreted.
@node Debugger Commands
@subsection Debugger Commands
@cindex debugger command list
The debugger buffer (in Debugger mode) provides special commands in
addition to the usual Emacs commands. The most important use of
debugger commands is for stepping through code, so that you can see
how control flows. The debugger can step through the control
structures of an interpreted function, but cannot do so in a
byte-compiled function. If you would like to step through a
byte-compiled function, replace it with an interpreted definition of
the same function. (To do this, visit the source for the function and
type @kbd{C-M-x} on its definition.) You cannot use the Lisp debugger
to step through a primitive function.
Here is a list of Debugger mode commands:
@table @kbd
@item c
Exit the debugger and continue execution. When continuing is possible,
it resumes execution of the program as if the debugger had never been
entered (aside from any side-effects that you caused by changing
variable values or data structures while inside the debugger).
Continuing is possible after entry to the debugger due to function entry
or exit, explicit invocation, or quitting. You cannot continue if the
debugger was entered because of an error.
@item d
Continue execution, but enter the debugger the next time any Lisp
function is called. This allows you to step through the
subexpressions of an expression, seeing what values the subexpressions
compute, and what else they do.
The stack frame made for the function call which enters the debugger in
this way will be flagged automatically so that the debugger will be
called again when the frame is exited. You can use the @kbd{u} command
to cancel this flag.
@item b
Flag the current frame so that the debugger will be entered when the
frame is exited. Frames flagged in this way are marked with stars
in the backtrace buffer.
@item u
Don't enter the debugger when the current frame is exited. This
cancels a @kbd{b} command on that frame. The visible effect is to
remove the star from the line in the backtrace buffer.
@item j
Flag the current frame like @kbd{b}. Then continue execution like
@kbd{c}, but temporarily disable break-on-entry for all functions that
are set up to do so by @code{debug-on-entry}.
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
value in the echo area. The debugger alters certain important
variables, and the current buffer, as part of its operation; @kbd{e}
temporarily restores their values from outside the debugger, so you can
examine and change them. This makes the debugger more transparent. By
contrast, @kbd{M-:} does nothing special in the debugger; it shows you
the variable values within the debugger.
@item R
Like @kbd{e}, but also save the result of evaluation in the
buffer @samp{*Debugger-record*}.
@item q
Terminate the program being debugged; return to top-level Emacs
command execution.
If the debugger was entered due to a @kbd{C-g} but you really want
to quit, and not debug, use the @kbd{q} command.
@item r
Return a value from the debugger. The value is computed by reading an
expression with the minibuffer and evaluating it.
The @kbd{r} command is useful when the debugger was invoked due to exit
from a Lisp call frame (as requested with @kbd{b} or by entering the
frame with @kbd{d}); then the value specified in the @kbd{r} command is
used as the value of that frame. It is also useful if you call
@code{debug} and use its return value. Otherwise, @kbd{r} has the same
effect as @kbd{c}, and the specified return value does not matter.
You can't use @kbd{r} when the debugger was entered due to an error.
@item l
Display a list of functions that will invoke the debugger when called.
This is a list of functions that are set to break on entry by means of
@code{debug-on-entry}. @strong{Warning:} if you redefine such a
function and thus cancel the effect of @code{debug-on-entry}, it may
erroneously show up in this list.
@end table
@node Invoking the Debugger
@subsection Invoking the Debugger
Here we describe in full detail the function @code{debug} that is used
to invoke the debugger.
@defun debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
named @samp{*Backtrace*} (or @samp{*Backtrace*<2>} if it is the second
recursive entry to the debugger, etc.), and fills it with information
about the stack of Lisp function calls. It then enters a recursive
edit, showing the backtrace buffer in Debugger mode.
The Debugger mode @kbd{c}, @kbd{d}, @kbd{j}, and @kbd{r} commands exit
the recursive edit; then @code{debug} switches back to the previous
buffer and returns to whatever called @code{debug}. This is the only
way the function @code{debug} can return to its caller.
The use of the @var{debugger-args} is that @code{debug} displays the
rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
that the user can see them. Except as described below, this is the
@emph{only} way these arguments are used.
However, certain values for first argument to @code{debug} have a
special significance. (Normally, these values are used only by the
internals of Emacs, and not by programmers calling @code{debug}.) Here
is a table of these special values:
@table @code
@item lambda
@cindex @code{lambda} in debug
A first argument of @code{lambda} means @code{debug} was called
because of entry to a function when @code{debug-on-next-call} was
non-@code{nil}. The debugger displays @samp{Debugger
entered--entering a function:} as a line of text at the top of the
buffer.
@item debug
@code{debug} as first argument means @code{debug} was called because
of entry to a function that was set to debug on entry. The debugger
displays the string @samp{Debugger entered--entering a function:},
just as in the @code{lambda} case. It also marks the stack frame for
that function so that it will invoke the debugger when exited.
@item t
When the first argument is @code{t}, this indicates a call to
@code{debug} due to evaluation of a function call form when
@code{debug-on-next-call} is non-@code{nil}. The debugger displays
@samp{Debugger entered--beginning evaluation of function call form:}
as the top line in the buffer.
@item exit
When the first argument is @code{exit}, it indicates the exit of a
stack frame previously marked to invoke the debugger on exit. The
second argument given to @code{debug} in this case is the value being
returned from the frame. The debugger displays @samp{Debugger
entered--returning value:} in the top line of the buffer, followed by
the value being returned.
@item error
@cindex @code{error} in debug
When the first argument is @code{error}, the debugger indicates that
it is being entered because an error or @code{quit} was signaled and
not handled, by displaying @samp{Debugger entered--Lisp error:}
followed by the error signaled and any arguments to @code{signal}.
For example,
@example
@group
(let ((debug-on-error t))
(/ 1 0))
@end group
@group
------ Buffer: *Backtrace* ------
Debugger entered--Lisp error: (arith-error)
/(1 0)
...
------ Buffer: *Backtrace* ------
@end group
@end example
If an error was signaled, presumably the variable
@code{debug-on-error} is non-@code{nil}. If @code{quit} was signaled,
then presumably the variable @code{debug-on-quit} is non-@code{nil}.
@item nil
Use @code{nil} as the first of the @var{debugger-args} when you want
to enter the debugger explicitly. The rest of the @var{debugger-args}
are printed on the top line of the buffer. You can use this feature to
display messages---for example, to remind yourself of the conditions
under which @code{debug} is called.
@end table
@end defun
@node Internals of Debugger
@subsection Internals of the Debugger
This section describes functions and variables used internally by the
debugger.
@defvar debugger
The value of this variable is the function to call to invoke the
debugger. Its value must be a function of any number of arguments, or,
more typically, the name of a function. This function should invoke
some kind of debugger. The default value of the variable is
@code{debug}.
The first argument that Lisp hands to the function indicates why it
was called. The convention for arguments is detailed in the description
of @code{debug} (@pxref{Invoking the Debugger}).
@end defvar
@deffn Command backtrace
@cindex run time stack
@cindex call stack
This function prints a trace of Lisp function calls currently active.
This is the function used by @code{debug} to fill up the
@samp{*Backtrace*} buffer. It is written in C, since it must have access
to the stack to determine which function calls are active. The return
value is always @code{nil}.
In the following example, a Lisp expression calls @code{backtrace}
explicitly. This prints the backtrace to the stream
@code{standard-output}, which, in this case, is the buffer
@samp{backtrace-output}.
Each line of the backtrace represents one function call. The line shows
the values of the function's arguments if they are all known; if they
are still being computed, the line says so. The arguments of special
forms are elided.
@smallexample
@group
(with-output-to-temp-buffer "backtrace-output"
(let ((var 1))
(save-excursion
(setq var (eval '(progn
(1+ var)
(list 'testing (backtrace))))))))
@result{} (testing nil)
@end group
@group
----------- Buffer: backtrace-output ------------
backtrace()
(list ...computing arguments...)
@end group
(progn ...)
eval((progn (1+ var) (list (quote testing) (backtrace))))
(setq ...)
(save-excursion ...)
(let ...)
(with-output-to-temp-buffer ...)
eval((with-output-to-temp-buffer ...))
eval-last-sexp-1(nil)
@group
eval-last-sexp(nil)
call-interactively(eval-last-sexp)
----------- Buffer: backtrace-output ------------
@end group
@end smallexample
@end deffn
@ignore @c Not worth mentioning
@defopt stack-trace-on-error
@cindex stack trace
This variable controls whether Lisp automatically displays a
backtrace buffer after every error that is not handled. A quit signal
counts as an error for this variable. If it is non-@code{nil} then a
backtrace is shown in a pop-up buffer named @samp{*Backtrace*} on every
error. If it is @code{nil}, then a backtrace is not shown.
When a backtrace is shown, that buffer is not selected. If either
@code{debug-on-quit} or @code{debug-on-error} is also non-@code{nil}, then
a backtrace is shown in one buffer, and the debugger is popped up in
another buffer with its own backtrace.
We consider this feature to be obsolete and superseded by the debugger
itself.
@end defopt
@end ignore
@defvar debug-on-next-call
@cindex @code{eval}, and debugging
@cindex @code{apply}, and debugging
@cindex @code{funcall}, and debugging
If this variable is non-@code{nil}, it says to call the debugger before
the next @code{eval}, @code{apply} or @code{funcall}. Entering the
debugger sets @code{debug-on-next-call} to @code{nil}.
The @kbd{d} command in the debugger works by setting this variable.
@end defvar
@defun backtrace-debug level flag
This function sets the debug-on-exit flag of the stack frame @var{level}
levels down the stack, giving it the value @var{flag}. If @var{flag} is
non-@code{nil}, this will cause the debugger to be entered when that
frame later exits. Even a nonlocal exit through that frame will enter
the debugger.
This function is used only by the debugger.
@end defun
@defvar command-debug-status
This variable records the debugging status of the current interactive
command. Each time a command is called interactively, this variable is
bound to @code{nil}. The debugger can set this variable to leave
information for future debugger invocations during the same command
invocation.
The advantage of using this variable rather than an ordinary global
variable is that the data will never carry over to a subsequent command
invocation.
@end defvar
@defun backtrace-frame frame-number
The function @code{backtrace-frame} is intended for use in Lisp
debuggers. It returns information about what computation is happening
in the stack frame @var{frame-number} levels down.
If that frame has not evaluated the arguments yet, or is a special
form, the value is @code{(nil @var{function} @var{arg-forms}@dots{})}.
If that frame has evaluated its arguments and called its function
already, the return value is @code{(t @var{function}
@var{arg-values}@dots{})}.
In the return value, @var{function} is whatever was supplied as the
@sc{car} of the evaluated list, or a @code{lambda} expression in the
case of a macro call. If the function has a @code{&rest} argument, that
is represented as the tail of the list @var{arg-values}.
If @var{frame-number} is out of range, @code{backtrace-frame} returns
@code{nil}.
@end defun
@include edebug.texi
@node Syntax Errors
@section Debugging Invalid Lisp Syntax
@cindex debugging invalid Lisp syntax
The Lisp reader reports invalid syntax, but cannot say where the real
problem is. For example, the error ``End of file during parsing'' in
evaluating an expression indicates an excess of open parentheses (or
square brackets). The reader detects this imbalance at the end of the
file, but it cannot figure out where the close parenthesis should have
been. Likewise, ``Invalid read syntax: ")"'' indicates an excess close
parenthesis or missing open parenthesis, but does not say where the
missing parenthesis belongs. How, then, to find what to change?
If the problem is not simply an imbalance of parentheses, a useful
technique is to try @kbd{C-M-e} at the beginning of each defun, and see
if it goes to the place where that defun appears to end. If it does
not, there is a problem in that defun.
@cindex unbalanced parentheses
@cindex parenthesis mismatch, debugging
However, unmatched parentheses are the most common syntax errors in
Lisp, and we can give further advice for those cases. (In addition,
just moving point through the code with Show Paren mode enabled might
find the mismatch.)
@menu
* Excess Open:: How to find a spurious open paren or missing close.
* Excess Close:: How to find a spurious close paren or missing open.
@end menu
@node Excess Open
@subsection Excess Open Parentheses
The first step is to find the defun that is unbalanced. If there is
an excess open parenthesis, the way to do this is to go to the end of
the file and type @kbd{C-u C-M-u}. This will move you to the
beginning of the first defun that is unbalanced.
The next step is to determine precisely what is wrong. There is no
way to be sure of this except by studying the program, but often the
existing indentation is a clue to where the parentheses should have
been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
and see what moves. @strong{But don't do this yet!} Keep reading,
first.
Before you do this, make sure the defun has enough close parentheses.
Otherwise, @kbd{C-M-q} will get an error, or will reindent all the rest
of the file until the end. So move to the end of the defun and insert a
close parenthesis there. Don't use @kbd{C-M-e} to move there, since
that too will fail to work until the defun is balanced.
Now you can go to the beginning of the defun and type @kbd{C-M-q}.
Usually all the lines from a certain point to the end of the function
will shift to the right. There is probably a missing close parenthesis,
or a superfluous open parenthesis, near that point. (However, don't
assume this is true; study the code to make sure.) Once you have found
the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the old
indentation is probably appropriate to the intended parentheses.
After you think you have fixed the problem, use @kbd{C-M-q} again. If
the old indentation actually fit the intended nesting of parentheses,
and you have put back those parentheses, @kbd{C-M-q} should not change
anything.
@node Excess Close
@subsection Excess Close Parentheses
To deal with an excess close parenthesis, first go to the beginning
of the file, then type @kbd{C-u -1 C-M-u} to find the end of the first
unbalanced defun.
Then find the actual matching close parenthesis by typing @kbd{C-M-f}
at the beginning of that defun. This will leave you somewhere short of
the place where the defun ought to end. It is possible that you will
find a spurious close parenthesis in that vicinity.
If you don't see a problem at that point, the next thing to do is to
type @kbd{C-M-q} at the beginning of the defun. A range of lines will
probably shift left; if so, the missing open parenthesis or spurious
close parenthesis is probably near the first of those lines. (However,
don't assume this is true; study the code to make sure.) Once you have
found the discrepancy, undo the @kbd{C-M-q} with @kbd{C-_}, since the
old indentation is probably appropriate to the intended parentheses.
After you think you have fixed the problem, use @kbd{C-M-q} again. If
the old indentation actually fits the intended nesting of parentheses,
and you have put back those parentheses, @kbd{C-M-q} should not change
anything.
@node Test Coverage
@section Test Coverage
@cindex coverage testing
@findex testcover-start
@findex testcover-mark-all
@findex testcover-next-mark
You can do coverage testing for a file of Lisp code by loading the
@code{testcover} library and using the command @kbd{M-x
testcover-start @key{RET} @var{file} @key{RET}} to instrument the
code. Then test your code by calling it one or more times. Then use
the command @kbd{M-x testcover-mark-all} to display colored highlights
on the code to show where coverage is insufficient. The command
@kbd{M-x testcover-next-mark} will move point forward to the next
highlighted spot.
Normally, a red highlight indicates the form was never completely
evaluated; a brown highlight means it always evaluated to the same
value (meaning there has been little testing of what is done with the
result). However, the red highlight is skipped for forms that can't
possibly complete their evaluation, such as @code{error}. The brown
highlight is skipped for forms that are expected to always evaluate to
the same value, such as @code{(setq x 14)}.
For difficult cases, you can add do-nothing macros to your code to
give advice to the test coverage tool.
@defmac 1value form
Evaluate @var{form} and return its value, but inform coverage testing
that @var{form}'s value should always be the same.
@end defmac
@defmac noreturn form
Evaluate @var{form}, informing coverage testing that @var{form} should
never return. If it ever does return, you get a run-time error.
@end defmac
Edebug also has a coverage testing feature (@pxref{Coverage
Testing}). These features partly duplicate each other, and it would
be cleaner to combine them.
@node Compilation Errors
@section Debugging Problems in Compilation
@cindex debugging byte compilation problems
When an error happens during byte compilation, it is normally due to
invalid syntax in the program you are compiling. The compiler prints a
suitable error message in the @samp{*Compile-Log*} buffer, and then
stops. The message may state a function name in which the error was
found, or it may not. Either way, here is how to find out where in the
file the error occurred.
What you should do is switch to the buffer @w{@samp{ *Compiler Input*}}.
(Note that the buffer name starts with a space, so it does not show
up in @kbd{M-x list-buffers}.) This buffer contains the program being
compiled, and point shows how far the byte compiler was able to read.
If the error was due to invalid Lisp syntax, point shows exactly where
the invalid syntax was @emph{detected}. The cause of the error is not
necessarily near by! Use the techniques in the previous section to find
the error.
If the error was detected while compiling a form that had been read
successfully, then point is located at the end of the form. In this
case, this technique can't localize the error precisely, but can still
show you which function to check.
@ignore
arch-tag: ddc57378-b0e6-4195-b7b6-43f8777395a7
@end ignore

5442
doc/lispref/display.texi Normal file
View file

File diff suppressed because it is too large Load diff

419
doc/lispref/doclicense.texi Normal file
View file

@ -0,0 +1,419 @@
@c -*-texinfo-*-
@node GNU Free Documentation License, GPL, Antinews, Top
@appendix GNU Free Documentation License
@center Version 1.2, November 2002
@display
Copyright (C) 2000,2001,2002 Free Software Foundation, Inc.
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
@end display
@sp 1
@enumerate 0
@item
PREAMBLE
The purpose of this License is to make a manual, textbook, or other
functional and useful document ``free'' in the sense of freedom: to
assure everyone the effective freedom to copy and redistribute it,
with or without modifying it, either commercially or noncommercially.
Secondarily, this License preserves for the author and publisher a way
to get credit for their work, while not being considered responsible
for modifications made by others.
This License is a kind of ``copyleft,'' which means that derivative
works of the document must themselves be free in the same sense. It
complements the GNU General Public License, which is a copyleft
license designed for free software.
We have designed this License in order to use it for manuals for free
software, because free software needs free documentation: a free
program should come with manuals providing the same freedoms that the
software does. But this License is not limited to software manuals;
it can be used for any textual work, regardless of subject matter or
whether it is published as a printed book. We recommend this License
principally for works whose purpose is instruction or reference.
@sp 1
@item
APPLICABILITY AND DEFINITIONS
This License applies to any manual or other work, in any medium, that
contains a notice placed by the copyright holder saying it can be
distributed under the terms of this License. Such a notice grants a
world-wide, royalty-free license, unlimited in duration, to use that
work under the conditions stated herein. The ``Document,'' below,
refers to any such manual or work. Any member of the public is a
licensee, and is addressed as ``you.'' You accept the license if you
copy, modify or distribute the work in a way requiring permission
under copyright law.
A ``Modified Version'' of the Document means any work containing the
Document or a portion of it, either copied verbatim, or with
modifications and/or translated into another language.
A ``Secondary Section'' is a named appendix or a front-matter section of
the Document that deals exclusively with the relationship of the
publishers or authors of the Document to the Document's overall subject
(or to related matters) and contains nothing that could fall directly
within that overall subject. (Thus, if the Document is in part a
textbook of mathematics, a Secondary Section may not explain any
mathematics.) The relationship could be a matter of historical
connection with the subject or with related matters, or of legal,
commercial, philosophical, ethical or political position regarding
them.
The ``Invariant Sections'' are certain Secondary Sections whose titles
are designated, as being those of Invariant Sections, in the notice
that says that the Document is released under this License. If a
section does not fit the above definition of Secondary then it is not
allowed to be designated as Invariant. The Document may contain zero
Invariant Sections. If the Document does not identify any Invariant
Sections then there are none.
The ``Cover Texts'' are certain short passages of text that are listed,
as Front-Cover Texts or Back-Cover Texts, in the notice that says that
the Document is released under this License. A Front-Cover Text may
be at most 5 words, and a Back-Cover Text may be at most 25 words.
A ``Transparent'' copy of the Document means a machine-readable copy,
represented in a format whose specification is available to the
general public, that is suitable for revising the document
straightforwardly with generic text editors or (for images composed of
pixels) generic paint programs or (for drawings) some widely available
drawing editor, and that is suitable for input to text formatters or
for automatic translation to a variety of formats suitable for input
to text formatters. A copy made in an otherwise Transparent file
format whose markup, or absence of markup, has been arranged to thwart
or discourage subsequent modification by readers is not Transparent.
An image format is not Transparent if used for any substantial amount
of text. A copy that is not ``Transparent'' is called ``Opaque.''
Examples of suitable formats for Transparent copies include plain
ASCII without markup, Texinfo input format, LaTeX input format, SGML
or XML using a publicly available DTD, and standard-conforming simple
HTML, PostScript or PDF designed for human modification. Examples of
transparent image formats include PNG, XCF and JPG. Opaque formats
include proprietary formats that can be read and edited only by
proprietary word processors, SGML or XML for which the DTD and/or
processing tools are not generally available, and the
machine-generated HTML, PostScript or PDF produced by some word
processors for output purposes only.
The ``Title Page'' means, for a printed book, the title page itself,
plus such following pages as are needed to hold, legibly, the material
this License requires to appear in the title page. For works in
formats which do not have any title page as such, ``Title Page'' means
the text near the most prominent appearance of the work's title,
preceding the beginning of the body of the text.
A section ``Entitled XYZ'' means a named subunit of the Document whose
title either is precisely XYZ or contains XYZ in parentheses following
text that translates XYZ in another language. (Here XYZ stands for a
specific section name mentioned below, such as ``Acknowledgements,''
``Dedications,'' ``Endorsements,'' or ``History.'') To ``Preserve the Title''
of such a section when you modify the Document means that it remains a
section ``Entitled XYZ'' according to this definition.
The Document may include Warranty Disclaimers next to the notice which
states that this License applies to the Document. These Warranty
Disclaimers are considered to be included by reference in this
License, but only as regards disclaiming warranties: any other
implication that these Warranty Disclaimers may have is void and has
no effect on the meaning of this License.
@sp 1
@item
VERBATIM COPYING
You may copy and distribute the Document in any medium, either
commercially or noncommercially, provided that this License, the
copyright notices, and the license notice saying this License applies
to the Document are reproduced in all copies, and that you add no other
conditions whatsoever to those of this License. You may not use
technical measures to obstruct or control the reading or further
copying of the copies you make or distribute. However, you may accept
compensation in exchange for copies. If you distribute a large enough
number of copies you must also follow the conditions in section 3.
You may also lend copies, under the same conditions stated above, and
you may publicly display copies.
@sp 1
@item
COPYING IN QUANTITY
If you publish printed copies (or copies in media that commonly have
printed covers) of the Document, numbering more than 100, and the
Document's license notice requires Cover Texts, you must enclose the
copies in covers that carry, clearly and legibly, all these Cover
Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
the back cover. Both covers must also clearly and legibly identify
you as the publisher of these copies. The front cover must present
the full title with all words of the title equally prominent and
visible. You may add other material on the covers in addition.
Copying with changes limited to the covers, as long as they preserve
the title of the Document and satisfy these conditions, can be treated
as verbatim copying in other respects.
If the required texts for either cover are too voluminous to fit
legibly, you should put the first ones listed (as many as fit
reasonably) on the actual cover, and continue the rest onto adjacent
pages.
If you publish or distribute Opaque copies of the Document numbering
more than 100, you must either include a machine-readable Transparent
copy along with each Opaque copy, or state in or with each Opaque copy
a computer-network location from which the general network-using
public has access to download using public-standard network protocols
a complete Transparent copy of the Document, free of added material.
If you use the latter option, you must take reasonably prudent steps,
when you begin distribution of Opaque copies in quantity, to ensure
that this Transparent copy will remain thus accessible at the stated
location until at least one year after the last time you distribute an
Opaque copy (directly or through your agents or retailers) of that
edition to the public.
It is requested, but not required, that you contact the authors of the
Document well before redistributing any large number of copies, to give
them a chance to provide you with an updated version of the Document.
@sp 1
@item
MODIFICATIONS
You may copy and distribute a Modified Version of the Document under
the conditions of sections 2 and 3 above, provided that you release
the Modified Version under precisely this License, with the Modified
Version filling the role of the Document, thus licensing distribution
and modification of the Modified Version to whoever possesses a copy
of it. In addition, you must do these things in the Modified Version:
A. Use in the Title Page (and on the covers, if any) a title distinct
from that of the Document, and from those of previous versions
(which should, if there were any, be listed in the History section
of the Document). You may use the same title as a previous version
if the original publisher of that version gives permission.@*
B. List on the Title Page, as authors, one or more persons or entities
responsible for authorship of the modifications in the Modified
Version, together with at least five of the principal authors of the
Document (all of its principal authors, if it has fewer than five),
unless they release you from this requirement.@*
C. State on the Title page the name of the publisher of the
Modified Version, as the publisher.@*
D. Preserve all the copyright notices of the Document.@*
E. Add an appropriate copyright notice for your modifications
adjacent to the other copyright notices.@*
F. Include, immediately after the copyright notices, a license notice
giving the public permission to use the Modified Version under the
terms of this License, in the form shown in the Addendum below.@*
G. Preserve in that license notice the full lists of Invariant Sections
and required Cover Texts given in the Document's license notice.@*
H. Include an unaltered copy of this License.@*
I. Preserve the section Entitled ``History,'' Preserve its Title, and add
to it an item stating at least the title, year, new authors, and
publisher of the Modified Version as given on the Title Page. If
there is no section Entitled ``History'' in the Document, create one
stating the title, year, authors, and publisher of the Document as
given on its Title Page, then add an item describing the Modified
Version as stated in the previous sentence.@*
J. Preserve the network location, if any, given in the Document for
public access to a Transparent copy of the Document, and likewise
the network locations given in the Document for previous versions
it was based on. These may be placed in the ``History'' section.
You may omit a network location for a work that was published at
least four years before the Document itself, or if the original
publisher of the version it refers to gives permission.@*
K. For any section Entitled ``Acknowledgements'' or ``Dedications,''
Preserve the Title of the section, and preserve in the section all
the substance and tone of each of the contributor acknowledgements
and/or dedications given therein.@*
L. Preserve all the Invariant Sections of the Document,
unaltered in their text and in their titles. Section numbers
or the equivalent are not considered part of the section titles.@*
M. Delete any section Entitled ``Endorsements.'' Such a section
may not be included in the Modified Version.@*
N. Do not retitle any existing section to be Entitled ``Endorsements''
or to conflict in title with any Invariant Section.@*
O. Preserve any Warranty Disclaimers.@*
@sp 1
If the Modified Version includes new front-matter sections or
appendices that qualify as Secondary Sections and contain no material
copied from the Document, you may at your option designate some or all
of these sections as invariant. To do this, add their titles to the
list of Invariant Sections in the Modified Version's license notice.
These titles must be distinct from any other section titles.
You may add a section Entitled ``Endorsements,'' provided it contains
nothing but endorsements of your Modified Version by various
parties--for example, statements of peer review or that the text has
been approved by an organization as the authoritative definition of a
standard.
You may add a passage of up to five words as a Front-Cover Text, and a
passage of up to 25 words as a Back-Cover Text, to the end of the list
of Cover Texts in the Modified Version. Only one passage of
Front-Cover Text and one of Back-Cover Text may be added by (or
through arrangements made by) any one entity. If the Document already
includes a cover text for the same cover, previously added by you or
by arrangement made by the same entity you are acting on behalf of,
you may not add another; but you may replace the old one, on explicit
permission from the previous publisher that added the old one.
The author(s) and publisher(s) of the Document do not by this License
give permission to use their names for publicity for or to assert or
imply endorsement of any Modified Version.
@sp 1
@item
COMBINING DOCUMENTS
You may combine the Document with other documents released under this
License, under the terms defined in section 4 above for modified
versions, provided that you include in the combination all of the
Invariant Sections of all of the original documents, unmodified, and
list them all as Invariant Sections of your combined work in its
license notice, and that you preserve all their Warranty Disclaimers.
The combined work need only contain one copy of this License, and
multiple identical Invariant Sections may be replaced with a single
copy. If there are multiple Invariant Sections with the same name but
different contents, make the title of each such section unique by
adding at the end of it, in parentheses, the name of the original
author or publisher of that section if known, or else a unique number.
Make the same adjustment to the section titles in the list of
Invariant Sections in the license notice of the combined work.
In the combination, you must combine any sections Entitled ``History''
in the various original documents, forming one section Entitled
``History''; likewise combine any sections Entitled ``Acknowledgements,''
and any sections Entitled ``Dedications.'' You must delete all sections
Entitled ``Endorsements.''
@sp 1
@item
COLLECTIONS OF DOCUMENTS
You may make a collection consisting of the Document and other documents
released under this License, and replace the individual copies of this
License in the various documents with a single copy that is included in
the collection, provided that you follow the rules of this License for
verbatim copying of each of the documents in all other respects.
You may extract a single document from such a collection, and distribute
it individually under this License, provided you insert a copy of this
License into the extracted document, and follow this License in all
other respects regarding verbatim copying of that document.
@sp 1
@item
AGGREGATION WITH INDEPENDENT WORKS
A compilation of the Document or its derivatives with other separate
and independent documents or works, in or on a volume of a storage or
distribution medium, is called an ``aggregate'' if the copyright
resulting from the compilation is not used to limit the legal rights
of the compilation's users beyond what the individual works permit.
When the Document is included in an aggregate, this License does not
apply to the other works in the aggregate which are not themselves
derivative works of the Document.
If the Cover Text requirement of section 3 is applicable to these
copies of the Document, then if the Document is less than one half of
the entire aggregate, the Document's Cover Texts may be placed on
covers that bracket the Document within the aggregate, or the
electronic equivalent of covers if the Document is in electronic form.
Otherwise they must appear on printed covers that bracket the whole
aggregate.
@sp 1
@item
TRANSLATION
Translation is considered a kind of modification, so you may
distribute translations of the Document under the terms of section 4.
Replacing Invariant Sections with translations requires special
permission from their copyright holders, but you may include
translations of some or all Invariant Sections in addition to the
original versions of these Invariant Sections. You may include a
translation of this License, and all the license notices in the
Document, and any Warranty Disclaimers, provided that you also include
the original English version of this License and the original versions
of those notices and disclaimers. In case of a disagreement between
the translation and the original version of this License or a notice
or disclaimer, the original version will prevail.
If a section in the Document is Entitled ``Acknowledgements,''
``Dedications,'' or ``History,'' the requirement (section 4) to Preserve
its Title (section 1) will typically require changing the actual
title.
@sp 1
@item
TERMINATION
You may not copy, modify, sublicense, or distribute the Document except
as expressly provided for under this License. Any other attempt to
copy, modify, sublicense or distribute the Document is void, and will
automatically terminate your rights under this License. However,
parties who have received copies, or rights, from you under this
License will not have their licenses terminated so long as such
parties remain in full compliance.
@sp 1
@item
FUTURE REVISIONS OF THIS LICENSE
The Free Software Foundation may publish new, revised versions
of the GNU Free Documentation License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns. See
http://www.gnu.org/copyleft/.
Each version of the License is given a distinguishing version number.
If the Document specifies that a particular numbered version of this
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that specified version or
of any later version that has been published (not as a draft) by the
Free Software Foundation. If the Document does not specify a version
number of this License, you may choose any version ever published (not
as a draft) by the Free Software Foundation.
@end enumerate
@unnumberedsec ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
license notices just after the title page:
@smallexample
@group
Copyright (C) @var{year} @var{your name}.
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.2
or any later version published by the Free Software Foundation;
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
A copy of the license is included in the section entitled ``GNU
Free Documentation License.''
@end group
@end smallexample
If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts,
replace the ``with...Texts.'' line with this:
@smallexample
@group
with the Invariant Sections being @var{list their titles}, with the
Front-Cover Texts being @var{list}, and with the Back-Cover Texts being
@var{list}.
@end group
@end smallexample
If you have Invariant Sections without Cover Texts, or some other
combination of the three, merge those two alternatives to suit the
situation.
If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License,
to permit their use in free software.
@ignore
arch-tag: 9014cf6e-f3c4-401d-b8da-4fe52723984c
@end ignore

1582
doc/lispref/edebug.texi Normal file
View file

File diff suppressed because it is too large Load diff

257
doc/lispref/elisp-covers.texi Normal file
View file

@ -0,0 +1,257 @@
\input texinfo @c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c
@comment %**start of header
@setfilename covers.info
@settitle GNU Emacs Lisp Reference Manual
@comment %**end of header
@titlepage
@c ================ Volume 1 ================
@w{ }
@sp 2
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 1}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@page
@c ================ Volume 2 ================
@w{ }
@sp 5
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 2}
@sp 2
@center by Bil Lewis,
@center Dan LaLiberte, and
@center the GNU Manual Group
@page
@c ================ Volume 1 with baseline skip 16pt ================
@tex
\global\baselineskip = 16pt
@end tex
16 pts baseline skip:
@w{ }
@sp 2
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 1}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@page
@c ================ Volume 1 with baseline skip 18pt ================
@tex
\global\baselineskip = 18pt
@end tex
18 pts baseline skip, with 15pts between sections
@w{ }
@sp 2
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@tex
\global\baselineskip = 15pt
@end tex
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 1}
@sp 2
@center by Bil Lewis,
@center Dan LaLiberte, and
@center the GNU Manual Group
@page
@c ================ Volume 1 with more baseline skip 24 pts ================
@tex
\global\baselineskip = 24pt
@end tex
24 pts baseline skip:
@w{ }
@sp 2
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 1}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@page
@c ================ Volume 2 with more baseline skip 18 pts ================
@tex
\global\baselineskip = 18pt
@end tex
18 pts baseline skip:
@w{ }
@sp 5
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 2}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@page
@c ================ Volume 2 with more baseline skip 24 pts ================
@tex
\global\baselineskip = 24pt
@end tex
24 pts baseline skip:
@w{ }
@sp 5
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 2
@center @titlefont{Volume 2}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@page
@c ================ Spine 1 ================
@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 1}}
@sp 4
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 4
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@sp 4
@author The GNU Emacs Lisp Reference Manual --- Vol. 1
@sp 3
@author FSF
@author
@page
@c ================ Spine 2 ================
@w{@titlefont{The GNU Emacs Lisp Reference Manual --- Vol. 2}}
@sp 4
@center GNU Emacs Version 19
@center for Unix Users
@center Edition 2.3, June 1994
@sp 4
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@sp 4
@author The GNU Emacs Lisp Reference Manual --- Vol. 2
@sp 3
@author FSF
@end titlepage
@bye
@ignore
arch-tag: 02d65d63-3b64-49bc-a5c0-bfd5eabb6c98
@end ignore

1483
doc/lispref/elisp.texi Normal file
View file

File diff suppressed because it is too large Load diff

209
doc/lispref/errors.texi Normal file
View file

@ -0,0 +1,209 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
@c 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/errors
@node Standard Errors, Standard Buffer-Local Variables, GNU Emacs Internals, Top
@appendix Standard Errors
@cindex standard errors
Here is the complete list of the error symbols in standard Emacs,
grouped by concept. The list includes each symbol's message (on the
@code{error-message} property of the symbol) and a cross reference to a
description of how the error can occur.
Each error symbol has an @code{error-conditions} property that is a
list of symbols. Normally this list includes the error symbol itself
and the symbol @code{error}. Occasionally it includes additional
symbols, which are intermediate classifications, narrower than
@code{error} but broader than a single error symbol. For example, all
the errors in accessing files have the condition @code{file-error}. If
we do not say here that a certain error symbol has additional error
conditions, that means it has none.
As a special exception, the error symbol @code{quit} does not have the
condition @code{error}, because quitting is not considered an error.
@xref{Errors}, for an explanation of how errors are generated and
handled.
@table @code
@item @var{symbol}
@var{string}; @var{reference}.
@item error
@code{"error"}@*
@xref{Errors}.
@item quit
@code{"Quit"}@*
@xref{Quitting}.
@item args-out-of-range
@code{"Args out of range"}@*
This happens when trying to access an element beyond the range of a
sequence or buffer.@*
@xref{Sequences Arrays Vectors}, @xref{Text}.
@item arith-error
@code{"Arithmetic error"}@*
@xref{Arithmetic Operations}.
@item beginning-of-buffer
@code{"Beginning of buffer"}@*
@xref{Character Motion}.
@item buffer-read-only
@code{"Buffer is read-only"}@*
@xref{Read Only Buffers}.
@item coding-system-error
@code{"Invalid coding system"}@*
@xref{Lisp and Coding Systems}.
@item cyclic-function-indirection
@code{"Symbol's chain of function indirections\@* contains a loop"}@*
@xref{Function Indirection}.
@item cyclic-variable-indirection
@code{"Symbol's chain of variable indirections\@* contains a loop"}@*
@xref{Variable Aliases}.
@item end-of-buffer
@code{"End of buffer"}@*
@xref{Character Motion}.
@item end-of-file
@code{"End of file during parsing"}@*
Note that this is not a subcategory of @code{file-error},
because it pertains to the Lisp reader, not to file I/O.@*
@xref{Input Functions}.
@item file-already-exists
This is a subcategory of @code{file-error}.@*
@xref{Writing to Files}.
@item file-date-error
This is a subcategory of @code{file-error}. It occurs when
@code{copy-file} tries and fails to set the last-modification time of
the output file.@*
@xref{Changing Files}.
@item file-error
We do not list the error-strings of this error and its subcategories,
because the error message is normally constructed from the data items
alone when the error condition @code{file-error} is present. Thus,
the error-strings are not very relevant. However, these error symbols
do have @code{error-message} properties, and if no data is provided,
the @code{error-message} property @emph{is} used.@*
@xref{Files}.
@item file-locked
This is a subcategory of @code{file-error}.@*
@xref{File Locks}.
@item file-supersession
This is a subcategory of @code{file-error}.@*
@xref{Modification Time}.
@item ftp-error
This is a subcategory of @code{file-error}, which results from problems
in accessing a remote file using ftp.@*
@xref{Remote Files,,, emacs, The GNU Emacs Manual}.
@item invalid-function
@code{"Invalid function"}@*
@xref{Function Indirection}.
@item invalid-read-syntax
@code{"Invalid read syntax"}@*
@xref{Printed Representation}.
@item invalid-regexp
@code{"Invalid regexp"}@*
@xref{Regular Expressions}.
@item mark-inactive
@code{"The mark is not active now"}@*
@xref{The Mark}.
@item no-catch
@code{"No catch for tag"}@*
@xref{Catch and Throw}.
@item scan-error
@code{"Scan error"}@*
This happens when certain syntax-parsing functions
find invalid syntax or mismatched parentheses.@*
@xref{List Motion}, and @ref{Parsing Expressions}.
@item search-failed
@code{"Search failed"}@*
@xref{Searching and Matching}.
@item setting-constant
@code{"Attempt to set a constant symbol"}@*
The values of the symbols @code{nil} and @code{t},
and any symbols that start with @samp{:},
may not be changed.@*
@xref{Constant Variables, , Variables that Never Change}.
@item text-read-only
@code{"Text is read-only"}@*
This is a subcategory of @code{buffer-read-only}.@*
@xref{Special Properties}.
@item undefined-color
@code{"Undefined color"}@*
@xref{Color Names}.
@item void-function
@code{"Symbol's function definition is void"}@*
@xref{Function Cells}.
@item void-variable
@code{"Symbol's value as variable is void"}@*
@xref{Accessing Variables}.
@item wrong-number-of-arguments
@code{"Wrong number of arguments"}@*
@xref{Classifying Lists}.
@item wrong-type-argument
@code{"Wrong type argument"}@*
@xref{Type Predicates}.
@end table
These kinds of error, which are classified as special cases of
@code{arith-error}, can occur on certain systems for invalid use of
mathematical functions.
@table @code
@item domain-error
@code{"Arithmetic domain error"}@*
@xref{Math Functions}.
@item overflow-error
@code{"Arithmetic overflow error"}@*
This is a subcategory of @code{domain-error}.@*
@xref{Math Functions}.
@item range-error
@code{"Arithmetic range error"}@*
@xref{Math Functions}.
@item singularity-error
@code{"Arithmetic singularity error"}@*
This is a subcategory of @code{domain-error}.@*
@xref{Math Functions}.
@item underflow-error
@code{"Arithmetic underflow error"}@*
This is a subcategory of @code{domain-error}.@*
@xref{Math Functions}.
@end table
@ignore
arch-tag: 717c6048-5d9d-4c7d-9a62-df57390b6f19
@end ignore

758
doc/lispref/eval.texi Normal file
View file

@ -0,0 +1,758 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 2001, 2002, 2003,
@c 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/eval
@node Evaluation, Control Structures, Symbols, Top
@chapter Evaluation
@cindex evaluation
@cindex interpreter
@cindex interpreter
@cindex value of expression
The @dfn{evaluation} of expressions in Emacs Lisp is performed by the
@dfn{Lisp interpreter}---a program that receives a Lisp object as input
and computes its @dfn{value as an expression}. How it does this depends
on the data type of the object, according to rules described in this
chapter. The interpreter runs automatically to evaluate portions of
your program, but can also be called explicitly via the Lisp primitive
function @code{eval}.
@ifnottex
@menu
* Intro Eval:: Evaluation in the scheme of things.
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in the program).
* Eval:: How to invoke the Lisp interpreter explicitly.
@end menu
@node Intro Eval
@section Introduction to Evaluation
The Lisp interpreter, or evaluator, is the program that computes
the value of an expression that is given to it. When a function
written in Lisp is called, the evaluator computes the value of the
function by evaluating the expressions in the function body. Thus,
running any Lisp program really means running the Lisp interpreter.
How the evaluator handles an object depends primarily on the data
type of the object.
@end ifnottex
@cindex forms
@cindex expression
A Lisp object that is intended for evaluation is called an
@dfn{expression} or a @dfn{form}. The fact that expressions are data
objects and not merely text is one of the fundamental differences
between Lisp-like languages and typical programming languages. Any
object can be evaluated, but in practice only numbers, symbols, lists
and strings are evaluated very often.
It is very common to read a Lisp expression and then evaluate the
expression, but reading and evaluation are separate activities, and
either can be performed alone. Reading per se does not evaluate
anything; it converts the printed representation of a Lisp object to the
object itself. It is up to the caller of @code{read} whether this
object is a form to be evaluated, or serves some entirely different
purpose. @xref{Input Functions}.
Do not confuse evaluation with command key interpretation. The
editor command loop translates keyboard input into a command (an
interactively callable function) using the active keymaps, and then
uses @code{call-interactively} to invoke the command. The execution of
the command itself involves evaluation if the command is written in
Lisp, but that is not a part of command key interpretation itself.
@xref{Command Loop}.
@cindex recursive evaluation
Evaluation is a recursive process. That is, evaluation of a form may
call @code{eval} to evaluate parts of the form. For example, evaluation
of a function call first evaluates each argument of the function call,
and then evaluates each form in the function body. Consider evaluation
of the form @code{(car x)}: the subform @code{x} must first be evaluated
recursively, so that its value can be passed as an argument to the
function @code{car}.
Evaluation of a function call ultimately calls the function specified
in it. @xref{Functions}. The execution of the function may itself work
by evaluating the function definition; or the function may be a Lisp
primitive implemented in C, or it may be a byte-compiled function
(@pxref{Byte Compilation}).
@cindex environment
The evaluation of forms takes place in a context called the
@dfn{environment}, which consists of the current values and bindings of
all Lisp variables.@footnote{This definition of ``environment'' is
specifically not intended to include all the data that can affect the
result of a program.} Whenever a form refers to a variable without
creating a new binding for it, the value of the variable's binding in
the current environment is used. @xref{Variables}.
@cindex side effect
Evaluation of a form may create new environments for recursive
evaluation by binding variables (@pxref{Local Variables}). These
environments are temporary and vanish by the time evaluation of the form
is complete. The form may also make changes that persist; these changes
are called @dfn{side effects}. An example of a form that produces side
effects is @code{(setq foo 1)}.
The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).
@node Forms
@section Kinds of Forms
A Lisp object that is intended to be evaluated is called a @dfn{form}.
How Emacs evaluates a form depends on its data type. Emacs has three
different kinds of form that are evaluated differently: symbols, lists,
and ``all other types.'' This section describes all three kinds, one by
one, starting with the ``all other types'' which are self-evaluating
forms.
@menu
* Self-Evaluating Forms:: Forms that evaluate to themselves.
* Symbol Forms:: Symbols evaluate as variables.
* Classifying Lists:: How to distinguish various sorts of list forms.
* Function Indirection:: When a symbol appears as the car of a list,
we find the real function via the symbol.
* Function Forms:: Forms that call functions.
* Macro Forms:: Forms that call macros.
* Special Forms:: "Special forms" are idiosyncratic primitives,
most of them extremely important.
* Autoloading:: Functions set up to load files
containing their real definitions.
@end menu
@node Self-Evaluating Forms
@subsection Self-Evaluating Forms
@cindex vector evaluation
@cindex literal evaluation
@cindex self-evaluating form
A @dfn{self-evaluating form} is any form that is not a list or symbol.
Self-evaluating forms evaluate to themselves: the result of evaluation
is the same object that was evaluated. Thus, the number 25 evaluates to
25, and the string @code{"foo"} evaluates to the string @code{"foo"}.
Likewise, evaluation of a vector does not cause evaluation of the
elements of the vector---it returns the same vector with its contents
unchanged.
@example
@group
'123 ; @r{A number, shown without evaluation.}
@result{} 123
@end group
@group
123 ; @r{Evaluated as usual---result is the same.}
@result{} 123
@end group
@group
(eval '123) ; @r{Evaluated ``by hand''---result is the same.}
@result{} 123
@end group
@group
(eval (eval '123)) ; @r{Evaluating twice changes nothing.}
@result{} 123
@end group
@end example
It is common to write numbers, characters, strings, and even vectors
in Lisp code, taking advantage of the fact that they self-evaluate.
However, it is quite unusual to do this for types that lack a read
syntax, because there's no way to write them textually. It is possible
to construct Lisp expressions containing these types by means of a Lisp
program. Here is an example:
@example
@group
;; @r{Build an expression containing a buffer object.}
(setq print-exp (list 'print (current-buffer)))
@result{} (print #<buffer eval.texi>)
@end group
@group
;; @r{Evaluate it.}
(eval print-exp)
@print{} #<buffer eval.texi>
@result{} #<buffer eval.texi>
@end group
@end example
@node Symbol Forms
@subsection Symbol Forms
@cindex symbol evaluation
When a symbol is evaluated, it is treated as a variable. The result
is the variable's value, if it has one. If it has none (if its value
cell is void), an error is signaled. For more information on the use of
variables, see @ref{Variables}.
In the following example, we set the value of a symbol with
@code{setq}. Then we evaluate the symbol, and get back the value that
@code{setq} stored.
@example
@group
(setq a 123)
@result{} 123
@end group
@group
(eval 'a)
@result{} 123
@end group
@group
a
@result{} 123
@end group
@end example
The symbols @code{nil} and @code{t} are treated specially, so that the
value of @code{nil} is always @code{nil}, and the value of @code{t} is
always @code{t}; you cannot set or bind them to any other values. Thus,
these two symbols act like self-evaluating forms, even though
@code{eval} treats them like any other symbol. A symbol whose name
starts with @samp{:} also self-evaluates in the same way; likewise,
its value ordinarily cannot be changed. @xref{Constant Variables}.
@node Classifying Lists
@subsection Classification of List Forms
@cindex list form evaluation
A form that is a nonempty list is either a function call, a macro
call, or a special form, according to its first element. These three
kinds of forms are evaluated in different ways, described below. The
remaining list elements constitute the @dfn{arguments} for the function,
macro, or special form.
The first step in evaluating a nonempty list is to examine its first
element. This element alone determines what kind of form the list is
and how the rest of the list is to be processed. The first element is
@emph{not} evaluated, as it would be in some Lisp dialects such as
Scheme.
@node Function Indirection
@subsection Symbol Function Indirection
@cindex symbol function indirection
@cindex indirection for functions
@cindex void function
If the first element of the list is a symbol then evaluation examines
the symbol's function cell, and uses its contents instead of the
original symbol. If the contents are another symbol, this process,
called @dfn{symbol function indirection}, is repeated until it obtains a
non-symbol. @xref{Function Names}, for more information about using a
symbol as a name for a function stored in the function cell of the
symbol.
One possible consequence of this process is an infinite loop, in the
event that a symbol's function cell refers to the same symbol. Or a
symbol may have a void function cell, in which case the subroutine
@code{symbol-function} signals a @code{void-function} error. But if
neither of these things happens, we eventually obtain a non-symbol,
which ought to be a function or other suitable object.
@kindex invalid-function
More precisely, we should now have a Lisp function (a lambda
expression), a byte-code function, a primitive function, a Lisp macro, a
special form, or an autoload object. Each of these types is a case
described in one of the following sections. If the object is not one of
these types, the error @code{invalid-function} is signaled.
The following example illustrates the symbol indirection process. We
use @code{fset} to set the function cell of a symbol and
@code{symbol-function} to get the function cell contents
(@pxref{Function Cells}). Specifically, we store the symbol @code{car}
into the function cell of @code{first}, and the symbol @code{first} into
the function cell of @code{erste}.
@smallexample
@group
;; @r{Build this function cell linkage:}
;; ------------- ----- ------- -------
;; | #<subr car> | <-- | car | <-- | first | <-- | erste |
;; ------------- ----- ------- -------
@end group
@end smallexample
@smallexample
@group
(symbol-function 'car)
@result{} #<subr car>
@end group
@group
(fset 'first 'car)
@result{} car
@end group
@group
(fset 'erste 'first)
@result{} first
@end group
@group
(erste '(1 2 3)) ; @r{Call the function referenced by @code{erste}.}
@result{} 1
@end group
@end smallexample
By contrast, the following example calls a function without any symbol
function indirection, because the first element is an anonymous Lisp
function, not a symbol.
@smallexample
@group
((lambda (arg) (erste arg))
'(1 2 3))
@result{} 1
@end group
@end smallexample
@noindent
Executing the function itself evaluates its body; this does involve
symbol function indirection when calling @code{erste}.
The built-in function @code{indirect-function} provides an easy way to
perform symbol function indirection explicitly.
@c Emacs 19 feature
@defun indirect-function function &optional noerror
@anchor{Definition of indirect-function}
This function returns the meaning of @var{function} as a function. If
@var{function} is a symbol, then it finds @var{function}'s function
definition and starts over with that value. If @var{function} is not a
symbol, then it returns @var{function} itself.
This function signals a @code{void-function} error if the final symbol
is unbound and optional argument @var{noerror} is @code{nil} or
omitted. Otherwise, if @var{noerror} is non-@code{nil}, it returns
@code{nil} if the final symbol is unbound.
It signals a @code{cyclic-function-indirection} error if there is a
loop in the chain of symbols.
Here is how you could define @code{indirect-function} in Lisp:
@smallexample
(defun indirect-function (function)
(if (symbolp function)
(indirect-function (symbol-function function))
function))
@end smallexample
@end defun
@node Function Forms
@subsection Evaluation of Function Forms
@cindex function form evaluation
@cindex function call
If the first element of a list being evaluated is a Lisp function
object, byte-code object or primitive function object, then that list is
a @dfn{function call}. For example, here is a call to the function
@code{+}:
@example
(+ 1 x)
@end example
The first step in evaluating a function call is to evaluate the
remaining elements of the list from left to right. The results are the
actual argument values, one value for each list element. The next step
is to call the function with this list of arguments, effectively using
the function @code{apply} (@pxref{Calling Functions}). If the function
is written in Lisp, the arguments are used to bind the argument
variables of the function (@pxref{Lambda Expressions}); then the forms
in the function body are evaluated in order, and the value of the last
body form becomes the value of the function call.
@node Macro Forms
@subsection Lisp Macro Evaluation
@cindex macro call evaluation
If the first element of a list being evaluated is a macro object, then
the list is a @dfn{macro call}. When a macro call is evaluated, the
elements of the rest of the list are @emph{not} initially evaluated.
Instead, these elements themselves are used as the arguments of the
macro. The macro definition computes a replacement form, called the
@dfn{expansion} of the macro, to be evaluated in place of the original
form. The expansion may be any sort of form: a self-evaluating
constant, a symbol, or a list. If the expansion is itself a macro call,
this process of expansion repeats until some other sort of form results.
Ordinary evaluation of a macro call finishes by evaluating the
expansion. However, the macro expansion is not necessarily evaluated
right away, or at all, because other programs also expand macro calls,
and they may or may not evaluate the expansions.
Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are computed when the expansion is evaluated.
For example, given a macro defined as follows:
@example
@group
(defmacro cadr (x)
(list 'car (list 'cdr x)))
@end group
@end example
@noindent
an expression such as @code{(cadr (assq 'handler list))} is a macro
call, and its expansion is:
@example
(car (cdr (assq 'handler list)))
@end example
@noindent
Note that the argument @code{(assq 'handler list)} appears in the
expansion.
@xref{Macros}, for a complete description of Emacs Lisp macros.
@node Special Forms
@subsection Special Forms
@cindex special form evaluation
A @dfn{special form} is a primitive function specially marked so that
its arguments are not all evaluated. Most special forms define control
structures or perform variable bindings---things which functions cannot
do.
Each special form has its own rules for which arguments are evaluated
and which are used without evaluation. Whether a particular argument is
evaluated may depend on the results of evaluating other arguments.
Here is a list, in alphabetical order, of all of the special forms in
Emacs Lisp with a reference to where each is described.
@table @code
@item and
@pxref{Combining Conditions}
@item catch
@pxref{Catch and Throw}
@item cond
@pxref{Conditionals}
@item condition-case
@pxref{Handling Errors}
@item defconst
@pxref{Defining Variables}
@item defmacro
@pxref{Defining Macros}
@item defun
@pxref{Defining Functions}
@item defvar
@pxref{Defining Variables}
@item function
@pxref{Anonymous Functions}
@item if
@pxref{Conditionals}
@item interactive
@pxref{Interactive Call}
@item let
@itemx let*
@pxref{Local Variables}
@item or
@pxref{Combining Conditions}
@item prog1
@itemx prog2
@itemx progn
@pxref{Sequencing}
@item quote
@pxref{Quoting}
@item save-current-buffer
@pxref{Current Buffer}
@item save-excursion
@pxref{Excursions}
@item save-restriction
@pxref{Narrowing}
@item save-window-excursion
@pxref{Window Configurations}
@item setq
@pxref{Setting Variables}
@item setq-default
@pxref{Creating Buffer-Local}
@item track-mouse
@pxref{Mouse Tracking}
@item unwind-protect
@pxref{Nonlocal Exits}
@item while
@pxref{Iteration}
@item with-output-to-temp-buffer
@pxref{Temporary Displays}
@end table
@cindex CL note---special forms compared
@quotation
@b{Common Lisp note:} Here are some comparisons of special forms in
GNU Emacs Lisp and Common Lisp. @code{setq}, @code{if}, and
@code{catch} are special forms in both Emacs Lisp and Common Lisp.
@code{defun} is a special form in Emacs Lisp, but a macro in Common
Lisp. @code{save-excursion} is a special form in Emacs Lisp, but
doesn't exist in Common Lisp. @code{throw} is a special form in
Common Lisp (because it must be able to throw multiple values), but it
is a function in Emacs Lisp (which doesn't have multiple
values).@refill
@end quotation
@node Autoloading
@subsection Autoloading
The @dfn{autoload} feature allows you to call a function or macro
whose function definition has not yet been loaded into Emacs. It
specifies which file contains the definition. When an autoload object
appears as a symbol's function definition, calling that symbol as a
function automatically loads the specified file; then it calls the real
definition loaded from that file. @xref{Autoload}.
@node Quoting
@section Quoting
The special form @code{quote} returns its single argument, as written,
without evaluating it. This provides a way to include constant symbols
and lists, which are not self-evaluating objects, in a program. (It is
not necessary to quote self-evaluating objects such as numbers, strings,
and vectors.)
@defspec quote object
This special form returns @var{object}, without evaluating it.
@end defspec
@cindex @samp{'} for quoting
@cindex quoting using apostrophe
@cindex apostrophe for quoting
Because @code{quote} is used so often in programs, Lisp provides a
convenient read syntax for it. An apostrophe character (@samp{'})
followed by a Lisp object (in read syntax) expands to a list whose first
element is @code{quote}, and whose second element is the object. Thus,
the read syntax @code{'x} is an abbreviation for @code{(quote x)}.
Here are some examples of expressions that use @code{quote}:
@example
@group
(quote (+ 1 2))
@result{} (+ 1 2)
@end group
@group
(quote foo)
@result{} foo
@end group
@group
'foo
@result{} foo
@end group
@group
''foo
@result{} (quote foo)
@end group
@group
'(quote foo)
@result{} (quote foo)
@end group
@group
['foo]
@result{} [(quote foo)]
@end group
@end example
Other quoting constructs include @code{function} (@pxref{Anonymous
Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
@node Eval
@section Eval
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list. On these occasions, use the @code{eval} function.
The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
values. Loading a file also does evaluation (@pxref{Loading}).
It is generally cleaner and more flexible to store a function in a
data structure, and call it with @code{funcall} or @code{apply}, than
to store an expression in the data structure and evaluate it. Using
functions provides the ability to pass information to them as
arguments.
@defun eval form
This is the basic function evaluating an expression. It evaluates
@var{form} in the current environment and returns the result. How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).
Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before
@code{eval} is called, and again by the @code{eval} function itself.
Here is an example:
@example
@group
(setq foo 'bar)
@result{} bar
@end group
@group
(setq bar 'baz)
@result{} baz
;; @r{Here @code{eval} receives argument @code{foo}}
(eval 'foo)
@result{} bar
;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
(eval foo)
@result{} baz
@end group
@end example
The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth} (see below).
@end defun
@deffn Command eval-region start end &optional stream read-function
@anchor{Definition of eval-region}
This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}. It reads forms from
the region and calls @code{eval} on them until the end of the region is
reached, or until an error is signaled and not handled.
By default, @code{eval-region} does not produce any output. However,
if @var{stream} is non-@code{nil}, any output produced by output
functions (@pxref{Output Functions}), as well as the values that
result from evaluating the expressions in the region are printed using
@var{stream}. @xref{Output Streams}.
If @var{read-function} is non-@code{nil}, it should be a function,
which is used instead of @code{read} to read expressions one by one.
This function is called with one argument, the stream for reading
input. You can also use the variable @code{load-read-function}
(@pxref{Definition of load-read-function,, How Programs Do Loading})
to specify this function, but it is more robust to use the
@var{read-function} argument.
@code{eval-region} does not move point. It always returns @code{nil}.
@end deffn
@cindex evaluation of buffer contents
@deffn Command eval-buffer &optional buffer-or-name stream filename unibyte print
This is similar to @code{eval-region}, but the arguments provide
different optional features. @code{eval-buffer} operates on the
entire accessible portion of buffer @var{buffer-or-name}.
@var{buffer-or-name} can be a buffer, a buffer name (a string), or
@code{nil} (or omitted), which means to use the current buffer.
@var{stream} is used as in @code{eval-region}, unless @var{stream} is
@code{nil} and @var{print} non-@code{nil}. In that case, values that
result from evaluating the expressions are still discarded, but the
output of the output functions is printed in the echo area.
@var{filename} is the file name to use for @code{load-history}
(@pxref{Unloading}), and defaults to @code{buffer-file-name}
(@pxref{Buffer File Name}). If @var{unibyte} is non-@code{nil},
@code{read} converts strings to unibyte whenever possible.
@findex eval-current-buffer
@code{eval-current-buffer} is an alias for this command.
@end deffn
@defvar max-lisp-eval-depth
@anchor{Definition of max-lisp-eval-depth}
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
message @code{"Lisp nesting exceeds max-lisp-eval-depth"}).
This limit, with the associated error when it is exceeded, is one way
Emacs Lisp avoids infinite recursion on an ill-defined function. If
you increase the value of @code{max-lisp-eval-depth} too much, such
code can cause stack overflow instead.
@cindex Lisp nesting error
The depth limit counts internal uses of @code{eval}, @code{apply}, and
@code{funcall}, such as for calling the functions mentioned in Lisp
expressions, and recursive evaluation of function call arguments and
function body forms, as well as explicit calls in Lisp code.
The default value of this variable is 300. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
Entry to the Lisp debugger increases the value, if there is little room
left, to make sure the debugger itself has room to execute.
@code{max-specpdl-size} provides another limit on nesting.
@xref{Definition of max-specpdl-size,, Local Variables}.
@end defvar
@defvar values
The value of this variable is a list of the values returned by all the
expressions that were read, evaluated, and printed from buffers
(including the minibuffer) by the standard Emacs commands which do
this. (Note that this does @emph{not} include evaluation in
@samp{*ielm*} buffers, nor evaluation using @kbd{C-j} in
@code{lisp-interaction-mode}.) The elements are ordered most recent
first.
@example
@group
(setq x 1)
@result{} 1
@end group
@group
(list 'A (1+ 2) auto-save-default)
@result{} (A 3 t)
@end group
@group
values
@result{} ((A 3 t) 1 @dots{})
@end group
@end example
This variable is useful for referring back to values of forms recently
evaluated. It is generally a bad idea to print the value of
@code{values} itself, since this may be very long. Instead, examine
particular elements, like this:
@example
@group
;; @r{Refer to the most recent evaluation result.}
(nth 0 values)
@result{} (A 3 t)
@end group
@group
;; @r{That put a new element on,}
;; @r{so all elements move back one.}
(nth 1 values)
@result{} (A 3 t)
@end group
@group
;; @r{This gets the element that was next-to-most-recent}
;; @r{before this example.}
(nth 3 values)
@result{} 1
@end group
@end example
@end defvar
@ignore
arch-tag: f723a4e0-31b3-453f-8afc-0bf8fd276d57
@end ignore

3108
doc/lispref/files.texi Normal file
View file

File diff suppressed because it is too large Load diff

2208
doc/lispref/frames.texi Normal file
View file

File diff suppressed because it is too large Load diff

56
doc/lispref/front-cover-1.texi Normal file
View file

@ -0,0 +1,56 @@
\input texinfo @c -*-texinfo-*-
@comment %**start of header
@setfilename front1.info
@settitle GNU Emacs Lisp Reference Manual
@smallbook
@comment %**end of header
@titlepage
.
@sp 2
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19.29
@center for Unix Users
@center Edition 2.4, June 1995
@sp 2
@center @titlefont{Volume 1}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@page
.
@sp 5
@center @titlefont{The}
@sp 1
@center @titlefont{GNU}
@sp 1
@center @titlefont{Emacs Lisp}
@sp 1
@center @titlefont{Reference}
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19.29
@center for Unix Users
@center Edition 2.4, June 1995
@sp 2
@center @titlefont{Volume 2}
@sp 2
@center by Bil Lewis, Dan LaLiberte,
@center and the GNU Manual Group
@end titlepage
@bye
@ignore
arch-tag: 5182b306-c403-4e4f-ba24-e1911bc6da9d
@end ignore

1374
doc/lispref/functions.texi Normal file
View file

File diff suppressed because it is too large Load diff

727
doc/lispref/gpl.texi Normal file
View file

@ -0,0 +1,727 @@
@c -*-texinfo-*-
@setfilename ../info/gpl
@node GPL, Tips, GNU Free Documentation License, Top
@comment node-name, next, previous, up
@appendix GNU General Public License
@c The GNU General Public License.
@center Version 3, 29 June 2007
@c This file is intended to be included within another document,
@c hence no sectioning command or @node.
@display
Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/}
Everyone is permitted to copy and distribute verbatim copies of this
license document, but changing it is not allowed.
@end display
@heading Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom
to share and change all versions of a program---to make sure it remains
free software for all its users. We, the Free Software Foundation,
use the GNU General Public License for most of our software; it
applies also to any other work released this way by its authors. You
can apply it to your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you
have certain responsibilities if you distribute copies of the
software, or if you modify it: responsibilities to respect the freedom
of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too,
receive or can get the source code. And you must show them these
terms so they know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the
manufacturer can do so. This is fundamentally incompatible with the
aim of protecting users' freedom to change the software. The
systematic pattern of such abuse occurs in the area of products for
individuals to use, which is precisely where it is most unacceptable.
Therefore, we have designed this version of the GPL to prohibit the
practice for those products. If such problems arise substantially in
other domains, we stand ready to extend this provision to those
domains in future versions of the GPL, as needed to protect the
freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish
to avoid the special danger that patents applied to a free program
could make it effectively proprietary. To prevent this, the GPL
assures that patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
@heading TERMS AND CONDITIONS
@enumerate 0
@item Definitions.
``This License'' refers to version 3 of the GNU General Public License.
``Copyright'' also means copyright-like laws that apply to other kinds
of works, such as semiconductor masks.
``The Program'' refers to any copyrightable work licensed under this
License. Each licensee is addressed as ``you''. ``Licensees'' and
``recipients'' may be individuals or organizations.
To ``modify'' a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of
an exact copy. The resulting work is called a ``modified version'' of
the earlier work or a work ``based on'' the earlier work.
A ``covered work'' means either the unmodified Program or a work based
on the Program.
To ``propagate'' a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To ``convey'' a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user
through a computer network, with no transfer of a copy, is not
conveying.
An interactive user interface displays ``Appropriate Legal Notices'' to
the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
@item Source Code.
The ``source code'' for a work means the preferred form of the work for
making modifications to it. ``Object code'' means any non-source form
of a work.
A ``Standard Interface'' means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The ``System Libraries'' of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
``Major Component'', in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The ``Corresponding Source'' for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users can
regenerate automatically from other parts of the Corresponding Source.
The Corresponding Source for a work in source code form is that same
work.
@item Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not convey,
without conditions so long as your license otherwise remains in force.
You may convey covered works to others for the sole purpose of having
them make modifications exclusively for you, or provide you with
facilities for running those works, provided that you comply with the
terms of this License in conveying all material for which you do not
control copyright. Those thus making or running the covered works for
you must do so exclusively on your behalf, under your direction and
control, on terms that prohibit them from making any copies of your
copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under the
conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
@item Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such
circumvention is effected by exercising rights under this License with
respect to the covered work, and you disclaim any intention to limit
operation or modification of the work as a means of enforcing, against
the work's users, your or third parties' legal rights to forbid
circumvention of technological measures.
@item Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
@item Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these
conditions:
@enumerate a
@item
The work must carry prominent notices stating that you modified it,
and giving a relevant date.
@item
The work must carry prominent notices stating that it is released
under this License and any conditions added under section 7. This
requirement modifies the requirement in section 4 to ``keep intact all
notices''.
@item
You must license the entire work, as a whole, under this License to
anyone who comes into possession of a copy. This License will
therefore apply, along with any applicable section 7 additional terms,
to the whole of the work, and all its parts, regardless of how they
are packaged. This License gives no permission to license the work in
any other way, but it does not invalidate such permission if you have
separately received it.
@item
If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your work
need not make them do so.
@end enumerate
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
``aggregate'' if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
@item Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms of
sections 4 and 5, provided that you also convey the machine-readable
Corresponding Source under the terms of this License, in one of these
ways:
@enumerate a
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium customarily
used for software interchange.
@item
Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a written
offer, valid for at least three years and valid for as long as you
offer spare parts or customer support for that product model, to give
anyone who possesses the object code either (1) a copy of the
Corresponding Source for all the software in the product that is
covered by this License, on a durable physical medium customarily used
for software interchange, for a price no more than your reasonable
cost of physically performing this conveying of source, or (2) access
to copy the Corresponding Source from a network server at no charge.
@item
Convey individual copies of the object code with a copy of the written
offer to provide the Corresponding Source. This alternative is
allowed only occasionally and noncommercially, and only if you
received the object code with such an offer, in accord with subsection
6b.
@item
Convey the object code by offering access from a designated place
(gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to copy
the object code is a network server, the Corresponding Source may be
on a different server (operated by you or a third party) that supports
equivalent copying facilities, provided you maintain clear directions
next to the object code saying where to find the Corresponding Source.
Regardless of what server hosts the Corresponding Source, you remain
obligated to ensure that it is available for as long as needed to
satisfy these requirements.
@item
Convey the object code using peer-to-peer transmission, provided you
inform other peers where the object code and Corresponding Source of
the work are being offered to the general public at no charge under
subsection 6d.
@end enumerate
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A ``User Product'' is either (1) a ``consumer product'', which means any
tangible personal property which is normally used for personal,
family, or household purposes, or (2) anything designed or sold for
incorporation into a dwelling. In determining whether a product is a
consumer product, doubtful cases shall be resolved in favor of
coverage. For a particular product received by a particular user,
``normally used'' refers to a typical or common use of that class of
product, regardless of the status of the particular user or of the way
in which the particular user actually uses, or expects or is expected
to use, the product. A product is a consumer product regardless of
whether the product has substantial commercial, industrial or
non-consumer uses, unless such uses represent the only significant
mode of use of the product.
``Installation Information'' for a User Product means any methods,
procedures, authorization keys, or other information required to
install and execute modified versions of a covered work in that User
Product from a modified version of its Corresponding Source. The
information must suffice to ensure that the continued functioning of
the modified object code is in no case prevented or interfered with
solely because modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or
updates for a work that has been modified or installed by the
recipient, or for the User Product in which it has been modified or
installed. Access to a network may be denied when the modification
itself materially and adversely affects the operation of the network
or violates the rules and protocols for communication across the
network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
@item Additional Terms.
``Additional permissions'' are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders
of that material) supplement the terms of this License with terms:
@enumerate a
@item
Disclaiming warranty or limiting liability differently from the terms
of sections 15 and 16 of this License; or
@item
Requiring preservation of specified reasonable legal notices or author
attributions in that material or in the Appropriate Legal Notices
displayed by works containing it; or
@item
Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
@item
Limiting the use for publicity purposes of names of licensors or
authors of the material; or
@item
Declining to grant rights under trademark law for use of some trade
names, trademarks, or service marks; or
@item
Requiring indemnification of licensors and authors of that material by
anyone who conveys the material (or modified versions of it) with
contractual assumptions of liability to the recipient, for any
liability that these contractual assumptions directly impose on those
licensors and authors.
@end enumerate
All other non-permissive additional terms are considered ``further
restrictions'' within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions; the
above requirements apply either way.
@item Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your license
from a particular copyright holder is reinstated (a) provisionally,
unless and until the copyright holder explicitly and finally
terminates your license, and (b) permanently, if the copyright holder
fails to notify you of the violation by some reasonable means prior to
60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
@item Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or run
a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
@item Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An ``entity transaction'' is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
@item Patents.
A ``contributor'' is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's ``contributor version''.
A contributor's ``essential patent claims'' are all patent claims owned
or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, ``control'' includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a ``patent license'' is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To ``grant'' such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. ``Knowingly relying'' means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is ``discriminatory'' if it does not include within the
scope of its coverage, prohibits the exercise of, or is conditioned on
the non-exercise of one or more of the rights that are specifically
granted under this License. You may not convey a covered work if you
are a party to an arrangement with a third party that is in the
business of distributing software, under which you make payment to the
third party based on the extent of your activity of conveying the
work, and under which the third party grants, to any of the parties
who would receive the covered work from you, a discriminatory patent
license (a) in connection with copies of the covered work conveyed by
you (or copies made from those copies), or (b) primarily for and in
connection with specific products or compilations that contain the
covered work, unless you entered into that arrangement, or that patent
license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
@item No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey
a covered work so as to satisfy simultaneously your obligations under
this License and any other pertinent obligations, then as a
consequence you may not convey it at all. For example, if you agree
to terms that obligate you to collect a royalty for further conveying
from those to whom you convey the Program, the only way you could
satisfy both those terms and this License would be to refrain entirely
from conveying the Program.
@item Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
@item Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions
of the GNU General Public License from time to time. Such new
versions will be similar in spirit to the present version, but may
differ in detail to address new problems or concerns.
Each version is given a distinguishing version number. If the Program
specifies that a certain numbered version of the GNU General Public
License ``or any later version'' applies to it, you have the option of
following the terms and conditions either of that numbered version or
of any later version published by the Free Software Foundation. If
the Program does not specify a version number of the GNU General
Public License, you may choose any version ever published by the Free
Software Foundation.
If the Program specifies that a proxy can decide which future versions
of the GNU General Public License can be used, that proxy's public
statement of acceptance of a version permanently authorizes you to
choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
@item Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``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 PROGRAM PROVE
DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR
CORRECTION.
@item Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR
CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES
ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT
NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM
TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER
PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
@item Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
@end enumerate
@heading END OF TERMS AND CONDITIONS
@heading How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the ``copyright'' line and a pointer to where the full notice is found.
@smallexample
@var{one line to give the program's name and a brief idea of what it does.}
Copyright (C) @var{year} @var{name of author}
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or (at
your option) any later version.
This program is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see @url{http://www.gnu.org/licenses/}.
@end smallexample
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
@smallexample
@var{program} Copyright (C) @var{year} @var{name of author}
This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}.
This is free software, and you are welcome to redistribute it
under certain conditions; type @samp{show c} for details.
@end smallexample
The hypothetical commands @samp{show w} and @samp{show c} should show
the appropriate parts of the General Public License. Of course, your
program's commands might be different; for a GUI interface, you would
use an ``about box''.
You should also get your employer (if you work as a programmer) or school,
if any, to sign a ``copyright disclaimer'' for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
@url{http://www.gnu.org/licenses/}.
The GNU General Public License does not permit incorporating your
program into proprietary programs. If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library. If this is what you want to do, use
the GNU Lesser General Public License instead of this License. But
first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}.
@ignore
arch-tag: d00ac830-e120-41fb-bbc5-7ca3eeaa227f
@end ignore

337
doc/lispref/hash.texi Normal file
View file

@ -0,0 +1,337 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1999, 2001, 2002, 2003, 2004, 2005,
@c 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/hash
@node Hash Tables, Symbols, Sequences Arrays Vectors, Top
@chapter Hash Tables
@cindex hash tables
@cindex lookup tables
A hash table is a very fast kind of lookup table, somewhat like an
alist (@pxref{Association Lists}) in that it maps keys to
corresponding values. It differs from an alist in these ways:
@itemize @bullet
@item
Lookup in a hash table is extremely fast for large tables---in fact, the
time required is essentially @emph{independent} of how many elements are
stored in the table. For smaller tables (a few tens of elements)
alists may still be faster because hash tables have a more-or-less
constant overhead.
@item
The correspondences in a hash table are in no particular order.
@item
There is no way to share structure between two hash tables,
the way two alists can share a common tail.
@end itemize
Emacs Lisp provides a general-purpose hash table data type, along
with a series of functions for operating on them. Hash tables have no
read syntax, and print in hash notation, like this:
@example
(make-hash-table)
@result{} #<hash-table 'eql nil 0/65 0x83af980>
@end example
@noindent
(The term ``hash notation'' refers to the initial @samp{#}
character---@pxref{Printed Representation}---and has nothing to do with
the term ``hash table.'')
Obarrays are also a kind of hash table, but they are a different type
of object and are used only for recording interned symbols
(@pxref{Creating Symbols}).
@menu
* Creating Hash:: Functions to create hash tables.
* Hash Access:: Reading and writing the hash table contents.
* Defining Hash:: Defining new comparison methods
* Other Hash:: Miscellaneous.
@end menu
@node Creating Hash
@section Creating Hash Tables
@cindex creating hash tables
The principal function for creating a hash table is
@code{make-hash-table}.
@defun make-hash-table &rest keyword-args
This function creates a new hash table according to the specified
arguments. The arguments should consist of alternating keywords
(particular symbols recognized specially) and values corresponding to
them.
Several keywords make sense in @code{make-hash-table}, but the only two
that you really need to know about are @code{:test} and @code{:weakness}.
@table @code
@item :test @var{test}
This specifies the method of key lookup for this hash table. The
default is @code{eql}; @code{eq} and @code{equal} are other
alternatives:
@table @code
@item eql
Keys which are numbers are ``the same'' if they are @code{equal}, that
is, if they are equal in value and either both are integers or both
are floating point numbers; otherwise, two distinct objects are never
``the same.''
@item eq
Any two distinct Lisp objects are ``different'' as keys.
@item equal
Two Lisp objects are ``the same,'' as keys, if they are equal
according to @code{equal}.
@end table
You can use @code{define-hash-table-test} (@pxref{Defining Hash}) to
define additional possibilities for @var{test}.
@item :weakness @var{weak}
The weakness of a hash table specifies whether the presence of a key or
value in the hash table preserves it from garbage collection.
The value, @var{weak}, must be one of @code{nil}, @code{key},
@code{value}, @code{key-or-value}, @code{key-and-value}, or @code{t}
which is an alias for @code{key-and-value}. If @var{weak} is @code{key}
then the hash table does not prevent its keys from being collected as
garbage (if they are not referenced anywhere else); if a particular key
does get collected, the corresponding association is removed from the
hash table.
If @var{weak} is @code{value}, then the hash table does not prevent
values from being collected as garbage (if they are not referenced
anywhere else); if a particular value does get collected, the
corresponding association is removed from the hash table.
If @var{weak} is @code{key-and-value} or @code{t}, both the key and
the value must be live in order to preserve the association. Thus,
the hash table does not protect either keys or values from garbage
collection; if either one is collected as garbage, that removes the
association.
If @var{weak} is @code{key-or-value}, either the key or
the value can preserve the association. Thus, associations are
removed from the hash table when both their key and value would be
collected as garbage (if not for references from weak hash tables).
The default for @var{weak} is @code{nil}, so that all keys and values
referenced in the hash table are preserved from garbage collection.
@item :size @var{size}
This specifies a hint for how many associations you plan to store in the
hash table. If you know the approximate number, you can make things a
little more efficient by specifying it this way. If you specify too
small a size, the hash table will grow automatically when necessary, but
doing that takes some extra time.
The default size is 65.
@item :rehash-size @var{rehash-size}
When you add an association to a hash table and the table is ``full,''
it grows automatically. This value specifies how to make the hash table
larger, at that time.
If @var{rehash-size} is an integer, it should be positive, and the hash
table grows by adding that much to the nominal size. If
@var{rehash-size} is a floating point number, it had better be greater
than 1, and the hash table grows by multiplying the old size by that
number.
The default value is 1.5.
@item :rehash-threshold @var{threshold}
This specifies the criterion for when the hash table is ``full'' (so
it should be made larger). The value, @var{threshold}, should be a
positive floating point number, no greater than 1. The hash table is
``full'' whenever the actual number of entries exceeds this fraction
of the nominal size. The default for @var{threshold} is 0.8.
@end table
@end defun
@defun makehash &optional test
This is equivalent to @code{make-hash-table}, but with a different style
argument list. The argument @var{test} specifies the method
of key lookup.
This function is obsolete. Use @code{make-hash-table} instead.
@end defun
@node Hash Access
@section Hash Table Access
This section describes the functions for accessing and storing
associations in a hash table. In general, any Lisp object can be used
as a hash key, unless the comparison method imposes limits. Any Lisp
object can also be used as the value.
@defun gethash key table &optional default
This function looks up @var{key} in @var{table}, and returns its
associated @var{value}---or @var{default}, if @var{key} has no
association in @var{table}.
@end defun
@defun puthash key value table
This function enters an association for @var{key} in @var{table}, with
value @var{value}. If @var{key} already has an association in
@var{table}, @var{value} replaces the old associated value.
@end defun
@defun remhash key table
This function removes the association for @var{key} from @var{table}, if
there is one. If @var{key} has no association, @code{remhash} does
nothing.
@b{Common Lisp note:} In Common Lisp, @code{remhash} returns
non-@code{nil} if it actually removed an association and @code{nil}
otherwise. In Emacs Lisp, @code{remhash} always returns @code{nil}.
@end defun
@defun clrhash table
This function removes all the associations from hash table @var{table},
so that it becomes empty. This is also called @dfn{clearing} the hash
table.
@b{Common Lisp note:} In Common Lisp, @code{clrhash} returns the empty
@var{table}. In Emacs Lisp, it returns @code{nil}.
@end defun
@defun maphash function table
@anchor{Definition of maphash}
This function calls @var{function} once for each of the associations in
@var{table}. The function @var{function} should accept two
arguments---a @var{key} listed in @var{table}, and its associated
@var{value}. @code{maphash} returns @code{nil}.
@end defun
@node Defining Hash
@section Defining Hash Comparisons
@cindex hash code
@cindex define hash comparisons
You can define new methods of key lookup by means of
@code{define-hash-table-test}. In order to use this feature, you need
to understand how hash tables work, and what a @dfn{hash code} means.
You can think of a hash table conceptually as a large array of many
slots, each capable of holding one association. To look up a key,
@code{gethash} first computes an integer, the hash code, from the key.
It reduces this integer modulo the length of the array, to produce an
index in the array. Then it looks in that slot, and if necessary in
other nearby slots, to see if it has found the key being sought.
Thus, to define a new method of key lookup, you need to specify both a
function to compute the hash code from a key, and a function to compare
two keys directly.
@defun define-hash-table-test name test-fn hash-fn
This function defines a new hash table test, named @var{name}.
After defining @var{name} in this way, you can use it as the @var{test}
argument in @code{make-hash-table}. When you do that, the hash table
will use @var{test-fn} to compare key values, and @var{hash-fn} to compute
a ``hash code'' from a key value.
The function @var{test-fn} should accept two arguments, two keys, and
return non-@code{nil} if they are considered ``the same.''
The function @var{hash-fn} should accept one argument, a key, and return
an integer that is the ``hash code'' of that key. For good results, the
function should use the whole range of integer values for hash codes,
including negative integers.
The specified functions are stored in the property list of @var{name}
under the property @code{hash-table-test}; the property value's form is
@code{(@var{test-fn} @var{hash-fn})}.
@end defun
@defun sxhash obj
This function returns a hash code for Lisp object @var{obj}.
This is an integer which reflects the contents of @var{obj}
and the other Lisp objects it points to.
If two objects @var{obj1} and @var{obj2} are equal, then @code{(sxhash
@var{obj1})} and @code{(sxhash @var{obj2})} are the same integer.
If the two objects are not equal, the values returned by @code{sxhash}
are usually different, but not always; once in a rare while, by luck,
you will encounter two distinct-looking objects that give the same
result from @code{sxhash}.
@end defun
This example creates a hash table whose keys are strings that are
compared case-insensitively.
@example
(defun case-fold-string= (a b)
(compare-strings a nil nil b nil nil t))
(defun case-fold-string-hash (a)
(sxhash (upcase a)))
(define-hash-table-test 'case-fold
'case-fold-string= 'case-fold-string-hash)
(make-hash-table :test 'case-fold)
@end example
Here is how you could define a hash table test equivalent to the
predefined test value @code{equal}. The keys can be any Lisp object,
and equal-looking objects are considered the same key.
@example
(define-hash-table-test 'contents-hash 'equal 'sxhash)
(make-hash-table :test 'contents-hash)
@end example
@node Other Hash
@section Other Hash Table Functions
Here are some other functions for working with hash tables.
@defun hash-table-p table
This returns non-@code{nil} if @var{table} is a hash table object.
@end defun
@defun copy-hash-table table
This function creates and returns a copy of @var{table}. Only the table
itself is copied---the keys and values are shared.
@end defun
@defun hash-table-count table
This function returns the actual number of entries in @var{table}.
@end defun
@defun hash-table-test table
This returns the @var{test} value that was given when @var{table} was
created, to specify how to hash and compare keys. See
@code{make-hash-table} (@pxref{Creating Hash}).
@end defun
@defun hash-table-weakness table
This function returns the @var{weak} value that was specified for hash
table @var{table}.
@end defun
@defun hash-table-rehash-size table
This returns the rehash size of @var{table}.
@end defun
@defun hash-table-rehash-threshold table
This returns the rehash threshold of @var{table}.
@end defun
@defun hash-table-size table
This returns the current nominal size of @var{table}.
@end defun
@ignore
arch-tag: 3b5107f9-d2f0-47d5-ad61-3498496bea0e
@end ignore

699
doc/lispref/help.texi Normal file
View file

@ -0,0 +1,699 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/help
@node Documentation, Files, Modes, Top
@chapter Documentation
@cindex documentation strings
GNU Emacs Lisp has convenient on-line help facilities, most of which
derive their information from the documentation strings associated with
functions and variables. This chapter describes how to write good
documentation strings for your Lisp programs, as well as how to write
programs to access documentation.
Note that the documentation strings for Emacs are not the same thing
as the Emacs manual. Manuals have their own source files, written in
the Texinfo language; documentation strings are specified in the
definitions of the functions and variables they apply to. A collection
of documentation strings is not sufficient as a manual because a good
manual is not organized in that fashion; it is organized in terms of
topics of discussion.
For commands to display documentation strings, see @ref{Help, ,
Help, emacs, The GNU Emacs Manual}. For the conventions for writing
documentation strings, see @ref{Documentation Tips}.
@menu
* Documentation Basics:: Good style for doc strings.
Where to put them. How Emacs stores them.
* Accessing Documentation:: How Lisp programs can access doc strings.
* Keys in Documentation:: Substituting current key bindings.
* Describing Characters:: Making printable descriptions of
non-printing characters and key sequences.
* Help Functions:: Subroutines used by Emacs help facilities.
@end menu
@node Documentation Basics
@comment node-name, next, previous, up
@section Documentation Basics
@cindex documentation conventions
@cindex writing a documentation string
@cindex string, writing a doc string
A documentation string is written using the Lisp syntax for strings,
with double-quote characters surrounding the text of the string. This
is because it really is a Lisp string object. The string serves as
documentation when it is written in the proper place in the definition
of a function or variable. In a function definition, the documentation
string follows the argument list. In a variable definition, the
documentation string follows the initial value of the variable.
When you write a documentation string, make the first line a
complete sentence (or two complete sentences) since some commands,
such as @code{apropos}, show only the first line of a multi-line
documentation string. Also, you should not indent the second line of
a documentation string, if it has one, because that looks odd when you
use @kbd{C-h f} (@code{describe-function}) or @kbd{C-h v}
(@code{describe-variable}) to view the documentation string. There
are many other conventions for doc strings; see @ref{Documentation
Tips}.
Documentation strings can contain several special substrings, which
stand for key bindings to be looked up in the current keymaps when the
documentation is displayed. This allows documentation strings to refer
to the keys for related commands and be accurate even when a user
rearranges the key bindings. (@xref{Keys in Documentation}.)
@vindex emacs-lisp-docstring-fill-column
Emacs Lisp mode fills documentation strings to the width
specified by @code{emacs-lisp-docstring-fill-column}.
In Emacs Lisp, a documentation string is accessible through the
function or variable that it describes:
@itemize @bullet
@item
@kindex function-documentation
The documentation for a function is usually stored in the function
definition itself (@pxref{Lambda Expressions}). The function
@code{documentation} knows how to extract it. You can also put
function documentation in the @code{function-documentation} property
of the function name. That is useful with definitions such as
keyboard macros that can't hold a documentation string.
@item
@kindex variable-documentation
The documentation for a variable is stored in the variable's property
list under the property name @code{variable-documentation}. The
function @code{documentation-property} knows how to retrieve it.
@end itemize
@cindex @file{DOC-@var{version}} (documentation) file
To save space, the documentation for preloaded functions and variables
(including primitive functions and autoloaded functions) is stored in
the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
documentation strings for functions and variables loaded during the
Emacs session from byte-compiled files are stored in those files
(@pxref{Docs and Compilation}).
The data structure inside Emacs has an integer offset into the file, or
a list containing a file name and an integer, in place of the
documentation string. The functions @code{documentation} and
@code{documentation-property} use that information to fetch the
documentation string from the appropriate file; this is transparent to
the user.
@c Wordy to prevent overfull hbox. --rjc 15mar92
The @file{emacs/lib-src} directory contains two utilities that you can
use to print nice-looking hardcopy for the file
@file{emacs/etc/DOC-@var{version}}. These are @file{sorted-doc} and
@file{digest-doc}.
@node Accessing Documentation
@section Access to Documentation Strings
@defun documentation-property symbol property &optional verbatim
This function returns the documentation string that is recorded in
@var{symbol}'s property list under property @var{property}. It
retrieves the text from a file if the value calls for that. If the
property value isn't @code{nil}, isn't a string, and doesn't refer to
text in a file, then it is evaluated to obtain a string.
The last thing this function does is pass the string through
@code{substitute-command-keys} to substitute actual key bindings,
unless @var{verbatim} is non-@code{nil}.
@smallexample
@group
(documentation-property 'command-line-processed
'variable-documentation)
@result{} "Non-nil once command line has been processed"
@end group
@group
(symbol-plist 'command-line-processed)
@result{} (variable-documentation 188902)
@end group
@group
(documentation-property 'emacs 'group-documentation)
@result{} "Customization of the One True Editor."
@end group
@end smallexample
@end defun
@defun documentation function &optional verbatim
This function returns the documentation string of @var{function}.
@code{documentation} handles macros, named keyboard macros, and
special forms, as well as ordinary functions.
If @var{function} is a symbol, this function first looks for the
@code{function-documentation} property of that symbol; if that has a
non-@code{nil} value, the documentation comes from that value (if the
value is not a string, it is evaluated). If @var{function} is not a
symbol, or if it has no @code{function-documentation} property, then
@code{documentation} extracts the documentation string from the actual
function definition, reading it from a file if called for.
Finally, unless @var{verbatim} is non-@code{nil}, it calls
@code{substitute-command-keys} so as to return a value containing the
actual (current) key bindings.
The function @code{documentation} signals a @code{void-function} error
if @var{function} has no function definition. However, it is OK if
the function definition has no documentation string. In that case,
@code{documentation} returns @code{nil}.
@end defun
@defun face-documentation face
This function returns the documentation string of @var{face} as a
face.
@end defun
@c Wordy to prevent overfull hboxes. --rjc 15mar92
Here is an example of using the two functions, @code{documentation} and
@code{documentation-property}, to display the documentation strings for
several symbols in a @samp{*Help*} buffer.
@anchor{describe-symbols example}
@smallexample
@group
(defun describe-symbols (pattern)
"Describe the Emacs Lisp symbols matching PATTERN.
All symbols that have PATTERN in their name are described
in the `*Help*' buffer."
(interactive "sDescribe symbols matching: ")
(let ((describe-func
(function
(lambda (s)
@end group
@group
;; @r{Print description of symbol.}
(if (fboundp s) ; @r{It is a function.}
(princ
(format "%s\t%s\n%s\n\n" s
(if (commandp s)
(let ((keys (where-is-internal s)))
(if keys
(concat
"Keys: "
(mapconcat 'key-description
keys " "))
"Keys: none"))
"Function")
@end group
@group
(or (documentation s)
"not documented"))))
(if (boundp s) ; @r{It is a variable.}
@end group
@group
(princ
(format "%s\t%s\n%s\n\n" s
(if (user-variable-p s)
"Option " "Variable")
@end group
@group
(or (documentation-property
s 'variable-documentation)
"not documented")))))))
sym-list)
@end group
@group
;; @r{Build a list of symbols that match pattern.}
(mapatoms (function
(lambda (sym)
(if (string-match pattern (symbol-name sym))
(setq sym-list (cons sym sym-list))))))
@end group
@group
;; @r{Display the data.}
(with-output-to-temp-buffer "*Help*"
(mapcar describe-func (sort sym-list 'string<))
(print-help-return-message))))
@end group
@end smallexample
The @code{describe-symbols} function works like @code{apropos},
but provides more information.
@smallexample
@group
(describe-symbols "goal")
---------- Buffer: *Help* ----------
goal-column Option
*Semipermanent goal column for vertical motion, as set by @dots{}
@end group
@c Do not blithely break or fill these lines.
@c That makes them incorrect.
@group
set-goal-column Keys: C-x C-n
Set the current horizontal position as a goal for C-n and C-p.
@end group
@c DO NOT put a blank line here! That is factually inaccurate!
@group
Those commands will move to this position in the line moved to
rather than trying to keep the same horizontal position.
With a non-nil argument, clears out the goal column
so that C-n and C-p resume vertical motion.
The goal column is stored in the variable `goal-column'.
@end group
@group
temporary-goal-column Variable
Current goal column for vertical motion.
It is the column where point was
at the start of current run of vertical motion commands.
When the `track-eol' feature is doing its job, the value is 9999.
---------- Buffer: *Help* ----------
@end group
@end smallexample
The asterisk @samp{*} as the first character of a variable's doc string,
as shown above for the @code{goal-column} variable, means that it is a
user option; see the description of @code{defvar} in @ref{Defining
Variables}.
@defun Snarf-documentation filename
@anchor{Definition of Snarf-documentation}
This function is used only during Emacs initialization, just before
the runnable Emacs is dumped. It finds the file offsets of the
documentation strings stored in the file @var{filename}, and records
them in the in-core function definitions and variable property lists in
place of the actual strings. @xref{Building Emacs}.
Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file will be looked
for in the directory @code{doc-directory}. Usually @var{filename} is
@code{"DOC-@var{version}"}.
@end defun
@c Emacs 19 feature
@defvar doc-directory
This variable holds the name of the directory which should contain the
file @code{"DOC-@var{version}"} that contains documentation strings for
built-in and preloaded functions and variables.
In most cases, this is the same as @code{data-directory}. They may be
different when you run Emacs from the directory where you built it,
without actually installing it. @xref{Definition of data-directory}.
In older Emacs versions, @code{exec-directory} was used for this.
@end defvar
@node Keys in Documentation
@section Substituting Key Bindings in Documentation
@cindex documentation, keys in
@cindex keys in documentation strings
@cindex substituting keys in documentation
When documentation strings refer to key sequences, they should use the
current, actual key bindings. They can do so using certain special text
sequences described below. Accessing documentation strings in the usual
way substitutes current key binding information for these special
sequences. This works by calling @code{substitute-command-keys}. You
can also call that function yourself.
Here is a list of the special sequences and what they mean:
@table @code
@item \[@var{command}]
stands for a key sequence that will invoke @var{command}, or @samp{M-x
@var{command}} if @var{command} has no key bindings.
@item \@{@var{mapvar}@}
stands for a summary of the keymap which is the value of the variable
@var{mapvar}. The summary is made using @code{describe-bindings}.
@item \<@var{mapvar}>
stands for no text itself. It is used only for a side effect: it
specifies @var{mapvar}'s value as the keymap for any following
@samp{\[@var{command}]} sequences in this documentation string.
@item \=
quotes the following character and is discarded; thus, @samp{\=\[} puts
@samp{\[} into the output, and @samp{\=\=} puts @samp{\=} into the
output.
@end table
@strong{Please note:} Each @samp{\} must be doubled when written in a
string in Emacs Lisp.
@defun substitute-command-keys string
This function scans @var{string} for the above special sequences and
replaces them by what they stand for, returning the result as a string.
This permits display of documentation that refers accurately to the
user's own customized key bindings.
@end defun
Here are examples of the special sequences:
@smallexample
@group
(substitute-command-keys
"To abort recursive edit, type: \\[abort-recursive-edit]")
@result{} "To abort recursive edit, type: C-]"
@end group
@group
(substitute-command-keys
"The keys that are defined for the minibuffer here are:
\\@{minibuffer-local-must-match-map@}")
@result{} "The keys that are defined for the minibuffer here are:
@end group
? minibuffer-completion-help
SPC minibuffer-complete-word
TAB minibuffer-complete
C-j minibuffer-complete-and-exit
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
@group
(substitute-command-keys
"To abort a recursive edit from the minibuffer, type\
\\<minibuffer-local-must-match-map>\\[abort-recursive-edit].")
@result{} "To abort a recursive edit from the minibuffer, type C-g."
@end group
@end smallexample
There are other special conventions for the text in documentation
strings---for instance, you can refer to functions, variables, and
sections of this manual. @xref{Documentation Tips}, for details.
@node Describing Characters
@section Describing Characters for Help Messages
@cindex describe characters and events
These functions convert events, key sequences, or characters to
textual descriptions. These descriptions are useful for including
arbitrary text characters or key sequences in messages, because they
convert non-printing and whitespace characters to sequences of printing
characters. The description of a non-whitespace printing character is
the character itself.
@defun key-description sequence &optional prefix
@cindex Emacs event standard notation
This function returns a string containing the Emacs standard notation
for the input events in @var{sequence}. If @var{prefix} is
non-@code{nil}, it is a sequence of input events leading up to
@var{sequence} and is included in the return value. Both arguments
may be strings, vectors or lists. @xref{Input Events}, for more
information about valid events.
@smallexample
@group
(key-description [?\M-3 delete])
@result{} "M-3 <delete>"
@end group
@group
(key-description [delete] "\M-3")
@result{} "M-3 <delete>"
@end group
@end smallexample
See also the examples for @code{single-key-description}, below.
@end defun
@defun single-key-description event &optional no-angles
@cindex event printing
@cindex character printing
@cindex control character printing
@cindex meta character printing
This function returns a string describing @var{event} in the standard
Emacs notation for keyboard input. A normal printing character
appears as itself, but a control character turns into a string
starting with @samp{C-}, a meta character turns into a string starting
with @samp{M-}, and space, tab, etc.@: appear as @samp{SPC},
@samp{TAB}, etc. A function key symbol appears inside angle brackets
@samp{<@dots{}>}. An event that is a list appears as the name of the
symbol in the @sc{car} of the list, inside angle brackets.
If the optional argument @var{no-angles} is non-@code{nil}, the angle
brackets around function keys and event symbols are omitted; this is
for compatibility with old versions of Emacs which didn't use the
brackets.
@smallexample
@group
(single-key-description ?\C-x)
@result{} "C-x"
@end group
@group
(key-description "\C-x \M-y \n \t \r \f123")
@result{} "C-x SPC M-y SPC C-j SPC TAB SPC RET SPC C-l 1 2 3"
@end group
@group
(single-key-description 'delete)
@result{} "<delete>"
@end group
@group
(single-key-description 'C-mouse-1)
@result{} "<C-mouse-1>"
@end group
@group
(single-key-description 'C-mouse-1 t)
@result{} "C-mouse-1"
@end group
@end smallexample
@end defun
@defun text-char-description character
This function returns a string describing @var{character} in the
standard Emacs notation for characters that appear in text---like
@code{single-key-description}, except that control characters are
represented with a leading caret (which is how control characters in
Emacs buffers are usually displayed). Another difference is that
@code{text-char-description} recognizes the 2**7 bit as the Meta
character, whereas @code{single-key-description} uses the 2**27 bit
for Meta.
@smallexample
@group
(text-char-description ?\C-c)
@result{} "^C"
@end group
@group
(text-char-description ?\M-m)
@result{} "\xed"
@end group
@group
(text-char-description ?\C-\M-m)
@result{} "\x8d"
@end group
@group
(text-char-description (+ 128 ?m))
@result{} "M-m"
@end group
@group
(text-char-description (+ 128 ?\C-m))
@result{} "M-^M"
@end group
@end smallexample
@end defun
@defun read-kbd-macro string &optional need-vector
This function is used mainly for operating on keyboard macros, but it
can also be used as a rough inverse for @code{key-description}. You
call it with a string containing key descriptions, separated by spaces;
it returns a string or vector containing the corresponding events.
(This may or may not be a single valid key sequence, depending on what
events you use; @pxref{Key Sequences}.) If @var{need-vector} is
non-@code{nil}, the return value is always a vector.
@end defun
@node Help Functions
@section Help Functions
Emacs provides a variety of on-line help functions, all accessible to
the user as subcommands of the prefix @kbd{C-h}. For more information
about them, see @ref{Help, , Help, emacs, The GNU Emacs Manual}. Here
we describe some program-level interfaces to the same information.
@deffn Command apropos pattern &optional do-all
This function finds all ``meaningful'' symbols whose names contain a
match for the apropos pattern @var{pattern}. An apropos pattern is
either a word to match, a space-separated list of words of which at
least two must match, or a regular expression (if any special regular
expression characters occur). A symbol is ``meaningful'' if it has a
definition as a function, variable, or face, or has properties.
The function returns a list of elements that look like this:
@example
(@var{symbol} @var{score} @var{fn-doc} @var{var-doc}
@var{plist-doc} @var{widget-doc} @var{face-doc} @var{group-doc})
@end example
Here, @var{score} is an integer measure of how important the symbol
seems to be as a match, and the remaining elements are documentation
strings for @var{symbol}'s various roles (or @code{nil}).
It also displays the symbols in a buffer named @samp{*Apropos*}, each
with a one-line description taken from the beginning of its
documentation string.
@c Emacs 19 feature
If @var{do-all} is non-@code{nil}, or if the user option
@code{apropos-do-all} is non-@code{nil}, then @code{apropos} also
shows key bindings for the functions that are found; it also shows
@emph{all} interned symbols, not just meaningful ones (and it lists
them in the return value as well).
@end deffn
@defvar help-map
The value of this variable is a local keymap for characters following the
Help key, @kbd{C-h}.
@end defvar
@deffn {Prefix Command} help-command
This symbol is not a function; its function definition cell holds the
keymap known as @code{help-map}. It is defined in @file{help.el} as
follows:
@smallexample
@group
(define-key global-map (char-to-string help-char) 'help-command)
(fset 'help-command help-map)
@end group
@end smallexample
@end deffn
@defun print-help-return-message &optional function
This function builds a string that explains how to restore the previous
state of the windows after a help command. After building the message,
it applies @var{function} to it if @var{function} is non-@code{nil}.
Otherwise it calls @code{message} to display it in the echo area.
This function expects to be called inside a
@code{with-output-to-temp-buffer} special form, and expects
@code{standard-output} to have the value bound by that special form.
For an example of its use, see the long example in @ref{Accessing
Documentation}.
@end defun
@defvar help-char
The value of this variable is the help character---the character that
Emacs recognizes as meaning Help. By default, its value is 8, which
stands for @kbd{C-h}. When Emacs reads this character, if
@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
expression, and displays the result in a window if it is a string.
Usually the value of @code{help-form} is @code{nil}. Then the
help character has no special meaning at the level of command input, and
it becomes part of a key sequence in the normal way. The standard key
binding of @kbd{C-h} is a prefix key for several general-purpose help
features.
The help character is special after prefix keys, too. If it has no
binding as a subcommand of the prefix key, it runs
@code{describe-prefix-bindings}, which displays a list of all the
subcommands of the prefix key.
@end defvar
@defvar help-event-list
The value of this variable is a list of event types that serve as
alternative ``help characters.'' These events are handled just like the
event specified by @code{help-char}.
@end defvar
@defvar help-form
If this variable is non-@code{nil}, its value is a form to evaluate
whenever the character @code{help-char} is read. If evaluating the form
produces a string, that string is displayed.
A command that calls @code{read-event} or @code{read-char} probably
should bind @code{help-form} to a non-@code{nil} expression while it
does input. (The time when you should not do this is when @kbd{C-h} has
some other meaning.) Evaluating this expression should result in a
string that explains what the input is for and how to enter it properly.
Entry to the minibuffer binds this variable to the value of
@code{minibuffer-help-form} (@pxref{Definition of minibuffer-help-form}).
@end defvar
@defvar prefix-help-command
This variable holds a function to print help for a prefix key. The
function is called when the user types a prefix key followed by the help
character, and the help character has no binding after that prefix. The
variable's default value is @code{describe-prefix-bindings}.
@end defvar
@defun describe-prefix-bindings
This function calls @code{describe-bindings} to display a list of all
the subcommands of the prefix key of the most recent key sequence. The
prefix described consists of all but the last event of that key
sequence. (The last event is, presumably, the help character.)
@end defun
The following two functions are meant for modes that want to provide
help without relinquishing control, such as the ``electric'' modes.
Their names begin with @samp{Helper} to distinguish them from the
ordinary help functions.
@deffn Command Helper-describe-bindings
This command pops up a window displaying a help buffer containing a
listing of all of the key bindings from both the local and global keymaps.
It works by calling @code{describe-bindings}.
@end deffn
@deffn Command Helper-help
This command provides help for the current mode. It prompts the user
in the minibuffer with the message @samp{Help (Type ? for further
options)}, and then provides assistance in finding out what the key
bindings are, and what the mode is intended for. It returns @code{nil}.
This can be customized by changing the map @code{Helper-help-map}.
@end deffn
@c Emacs 19 feature
@defvar data-directory
@anchor{Definition of data-directory}
This variable holds the name of the directory in which Emacs finds
certain documentation and text files that come with Emacs. In older
Emacs versions, @code{exec-directory} was used for this.
@end defvar
@c Emacs 19 feature
@defmac make-help-screen fname help-line help-text help-map
This macro defines a help command named @var{fname} that acts like a
prefix key that shows a list of the subcommands it offers.
When invoked, @var{fname} displays @var{help-text} in a window, then
reads and executes a key sequence according to @var{help-map}. The
string @var{help-text} should describe the bindings available in
@var{help-map}.
The command @var{fname} is defined to handle a few events itself, by
scrolling the display of @var{help-text}. When @var{fname} reads one of
those special events, it does the scrolling and then reads another
event. When it reads an event that is not one of those few, and which
has a binding in @var{help-map}, it executes that key's binding and
then returns.
The argument @var{help-line} should be a single-line summary of the
alternatives in @var{help-map}. In the current version of Emacs, this
argument is used only if you set the option @code{three-step-help} to
@code{t}.
This macro is used in the command @code{help-for-help} which is the
binding of @kbd{C-h C-h}.
@end defmac
@defopt three-step-help
If this variable is non-@code{nil}, commands defined with
@code{make-help-screen} display their @var{help-line} strings in the
echo area at first, and display the longer @var{help-text} strings only
if the user types the help character again.
@end defopt
@ignore
arch-tag: ba36b4c2-e60f-49e2-bc25-61158fdcd815
@end ignore

338
doc/lispref/hooks.texi Normal file
View file

@ -0,0 +1,338 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998, 2001, 2002, 2003, 2004,
@c 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/hooks
@node Standard Hooks, Index, Standard Keymaps, Top
@appendix Standard Hooks
@cindex standard hooks
@cindex hook variables, list of
The following is a list of hook variables that let you provide
functions to be called from within Emacs on suitable occasions.
Most of these variables have names ending with @samp{-hook}. They are
@dfn{normal hooks}, run by means of @code{run-hooks}. The value of such
a hook is a list of functions; the functions are called with no
arguments and their values are completely ignored. The recommended way
to put a new function on such a hook is to call @code{add-hook}.
@xref{Hooks}, for more information about using hooks.
Every major mode defines a mode hook named
@samp{@var{modename}-mode-hook}. The major mode command runs this
normal hook with @code{run-mode-hooks} as the very last thing it does.
@xref{Mode Hooks}. Most minor modes have mode hooks too. Mode hooks
are omitted in the list below.
The variables whose names end in @samp{-hooks} or @samp{-functions} are
usually @dfn{abnormal hooks}; their values are lists of functions, but
these functions are called in a special way (they are passed arguments,
or their values are used). The variables whose names end in
@samp{-function} have single functions as their values.
@c We need to xref to where each hook is documented or else document
@c it here.
@table @code
@item activate-mark-hook
@xref{The Mark}.
@item after-change-functions
@xref{Change Hooks}.
@item after-change-major-mode-hook
@xref{Mode Hooks}.
@item after-init-hook
@xref{Init File}.
@item after-insert-file-functions
@xref{Format Conversion}.
@item after-make-frame-functions
@xref{Creating Frames}.
@item after-revert-hook
@xref{Reverting}.
@item after-save-hook
@xref{Saving Buffers}.
@item auto-fill-function
@xref{Auto Filling}.
@item auto-save-hook
@xref{Auto-Saving}.
@item before-change-functions
@xref{Change Hooks}.
@item before-init-hook
@xref{Init File}.
@item before-make-frame-hook
@xref{Creating Frames}.
@item before-revert-hook
@xref{Reverting}.
@item before-save-hook
@xref{Saving Buffers}.
@item blink-paren-function
@xref{Blinking}.
@item buffer-access-fontify-functions
@xref{Lazy Properties}.
@item calendar-load-hook
@iftex
@inforef{Calendar Customizing,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Calendar Customizing,,, emacs}.
@end ifnottex
@item change-major-mode-hook
@xref{Creating Buffer-Local}.
@item command-line-functions
@xref{Command-Line Arguments}.
@item comment-indent-function
@xref{Options for Comments,, Options Controlling Comments, emacs, the
GNU Emacs Manual}.
@item compilation-finish-functions
Functions to call when a compilation process finishes.
@item custom-define-hook
Hook called after defining each customize option.
@item deactivate-mark-hook
@xref{The Mark}.
@item desktop-after-read-hook
Normal hook run after a successful @code{desktop-read}. May be used
to show a buffer list. @xref{Saving Emacs Sessions,, Saving Emacs
Sessions, emacs, the GNU Emacs Manual}.
@item desktop-no-desktop-file-hook
Normal hook run when @code{desktop-read} can't find a desktop file.
May be used to show a dired buffer. @xref{Saving Emacs Sessions,,
Saving Emacs Sessions, emacs, the GNU Emacs Manual}.
@item desktop-save-hook
Normal hook run before the desktop is saved in a desktop file. This
is useful for truncating history lists, for example. @xref{Saving
Emacs Sessions,, Saving Emacs Sessions, emacs, the GNU Emacs Manual}.
@item diary-display-hook
@iftex
@inforef{Fancy Diary Display,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Fancy Diary Display,,, emacs}.
@end ifnottex
@item diary-hook
List of functions called after the display of the diary. Can be used
for appointment notification.
@item disabled-command-function
@xref{Disabling Commands}.
@item echo-area-clear-hook
@xref{Echo Area Customization}.
@item emacs-startup-hook
@xref{Init File}.
@item find-file-hook
@xref{Visiting Functions}.
@item find-file-not-found-functions
@xref{Visiting Functions}.
@item first-change-hook
@xref{Change Hooks}.
@item font-lock-beginning-of-syntax-function
@xref{Syntactic Font Lock}.
@item font-lock-fontify-buffer-function
@xref{Other Font Lock Variables}.
@item font-lock-fontify-region-function
@xref{Other Font Lock Variables}.
@item font-lock-mark-block-function
@xref{Other Font Lock Variables}.
@item font-lock-syntactic-face-function
@xref{Syntactic Font Lock}.
@item font-lock-unfontify-buffer-function
@xref{Other Font Lock Variables}.
@item font-lock-unfontify-region-function
@xref{Other Font Lock Variables}.
@item initial-calendar-window-hook
@iftex
@inforef{Calendar Customizing,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Calendar Customizing,,, emacs}.
@end ifnottex
@item kbd-macro-termination-hook
@xref{Keyboard Macros}.
@item kill-buffer-hook
@xref{Killing Buffers}.
@item kill-buffer-query-functions
@xref{Killing Buffers}.
@item kill-emacs-hook
@xref{Killing Emacs}.
@item kill-emacs-query-functions
@xref{Killing Emacs}.
@item lisp-indent-function
@item list-diary-entries-hook
@iftex
@inforef{Fancy Diary Display,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Fancy Diary Display,,, emacs}.
@end ifnottex
@item mail-setup-hook
@xref{Mail Mode Misc,, Mail Mode Miscellany, emacs, the GNU Emacs
Manual}.
@item mark-diary-entries-hook
@iftex
@inforef{Fancy Diary Display,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Fancy Diary Display,,, emacs}.
@end ifnottex
@item menu-bar-update-hook
@xref{Menu Bar}.
@item minibuffer-setup-hook
@xref{Minibuffer Misc}.
@item minibuffer-exit-hook
@xref{Minibuffer Misc}.
@item mouse-position-function
@xref{Mouse Position}.
@item nongregorian-diary-listing-hook
@iftex
@inforef{Hebrew/Islamic Entries,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Hebrew/Islamic Entries,,, emacs}.
@end ifnottex
@item nongregorian-diary-marking-hook
@iftex
@inforef{Hebrew/Islamic Entries,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Hebrew/Islamic Entries,,, emacs}.
@end ifnottex
@item occur-hook
@item post-command-hook
@xref{Command Overview}.
@item pre-abbrev-expand-hook
@xref{Abbrev Expansion}.
@item pre-command-hook
@xref{Command Overview}.
@item print-diary-entries-hook
@iftex
@inforef{Diary Customizing,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Diary Customizing,,, emacs}.
@end ifnottex
@item redisplay-end-trigger-functions
@xref{Window Hooks}.
@item scheme-indent-function
@item suspend-hook
@xref{Suspending Emacs}.
@item suspend-resume-hook
@xref{Suspending Emacs}.
@item temp-buffer-setup-hook
@xref{Temporary Displays}.
@item temp-buffer-show-function
@xref{Temporary Displays}.
@item temp-buffer-show-hook
@xref{Temporary Displays}.
@item term-setup-hook
@xref{Terminal-Specific}.
@item today-visible-calendar-hook
@iftex
@inforef{Calendar Customizing,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Calendar Customizing,,, emacs}.
@end ifnottex
@item today-invisible-calendar-hook
@iftex
@inforef{Calendar Customizing,, emacs-xtra}.
@end iftex
@ifnottex
@xref{Calendar Customizing,,, emacs}.
@end ifnottex
@item window-configuration-change-hook
@xref{Window Hooks}.
@item window-scroll-functions
@xref{Window Hooks}.
@item window-setup-hook
@xref{Window Systems}.
@item window-size-change-functions
@xref{Window Hooks}.
@item write-contents-functions
@xref{Saving Buffers}.
@item write-file-functions
@xref{Saving Buffers}.
@item write-region-annotate-functions
@xref{Format Conversion}.
@end table
@ignore
arch-tag: 55fd0296-d906-4551-b300-979d3846aa88
@end ignore

29
doc/lispref/index.texi Normal file
View file

@ -0,0 +1,29 @@
@c -*-texinfo-*-
@setfilename ../info/index
@c Indexing guidelines
@c I assume that all indexes will be combined.
@c Therefore, if a generated findex and permutations
@c cover the ways an index user would look up the entry,
@c then no cindex is added.
@c Concept index (cindex) entries will also be permuted. Therefore, they
@c have no commas and few irrelevant connectives in them.
@c I tried to include words in a cindex that give the context of the entry,
@c particularly if there is more than one entry for the same concept.
@c For example, "nil in keymap"
@c Similarly for explicit findex and vindex entries, e.g. "print example".
@c Error codes are given cindex entries, e.g. "end-of-file error".
@c pindex is used for .el files and Unix programs
@node Index, , Standard Hooks, Top
@unnumbered Index
@c Print the indices
@printindex fn

1522
doc/lispref/internals.texi Normal file
View file

File diff suppressed because it is too large Load diff

560
doc/lispref/intro.texi Normal file
View file

@ -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

2785
doc/lispref/keymaps.texi Normal file
View file

File diff suppressed because it is too large Load diff

48
doc/lispref/lay-flat.texi Normal file
View file

@ -0,0 +1,48 @@
\input texinfo @c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c
@comment %**start of header
@setfilename inner-covers.info
@settitle Inner Covers
@smallbook
@comment %**end of header
@headings off
@w{ }
@sp 4
@tex
\center {\secfonts \rm Lay-Flat Binding}
@end tex
@sp 2
We have bound this manual using a new @dfn{lay-flat} binding
technology. This type of binding allows you to open a soft cover book
so that it ``lays flat'' on a table without creasing the binding.
In order to make the book lay flat properly, you need to ``crack'' the
binding. To do this, divide the book into two sections and bend it so
that the front and back covers meet. Do not worry; the pages are
sewn and glued to the binding, and will not fall out easily.
The outer cardboard binding itself is designed so that it will not
break or crease as an ordinary paperback binding will. Bend the book
several times in this manner, dividing it in a different place each
time and pressing the pages flat and open. With use, the binding will
become flexible and the pages will lay flat without needing to be
pushed or held down.
@page
@tex
\center {\secfonts \rm Notes}
@end tex
@bye
@ignore
arch-tag: 9e03a1c7-6f62-4346-85d9-ed5b79386e07
@end ignore

1904
doc/lispref/lists.texi Normal file
View file

File diff suppressed because it is too large Load diff

968
doc/lispref/loading.texi Normal file
View file

@ -0,0 +1,968 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Customization, Top
@chapter Loading
@cindex loading
@cindex library
@cindex Lisp library
Loading a file of Lisp code means bringing its contents into the Lisp
environment in the form of Lisp objects. Emacs finds and opens the
file, reads the text, evaluates each form, and then closes the file.
The load functions evaluate all the expressions in a file just
as the @code{eval-buffer} function evaluates all the
expressions in a buffer. The difference is that the load functions
read and evaluate the text in the file as found on disk, not the text
in an Emacs buffer.
@cindex top-level form
The loaded file must contain Lisp expressions, either as source code
or as byte-compiled code. Each form in the file is called a
@dfn{top-level form}. There is no special format for the forms in a
loadable file; any form in a file may equally well be typed directly
into a buffer and evaluated there. (Indeed, most code is tested this
way.) Most often, the forms are function definitions and variable
definitions.
A file containing Lisp code is often called a @dfn{library}. Thus,
the ``Rmail library'' is a file containing code for Rmail mode.
Similarly, a ``Lisp library directory'' is a directory of files
containing Lisp code.
@menu
* How Programs Do Loading:: The @code{load} function and others.
* Load Suffixes:: Details about the suffixes that @code{load} tries.
* Library Search:: Finding a library to load.
* Loading Non-ASCII:: Non-@acronym{ASCII} characters in Emacs Lisp files.
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
* Where Defined:: Finding which file defined a certain symbol.
* Unloading:: How to "unload" a library that was loaded.
* Hooks for Loading:: Providing code to be run when
particular libraries are loaded.
@end menu
@node How Programs Do Loading
@section How Programs Do Loading
Emacs Lisp has several interfaces for loading. For example,
@code{autoload} creates a placeholder object for a function defined in a
file; trying to call the autoloading function loads the file to get the
function's real definition (@pxref{Autoload}). @code{require} loads a
file if it isn't already loaded (@pxref{Named Features}). Ultimately,
all these facilities call the @code{load} function to do the work.
@defun load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.
To find the file, @code{load} first looks for a file named
@file{@var{filename}.elc}, that is, for a file whose name is
@var{filename} with the extension @samp{.elc} appended. If such a
file exists, it is loaded. If there is no file by that name, then
@code{load} looks for a file named @file{@var{filename}.el}. If that
file exists, it is loaded. Finally, if neither of those names is
found, @code{load} looks for a file named @var{filename} with nothing
appended, and loads it if it exists. (The @code{load} function is not
clever about looking at @var{filename}. In the perverse case of a
file named @file{foo.el.el}, evaluation of @code{(load "foo.el")} will
indeed find it.)
If Auto Compression mode is enabled, as it is by default, then if
@code{load} can not find a file, it searches for a compressed version
of the file before trying other file names. It decompresses and loads
it if it exists. It looks for compressed versions by appending each
of the suffixes in @code{jka-compr-load-suffixes} to the file name.
The value of this variable must be a list of strings. Its standard
value is @code{(".gz")}.
If the optional argument @var{nosuffix} is non-@code{nil}, then
@code{load} does not try the suffixes @samp{.elc} and @samp{.el}. In
this case, you must specify the precise file name you want, except
that, if Auto Compression mode is enabled, @code{load} will still use
@code{jka-compr-load-suffixes} to find compressed versions. By
specifying the precise file name and using @code{t} for
@var{nosuffix}, you can prevent perverse file names such as
@file{foo.el.el} from being tried.
If the optional argument @var{must-suffix} is non-@code{nil}, then
@code{load} insists that the file name used must end in either
@samp{.el} or @samp{.elc} (possibly extended with a compression
suffix), unless it contains an explicit directory name.
If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@code{load-path}. It appends @var{filename} to each of the directories
listed in @code{load-path}, and loads the first file it finds whose name
matches. The current default directory is tried only if it is specified
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
so on. @xref{Library Search}.
If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
means you should consider recompiling @file{foo.el}. @xref{Byte
Compilation}.
When loading a source file (not compiled), @code{load} performs
character set translation just as Emacs would do when visiting the file.
@xref{Coding Systems}.
Messages like @samp{Loading foo...} and @samp{Loading foo...done} appear
in the echo area during loading unless @var{nomessage} is
non-@code{nil}.
@cindex load errors
Any unhandled errors while loading a file terminate loading. If the
load was done for the sake of @code{autoload}, any function definitions
made during the loading are undone.
@kindex file-error
If @code{load} can't find the file to load, then normally it signals the
error @code{file-error} (with @samp{Cannot open load file
@var{filename}}). But if @var{missing-ok} is non-@code{nil}, then
@code{load} just returns @code{nil}.
You can use the variable @code{load-read-function} to specify a function
for @code{load} to use instead of @code{read} for reading expressions.
See below.
@code{load} returns @code{t} if the file loads successfully.
@end defun
@deffn Command load-file filename
This command loads the file @var{filename}. If @var{filename} is a
relative file name, then the current default directory is assumed.
This command does not use @code{load-path}, and does not append
suffixes. However, it does look for compressed versions (if Auto
Compression Mode is enabled). Use this command if you wish to specify
precisely the file name to load.
@end deffn
@deffn Command load-library library
This command loads the library named @var{library}. It is equivalent to
@code{load}, except in how it reads its argument interactively.
@end deffn
@defvar load-in-progress
This variable is non-@code{nil} if Emacs is in the process of loading a
file, and it is @code{nil} otherwise.
@end defvar
@defvar load-read-function
@anchor{Definition of load-read-function}
@c do not allow page break at anchor; work around Texinfo deficiency.
This variable specifies an alternate expression-reading function for
@code{load} and @code{eval-region} to use instead of @code{read}.
The function should accept one argument, just as @code{read} does.
Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
Instead of using this variable, it is cleaner to use another, newer
feature: to pass the function as the @var{read-function} argument to
@code{eval-region}. @xref{Definition of eval-region,, Eval}.
@end defvar
For information about how @code{load} is used in building Emacs, see
@ref{Building Emacs}.
@node Load Suffixes
@section Load Suffixes
We now describe some technical details about the exact suffixes that
@code{load} tries.
@defvar load-suffixes
This is a list of suffixes indicating (compiled or source) Emacs Lisp
files. It should not include the empty string. @code{load} uses
these suffixes in order when it appends Lisp suffixes to the specified
file name. The standard value is @code{(".elc" ".el")} which produces
the behavior described in the previous section.
@end defvar
@defvar load-file-rep-suffixes
This is a list of suffixes that indicate representations of the same
file. This list should normally start with the empty string.
When @code{load} searches for a file it appends the suffixes in this
list, in order, to the file name, before searching for another file.
Enabling Auto Compression mode appends the suffixes in
@code{jka-compr-load-suffixes} to this list and disabling Auto
Compression mode removes them again. The standard value of
@code{load-file-rep-suffixes} if Auto Compression mode is disabled is
@code{("")}. Given that the standard value of
@code{jka-compr-load-suffixes} is @code{(".gz")}, the standard value
of @code{load-file-rep-suffixes} if Auto Compression mode is enabled
is @code{("" ".gz")}.
@end defvar
@defun get-load-suffixes
This function returns the list of all suffixes that @code{load} should
try, in order, when its @var{must-suffix} argument is non-@code{nil}.
This takes both @code{load-suffixes} and @code{load-file-rep-suffixes}
into account. If @code{load-suffixes}, @code{jka-compr-load-suffixes}
and @code{load-file-rep-suffixes} all have their standard values, this
function returns @code{(".elc" ".elc.gz" ".el" ".el.gz")} if Auto
Compression mode is enabled and @code{(".elc" ".el")} if Auto
Compression mode is disabled.
@end defun
To summarize, @code{load} normally first tries the suffixes in the
value of @code{(get-load-suffixes)} and then those in
@code{load-file-rep-suffixes}. If @var{nosuffix} is non-@code{nil},
it skips the former group, and if @var{must-suffix} is non-@code{nil},
it skips the latter group.
@node Library Search
@section Library Search
@cindex library search
@cindex find library
When Emacs loads a Lisp library, it searches for the library
in a list of directories specified by the variable @code{load-path}.
@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when
loading files with @code{load}. Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
directory).
@end defopt
The value of @code{load-path} is initialized from the environment
variable @code{EMACSLOADPATH}, if that exists; otherwise its default
value is specified in @file{emacs/src/epaths.h} when Emacs is built.
Then the list is expanded by adding subdirectories of the directories
in the list.
The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@samp{:} (or @samp{;}, according to the operating system) separates
directory names, and @samp{.} is used for the current default directory.
Here is an example of how to set your @code{EMACSLOADPATH} variable from
a @code{csh} @file{.login} file:
@smallexample
setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
Here is how to set it using @code{sh}:
@smallexample
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/share/emacs/20.3/lisp
@end smallexample
Here is an example of code you can place in your init file (@pxref{Init
File}) to add several directories to the front of your default
@code{load-path}:
@smallexample
@group
(setq load-path
(append (list nil "/user/bil/emacs"
"/usr/local/lisplib"
"~/emacs")
load-path))
@end group
@end smallexample
@c Wordy to rid us of an overfull hbox. --rjc 15mar92
@noindent
In this example, the path searches the current working directory first,
followed then by the @file{/user/bil/emacs} directory, the
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.
Dumping Emacs uses a special value of @code{load-path}. If the value of
@code{load-path} at the end of dumping is unchanged (that is, still the
same special value), the dumped Emacs switches to the ordinary
@code{load-path} value when it starts up, as described above. But if
@code{load-path} has any other value at the end of dumping, that value
is used for execution of the dumped Emacs also.
Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.
The default value of @code{load-path}, when running an Emacs which has
been installed on the system, includes two special directories (and
their subdirectories as well):
@smallexample
"/usr/local/share/emacs/@var{version}/site-lisp"
@end smallexample
@noindent
and
@smallexample
"/usr/local/share/emacs/site-lisp"
@end smallexample
@noindent
The first one is for locally installed packages for a particular Emacs
version; the second is for locally installed packages meant for use with
all installed Emacs versions.
There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another. Sometimes packages need
updating for incompatible changes in Emacs; sometimes they depend on
undocumented internal Emacs data that can change without notice;
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.
Emacs finds these directories' subdirectories and adds them to
@code{load-path} when it starts up. Both immediate subdirectories and
subdirectories multiple levels down are added to @code{load-path}.
Not all subdirectories are included, though. Subdirectories whose
names do not start with a letter or digit are excluded. Subdirectories
named @file{RCS} or @file{CVS} are excluded. Also, a subdirectory which
contains a file named @file{.nosearch} is excluded. You can use these
methods to prevent certain subdirectories of the @file{site-lisp}
directories from being searched.
If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path}
normally contains two additional directories. These are the @code{lisp}
and @code{site-lisp} subdirectories of the main build directory. (Both
are represented as absolute file names.)
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
searches for the library in the same way @code{load} does, and the
argument @var{nosuffix} has the same meaning as in @code{load}: don't
add suffixes @samp{.elc} or @samp{.el} to the specified name
@var{library}.
If the @var{path} is non-@code{nil}, that list of directories is used
instead of @code{load-path}.
When @code{locate-library} is called from a program, it returns the file
name as a string. When the user runs @code{locate-library}
interactively, the argument @var{interactive-call} is @code{t}, and this
tells @code{locate-library} to display the file name in the echo area.
@end deffn
@node Loading Non-ASCII
@section Loading Non-@acronym{ASCII} Characters
When Emacs Lisp programs contain string constants with non-@acronym{ASCII}
characters, these can be represented within Emacs either as unibyte
strings or as multibyte strings (@pxref{Text Representations}). Which
representation is used depends on how the file is read into Emacs. If
it is read with decoding into multibyte representation, the text of the
Lisp program will be multibyte text, and its string constants will be
multibyte strings. If a file containing Latin-1 characters (for
example) is read without decoding, the text of the program will be
unibyte text, and its string constants will be unibyte strings.
@xref{Coding Systems}.
To make the results more predictable, Emacs always performs decoding
into the multibyte representation when loading Lisp files, even if it
was started with the @samp{--unibyte} option. This means that string
constants with non-@acronym{ASCII} characters translate into multibyte
strings. The only exception is when a particular file specifies no
decoding.
The reason Emacs is designed this way is so that Lisp programs give
predictable results, regardless of how Emacs was started. In addition,
this enables programs that depend on using multibyte text to work even
in a unibyte Emacs. Of course, such programs should be designed to
notice whether the user prefers unibyte or multibyte text, by checking
@code{default-enable-multibyte-characters}, and convert representations
appropriately.
In most Emacs Lisp programs, the fact that non-@acronym{ASCII} strings are
multibyte strings should not be noticeable, since inserting them in
unibyte buffers converts them to unibyte automatically. However, if
this does make a difference, you can force a particular Lisp file to be
interpreted as unibyte by writing @samp{-*-unibyte: t;-*-} in a
comment on the file's first line. With that designator, the file will
unconditionally be interpreted as unibyte, even in an ordinary
multibyte Emacs session. This can matter when making keybindings to
non-@acronym{ASCII} characters written as @code{?v@var{literal}}.
@node Autoload
@section Autoload
@cindex autoload
The @dfn{autoload} facility allows you to make a function or macro
known in Lisp, but put off loading the file that defines it. The first
call to the function automatically reads the proper file to install the
real definition and other associated code, then runs the real definition
as if it had been loaded all along.
There are two ways to set up an autoloaded function: by calling
@code{autoload}, and by writing a special ``magic'' comment in the
source before the real definition. @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time. Magic comments are the most convenient way to make a function
autoload, for packages installed along with Emacs. These comments do
nothing on their own, but they serve as a guide for the command
@code{update-file-autoloads}, which constructs calls to @code{autoload}
and arranges to execute them when Emacs is built.
@defun autoload function filename &optional docstring interactive type
This function defines the function (or macro) named @var{function} so as
to load automatically from @var{filename}. The string @var{filename}
specifies the file to load to get the real definition of @var{function}.
If @var{filename} does not contain either a directory name, or the
suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
one of these suffixes, and it will not load from a file whose name is
just @var{filename} with no added suffix. (The variable
@code{load-suffixes} specifies the exact required suffixes.)
The argument @var{docstring} is the documentation string for the
function. Specifying the documentation string in the call to
@code{autoload} makes it possible to look at the documentation without
loading the function's real definition. Normally, this should be
identical to the documentation string in the function definition
itself. If it isn't, the function definition's documentation string
takes effect when it is loaded.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
loading @var{function}'s real definition. The complete interactive
specification is not given here; it's not needed unless the user
actually calls @var{function}, and when that happens, it's time to load
the real definition.
You can autoload macros and keymaps as well as ordinary functions.
Specify @var{type} as @code{macro} if @var{function} is really a macro.
Specify @var{type} as @code{keymap} if @var{function} is really a
keymap. Various parts of Emacs need to know this information without
loading the real definition.
An autoloaded keymap loads automatically during key lookup when a prefix
key's binding is the symbol @var{function}. Autoloading does not occur
for other kinds of access to the keymap. In particular, it does not
happen when a Lisp program gets the keymap from the value of a variable
and calls @code{define-key}; not even if the variable name is the same
symbol @var{function}.
@cindex function cell in autoload
If @var{function} already has a non-void function definition that is not
an autoload object, @code{autoload} does nothing and returns @code{nil}.
If the function cell of @var{function} is void, or is already an autoload
object, then it is defined as an autoload object like this:
@example
(autoload @var{filename} @var{docstring} @var{interactive} @var{type})
@end example
For example,
@example
@group
(symbol-function 'run-prolog)
@result{} (autoload "prolog" 169681 t nil)
@end group
@end example
@noindent
In this case, @code{"prolog"} is the name of the file to load, 169681
refers to the documentation string in the
@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
@code{t} means the function is interactive, and @code{nil} that it is
not a macro or a keymap.
@end defun
@cindex autoload errors
The autoloaded file usually contains other definitions and may require
or provide one or more features. If the file is not completely loaded
(due to an error in the evaluation of its contents), any function
definitions or @code{provide} calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
this, then some of the functions in the file might be defined by the
aborted load, but fail to work properly for the lack of certain
subroutines not loaded successfully because they come later in the file.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
define function @var{function-name}"}.
@findex update-file-autoloads
@findex update-directory-autoloads
@cindex magic autoload comment
@cindex autoload cookie
@anchor{autoload cookie}
A magic autoload comment (often called an @dfn{autoload cookie})
consists of @samp{;;;###autoload}, on a line by itself,
just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
Building Emacs loads @file{loaddefs.el} and thus calls @code{autoload}.
@kbd{M-x update-directory-autoloads} is even more powerful; it updates
autoloads for all files in the current directory.
The same magic comment can copy any kind of form into
@file{loaddefs.el}. If the form following the magic comment is not a
function-defining form or a @code{defcustom} form, it is copied
verbatim. ``Function-defining forms'' include @code{define-skeleton},
@code{define-derived-mode}, @code{define-generic-mode} and
@code{define-minor-mode} as well as @code{defun} and
@code{defmacro}. To save space, a @code{defcustom} form is converted to
a @code{defvar} in @file{loaddefs.el}, with some additional information
if it uses @code{:require}.
You can also use a magic comment to execute a form at build time
@emph{without} executing it when the file itself is loaded. To do this,
write the form @emph{on the same line} as the magic comment. Since it
is in a comment, it does nothing when you load the source file; but
@kbd{M-x update-file-autoloads} copies it to @file{loaddefs.el}, where
it is executed while building Emacs.
The following example shows how @code{doctor} is prepared for
autoloading with a magic comment:
@smallexample
;;;###autoload
(defun doctor ()
"Switch to *doctor* buffer and start giving psychotherapy."
(interactive)
(switch-to-buffer "*doctor*")
(doctor-mode))
@end smallexample
@noindent
Here's what that produces in @file{loaddefs.el}:
@smallexample
(autoload (quote doctor) "doctor" "\
Switch to *doctor* buffer and start giving psychotherapy.
\(fn)" t nil)
@end smallexample
@noindent
@cindex @code{fn} in function's documentation string
The backslash and newline immediately following the double-quote are a
convention used only in the preloaded uncompiled Lisp files such as
@file{loaddefs.el}; they tell @code{make-docfile} to put the
documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
See also the commentary in @file{lib-src/make-docfile.c}. @samp{(fn)}
in the usage part of the documentation string is replaced with the
function's name when the various help functions (@pxref{Help
Functions}) display it.
If you write a function definition with an unusual macro that is not
one of the known and recognized function definition methods, use of an
ordinary magic autoload comment would copy the whole definition into
@code{loaddefs.el}. That is not desirable. You can put the desired
@code{autoload} call into @code{loaddefs.el} instead by writing this:
@smallexample
;;;###autoload (autoload 'foo "myfile")
(mydefunmacro foo
...)
@end smallexample
@node Repeated Loading
@section Repeated Loading
@cindex repeated loading
You can load a given file more than once in an Emacs session. For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.
When you load or reload files, bear in mind that the @code{load} and
@code{load-library} functions automatically load a byte-compiled file
rather than a non-compiled file of similar name. If you rewrite a file
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file! If that happens, the message
displayed when loading the file includes, @samp{(compiled; note, source is
newer)}, to remind you to recompile it.
When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once. For example, think about whether
each variable should be reinitialized when you reload the library;
@code{defvar} does not change the value if the variable is already
initialized. (@xref{Defining Variables}.)
The simplest way to add an element to an alist is like this:
@example
(push '(leif-mode " Leif") minor-mode-alist)
@end example
@noindent
But this would add multiple elements if the library is reloaded.
To avoid the problem, write this:
@example
(or (assq 'leif-mode minor-mode-alist)
(push '(leif-mode " Leif") minor-mode-alist))
@end example
@noindent
or this:
@example
(add-to-list '(leif-mode " Leif") minor-mode-alist)
@end example
Occasionally you will want to test explicitly whether a library has
already been loaded. Here's one way to test, in a library, whether it
has been loaded before:
@example
(defvar foo-was-loaded nil)
(unless foo-was-loaded
@var{execute-first-time-only}
(setq foo-was-loaded t))
@end example
@noindent
If the library uses @code{provide} to provide a named feature, you can
use @code{featurep} earlier in the file to test whether the
@code{provide} call has been executed before.
@ifnottex
@xref{Named Features}.
@end ifnottex
@node Named Features
@section Features
@cindex features
@cindex requiring features
@cindex providing features
@code{provide} and @code{require} are an alternative to
@code{autoload} for loading files automatically. They work in terms of
named @dfn{features}. Autoloading is triggered by calling a specific
function, but a feature is loaded the first time another program asks
for it by name.
A feature name is a symbol that stands for a collection of functions,
variables, etc. The file that defines them should @dfn{provide} the
feature. Another program that uses them may ensure they are defined by
@dfn{requiring} the feature. This loads the file of definitions if it
hasn't been loaded already.
To require the presence of a feature, call @code{require} with the
feature name as argument. @code{require} looks in the global variable
@code{features} to see whether the desired feature has been provided
already. If not, it loads the feature from the appropriate file. This
file should call @code{provide} at the top level to add the feature to
@code{features}; if it fails to do so, @code{require} signals an error.
@cindex load error with require
For example, in @file{emacs/lisp/prolog.el},
the definition for @code{run-prolog} includes the following code:
@smallexample
(defun run-prolog ()
"Run an inferior Prolog process, with I/O via buffer *prolog*."
(interactive)
(require 'comint)
(switch-to-buffer (make-comint "prolog" prolog-program-name))
(inferior-prolog-mode))
@end smallexample
@noindent
The expression @code{(require 'comint)} loads the file @file{comint.el}
if it has not yet been loaded. This ensures that @code{make-comint} is
defined. Features are normally named after the files that provide them,
so that @code{require} need not be given the file name.
The @file{comint.el} file contains the following top-level expression:
@smallexample
(provide 'comint)
@end smallexample
@noindent
This adds @code{comint} to the global @code{features} list, so that
@code{(require 'comint)} will henceforth know that nothing needs to be
done.
@cindex byte-compiling @code{require}
When @code{require} is used at top level in a file, it takes effect
when you byte-compile that file (@pxref{Byte Compilation}) as well as
when you load it. This is in case the required package contains macros
that the byte compiler must know about. It also avoids byte-compiler
warnings for functions and variables defined in the file loaded with
@code{require}.
Although top-level calls to @code{require} are evaluated during
byte compilation, @code{provide} calls are not. Therefore, you can
ensure that a file of definitions is loaded before it is byte-compiled
by including a @code{provide} followed by a @code{require} for the same
feature, as in the following example.
@smallexample
@group
(provide 'my-feature) ; @r{Ignored by byte compiler,}
; @r{evaluated by @code{load}.}
(require 'my-feature) ; @r{Evaluated by byte compiler.}
@end group
@end smallexample
@noindent
The compiler ignores the @code{provide}, then processes the
@code{require} by loading the file in question. Loading the file does
execute the @code{provide} call, so the subsequent @code{require} call
does nothing when the file is loaded.
@defun provide feature &optional subfeatures
This function announces that @var{feature} is now loaded, or being
loaded, into the current Emacs session. This means that the facilities
associated with @var{feature} are or will be available for other Lisp
programs.
The direct effect of calling @code{provide} is to add @var{feature} to
the front of the list @code{features} if it is not already in the list.
The argument @var{feature} must be a symbol. @code{provide} returns
@var{feature}.
If provided, @var{subfeatures} should be a list of symbols indicating
a set of specific subfeatures provided by this version of
@var{feature}. You can test the presence of a subfeature using
@code{featurep}. The idea of subfeatures is that you use them when a
package (which is one @var{feature}) is complex enough to make it
useful to give names to various parts or functionalities of the
package, which might or might not be loaded, or might or might not be
present in a given version. @xref{Network Feature Testing}, for
an example.
@smallexample
features
@result{} (bar bish)
(provide 'foo)
@result{} foo
features
@result{} (foo bar bish)
@end smallexample
When a file is loaded to satisfy an autoload, and it stops due to an
error in the evaluation of its contents, any function definitions or
@code{provide} calls that occurred during the load are undone.
@xref{Autoload}.
@end defun
@defun require feature &optional filename noerror
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below). The
argument @var{feature} must be a symbol.
If the feature is not present, then @code{require} loads @var{filename}
with @code{load}. If @var{filename} is not supplied, then the name of
the symbol @var{feature} is used as the base file name to load.
However, in this case, @code{require} insists on finding @var{feature}
with an added @samp{.el} or @samp{.elc} suffix (possibly extended with
a compression suffix); a file whose name is just @var{feature} won't
be used. (The variable @code{load-suffixes} specifies the exact
required Lisp suffixes.)
If @var{noerror} is non-@code{nil}, that suppresses errors from actual
loading of the file. In that case, @code{require} returns @code{nil}
if loading the file fails. Normally, @code{require} returns
@var{feature}.
If loading the file succeeds but does not provide @var{feature},
@code{require} signals an error, @samp{Required feature @var{feature}
was not provided}.
@end defun
@defun featurep feature &optional subfeature
This function returns @code{t} if @var{feature} has been provided in
the current Emacs session (i.e.@:, if @var{feature} is a member of
@code{features}.) If @var{subfeature} is non-@code{nil}, then the
function returns @code{t} only if that subfeature is provided as well
(i.e.@: if @var{subfeature} is a member of the @code{subfeature}
property of the @var{feature} symbol.)
@end defun
@defvar features
The value of this variable is a list of symbols that are the features
loaded in the current Emacs session. Each symbol was put in this list
with a call to @code{provide}. The order of the elements in the
@code{features} list is not significant.
@end defvar
@node Where Defined
@section Which File Defined a Certain Symbol
@defun symbol-file symbol &optional type
This function returns the name of the file that defined @var{symbol}.
If @var{type} is @code{nil}, then any kind of definition is
acceptable. If @var{type} is @code{defun} or @code{defvar}, that
specifies function definition only or variable definition only.
The value is normally an absolute file name. It can also be
@code{nil}, if the definition is not associated with any file.
@end defun
The basis for @code{symbol-file} is the data in the variable
@code{load-history}.
@defvar load-history
This variable's value is an alist connecting library file names with the
names of functions and variables they define, the features they provide,
and the features they require.
Each element is a list and describes one library. The @sc{car} of the
list is the absolute file name of the library, as a string. The rest
of the list elements have these forms:
@table @code
@item @var{var}
The symbol @var{var} was defined as a variable.
@item (defun . @var{fun})
The function @var{fun} was defined.
@item (t . @var{fun})
The function @var{fun} was previously an autoload before this library
redefined it as a function. The following element is always
@code{(defun . @var{fun})}, which represents defining @var{fun} as a
function.
@item (autoload . @var{fun})
The function @var{fun} was defined as an autoload.
@item (require . @var{feature})
The feature @var{feature} was required.
@item (provide . @var{feature})
The feature @var{feature} was provided.
@end table
The value of @code{load-history} may have one element whose @sc{car} is
@code{nil}. This element describes definitions made with
@code{eval-buffer} on a buffer that is not visiting a file.
@end defvar
The command @code{eval-region} updates @code{load-history}, but does so
by adding the symbols defined to the element for the file being visited,
rather than replacing that element. @xref{Eval}.
@node Unloading
@section Unloading
@cindex unloading packages
@c Emacs 19 feature
You can discard the functions and variables loaded by a library to
reclaim memory for other Lisp objects. To do this, use the function
@code{unload-feature}:
@deffn Command unload-feature feature &optional force
This command unloads the library that provided feature @var{feature}.
It undefines all functions, macros, and variables defined in that
library with @code{defun}, @code{defalias}, @code{defsubst},
@code{defmacro}, @code{defconst}, @code{defvar}, and @code{defcustom}.
It then restores any autoloads formerly associated with those symbols.
(Loading saves these in the @code{autoload} property of the symbol.)
@vindex unload-feature-special-hooks
Before restoring the previous definitions, @code{unload-feature} runs
@code{remove-hook} to remove functions in the library from certain
hooks. These hooks include variables whose names end in @samp{hook}
or @samp{-hooks}, plus those listed in
@code{unload-feature-special-hooks}. This is to prevent Emacs from
ceasing to function because important hooks refer to functions that
are no longer defined.
@vindex @var{feature}-unload-hook
If these measures are not sufficient to prevent malfunction, a library
can define an explicit unload hook. If @code{@var{feature}-unload-hook}
is defined, it is run as a normal hook before restoring the previous
definitions, @emph{instead of} the usual hook-removing actions. The
unload hook ought to undo all the global state changes made by the
library that might cease to work once the library is unloaded.
@code{unload-feature} can cause problems with libraries that fail to do
this, so it should be used with caution.
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
@var{b} if @var{a} contains a @code{require} for @var{b}.) If the
optional argument @var{force} is non-@code{nil}, dependencies are
ignored and you can unload any library.
@end deffn
The @code{unload-feature} function is written in Lisp; its actions are
based on the variable @code{load-history}.
@defvar unload-feature-special-hooks
This variable holds a list of hooks to be scanned before unloading a
library, to remove functions defined in the library.
@end defvar
@node Hooks for Loading
@section Hooks for Loading
@cindex loading hooks
@cindex hooks for loading
You can ask for code to be executed if and when a particular library is
loaded, by calling @code{eval-after-load}.
@defun eval-after-load library form
This function arranges to evaluate @var{form} at the end of loading
the file @var{library}, each time @var{library} is loaded. If
@var{library} is already loaded, it evaluates @var{form} right away.
Don't forget to quote @var{form}!
You don't need to give a directory or extension in the file name
@var{library}---normally you just give a bare file name, like this:
@example
(eval-after-load "edebug" '(def-edebug-spec c-point t))
@end example
To restrict which files can trigger the evaluation, include a
directory or an extension or both in @var{library}. Only a file whose
absolute true name (i.e., the name with all symbolic links chased out)
matches all the given name components will match. In the following
example, @file{my_inst.elc} or @file{my_inst.elc.gz} in some directory
@code{..../foo/bar} will trigger the evaluation, but not
@file{my_inst.el}:
@example
(eval-after-load "foo/bar/my_inst.elc" @dots{})
@end example
@var{library} can also be a feature (i.e.@: a symbol), in which case
@var{form} is evaluated when @code{(provide @var{library})} is called.
An error in @var{form} does not undo the load, but does prevent
execution of the rest of @var{form}.
@end defun
In general, well-designed Lisp programs should not use this feature.
The clean and modular ways to interact with a Lisp library are (1)
examine and set the library's variables (those which are meant for
outside use), and (2) call the library's functions. If you wish to
do (1), you can do it immediately---there is no need to wait for when
the library is loaded. To do (2), you must load the library (preferably
with @code{require}).
But it is OK to use @code{eval-after-load} in your personal
customizations if you don't feel they must meet the design standards for
programs meant for wider use.
@defvar after-load-alist
This variable, an alist built by @code{eval-after-load}, holds the
expressions to evaluate when particular libraries are loaded. Each
element looks like this:
@example
(@var{regexp-or-feature} @var{forms}@dots{})
@end example
The key @var{regexp-or-feature} is either a regular expression or a
symbol, and the value is a list of forms. The forms are evaluated when
the key matches the absolute true name of the file being
@code{load}ed or the symbol being @code{provide}d.
@end defvar
@ignore
arch-tag: df731f89-0900-4389-a436-9105241b6f7a
@end ignore

232
doc/lispref/locals.texi Normal file
View file

@ -0,0 +1,232 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
@c 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/locals
@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top
@appendix Buffer-Local Variables
@c The title "Standard Buffer-Local Variables" is too long for
@c smallbook. --rjc 30mar92
@cindex buffer-local variables, general-purpose
@cindex standard buffer-local variables
The table below lists the general-purpose Emacs variables that
automatically become buffer-local in each buffer. Most become
buffer-local only when set; a few of them are always local in every
buffer. Many Lisp packages define such variables for their internal
use, but we don't try to list them all here.
Every buffer-specific minor mode defines a buffer-local variable
named @samp{@var{modename}-mode}. @xref{Minor Mode Conventions}.
Minor mode variables will not be listed here.
@table @code
@item auto-fill-function
@xref{Auto Filling}.
@item buffer-auto-save-file-format
@xref{Format Conversion}.
@item buffer-auto-save-file-name
@xref{Auto-Saving}.
@item buffer-backed-up
@xref{Making Backups}.
@item buffer-display-count
@xref{Buffers and Windows}.
@item buffer-display-table
@xref{Active Display Table}.
@item buffer-display-time
@xref{Buffers and Windows}.
@item buffer-file-coding-system
@xref{Encoding and I/O}.
@item buffer-file-format
@xref{Format Conversion}.
@item buffer-file-name
@xref{Buffer File Name}.
@item buffer-file-number
@xref{Buffer File Name}.
@item buffer-file-truename
@xref{Buffer File Name}.
@item buffer-file-type
@xref{MS-DOS File Types}.
@item buffer-invisibility-spec
@xref{Invisible Text}.
@item buffer-offer-save
@xref{Killing Buffers}.
@item buffer-save-without-query
@xref{Killing Buffers}.
@item buffer-read-only
@xref{Read Only Buffers}.
@item buffer-saved-size
@xref{Auto-Saving}.
@item buffer-undo-list
@xref{Undo}.
@item cache-long-line-scans
@xref{Truncation}.
@item case-fold-search
@xref{Searching and Case}.
@item ctl-arrow
@xref{Usual Display}.
@item cursor-type
@xref{Cursor Parameters}.
@item cursor-in-non-selected-windows
@xref{Basic Windows}.
@item comment-column
@xref{Comments,,, emacs, The GNU Emacs Manual}.
@item default-directory
@xref{File Name Expansion}.
@item defun-prompt-regexp
@xref{List Motion}.
@item desktop-save-buffer
@xref{Desktop Save Mode}.
@ignore
@item direction-reversed
Does not work yet.
@end ignore
@item enable-multibyte-characters
@ref{Text Representations}.
@item fill-column
@xref{Margins}.
@item fill-prefix
@xref{Margins}.
@item font-lock-defaults
@xref{Font Lock Basics}.
@item fringe-cursor-alist
@xref{Fringe Cursors}.
@item fringe-indicator-alist
@xref{Fringe Indicators}.
@item fringes-outside-margins
@xref{Fringes}.
@item goal-column
@xref{Moving Point,,, emacs, The GNU Emacs Manual}.
@item header-line-format
@xref{Header Lines}.
@item indicate-buffer-boundaries
@xref{Usual Display}.
@item indicate-empty-lines
@xref{Usual Display}.
@item left-fringe-width
@xref{Fringe Size/Pos}.
@item left-margin
@xref{Margins}.
@item left-margin-width
@xref{Display Margins}.
@item line-spacing
@xref{Line Height}.
@item local-abbrev-table
@xref{Standard Abbrev Tables}.
@item major-mode
@xref{Mode Help}.
@item mark-active
@xref{The Mark}.
@item mark-ring
@xref{The Mark}.
@item mode-line-buffer-identification
@xref{Mode Line Variables}.
@item mode-line-format
@xref{Mode Line Data}.
@item mode-line-modified
@xref{Mode Line Variables}.
@item mode-line-process
@xref{Mode Line Variables}.
@item mode-name
@xref{Mode Line Variables}.
@item point-before-scroll
Used for communication between mouse commands and scroll-bar commands.
@item right-fringe-width
@xref{Fringe Size/Pos}.
@item right-margin-width
@xref{Display Margins}.
@item save-buffer-coding-system
@xref{Encoding and I/O}.
@item scroll-bar-width
@xref{Scroll Bars}.
@item scroll-down-aggressively
@xref{Textual Scrolling}.
@item scroll-up-aggressively
@xref{Textual Scrolling}.
@item selective-display
@xref{Selective Display}.
@item selective-display-ellipses
@xref{Selective Display}.
@item tab-width
@xref{Usual Display}.
@item truncate-lines
@xref{Truncation}.
@item vertical-scroll-bar
@xref{Scroll Bars}.
@item window-size-fixed
@xref{Resizing Windows}.
@item write-contents-functions
@xref{Saving Buffers}.
@end table
@ignore
arch-tag: 6baae835-b667-4447-91e2-9829ae1cf543
@end ignore

752
doc/lispref/macros.texi Normal file
View file

@ -0,0 +1,752 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 2001, 2002,
@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/macros
@node Macros, Customization, Functions, Top
@chapter Macros
@cindex macros
@dfn{Macros} enable you to define new control constructs and other
language features. A macro is defined much like a function, but instead
of telling how to compute a value, it tells how to compute another Lisp
expression which will in turn compute the value. We call this
expression the @dfn{expansion} of the macro.
Macros can do this because they operate on the unevaluated expressions
for the arguments, not on the argument values as functions do. They can
therefore construct an expansion containing these argument expressions
or parts of them.
If you are using a macro to do something an ordinary function could
do, just for the sake of speed, consider using an inline function
instead. @xref{Inline Functions}.
@menu
* Simple Macro:: A basic example.
* Expansion:: How, when and why macros are expanded.
* Compiling Macros:: How macros are expanded by the compiler.
* Defining Macros:: How to write a macro definition.
* Backquote:: Easier construction of list structure.
* Problems with Macros:: Don't evaluate the macro arguments too many times.
Don't hide the user's variables.
* Indenting Macros:: Specifying how to indent macro calls.
@end menu
@node Simple Macro
@section A Simple Example of a Macro
Suppose we would like to define a Lisp construct to increment a
variable value, much like the @code{++} operator in C. We would like to
write @code{(inc x)} and have the effect of @code{(setq x (1+ x))}.
Here's a macro definition that does the job:
@findex inc
@example
@group
(defmacro inc (var)
(list 'setq var (list '1+ var)))
@end group
@end example
When this is called with @code{(inc x)}, the argument @var{var} is the
symbol @code{x}---@emph{not} the @emph{value} of @code{x}, as it would
be in a function. The body of the macro uses this to construct the
expansion, which is @code{(setq x (1+ x))}. Once the macro definition
returns this expansion, Lisp proceeds to evaluate it, thus incrementing
@code{x}.
@node Expansion
@section Expansion of a Macro Call
@cindex expansion of macros
@cindex macro call
A macro call looks just like a function call in that it is a list which
starts with the name of the macro. The rest of the elements of the list
are the arguments of the macro.
Evaluation of the macro call begins like evaluation of a function call
except for one crucial difference: the macro arguments are the actual
expressions appearing in the macro call. They are not evaluated before
they are given to the macro definition. By contrast, the arguments of a
function are results of evaluating the elements of the function call
list.
Having obtained the arguments, Lisp invokes the macro definition just
as a function is invoked. The argument variables of the macro are bound
to the argument values from the macro call, or to a list of them in the
case of a @code{&rest} argument. And the macro body executes and
returns its value just as a function body does.
The second crucial difference between macros and functions is that the
value returned by the macro body is not the value of the macro call.
Instead, it is an alternate expression for computing that value, also
known as the @dfn{expansion} of the macro. The Lisp interpreter
proceeds to evaluate the expansion as soon as it comes back from the
macro.
Since the expansion is evaluated in the normal manner, it may contain
calls to other macros. It may even be a call to the same macro, though
this is unusual.
You can see the expansion of a given macro call by calling
@code{macroexpand}.
@defun macroexpand form &optional environment
@cindex macro expansion
This function expands @var{form}, if it is a macro call. If the result
is another macro call, it is expanded in turn, until something which is
not a macro call results. That is the value returned by
@code{macroexpand}. If @var{form} is not a macro call to begin with, it
is returned as given.
Note that @code{macroexpand} does not look at the subexpressions of
@var{form} (although some macro definitions may do so). Even if they
are macro calls themselves, @code{macroexpand} does not expand them.
The function @code{macroexpand} does not expand calls to inline functions.
Normally there is no need for that, since a call to an inline function is
no harder to understand than a call to an ordinary function.
If @var{environment} is provided, it specifies an alist of macro
definitions that shadow the currently defined macros. Byte compilation
uses this feature.
@smallexample
@group
(defmacro inc (var)
(list 'setq var (list '1+ var)))
@result{} inc
@end group
@group
(macroexpand '(inc r))
@result{} (setq r (1+ r))
@end group
@group
(defmacro inc2 (var1 var2)
(list 'progn (list 'inc var1) (list 'inc var2)))
@result{} inc2
@end group
@group
(macroexpand '(inc2 r s))
@result{} (progn (inc r) (inc s)) ; @r{@code{inc} not expanded here.}
@end group
@end smallexample
@end defun
@defun macroexpand-all form &optional environment
@code{macroexpand-all} expands macros like @code{macroexpand}, but
will look for and expand all macros in @var{form}, not just at the
top-level. If no macros are expanded, the return value is @code{eq}
to @var{form}.
Repeating the example used for @code{macroexpand} above with
@code{macroexpand-all}, we see that @code{macroexpand-all} @emph{does}
expand the embedded calls to @code{inc}:
@smallexample
(macroexpand-all '(inc2 r s))
@result{} (progn (setq r (1+ r)) (setq s (1+ s)))
@end smallexample
@end defun
@node Compiling Macros
@section Macros and Byte Compilation
@cindex byte-compiling macros
You might ask why we take the trouble to compute an expansion for a
macro and then evaluate the expansion. Why not have the macro body
produce the desired results directly? The reason has to do with
compilation.
When a macro call appears in a Lisp program being compiled, the Lisp
compiler calls the macro definition just as the interpreter would, and
receives an expansion. But instead of evaluating this expansion, it
compiles the expansion as if it had appeared directly in the program.
As a result, the compiled code produces the value and side effects
intended for the macro, but executes at full compiled speed. This would
not work if the macro body computed the value and side effects
itself---they would be computed at compile time, which is not useful.
In order for compilation of macro calls to work, the macros must
already be defined in Lisp when the calls to them are compiled. The
compiler has a special feature to help you do this: if a file being
compiled contains a @code{defmacro} form, the macro is defined
temporarily for the rest of the compilation of that file. To make this
feature work, you must put the @code{defmacro} in the same file where it
is used, and before its first use.
Byte-compiling a file executes any @code{require} calls at top-level
in the file. This is in case the file needs the required packages for
proper compilation. One way to ensure that necessary macro definitions
are available during compilation is to require the files that define
them (@pxref{Named Features}). To avoid loading the macro definition files
when someone @emph{runs} the compiled program, write
@code{eval-when-compile} around the @code{require} calls (@pxref{Eval
During Compile}).
@node Defining Macros
@section Defining Macros
A Lisp macro is a list whose @sc{car} is @code{macro}. Its @sc{cdr} should
be a function; expansion of the macro works by applying the function
(with @code{apply}) to the list of unevaluated argument-expressions
from the macro call.
It is possible to use an anonymous Lisp macro just like an anonymous
function, but this is never done, because it does not make sense to pass
an anonymous macro to functionals such as @code{mapcar}. In practice,
all Lisp macros have names, and they are usually defined with the
special form @code{defmacro}.
@defspec defmacro name argument-list body-forms@dots{}
@code{defmacro} defines the symbol @var{name} as a macro that looks
like this:
@example
(macro lambda @var{argument-list} . @var{body-forms})
@end example
(Note that the @sc{cdr} of this list is a function---a lambda expression.)
This macro object is stored in the function cell of @var{name}. The
value returned by evaluating the @code{defmacro} form is @var{name}, but
usually we ignore this value.
The shape and meaning of @var{argument-list} is the same as in a
function, and the keywords @code{&rest} and @code{&optional} may be used
(@pxref{Argument List}). Macros may have a documentation string, but
any @code{interactive} declaration is ignored since macros cannot be
called interactively.
@end defspec
The body of the macro definition can include a @code{declare} form,
which can specify how @key{TAB} should indent macro calls, and how to
step through them for Edebug.
@defmac declare @var{specs}@dots{}
@anchor{Definition of declare}
A @code{declare} form is used in a macro definition to specify various
additional information about it. Two kinds of specification are
currently supported:
@table @code
@item (debug @var{edebug-form-spec})
Specify how to step through macro calls for Edebug.
@xref{Instrumenting Macro Calls}.
@item (indent @var{indent-spec})
Specify how to indent calls to this macro. @xref{Indenting Macros},
for more details.
@end table
A @code{declare} form only has its special effect in the body of a
@code{defmacro} form if it immediately follows the documentation
string, if present, or the argument list otherwise. (Strictly
speaking, @emph{several} @code{declare} forms can follow the
documentation string or argument list, but since a @code{declare} form
can have several @var{specs}, they can always be combined into a
single form.) When used at other places in a @code{defmacro} form, or
outside a @code{defmacro} form, @code{declare} just returns @code{nil}
without evaluating any @var{specs}.
@end defmac
No macro absolutely needs a @code{declare} form, because that form
has no effect on how the macro expands, on what the macro means in the
program. It only affects secondary features: indentation and Edebug.
@node Backquote
@section Backquote
@cindex backquote (list substitution)
@cindex ` (list substitution)
@findex `
Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the @samp{`}
syntax (usually called @dfn{backquote}).
Backquote allows you to quote a list, but selectively evaluate
elements of that list. In the simplest case, it is identical to the
special form @code{quote} (@pxref{Quoting}). For example, these
two forms yield identical results:
@example
@group
`(a list of (+ 2 3) elements)
@result{} (a list of (+ 2 3) elements)
@end group
@group
'(a list of (+ 2 3) elements)
@result{} (a list of (+ 2 3) elements)
@end group
@end example
@findex , @r{(with backquote)}
The special marker @samp{,} inside of the argument to backquote
indicates a value that isn't constant. Backquote evaluates the
argument of @samp{,} and puts the value in the list structure:
@example
@group
(list 'a 'list 'of (+ 2 3) 'elements)
@result{} (a list of 5 elements)
@end group
@group
`(a list of ,(+ 2 3) elements)
@result{} (a list of 5 elements)
@end group
@end example
Substitution with @samp{,} is allowed at deeper levels of the list
structure also. For example:
@example
@group
(defmacro t-becomes-nil (variable)
`(if (eq ,variable t)
(setq ,variable nil)))
@end group
@group
(t-becomes-nil foo)
@equiv{} (if (eq foo t) (setq foo nil))
@end group
@end example
@findex ,@@ @r{(with backquote)}
@cindex splicing (with backquote)
You can also @dfn{splice} an evaluated value into the resulting list,
using the special marker @samp{,@@}. The elements of the spliced list
become elements at the same level as the other elements of the resulting
list. The equivalent code without using @samp{`} is often unreadable.
Here are some examples:
@example
@group
(setq some-list '(2 3))
@result{} (2 3)
@end group
@group
(cons 1 (append some-list '(4) some-list))
@result{} (1 2 3 4 2 3)
@end group
@group
`(1 ,@@some-list 4 ,@@some-list)
@result{} (1 2 3 4 2 3)
@end group
@group
(setq list '(hack foo bar))
@result{} (hack foo bar)
@end group
@group
(cons 'use
(cons 'the
(cons 'words (append (cdr list) '(as elements)))))
@result{} (use the words foo bar as elements)
@end group
@group
`(use the words ,@@(cdr list) as elements)
@result{} (use the words foo bar as elements)
@end group
@end example
In old Emacs versions, before version 19.29, @samp{`} used a different
syntax which required an extra level of parentheses around the entire
backquote construct. Likewise, each @samp{,} or @samp{,@@} substitution
required an extra level of parentheses surrounding both the @samp{,} or
@samp{,@@} and the following expression. The old syntax required
whitespace between the @samp{`}, @samp{,} or @samp{,@@} and the
following expression.
This syntax is still accepted, for compatibility with old Emacs
versions, but support for it will soon disappear.
@node Problems with Macros
@section Common Problems Using Macros
The basic facts of macro expansion have counterintuitive consequences.
This section describes some important consequences that can lead to
trouble, and rules to follow to avoid trouble.
@menu
* Wrong Time:: Do the work in the expansion, not in the macro.
* Argument Evaluation:: The expansion should evaluate each macro arg once.
* Surprising Local Vars:: Local variable bindings in the expansion
require special care.
* Eval During Expansion:: Don't evaluate them; put them in the expansion.
* Repeated Expansion:: Avoid depending on how many times expansion is done.
@end menu
@node Wrong Time
@subsection Wrong Time
The most common problem in writing macros is doing some of the
real work prematurely---while expanding the macro, rather than in the
expansion itself. For instance, one real package had this macro
definition:
@example
(defmacro my-set-buffer-multibyte (arg)
(if (fboundp 'set-buffer-multibyte)
(set-buffer-multibyte arg)))
@end example
With this erroneous macro definition, the program worked fine when
interpreted but failed when compiled. This macro definition called
@code{set-buffer-multibyte} during compilation, which was wrong, and
then did nothing when the compiled package was run. The definition
that the programmer really wanted was this:
@example
(defmacro my-set-buffer-multibyte (arg)
(if (fboundp 'set-buffer-multibyte)
`(set-buffer-multibyte ,arg)))
@end example
@noindent
This macro expands, if appropriate, into a call to
@code{set-buffer-multibyte} that will be executed when the compiled
program is actually run.
@node Argument Evaluation
@subsection Evaluating Macro Arguments Repeatedly
When defining a macro you must pay attention to the number of times
the arguments will be evaluated when the expansion is executed. The
following macro (used to facilitate iteration) illustrates the problem.
This macro allows us to write a simple ``for'' loop such as one might
find in Pascal.
@findex for
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
(list 'let (list (list var init))
(cons 'while (cons (list '<= var final)
(append body (list (list 'inc var)))))))
@end group
@result{} for
@group
(for i from 1 to 3 do
(setq square (* i i))
(princ (format "\n%d %d" i square)))
@expansion{}
@end group
@group
(let ((i 1))
(while (<= i 3)
(setq square (* i i))
(princ (format "\n%d %d" i square))
(inc i)))
@end group
@group
@print{}1 1
@print{}2 4
@print{}3 9
@result{} nil
@end group
@end smallexample
@noindent
The arguments @code{from}, @code{to}, and @code{do} in this macro are
``syntactic sugar''; they are entirely ignored. The idea is that you
will write noise words (such as @code{from}, @code{to}, and @code{do})
in those positions in the macro call.
Here's an equivalent definition simplified through use of backquote:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple \"for\" loop.
For example, (for i from 1 to 10 do (print i))."
`(let ((,var ,init))
(while (<= ,var ,final)
,@@body
(inc ,var))))
@end group
@end smallexample
Both forms of this definition (with backquote and without) suffer from
the defect that @var{final} is evaluated on every iteration. If
@var{final} is a constant, this is not a problem. If it is a more
complex form, say @code{(long-complex-calculation x)}, this can slow
down the execution significantly. If @var{final} has side effects,
executing it more than once is probably incorrect.
@cindex macro argument evaluation
A well-designed macro definition takes steps to avoid this problem by
producing an expansion that evaluates the argument expressions exactly
once unless repeated evaluation is part of the intended purpose of the
macro. Here is a correct expansion for the @code{for} macro:
@smallexample
@group
(let ((i 1)
(max 3))
(while (<= i max)
(setq square (* i i))
(princ (format "%d %d" i square))
(inc i)))
@end group
@end smallexample
Here is a macro definition that creates this expansion:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
`(let ((,var ,init)
(max ,final))
(while (<= ,var max)
,@@body
(inc ,var))))
@end group
@end smallexample
Unfortunately, this fix introduces another problem,
described in the following section.
@node Surprising Local Vars
@subsection Local Variables in Macro Expansions
@ifnottex
In the previous section, the definition of @code{for} was fixed as
follows to make the expansion evaluate the macro arguments the proper
number of times:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
@end group
@group
`(let ((,var ,init)
(max ,final))
(while (<= ,var max)
,@@body
(inc ,var))))
@end group
@end smallexample
@end ifnottex
The new definition of @code{for} has a new problem: it introduces a
local variable named @code{max} which the user does not expect. This
causes trouble in examples such as the following:
@smallexample
@group
(let ((max 0))
(for x from 0 to 10 do
(let ((this (frob x)))
(if (< max this)
(setq max this)))))
@end group
@end smallexample
@noindent
The references to @code{max} inside the body of the @code{for}, which
are supposed to refer to the user's binding of @code{max}, really access
the binding made by @code{for}.
The way to correct this is to use an uninterned symbol instead of
@code{max} (@pxref{Creating Symbols}). The uninterned symbol can be
bound and referred to just like any other symbol, but since it is
created by @code{for}, we know that it cannot already appear in the
user's program. Since it is not interned, there is no way the user can
put it into the program later. It will never appear anywhere except
where put by @code{for}. Here is a definition of @code{for} that works
this way:
@smallexample
@group
(defmacro for (var from init to final do &rest body)
"Execute a simple for loop: (for i from 1 to 10 do (print i))."
(let ((tempvar (make-symbol "max")))
`(let ((,var ,init)
(,tempvar ,final))
(while (<= ,var ,tempvar)
,@@body
(inc ,var)))))
@end group
@end smallexample
@noindent
This creates an uninterned symbol named @code{max} and puts it in the
expansion instead of the usual interned symbol @code{max} that appears
in expressions ordinarily.
@node Eval During Expansion
@subsection Evaluating Macro Arguments in Expansion
Another problem can happen if the macro definition itself
evaluates any of the macro argument expressions, such as by calling
@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
variable with the same name as one of the macro arguments. Inside the
macro body, the macro argument binding is the most local binding of this
variable, so any references inside the form being evaluated do refer to
it. Here is an example:
@example
@group
(defmacro foo (a)
(list 'setq (eval a) t))
@result{} foo
@end group
@group
(setq x 'b)
(foo x) @expansion{} (setq b t)
@result{} t ; @r{and @code{b} has been set.}
;; @r{but}
(setq a 'c)
(foo a) @expansion{} (setq a t)
@result{} t ; @r{but this set @code{a}, not @code{c}.}
@end group
@end example
It makes a difference whether the user's variable is named @code{a} or
@code{x}, because @code{a} conflicts with the macro argument variable
@code{a}.
Another problem with calling @code{eval} in a macro definition is that
it probably won't do what you intend in a compiled program. The
byte-compiler runs macro definitions while compiling the program, when
the program's own computations (which you might have wished to access
with @code{eval}) don't occur and its local variable bindings don't
exist.
To avoid these problems, @strong{don't evaluate an argument expression
while computing the macro expansion}. Instead, substitute the
expression into the macro expansion, so that its value will be computed
as part of executing the expansion. This is how the other examples in
this chapter work.
@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?
Occasionally problems result from the fact that a macro call is
expanded each time it is evaluated in an interpreted function, but is
expanded only once (during compilation) for a compiled function. If the
macro definition has side effects, they will work differently depending
on how many times the macro is expanded.
Therefore, you should avoid side effects in computation of the
macro expansion, unless you really know what you are doing.
One special kind of side effect can't be avoided: constructing Lisp
objects. Almost all macro expansions include constructed lists; that is
the whole point of most macros. This is usually safe; there is just one
case where you must be careful: when the object you construct is part of a
quoted constant in the macro expansion.
If the macro is expanded just once, in compilation, then the object is
constructed just once, during compilation. But in interpreted
execution, the macro is expanded each time the macro call runs, and this
means a new object is constructed each time.
In most clean Lisp code, this difference won't matter. It can matter
only if you perform side-effects on the objects constructed by the macro
definition. Thus, to avoid trouble, @strong{avoid side effects on
objects constructed by macro definitions}. Here is an example of how
such side effects can get you into trouble:
@lisp
@group
(defmacro empty-object ()
(list 'quote (cons nil nil)))
@end group
@group
(defun initialize (condition)
(let ((object (empty-object)))
(if condition
(setcar object condition))
object))
@end group
@end lisp
@noindent
If @code{initialize} is interpreted, a new list @code{(nil)} is
constructed each time @code{initialize} is called. Thus, no side effect
survives between calls. If @code{initialize} is compiled, then the
macro @code{empty-object} is expanded during compilation, producing a
single ``constant'' @code{(nil)} that is reused and altered each time
@code{initialize} is called.
One way to avoid pathological cases like this is to think of
@code{empty-object} as a funny kind of constant, not as a memory
allocation construct. You wouldn't use @code{setcar} on a constant such
as @code{'(nil)}, so naturally you won't use it on @code{(empty-object)}
either.
@node Indenting Macros
@section Indenting Macros
You can use the @code{declare} form in the macro definition to
specify how to @key{TAB} should indent indent calls to the macro. You
write it like this:
@example
(declare (indent @var{indent-spec}))
@end example
@noindent
Here are the possibilities for @var{indent-spec}:
@table @asis
@item @code{nil}
This is the same as no property---use the standard indentation pattern.
@item @code{defun}
Handle this function like a @samp{def} construct: treat the second
line as the start of a @dfn{body}.
@item an integer, @var{number}
The first @var{number} arguments of the function are
@dfn{distinguished} arguments; the rest are considered the body
of the expression. A line in the expression is indented according to
whether the first argument on it is distinguished or not. If the
argument is part of the body, the line is indented @code{lisp-body-indent}
more columns than the open-parenthesis starting the containing
expression. If the argument is distinguished and is either the first
or second argument, it is indented @emph{twice} that many extra columns.
If the argument is distinguished and not the first or second argument,
the line uses the standard pattern.
@item a symbol, @var{symbol}
@var{symbol} should be a function name; that function is called to
calculate the indentation of a line within this expression. The
function receives two arguments:
@table @asis
@item @var{state}
The value returned by @code{parse-partial-sexp} (a Lisp primitive for
indentation and nesting computation) when it parses up to the
beginning of this line.
@item @var{pos}
The position at which the line being indented begins.
@end table
@noindent
It should return either a number, which is the number of columns of
indentation for that line, or a list whose car is such a number. The
difference between returning a number and returning a list is that a
number says that all following lines at the same nesting level should
be indented just like this one; a list says that following lines might
call for different indentations. This makes a difference when the
indentation is being computed by @kbd{C-M-q}; if the value is a
number, @kbd{C-M-q} need not recalculate indentation for the following
lines until the end of the list.
@end table
@ignore
arch-tag: d4cce66d-1047-45c3-bfde-db6719d6e82b
@end ignore

123
doc/lispref/makefile.w32-in Normal file
View file

@ -0,0 +1,123 @@
# -*- Makefile -*- for the GNU Emacs Lisp Reference Manual.
# Copyright (C) 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
# This file is part of GNU Emacs.
# GNU Emacs is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
# GNU Emacs is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
# You should have received a copy of the GNU General Public License
# along with GNU Emacs; see the file COPYING. If not, write to
# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
# Standard configure variables.
srcdir = .
infodir = $(srcdir)/../info
usermanualdir = $(srcdir)/../man
# Redefine `TEX' if `tex' does not invoke plain TeX. For example:
# TEX=platex
TEX=tex
INSTALL_INFO = install-info
MAKEINFO = makeinfo --force
# The environment variable and its value to add $(srcdir) to the path
# searched for TeX input files.
texinputdir = $(srcdir)\..\nt\envadd.bat "TEXINPUTS=$(srcdir);$(TEXINPUTS)" /C
# The name of the manual:
VERSION=2.9
manual = elisp-manual-21-$(VERSION)
# List of all the texinfo files in the manual:
srcs = \
$(srcdir)/abbrevs.texi \
$(srcdir)/advice.texi \
$(srcdir)/anti.texi \
$(srcdir)/back.texi \
$(srcdir)/backups.texi \
$(srcdir)/buffers.texi \
$(srcdir)/commands.texi \
$(srcdir)/compile.texi \
$(srcdir)/control.texi \
$(srcdir)/customize.texi \
$(srcdir)/debugging.texi \
$(srcdir)/display.texi \
$(srcdir)/edebug.texi \
$(srcdir)/elisp.texi \
$(srcdir)/errors.texi \
$(srcdir)/eval.texi \
$(srcdir)/files.texi \
$(srcdir)/frames.texi \
$(srcdir)/functions.texi \
$(srcdir)/hash.texi \
$(srcdir)/help.texi \
$(srcdir)/hooks.texi \
$(srcdir)/internals.texi \
$(srcdir)/intro.texi \
$(srcdir)/keymaps.texi \
$(srcdir)/lists.texi \
$(srcdir)/loading.texi \
$(srcdir)/locals.texi \
$(srcdir)/macros.texi \
$(srcdir)/maps.texi \
$(srcdir)/markers.texi \
$(srcdir)/minibuf.texi \
$(srcdir)/modes.texi \
$(srcdir)/nonascii.texi \
$(srcdir)/numbers.texi \
$(srcdir)/objects.texi \
$(srcdir)/os.texi \
$(srcdir)/positions.texi \
$(srcdir)/processes.texi \
$(srcdir)/searching.texi \
$(srcdir)/sequences.texi \
$(srcdir)/streams.texi \
$(srcdir)/strings.texi \
$(srcdir)/symbols.texi \
$(srcdir)/syntax.texi \
$(srcdir)/text.texi \
$(srcdir)/tips.texi \
$(srcdir)/variables.texi \
$(srcdir)/windows.texi \
$(srcdir)/index.texi \
$(srcdir)/gpl.texi \
$(srcdir)/doclicense.texi
.PHONY: clean
# The info file is named `elisp'.
info: $(infodir)/elisp
$(infodir)/dir:
$(INSTALL_INFO) --info-dir=$(infodir) $(infodir)/elisp
$(infodir)/elisp: $(srcs)
$(MAKEINFO) -I. -I$(srcdir) -o $(infodir)/elisp $(srcdir)/elisp.texi
elisp.dvi: $(srcs)
$(texinputdir) $(TEX) -I $(usermanualdir) $(srcdir)/elisp.texi
clean:
- $(DEL) *.toc *.aux *.log *.cp *.cps *.fn *.fns *.tp *.tps \
*.vr *.vrs *.pg *.pgs *.ky *.kys
- $(DEL) make.out core
- $(DEL) $(infodir)/elisp*
distclean: clean
maintainer-clean: distclean
- $(DEL) elisp elisp-? elisp-?? elisp.dvi elisp.oaux

230
doc/lispref/maps.texi Normal file
View file

@ -0,0 +1,230 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1999, 2001, 2002, 2003, 2004,
@c 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/maps
@node Standard Keymaps, Standard Hooks, Standard Buffer-Local Variables, Top
@appendix Standard Keymaps
@cindex standard keymaps
The following symbols are used as the names for various keymaps.
Some of these exist when Emacs is first started, others are
loaded only when their respective mode is used. This is not
an exhaustive list.
Several keymaps are used in the minibuffer. @xref{Completion Commands}.
Almost all of these maps are used as local maps. Indeed, of the modes
that presently exist, only Vip mode and Terminal mode ever change the
global keymap.
@table @code
@item apropos-mode-map
@vindex apropos-mode-map
A sparse keymap for @code{apropos} buffers.
@item Buffer-menu-mode-map
@vindex Buffer-menu-mode-map
A full keymap used by Buffer Menu mode.
@item c-mode-map
@vindex c-mode-map
A sparse keymap used by C mode.
@item command-history-map
@vindex command-history-map
A full keymap used by Command History mode.
@item ctl-x-4-map
A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
@item ctl-x-5-map
A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
@item ctl-x-map
A full keymap for @kbd{C-x} commands.
@item custom-mode-map
A full keymap for Custom mode.
@item debugger-mode-map
@vindex debugger-mode-map
A full keymap used by Debugger mode.
@item dired-mode-map
@vindex dired-mode-map
A full keymap for @code{dired-mode} buffers.
@item edit-abbrevs-map
@vindex edit-abbrevs-map
A sparse keymap used in @code{edit-abbrevs}.
@item edit-tab-stops-map
@vindex edit-tab-stops-map
A sparse keymap used in @code{edit-tab-stops}.
@item electric-buffer-menu-mode-map
@vindex electric-buffer-menu-mode-map
A full keymap used by Electric Buffer Menu mode.
@item electric-history-map
@vindex electric-history-map
A full keymap used by Electric Command History mode.
@item emacs-lisp-mode-map
@vindex emacs-lisp-mode-map
A sparse keymap used by Emacs Lisp mode.
@item esc-map
A full keymap for @kbd{ESC} (or @kbd{Meta}) commands.
@item facemenu-menu
@vindex facemenu-menu
The sparse keymap that displays the Text Properties menu.
@item facemenu-background-menu
@vindex facemenu-background-menu
The sparse keymap that displays the Background Color submenu of the Text
Properties menu.
@item facemenu-face-menu
@vindex facemenu-face-menu
The sparse keymap that displays the Face submenu of the Text Properties menu.
@item facemenu-foreground-menu
@vindex facemenu-foreground-menu
The sparse keymap that displays the Foreground Color submenu of the Text
Properties menu.
@item facemenu-indentation-menu
@vindex facemenu-indentation-menu
The sparse keymap that displays the Indentation submenu of the Text
Properties menu.
@item facemenu-justification-menu
@vindex facemenu-justification-menu
The sparse keymap that displays the Justification submenu of the Text
Properties menu.
@item facemenu-special-menu
@vindex facemenu-special-menu
The sparse keymap that displays the Special Props submenu of the Text
Properties menu.
@item function-key-map
The keymap for translating keypad and function keys.@*
If there are none, then it contains an empty sparse keymap.
@xref{Translation Keymaps}.
@item fundamental-mode-map
@vindex fundamental-mode-map
The sparse keymap for Fundamental mode.@*
It is empty and should not be changed.
@item global-map
The full keymap containing default global key bindings.@*
Modes should not modify the Global map.
@item grep-mode-map
@vindex grep-mode-map
The keymap for @code{grep-mode} buffers.
@item help-map
The sparse keymap for the keys that follow the help character @kbd{C-h}.
@item help-mode-map
@vindex help-mode-map
The sparse keymap for Help mode.
@item Helper-help-map
@vindex Helper-help-map
A full keymap used by the help utility package.@*
It has the same keymap in its value cell and in its function
cell.
@item Info-edit-map
@vindex Info-edit-map
A sparse keymap used by the @kbd{e} command of Info.
@item Info-mode-map
@vindex Info-mode-map
A sparse keymap containing Info commands.
@item isearch-mode-map
@vindex isearch-mode-map
A keymap that defines the characters you can type within incremental
search.
@item key-translation-map
A keymap for translating keys. This one overrides ordinary key
bindings, unlike @code{function-key-map}. @xref{Translation Keymaps}.
@item kmacro-map
@vindex kmacro-map
A sparse keymap for keys that follows the @kbd{C-x C-k} prefix
search.
@item lisp-interaction-mode-map
@vindex lisp-interaction-mode-map
A sparse keymap used by Lisp Interaction mode.
@item lisp-mode-map
@vindex lisp-mode-map
A sparse keymap used by Lisp mode.
@item menu-bar-edit-menu
@vindex menu-bar-edit-menu
The keymap which displays the Edit menu in the menu bar.
@item menu-bar-files-menu
@vindex menu-bar-files-menu
The keymap which displays the Files menu in the menu bar.
@item menu-bar-help-menu
@vindex menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.
@item menu-bar-mule-menu
@vindex menu-bar-mule-menu
The keymap which displays the Mule menu in the menu bar.
@item menu-bar-search-menu
@vindex menu-bar-search-menu
The keymap which displays the Search menu in the menu bar.
@item menu-bar-tools-menu
@vindex menu-bar-tools-menu
The keymap which displays the Tools menu in the menu bar.
@item mode-specific-map
The keymap for characters following @kbd{C-c}. Note, this is in the
global map. This map is not actually mode specific: its name was chosen
to be informative for the user in @kbd{C-h b} (@code{display-bindings}),
where it describes the main use of the @kbd{C-c} prefix key.
@item occur-mode-map
@vindex occur-mode-map
A sparse keymap used by Occur mode.
@item query-replace-map
A sparse keymap used for responses in @code{query-replace} and related
commands; also for @code{y-or-n-p} and @code{map-y-or-n-p}. The functions
that use this map do not support prefix keys; they look up one event at a
time.
@item text-mode-map
@vindex text-mode-map
A sparse keymap used by Text mode.
@item tool-bar-map
The keymap defining the contents of the tool bar.
@item view-mode-map
@vindex view-mode-map
A full keymap used by View mode.
@end table
@ignore
arch-tag: b741253c-7e23-4a02-b3fa-cffd9e4d72b9
@end ignore

664
doc/lispref/markers.texi Normal file
View file

@ -0,0 +1,664 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/markers
@node Markers, Text, Positions, Top
@chapter Markers
@cindex markers
A @dfn{marker} is a Lisp object used to specify a position in a buffer
relative to the surrounding text. A marker changes its offset from the
beginning of the buffer automatically whenever text is inserted or
deleted, so that it stays with the two characters on either side of it.
@menu
* Overview of Markers:: The components of a marker, and how it relocates.
* Predicates on Markers:: Testing whether an object is a marker.
* Creating Markers:: Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Marker Insertion Types:: Two ways a marker can relocate when you
insert where it points.
* Moving Markers:: Moving the marker to a new buffer or position.
* The Mark:: How "the mark" is implemented with a marker.
* The Region:: How to access "the region".
@end menu
@node Overview of Markers
@section Overview of Markers
A marker specifies a buffer and a position in that buffer. The
marker can be used to represent a position in the functions that
require one, just as an integer could be used. In that case, the
marker's buffer is normally ignored. Of course, a marker used in this
way usually points to a position in the buffer that the function
operates on, but that is entirely the programmer's responsibility.
@xref{Positions}, for a complete description of positions.
A marker has three attributes: the marker position, the marker
buffer, and the insertion type. The marker position is an integer
that is equivalent (at a given time) to the marker as a position in
that buffer. But the marker's position value can change often during
the life of the marker. Insertion and deletion of text in the buffer
relocate the marker. The idea is that a marker positioned between two
characters remains between those two characters despite insertion and
deletion elsewhere in the buffer. Relocation changes the integer
equivalent of the marker.
@cindex marker relocation
Deleting text around a marker's position leaves the marker between the
characters immediately before and after the deleted text. Inserting
text at the position of a marker normally leaves the marker either in
front of or after the new text, depending on the marker's @dfn{insertion
type} (@pxref{Marker Insertion Types})---unless the insertion is done
with @code{insert-before-markers} (@pxref{Insertion}).
@cindex marker garbage collection
Insertion and deletion in a buffer must check all the markers and
relocate them if necessary. This slows processing in a buffer with a
large number of markers. For this reason, it is a good idea to make a
marker point nowhere if you are sure you don't need it any more.
Unreferenced markers are garbage collected eventually, but until then
will continue to use time if they do point somewhere.
@cindex markers as numbers
Because it is common to perform arithmetic operations on a marker
position, most of the arithmetic operations (including @code{+} and
@code{-}) accept markers as arguments. In such cases, the marker
stands for its current position.
Here are examples of creating markers, setting markers, and moving point
to markers:
@example
@group
;; @r{Make a new marker that initially does not point anywhere:}
(setq m1 (make-marker))
@result{} #<marker in no buffer>
@end group
@group
;; @r{Set @code{m1} to point between the 99th and 100th characters}
;; @r{in the current buffer:}
(set-marker m1 100)
@result{} #<marker at 100 in markers.texi>
@end group
@group
;; @r{Now insert one character at the beginning of the buffer:}
(goto-char (point-min))
@result{} 1
(insert "Q")
@result{} nil
@end group
@group
;; @r{@code{m1} is updated appropriately.}
m1
@result{} #<marker at 101 in markers.texi>
@end group
@group
;; @r{Two markers that point to the same position}
;; @r{are not @code{eq}, but they are @code{equal}.}
(setq m2 (copy-marker m1))
@result{} #<marker at 101 in markers.texi>
(eq m1 m2)
@result{} nil
(equal m1 m2)
@result{} t
@end group
@group
;; @r{When you are finished using a marker, make it point nowhere.}
(set-marker m1 nil)
@result{} #<marker in no buffer>
@end group
@end example
@node Predicates on Markers
@section Predicates on Markers
You can test an object to see whether it is a marker, or whether it is
either an integer or a marker. The latter test is useful in connection
with the arithmetic functions that work with both markers and integers.
@defun markerp object
This function returns @code{t} if @var{object} is a marker, @code{nil}
otherwise. Note that integers are not markers, even though many
functions will accept either a marker or an integer.
@end defun
@defun integer-or-marker-p object
This function returns @code{t} if @var{object} is an integer or a marker,
@code{nil} otherwise.
@end defun
@defun number-or-marker-p object
This function returns @code{t} if @var{object} is a number (either
integer or floating point) or a marker, @code{nil} otherwise.
@end defun
@node Creating Markers
@section Functions that Create Markers
When you create a new marker, you can make it point nowhere, or point
to the present position of point, or to the beginning or end of the
accessible portion of the buffer, or to the same place as another given
marker.
The next four functions all return markers with insertion type
@code{nil}. @xref{Marker Insertion Types}.
@defun make-marker
This function returns a newly created marker that does not point
anywhere.
@example
@group
(make-marker)
@result{} #<marker in no buffer>
@end group
@end example
@end defun
@defun point-marker
This function returns a new marker that points to the present position
of point in the current buffer. @xref{Point}. For an example, see
@code{copy-marker}, below.
@end defun
@defun point-min-marker
This function returns a new marker that points to the beginning of the
accessible portion of the buffer. This will be the beginning of the
buffer unless narrowing is in effect. @xref{Narrowing}.
@end defun
@defun point-max-marker
This function returns a new marker that points to the end of the
accessible portion of the buffer. This will be the end of the buffer
unless narrowing is in effect. @xref{Narrowing}.
Here are examples of this function and @code{point-min-marker}, shown in
a buffer containing a version of the source file for the text of this
chapter.
@example
@group
(point-min-marker)
@result{} #<marker at 1 in markers.texi>
(point-max-marker)
@result{} #<marker at 15573 in markers.texi>
@end group
@group
(narrow-to-region 100 200)
@result{} nil
@end group
@group
(point-min-marker)
@result{} #<marker at 100 in markers.texi>
@end group
@group
(point-max-marker)
@result{} #<marker at 200 in markers.texi>
@end group
@end example
@end defun
@defun copy-marker marker-or-integer &optional insertion-type
If passed a marker as its argument, @code{copy-marker} returns a
new marker that points to the same place and the same buffer as does
@var{marker-or-integer}. If passed an integer as its argument,
@code{copy-marker} returns a new marker that points to position
@var{marker-or-integer} in the current buffer.
The new marker's insertion type is specified by the argument
@var{insertion-type}. @xref{Marker Insertion Types}.
If passed an integer argument less than 1, @code{copy-marker} returns a
new marker that points to the beginning of the current buffer. If
passed an integer argument greater than the length of the buffer,
@code{copy-marker} returns a new marker that points to the end of the
buffer.
@example
@group
(copy-marker 0)
@result{} #<marker at 1 in markers.texi>
@end group
@group
(copy-marker 20000)
@result{} #<marker at 7572 in markers.texi>
@end group
@end example
An error is signaled if @var{marker} is neither a marker nor an
integer.
@end defun
Two distinct markers are considered @code{equal} (even though not
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.
@example
@group
(setq p (point-marker))
@result{} #<marker at 2139 in markers.texi>
@end group
@group
(setq q (copy-marker p))
@result{} #<marker at 2139 in markers.texi>
@end group
@group
(eq p q)
@result{} nil
@end group
@group
(equal p q)
@result{} t
@end group
@end example
@node Information from Markers
@section Information from Markers
This section describes the functions for accessing the components of a
marker object.
@defun marker-position marker
This function returns the position that @var{marker} points to, or
@code{nil} if it points nowhere.
@end defun
@defun marker-buffer marker
This function returns the buffer that @var{marker} points into, or
@code{nil} if it points nowhere.
@example
@group
(setq m (make-marker))
@result{} #<marker in no buffer>
@end group
@group
(marker-position m)
@result{} nil
@end group
@group
(marker-buffer m)
@result{} nil
@end group
@group
(set-marker m 3770 (current-buffer))
@result{} #<marker at 3770 in markers.texi>
@end group
@group
(marker-buffer m)
@result{} #<buffer markers.texi>
@end group
@group
(marker-position m)
@result{} 3770
@end group
@end example
@end defun
@defun buffer-has-markers-at position
This function returns @code{t} if one or more markers
point at position @var{position} in the current buffer.
@end defun
@node Marker Insertion Types
@section Marker Insertion Types
@cindex insertion type of a marker
When you insert text directly at the place where a marker points,
there are two possible ways to relocate that marker: it can point before
the inserted text, or point after it. You can specify which one a given
marker should do by setting its @dfn{insertion type}. Note that use of
@code{insert-before-markers} ignores markers' insertion types, always
relocating a marker to point after the inserted text.
@defun set-marker-insertion-type marker type
This function sets the insertion type of marker @var{marker} to
@var{type}. If @var{type} is @code{t}, @var{marker} will advance when
text is inserted at its position. If @var{type} is @code{nil},
@var{marker} does not advance when text is inserted there.
@end defun
@defun marker-insertion-type marker
This function reports the current insertion type of @var{marker}.
@end defun
Most functions that create markers, without an argument allowing to
specify the insertion type, create them with insertion type
@code{nil}. Also, the mark has, by default, insertion type
@code{nil}.
@node Moving Markers
@section Moving Marker Positions
This section describes how to change the position of an existing
marker. When you do this, be sure you know whether the marker is used
outside of your program, and, if so, what effects will result from
moving it---otherwise, confusing things may happen in other parts of
Emacs.
@defun set-marker marker position &optional buffer
This function moves @var{marker} to @var{position}
in @var{buffer}. If @var{buffer} is not provided, it defaults to
the current buffer.
If @var{position} is less than 1, @code{set-marker} moves @var{marker}
to the beginning of the buffer. If @var{position} is greater than the
size of the buffer, @code{set-marker} moves marker to the end of the
buffer. If @var{position} is @code{nil} or a marker that points
nowhere, then @var{marker} is set to point nowhere.
The value returned is @var{marker}.
@example
@group
(setq m (point-marker))
@result{} #<marker at 4714 in markers.texi>
@end group
@group
(set-marker m 55)
@result{} #<marker at 55 in markers.texi>
@end group
@group
(setq b (get-buffer "foo"))
@result{} #<buffer foo>
@end group
@group
(set-marker m 0 b)
@result{} #<marker at 1 in foo>
@end group
@end example
@end defun
@defun move-marker marker position &optional buffer
This is another name for @code{set-marker}.
@end defun
@node The Mark
@section The Mark
@cindex mark, the
@cindex mark ring
One special marker in each buffer is designated @dfn{the mark}. It
specifies a position to bound a range of text for commands such as
@code{kill-region} and @code{indent-rigidly}. Lisp programs should
set the mark only to values that have a potential use to the user, and
never for their own internal purposes. For example, the
@code{replace-regexp} command sets the mark to the value of point
before doing any replacements, because this enables the user to move
back there conveniently after the replace is finished.
Many commands are designed to operate on the text between point and
the mark when called interactively. If you are writing such a
command, don't examine the mark directly; instead, use
@code{interactive} with the @samp{r} specification. This provides the
values of point and the mark as arguments to the command in an
interactive call, but permits other Lisp programs to specify arguments
explicitly. @xref{Interactive Codes}.
Each buffer has a marker which represents the value of the mark in
that buffer, independent of any other buffer. When a buffer is newly
created, this marker exists but does not point anywhere. That means
the mark ``doesn't exist'' in that buffer as yet.
Once the mark ``exists'' in a buffer, it normally never ceases to
exist. However, it may become @dfn{inactive}, if Transient Mark mode is
enabled. The variable @code{mark-active}, which is always buffer-local
in all buffers, indicates whether the mark is active: non-@code{nil}
means yes. A command can request deactivation of the mark upon return
to the editor command loop by setting @code{deactivate-mark} to a
non-@code{nil} value (but this causes deactivation only if Transient
Mark mode is enabled).
The main motivation for using Transient Mark mode is that this mode
also enables highlighting of the region when the mark is active.
@xref{Display}.
In addition to the mark, each buffer has a @dfn{mark ring} which is a
list of markers containing previous values of the mark. When editing
commands change the mark, they should normally save the old value of the
mark on the mark ring. The variable @code{mark-ring-max} specifies the
maximum number of entries in the mark ring; once the list becomes this
long, adding a new element deletes the last element.
There is also a separate global mark ring, but that is used only in a
few particular user-level commands, and is not relevant to Lisp
programming. So we do not describe it here.
@defun mark &optional force
@cindex current buffer mark
This function returns the current buffer's mark position as an integer,
or @code{nil} if no mark has ever been set in this buffer.
If Transient Mark mode is enabled, and @code{mark-even-if-inactive} is
@code{nil}, @code{mark} signals an error if the mark is inactive.
However, if @var{force} is non-@code{nil}, then @code{mark} disregards
inactivity of the mark, and returns the mark position anyway (or
@code{nil}).
@end defun
@defun mark-marker
This function returns the marker that represents the current buffer's
mark. It is not a copy, it is the marker used internally. Therefore,
changing this marker's position will directly affect the buffer's
mark. Don't do that unless that is the effect you want.
@example
@group
(setq m (mark-marker))
@result{} #<marker at 3420 in markers.texi>
@end group
@group
(set-marker m 100)
@result{} #<marker at 100 in markers.texi>
@end group
@group
(mark-marker)
@result{} #<marker at 100 in markers.texi>
@end group
@end example
Like any marker, this marker can be set to point at any buffer you
like. If you make it point at any buffer other than the one of which
it is the mark, it will yield perfectly consistent, but rather odd,
results. We recommend that you not do it!
@end defun
@ignore
@deffn Command set-mark-command jump
If @var{jump} is @code{nil}, this command sets the mark to the value
of point and pushes the previous value of the mark on the mark ring. The
message @samp{Mark set} is also displayed in the echo area.
If @var{jump} is not @code{nil}, this command sets point to the value
of the mark, and sets the mark to the previous saved mark value, which
is popped off the mark ring.
This function is @emph{only} intended for interactive use.
@end deffn
@end ignore
@defun set-mark position
This function sets the mark to @var{position}, and activates the mark.
The old value of the mark is @emph{not} pushed onto the mark ring.
@strong{Please note:} Use this function only if you want the user to
see that the mark has moved, and you want the previous mark position to
be lost. Normally, when a new mark is set, the old one should go on the
@code{mark-ring}. For this reason, most applications should use
@code{push-mark} and @code{pop-mark}, not @code{set-mark}.
Novice Emacs Lisp programmers often try to use the mark for the wrong
purposes. The mark saves a location for the user's convenience. An
editing command should not alter the mark unless altering the mark is
part of the user-level functionality of the command. (And, in that
case, this effect should be documented.) To remember a location for
internal use in the Lisp program, store it in a Lisp variable. For
example:
@example
@group
(let ((beg (point)))
(forward-line 1)
(delete-region beg (point))).
@end group
@end example
@end defun
@c for interactive use only
@ignore
@deffn Command exchange-point-and-mark
This function exchanges the positions of point and the mark.
It is intended for interactive use.
@end deffn
@end ignore
@defun push-mark &optional position nomsg activate
This function sets the current buffer's mark to @var{position}, and
pushes a copy of the previous mark onto @code{mark-ring}. If
@var{position} is @code{nil}, then the value of point is used.
@code{push-mark} returns @code{nil}.
The function @code{push-mark} normally @emph{does not} activate the
mark. To do that, specify @code{t} for the argument @var{activate}.
A @samp{Mark set} message is displayed unless @var{nomsg} is
non-@code{nil}.
@end defun
@defun pop-mark
This function pops off the top element of @code{mark-ring} and makes
that mark become the buffer's actual mark. This does not move point in
the buffer, and it does nothing if @code{mark-ring} is empty. It
deactivates the mark.
The return value is not meaningful.
@end defun
@defopt transient-mark-mode
@c @cindex Transient Mark mode Redundant
This variable if non-@code{nil} enables Transient Mark mode, in which
every buffer-modifying primitive sets @code{deactivate-mark}. The
consequence of this is that commands that modify the buffer normally
make the mark inactive.
Lisp programs can set @code{transient-mark-mode} to @code{only} to
enable Transient Mark mode for the following command only. During
that following command, the value of @code{transient-mark-mode} is
@code{identity}. If it is still @code{identity} at the end of the
command, it changes to @code{nil}.
@end defopt
@defopt mark-even-if-inactive
If this is non-@code{nil}, Lisp programs and the Emacs user can use the
mark even when it is inactive. This option affects the behavior of
Transient Mark mode. When the option is non-@code{nil}, deactivation of
the mark turns off region highlighting, but commands that use the mark
behave as if the mark were still active.
@end defopt
@defvar deactivate-mark
If an editor command sets this variable non-@code{nil}, then the editor
command loop deactivates the mark after the command returns (if
Transient Mark mode is enabled). All the primitives that change the
buffer set @code{deactivate-mark}, to deactivate the mark when the
command is finished.
To write Lisp code that modifies the buffer without causing
deactivation of the mark at the end of the command, bind
@code{deactivate-mark} to @code{nil} around the code that does the
modification. For example:
@example
(let (deactivate-mark)
(insert " "))
@end example
@end defvar
@defun deactivate-mark
This function deactivates the mark, if Transient Mark mode is enabled.
Otherwise it does nothing.
@end defun
@defvar mark-active
The mark is active when this variable is non-@code{nil}. This variable
is always buffer-local in each buffer.
@end defvar
@defvar activate-mark-hook
@defvarx deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active
and when it becomes inactive. The hook @code{activate-mark-hook} is
also run at the end of a command if the mark is active and it is
possible that the region may have changed.
@end defvar
@defvar mark-ring
The value of this buffer-local variable is the list of saved former
marks of the current buffer, most recent first.
@example
@group
mark-ring
@result{} (#<marker at 11050 in markers.texi>
#<marker at 10832 in markers.texi>
@dots{})
@end group
@end example
@end defvar
@defopt mark-ring-max
The value of this variable is the maximum size of @code{mark-ring}. If
more marks than this are pushed onto the @code{mark-ring},
@code{push-mark} discards an old mark when it adds a new one.
@end defopt
@node The Region
@section The Region
@cindex region (between point and mark)
The text between point and the mark is known as @dfn{the region}.
Various functions operate on text delimited by point and the mark, but
only those functions specifically related to the region itself are
described here.
The next two functions signal an error if the mark does not point
anywhere. If Transient Mark mode is enabled and
@code{mark-even-if-inactive} is @code{nil}, they also signal an error
if the mark is inactive.
@defun region-beginning
This function returns the position of the beginning of the region (as
an integer). This is the position of either point or the mark,
whichever is smaller.
@end defun
@defun region-end
This function returns the position of the end of the region (as an
integer). This is the position of either point or the mark, whichever is
larger.
@end defun
Few programs need to use the @code{region-beginning} and
@code{region-end} functions. A command designed to operate on a region
should normally use @code{interactive} with the @samp{r} specification
to find the beginning and end of the region. This lets other Lisp
programs specify the bounds explicitly as arguments. (@xref{Interactive
Codes}.)
@ignore
arch-tag: b1ba2e7a-a0f3-4c5e-875c-7d8e22d73299
@end ignore

1964
doc/lispref/minibuf.texi Normal file
View file

File diff suppressed because it is too large Load diff

38
doc/lispref/mkinstalldirs Executable file
View file

@ -0,0 +1,38 @@
#! /bin/sh
# mkinstalldirs --- make directory hierarchy
# Author: Noah Friedman <friedman@prep.ai.mit.edu>
# Created: 1993-05-16
# Public domain
errstatus=0
for file
do
set fnord `echo ":$file" | sed -ne 's/^:\//#/;s/^://;s/\// /g;s/^#/\//;p'`
shift
pathcomp=
for d
do
pathcomp="$pathcomp$d"
case "$pathcomp" in
-* ) pathcomp=./$pathcomp ;;
esac
if test ! -d "$pathcomp"; then
echo "mkdir $pathcomp" 1>&2
mkdir "$pathcomp" || lasterr=$?
if test ! -d "$pathcomp"; then
errstatus=$lasterr
fi
fi
pathcomp="$pathcomp/"
done
done
exit $errstatus
# mkinstalldirs ends here

3271
doc/lispref/modes.texi Normal file
View file

File diff suppressed because it is too large Load diff

1504
doc/lispref/nonascii.texi Normal file
View file

File diff suppressed because it is too large Load diff

1211
doc/lispref/numbers.texi Normal file
View file

File diff suppressed because it is too large Load diff

2036
doc/lispref/objects.texi Normal file
View file

File diff suppressed because it is too large Load diff

2004
doc/lispref/os.texi Normal file
View file

File diff suppressed because it is too large Load diff

1004
doc/lispref/positions.texi Normal file
View file

File diff suppressed because it is too large Load diff

2561
doc/lispref/processes.texi Normal file
View file

File diff suppressed because it is too large Load diff

1766
doc/lispref/searching.texi Normal file
View file

File diff suppressed because it is too large Load diff

734
doc/lispref/sequences.texi Normal file
View file

@ -0,0 +1,734 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/sequences
@node Sequences Arrays Vectors, Hash Tables, Lists, Top
@chapter Sequences, Arrays, and Vectors
@cindex sequence
Recall that the @dfn{sequence} type is the union of two other Lisp
types: lists and arrays. In other words, any list is a sequence, and
any array is a sequence. The common property that all sequences have is
that each is an ordered collection of elements.
An @dfn{array} is a single primitive object that has a slot for each
of its elements. All the elements are accessible in constant time, but
the length of an existing array cannot be changed. Strings, vectors,
char-tables and bool-vectors are the four types of arrays.
A list is a sequence of elements, but it is not a single primitive
object; it is made of cons cells, one cell per element. Finding the
@var{n}th element requires looking through @var{n} cons cells, so
elements farther from the beginning of the list take longer to access.
But it is possible to add elements to the list, or remove elements.
The following diagram shows the relationship between these types:
@example
@group
_____________________________________________
| |
| Sequence |
| ______ ________________________________ |
| | | | | |
| | List | | Array | |
| | | | ________ ________ | |
| |______| | | | | | | |
| | | Vector | | String | | |
| | |________| |________| | |
| | ____________ _____________ | |
| | | | | | | |
| | | Char-table | | Bool-vector | | |
| | |____________| |_____________| | |
| |________________________________| |
|_____________________________________________|
@end group
@end example
The elements of vectors and lists may be any Lisp objects. The
elements of strings are all characters.
@menu
* Sequence Functions:: Functions that accept any kind of sequence.
* Arrays:: Characteristics of arrays in Emacs Lisp.
* Array Functions:: Functions specifically for arrays.
* Vectors:: Special characteristics of Emacs Lisp vectors.
* Vector Functions:: Functions specifically for vectors.
* Char-Tables:: How to work with char-tables.
* Bool-Vectors:: How to work with bool-vectors.
@end menu
@node Sequence Functions
@section Sequences
In Emacs Lisp, a @dfn{sequence} is either a list or an array. The
common property of all sequences is that they are ordered collections of
elements. This section describes functions that accept any kind of
sequence.
@defun sequencep object
Returns @code{t} if @var{object} is a list, vector, string,
bool-vector, or char-table, @code{nil} otherwise.
@end defun
@defun length sequence
@cindex string length
@cindex list length
@cindex vector length
@cindex sequence length
@cindex char-table length
This function returns the number of elements in @var{sequence}. If
@var{sequence} is a dotted list, a @code{wrong-type-argument} error is
signaled. Circular lists may cause an infinite loop. For a
char-table, the value returned is always one more than the maximum
Emacs character code.
@xref{Definition of safe-length}, for the related function @code{safe-length}.
@example
@group
(length '(1 2 3))
@result{} 3
@end group
@group
(length ())
@result{} 0
@end group
@group
(length "foobar")
@result{} 6
@end group
@group
(length [1 2 3])
@result{} 3
@end group
@group
(length (make-bool-vector 5 nil))
@result{} 5
@end group
@end example
@end defun
@noindent
See also @code{string-bytes}, in @ref{Text Representations}.
@defun elt sequence index
@cindex elements of sequences
This function returns the element of @var{sequence} indexed by
@var{index}. Legitimate values of @var{index} are integers ranging
from 0 up to one less than the length of @var{sequence}. If
@var{sequence} is a list, out-of-range values behave as for
@code{nth}. @xref{Definition of nth}. Otherwise, out-of-range values
trigger an @code{args-out-of-range} error.
@example
@group
(elt [1 2 3 4] 2)
@result{} 3
@end group
@group
(elt '(1 2 3 4) 2)
@result{} 3
@end group
@group
;; @r{We use @code{string} to show clearly which character @code{elt} returns.}
(string (elt "1234" 2))
@result{} "3"
@end group
@group
(elt [1 2 3 4] 4)
@error{} Args out of range: [1 2 3 4], 4
@end group
@group
(elt [1 2 3 4] -1)
@error{} Args out of range: [1 2 3 4], -1
@end group
@end example
This function generalizes @code{aref} (@pxref{Array Functions}) and
@code{nth} (@pxref{Definition of nth}).
@end defun
@defun copy-sequence sequence
@cindex copying sequences
Returns a copy of @var{sequence}. The copy is the same type of object
as the original sequence, and it has the same elements in the same order.
Storing a new element into the copy does not affect the original
@var{sequence}, and vice versa. However, the elements of the new
sequence are not copies; they are identical (@code{eq}) to the elements
of the original. Therefore, changes made within these elements, as
found via the copied sequence, are also visible in the original
sequence.
If the sequence is a string with text properties, the property list in
the copy is itself a copy, not shared with the original's property
list. However, the actual values of the properties are shared.
@xref{Text Properties}.
This function does not work for dotted lists. Trying to copy a
circular list may cause an infinite loop.
See also @code{append} in @ref{Building Lists}, @code{concat} in
@ref{Creating Strings}, and @code{vconcat} in @ref{Vector Functions},
for other ways to copy sequences.
@example
@group
(setq bar '(1 2))
@result{} (1 2)
@end group
@group
(setq x (vector 'foo bar))
@result{} [foo (1 2)]
@end group
@group
(setq y (copy-sequence x))
@result{} [foo (1 2)]
@end group
@group
(eq x y)
@result{} nil
@end group
@group
(equal x y)
@result{} t
@end group
@group
(eq (elt x 1) (elt y 1))
@result{} t
@end group
@group
;; @r{Replacing an element of one sequence.}
(aset x 0 'quux)
x @result{} [quux (1 2)]
y @result{} [foo (1 2)]
@end group
@group
;; @r{Modifying the inside of a shared element.}
(setcar (aref x 1) 69)
x @result{} [quux (69 2)]
y @result{} [foo (69 2)]
@end group
@end example
@end defun
@node Arrays
@section Arrays
@cindex array
An @dfn{array} object has slots that hold a number of other Lisp
objects, called the elements of the array. Any element of an array may
be accessed in constant time. In contrast, an element of a list
requires access time that is proportional to the position of the element
in the list.
Emacs defines four types of array, all one-dimensional: @dfn{strings},
@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}. A vector is a
general array; its elements can be any Lisp objects. A string is a
specialized array; its elements must be characters. Each type of array
has its own read syntax.
@xref{String Type}, and @ref{Vector Type}.
All four kinds of array share these characteristics:
@itemize @bullet
@item
The first element of an array has index zero, the second element has
index 1, and so on. This is called @dfn{zero-origin} indexing. For
example, an array of four elements has indices 0, 1, 2, @w{and 3}.
@item
The length of the array is fixed once you create it; you cannot
change the length of an existing array.
@item
For purposes of evaluation, the array is a constant---in other words,
it evaluates to itself.
@item
The elements of an array may be referenced or changed with the functions
@code{aref} and @code{aset}, respectively (@pxref{Array Functions}).
@end itemize
When you create an array, other than a char-table, you must specify
its length. You cannot specify the length of a char-table, because that
is determined by the range of character codes.
In principle, if you want an array of text characters, you could use
either a string or a vector. In practice, we always choose strings for
such applications, for four reasons:
@itemize @bullet
@item
They occupy one-fourth the space of a vector of the same elements.
@item
Strings are printed in a way that shows the contents more clearly
as text.
@item
Strings can hold text properties. @xref{Text Properties}.
@item
Many of the specialized editing and I/O facilities of Emacs accept only
strings. For example, you cannot insert a vector of characters into a
buffer the way you can insert a string. @xref{Strings and Characters}.
@end itemize
By contrast, for an array of keyboard input characters (such as a key
sequence), a vector may be necessary, because many keyboard input
characters are outside the range that will fit in a string. @xref{Key
Sequence Input}.
@node Array Functions
@section Functions that Operate on Arrays
In this section, we describe the functions that accept all types of
arrays.
@defun arrayp object
This function returns @code{t} if @var{object} is an array (i.e., a
vector, a string, a bool-vector or a char-table).
@example
@group
(arrayp [a])
@result{} t
(arrayp "asdf")
@result{} t
(arrayp (syntax-table)) ;; @r{A char-table.}
@result{} t
@end group
@end example
@end defun
@defun aref array index
@cindex array elements
This function returns the @var{index}th element of @var{array}. The
first element is at index zero.
@example
@group
(setq primes [2 3 5 7 11 13])
@result{} [2 3 5 7 11 13]
(aref primes 4)
@result{} 11
@end group
@group
(aref "abcdefg" 1)
@result{} 98 ; @r{@samp{b} is @acronym{ASCII} code 98.}
@end group
@end example
See also the function @code{elt}, in @ref{Sequence Functions}.
@end defun
@defun aset array index object
This function sets the @var{index}th element of @var{array} to be
@var{object}. It returns @var{object}.
@example
@group
(setq w [foo bar baz])
@result{} [foo bar baz]
(aset w 0 'fu)
@result{} fu
w
@result{} [fu bar baz]
@end group
@group
(setq x "asdfasfd")
@result{} "asdfasfd"
(aset x 3 ?Z)
@result{} 90
x
@result{} "asdZasfd"
@end group
@end example
If @var{array} is a string and @var{object} is not a character, a
@code{wrong-type-argument} error results. The function converts a
unibyte string to multibyte if necessary to insert a character.
@end defun
@defun fillarray array object
This function fills the array @var{array} with @var{object}, so that
each element of @var{array} is @var{object}. It returns @var{array}.
@example
@group
(setq a [a b c d e f g])
@result{} [a b c d e f g]
(fillarray a 0)
@result{} [0 0 0 0 0 0 0]
a
@result{} [0 0 0 0 0 0 0]
@end group
@group
(setq s "When in the course")
@result{} "When in the course"
(fillarray s ?-)
@result{} "------------------"
@end group
@end example
If @var{array} is a string and @var{object} is not a character, a
@code{wrong-type-argument} error results.
@end defun
The general sequence functions @code{copy-sequence} and @code{length}
are often useful for objects known to be arrays. @xref{Sequence Functions}.
@node Vectors
@section Vectors
@cindex vector (type)
Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in constant time. A @dfn{vector} is a
general-purpose array of specified length; its elements can be any Lisp
objects. (By contrast, a string can hold only characters as elements.)
Vectors in Emacs are used for obarrays (vectors of symbols), and as part
of keymaps (vectors of commands). They are also used internally as part
of the representation of a byte-compiled function; if you print such a
function, you will see a vector in it.
In Emacs Lisp, the indices of the elements of a vector start from zero
and count up from there.
Vectors are printed with square brackets surrounding the elements.
Thus, a vector whose elements are the symbols @code{a}, @code{b} and
@code{a} is printed as @code{[a b a]}. You can write vectors in the
same way in Lisp input.
A vector, like a string or a number, is considered a constant for
evaluation: the result of evaluating it is the same vector. This does
not evaluate or even examine the elements of the vector.
@xref{Self-Evaluating Forms}.
Here are examples illustrating these principles:
@example
@group
(setq avector [1 two '(three) "four" [five]])
@result{} [1 two (quote (three)) "four" [five]]
(eval avector)
@result{} [1 two (quote (three)) "four" [five]]
(eq avector (eval avector))
@result{} t
@end group
@end example
@node Vector Functions
@section Functions for Vectors
Here are some functions that relate to vectors:
@defun vectorp object
This function returns @code{t} if @var{object} is a vector.
@example
@group
(vectorp [a])
@result{} t
(vectorp "asdf")
@result{} nil
@end group
@end example
@end defun
@defun vector &rest objects
This function creates and returns a vector whose elements are the
arguments, @var{objects}.
@example
@group
(vector 'foo 23 [bar baz] "rats")
@result{} [foo 23 [bar baz] "rats"]
(vector)
@result{} []
@end group
@end example
@end defun
@defun make-vector length object
This function returns a new vector consisting of @var{length} elements,
each initialized to @var{object}.
@example
@group
(setq sleepy (make-vector 9 'Z))
@result{} [Z Z Z Z Z Z Z Z Z]
@end group
@end example
@end defun
@defun vconcat &rest sequences
@cindex copying vectors
This function returns a new vector containing all the elements of the
@var{sequences}. The arguments @var{sequences} may be true lists,
vectors, strings or bool-vectors. If no @var{sequences} are given, an
empty vector is returned.
The value is a newly constructed vector that is not @code{eq} to any
existing vector.
@example
@group
(setq a (vconcat '(A B C) '(D E F)))
@result{} [A B C D E F]
(eq a (vconcat a))
@result{} nil
@end group
@group
(vconcat)
@result{} []
(vconcat [A B C] "aa" '(foo (6 7)))
@result{} [A B C 97 97 foo (6 7)]
@end group
@end example
The @code{vconcat} function also allows byte-code function objects as
arguments. This is a special feature to make it easy to access the entire
contents of a byte-code function object. @xref{Byte-Code Objects}.
In Emacs versions before 21, the @code{vconcat} function allowed
integers as arguments, converting them to strings of digits, but that
feature has been eliminated. The proper way to convert an integer to
a decimal number in this way is with @code{format} (@pxref{Formatting
Strings}) or @code{number-to-string} (@pxref{String Conversion}).
For other concatenation functions, see @code{mapconcat} in @ref{Mapping
Functions}, @code{concat} in @ref{Creating Strings}, and @code{append}
in @ref{Building Lists}.
@end defun
The @code{append} function also provides a way to convert a vector into a
list with the same elements:
@example
@group
(setq avector [1 two (quote (three)) "four" [five]])
@result{} [1 two (quote (three)) "four" [five]]
(append avector nil)
@result{} (1 two (quote (three)) "four" [five])
@end group
@end example
@node Char-Tables
@section Char-Tables
@cindex char-tables
@cindex extra slots of char-table
A char-table is much like a vector, except that it is indexed by
character codes. Any valid character code, without modifiers, can be
used as an index in a char-table. You can access a char-table's
elements with @code{aref} and @code{aset}, as with any array. In
addition, a char-table can have @dfn{extra slots} to hold additional
data not associated with particular character codes. Char-tables are
constants when evaluated.
@cindex subtype of char-table
Each char-table has a @dfn{subtype} which is a symbol. The subtype
has two purposes: to distinguish char-tables meant for different uses,
and to control the number of extra slots. For example, display tables
are char-tables with @code{display-table} as the subtype, and syntax
tables are char-tables with @code{syntax-table} as the subtype. A valid
subtype must have a @code{char-table-extra-slots} property which is an
integer between 0 and 10. This integer specifies the number of
@dfn{extra slots} in the char-table.
@cindex parent of char-table
A char-table can have a @dfn{parent}, which is another char-table. If
it does, then whenever the char-table specifies @code{nil} for a
particular character @var{c}, it inherits the value specified in the
parent. In other words, @code{(aref @var{char-table} @var{c})} returns
the value from the parent of @var{char-table} if @var{char-table} itself
specifies @code{nil}.
@cindex default value of char-table
A char-table can also have a @dfn{default value}. If so, then
@code{(aref @var{char-table} @var{c})} returns the default value
whenever the char-table does not specify any other non-@code{nil} value.
@defun make-char-table subtype &optional init
Return a newly created char-table, with subtype @var{subtype}. Each
element is initialized to @var{init}, which defaults to @code{nil}. You
cannot alter the subtype of a char-table after the char-table is
created.
There is no argument to specify the length of the char-table, because
all char-tables have room for any valid character code as an index.
@end defun
@defun char-table-p object
This function returns @code{t} if @var{object} is a char-table,
otherwise @code{nil}.
@end defun
@defun char-table-subtype char-table
This function returns the subtype symbol of @var{char-table}.
@end defun
@defun set-char-table-default char-table char new-default
This function sets the default value of generic character @var{char}
in @var{char-table} to @var{new-default}.
There is no special function to access default values in a char-table.
To do that, use @code{char-table-range} (see below).
@end defun
@defun char-table-parent char-table
This function returns the parent of @var{char-table}. The parent is
always either @code{nil} or another char-table.
@end defun
@defun set-char-table-parent char-table new-parent
This function sets the parent of @var{char-table} to @var{new-parent}.
@end defun
@defun char-table-extra-slot char-table n
This function returns the contents of extra slot @var{n} of
@var{char-table}. The number of extra slots in a char-table is
determined by its subtype.
@end defun
@defun set-char-table-extra-slot char-table n value
This function stores @var{value} in extra slot @var{n} of
@var{char-table}.
@end defun
A char-table can specify an element value for a single character code;
it can also specify a value for an entire character set.
@defun char-table-range char-table range
This returns the value specified in @var{char-table} for a range of
characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
@item @code{nil}
Refers to the default value.
@item @var{char}
Refers to the element for character @var{char}
(supposing @var{char} is a valid character code).
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
@item @var{generic-char}
A generic character stands for a character set, or a row of a
character set; specifying the generic character as argument is
equivalent to specifying the character set name. @xref{Splitting
Characters}, for a description of generic characters.
@end table
@end defun
@defun set-char-table-range char-table range value
This function sets the value in @var{char-table} for a range of
characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
@item @code{nil}
Refers to the default value.
@item @code{t}
Refers to the whole range of character codes.
@item @var{char}
Refers to the element for character @var{char}
(supposing @var{char} is a valid character code).
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
@item @var{generic-char}
A generic character stands for a character set; specifying the generic
character as argument is equivalent to specifying the character set
name. @xref{Splitting Characters}, for a description of generic characters.
@end table
@end defun
@defun map-char-table function char-table
This function calls @var{function} for each element of @var{char-table}.
@var{function} is called with two arguments, a key and a value. The key
is a possible @var{range} argument for @code{char-table-range}---either
a valid character or a generic character---and the value is
@code{(char-table-range @var{char-table} @var{key})}.
Overall, the key-value pairs passed to @var{function} describe all the
values stored in @var{char-table}.
The return value is always @code{nil}; to make this function useful,
@var{function} should have side effects. For example,
here is how to examine each element of the syntax table:
@example
(let (accumulator)
(map-char-table
#'(lambda (key value)
(setq accumulator
(cons (list key value) accumulator)))
(syntax-table))
accumulator)
@result{}
((475008 nil) (474880 nil) (474752 nil) (474624 nil)
... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
@end example
@end defun
@node Bool-Vectors
@section Bool-vectors
@cindex Bool-vectors
A bool-vector is much like a vector, except that it stores only the
values @code{t} and @code{nil}. If you try to store any non-@code{nil}
value into an element of the bool-vector, the effect is to store
@code{t} there. As with all arrays, bool-vector indices start from 0,
and the length cannot be changed once the bool-vector is created.
Bool-vectors are constants when evaluated.
There are two special functions for working with bool-vectors; aside
from that, you manipulate them with same functions used for other kinds
of arrays.
@defun make-bool-vector length initial
Return a new bool-vector of @var{length} elements,
each one initialized to @var{initial}.
@end defun
@defun bool-vector-p object
This returns @code{t} if @var{object} is a bool-vector,
and @code{nil} otherwise.
@end defun
Here is an example of creating, examining, and updating a
bool-vector. Note that the printed form represents up to 8 boolean
values as a single character.
@example
(setq bv (make-bool-vector 5 t))
@result{} #&5"^_"
(aref bv 1)
@result{} t
(aset bv 3 nil)
@result{} nil
bv
@result{} #&5"^W"
@end example
@noindent
These results make sense because the binary codes for control-_ and
control-W are 11111 and 10111, respectively.
@ignore
arch-tag: fcf1084a-cd29-4adc-9f16-68586935b386
@end ignore

738
doc/lispref/spellfile Normal file
View file

@ -0,0 +1,738 @@
ARPA
Abbrev
Acknowledgements
Alan
Arnold
Autoloading
BAppend
Backquote
Beeping
Beverly
Boyes
Brian
CL
CSWKg
Carl
Carroll
Chris
Cleanups
DEC
DStandard
Dan
Dired's
Disassembly
Duff
EMAC
EMACSLOADPATH
Eckelkamp
Edward
Eirik
Emacses
Eric
Erlebacher
Fcar
Fcdr
Fcons
Fcoordinates
Feval
Frazzle
Frederick
Fri
Gardiner
Gentlemen
HAL
HATTED
HS
HU
Hanchrow
Hartzell
Hess
Hewlett
IBM
ISBN
Impl
Interning
Ithought
J's
Jacobson
Jak
Joe
Jones
Jr
Jul
Keymaps
Kimmo
Kirman
Knighten
Korz
Krawitz
LTsHm
LaLiberte
LaTeX
Lammens
Local'
MAC
MONIES
MSS
Maclisp
Magill
Marick
Matthew
Minibuf
Misc
Miscellany
Mocklisp
Montanaro
Myers
NFS
Nathan
Nope
OS
OSITIONS
Oct
Ovwrt
PURESIZE
Packard
Qlistp
Qnil
RMAIL
Raul
Resizing
Robbins
Rockwell
SCO
SIGCONT
SIGHUP
SIGINT
SIGKILL
SIGQUIT
SIGTSTP
SLOAD
Scoordinates
Set'
Setcar
Setcdr
Shinichirou
Snarf
Sor
SourceFile
Stops'
Subprocess
Sugou
Sunview
Suominen
T's
TCP
ThXs
Tharp
Thu
Trost
UCB
UNEVALLED
UNGCPRO
UniPlus
UniSoft's
VMS
Vip
Void'
Warren
Welty
Wethought
Wilding
Worley
Wright
XDVI
XFASTINT
XINT
XWINDOW
Xs
Yo
Zuhn
aB
aa
aaa
abbrevname
abbrevs
abc
abcdefg
abcxyz
abd
above'
abracadabra
address'
after'
alist
alists
anchored'
and'
ar
aref
arg'th
argdecl
arith
arrayp
arrow'
asa
asdZasfd
asdf
asdfasfd
aset
assoc
assq
at'
aug
autoload
automatic'
automatically'
avector
bBuffer
bFrobnicate
ba
back'
bananana
barfoo
barx
bballs
before'
beforep
bfoo
bil
binding's
bish
bobp
bolp
bottommost
boundp
brief'
buf
buffer'
bufferp
buttercup
ca
caaaar
caaar
caddaar
cadr
callable
cbreak
ce
cell'
cells'
cf
chaprm
character'
childp
chistory
ck
column'
commandp
concat
cond
conses
consing
consp
constant'
contains'
continuable
convert'
copyleft
correct'
counterintuitive
cr
creatable
customie
deactivate
deactivated
deassigns
decrement'
deffnx
definition'
defmacro
defsubr
deletable
deletion'
delq
depiction
descendents
deselecting
destructive'
destructively'
diffs
ding
directory'
dired
dirname
disassembler
dland
docfile
docstring
doesnt
dont
down'
downcasing
downloadable
dribble
dup
ef
efg
electric'
elided
elt
enablement
endkeyfun
endrecfun
environment'
eobp
eof
eol
eolp
eq
eqlsign
erminal
erste
etags
eval
evalled
evals
evaluate'
excess'
exec
exitcode
expression'
extendible
extra'
fails'
fascist
fboundp
featurep
ff
fg
fi
file'
filespec
filesystems
fillarray
firstchar
firstonly
fixedcase
fixit
fixup
floatp
fmakunbound
fns
fo
fol
folded'
following'
fooba
foobaz
foox
for'
formfeed
forms'
forw
forwa
found'
frob
from'
front'
fset
fstab
ftp
fu
funtions
garbles
gc
gcpro
gd
getenv
getprv
gid
gnuemacs
gp
grep
gtr
halves'
hand'
hashes'
hd
hexadecimal
hf
hfil
hookvar
horsechestnut
hostname
hpux
hscroll
ibmapa
ick
id
idiom
ii
indrm
inode
input'
inputinput
inserting'
integerp
intermixed
ints
inturned
irreversibly
jum
keymapp
kill'
killed'
killp
kludge
kolstad
language'
lastchar
lcl
ledit
leif
lessp
level'
lewis
library'
link'
lisplib
listexp
loadable
loadst
loadup
logand
logior
lognot
logxor
long'
loop's
lru
lrwxrwxrwx
ls
lsh
m's
macroexpand
makunbound
malloc
mapatoms
mapconcat
mapvar
mark'
marker's
markerp
mathsurround
medit
memq
mh
mim
mini
minibuffer's
minibuffers
misalignment
misnamed
mode's
modename
modes'
mods
modtime
mqueue
msg
multicharacter
myfile
nCount
nXExpression
na
name's
natnump
nb
nbBuffer
nconc
newdef
newelt
newname
nextrecfun
nfsusr
ninett
nlines
nlinks
nlistp
noconfirm
nodigits
noerror
noforce
nomessage
nominees
nomsg
nonblank
nonconstant
nondestructive
nondirectory
nonidentical
noninteractive
noninteractively
nonletter
nonletters
nonlocally
nonoverlapping
nonprinting
nonselected
nonsequentially
nonvoid
nonwarranty
nonwritable
noop
noprint
norecord
normal'
noselect
nosuffix
nots
noundo
nr
nreverse
ns
nsRename
nth
nthcdr
num
number'
numberp
nums
obarray
obarrays
object'
oldbuf
olddef
oldname
oo
oops
op
or'
otl
out'
over'
overful
overfullrule
overstrike
overstriking
overstruck
p'
paren
part'
passwd
pe
ped
perverse
pid
plist
pnt
pointer'
pointm
pos
preallocate
predicale
preload
prepend
prepended
prepends
pretty'
prin
princ
print'
printenv
printer'
proc
process'
processp
programmer'
prolog
protect'
ps
psf
psychotherapy
pty
purecopy
qu
quux
rassq
reader'
readin
rebind
rec
rechecking
recursively'
recycler'
redo
redrawing
redraws
redump
reenabled
reexposed
reg
region'
reindent
reindents
reinitialization
reinitialize
reinitialized
reinstall
reinstalled
resize
resized
resizes
reversibly
reworded
rhetorical
right'
ring'
risky
rmailedit
rms
rplaca
rplacd
rtu
runnable
rw
rwxrwxrwx
sDescribe
sans
se
searching'
section'
seed'
sequence'
sequencep
setp
setplist
setprv
settable
setuid
sexp
sexps
shape'
shell's
sideline
special'
specpdl
st
stanford
startkeyfun
str
stringp
stty
subcategories
subcommands
subexp
subform
subforms
subjob
submap
subprocesses
subr
subr'
subroutine'
subrp
subrs
subwindows
sugar'
suid
supersession
suspension'
symbolp
symlink
syms
syntatic
tabname
temacs
temporarily'
tempvar
tenths
termcap
termcaps
terminfo
termscript
termtype
terpri
text'
textrm
textsl
texttt
than'
the'
tildes
time's
to'
towars
transportable
txt
types'
uid
unbind
unbinding
unbinds
unchanged'
unclutters
undefine
undefines
underfull
undo's
undodata
unevaluated'
unexec
unexpand
unhesitatingly
uninterned
unisoft
unpaired
unread
unreadable
unreading
unsaved
untyped
ununderline
up'
uptime
usecount
used'
user'
userlock
usg
val
varbind
varname
varref
vars
varset
vb
vconcat
vectorp
vfil
vi
vn
voidness
vrs
vt
window'
windowing
windowp
wrapped'
xSpecify
xcoord
xcssun
xemacs
xenix
xf
xfirst
xoff
xon
xx
xxxxx
xxxxxxxxx
xy
xyz
ycoord
yes'
zA
zap
zerop

837
doc/lispref/streams.texi Normal file
View file

@ -0,0 +1,837 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998, 1999, 2001, 2002,
@c 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/streams
@node Read and Print, Minibuffers, Debugging, Top
@comment node-name, next, previous, up
@chapter Reading and Printing Lisp Objects
@dfn{Printing} and @dfn{reading} are the operations of converting Lisp
objects to textual form and vice versa. They use the printed
representations and read syntax described in @ref{Lisp Data Types}.
This chapter describes the Lisp functions for reading and printing.
It also describes @dfn{streams}, which specify where to get the text (if
reading) or where to put it (if printing).
@menu
* Streams Intro:: Overview of streams, reading and printing.
* Input Streams:: Various data types that can be used as input streams.
* Input Functions:: Functions to read Lisp objects from text.
* Output Streams:: Various data types that can be used as output streams.
* Output Functions:: Functions to print Lisp objects as text.
* Output Variables:: Variables that control what the printing functions do.
@end menu
@node Streams Intro
@section Introduction to Reading and Printing
@cindex Lisp reader
@cindex printing
@cindex reading
@dfn{Reading} a Lisp object means parsing a Lisp expression in textual
form and producing a corresponding Lisp object. This is how Lisp
programs get into Lisp from files of Lisp code. We call the text the
@dfn{read syntax} of the object. For example, the text @samp{(a .@: 5)}
is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
@sc{cdr} is the number 5.
@dfn{Printing} a Lisp object means producing text that represents that
object---converting the object to its @dfn{printed representation}
(@pxref{Printed Representation}). Printing the cons cell described
above produces the text @samp{(a .@: 5)}.
Reading and printing are more or less inverse operations: printing the
object that results from reading a given piece of text often produces
the same text, and reading the text that results from printing an object
usually produces a similar-looking object. For example, printing the
symbol @code{foo} produces the text @samp{foo}, and reading that text
returns the symbol @code{foo}. Printing a list whose elements are
@code{a} and @code{b} produces the text @samp{(a b)}, and reading that
text produces a list (but not the same list) with elements @code{a}
and @code{b}.
However, these two operations are not precisely inverse to each other.
There are three kinds of exceptions:
@itemize @bullet
@item
Printing can produce text that cannot be read. For example, buffers,
windows, frames, subprocesses and markers print as text that starts
with @samp{#}; if you try to read this text, you get an error. There is
no way to read those data types.
@item
One object can have multiple textual representations. For example,
@samp{1} and @samp{01} represent the same integer, and @samp{(a b)} and
@samp{(a .@: (b))} represent the same list. Reading will accept any of
the alternatives, but printing must choose one of them.
@item
Comments can appear at certain points in the middle of an object's
read sequence without affecting the result of reading it.
@end itemize
@node Input Streams
@section Input Streams
@cindex stream (for reading)
@cindex input stream
Most of the Lisp functions for reading text take an @dfn{input stream}
as an argument. The input stream specifies where or how to get the
characters of the text to be read. Here are the possible types of input
stream:
@table @asis
@item @var{buffer}
@cindex buffer input stream
The input characters are read from @var{buffer}, starting with the
character directly after point. Point advances as characters are read.
@item @var{marker}
@cindex marker input stream
The input characters are read from the buffer that @var{marker} is in,
starting with the character directly after the marker. The marker
position advances as characters are read. The value of point in the
buffer has no effect when the stream is a marker.
@item @var{string}
@cindex string input stream
The input characters are taken from @var{string}, starting at the first
character in the string and using as many characters as required.
@item @var{function}
@cindex function input stream
The input characters are generated by @var{function}, which must support
two kinds of calls:
@itemize @bullet
@item
When it is called with no arguments, it should return the next character.
@item
When it is called with one argument (always a character), @var{function}
should save the argument and arrange to return it on the next call.
This is called @dfn{unreading} the character; it happens when the Lisp
reader reads one character too many and wants to ``put it back where it
came from.'' In this case, it makes no difference what value
@var{function} returns.
@end itemize
@item @code{t}
@cindex @code{t} input stream
@code{t} used as a stream means that the input is read from the
minibuffer. In fact, the minibuffer is invoked once and the text
given by the user is made into a string that is then used as the
input stream. If Emacs is running in batch mode, standard input is used
instead of the minibuffer. For example,
@example
(message "%s" (read t))
@end example
will read a Lisp expression from standard input and print the result
to standard output.
@item @code{nil}
@cindex @code{nil} input stream
@code{nil} supplied as an input stream means to use the value of
@code{standard-input} instead; that value is the @dfn{default input
stream}, and must be a non-@code{nil} input stream.
@item @var{symbol}
A symbol as input stream is equivalent to the symbol's function
definition (if any).
@end table
Here is an example of reading from a stream that is a buffer, showing
where point is located before and after:
@example
@group
---------- Buffer: foo ----------
This@point{} is the contents of foo.
---------- Buffer: foo ----------
@end group
@group
(read (get-buffer "foo"))
@result{} is
@end group
@group
(read (get-buffer "foo"))
@result{} the
@end group
@group
---------- Buffer: foo ----------
This is the@point{} contents of foo.
---------- Buffer: foo ----------
@end group
@end example
@noindent
Note that the first read skips a space. Reading skips any amount of
whitespace preceding the significant text.
Here is an example of reading from a stream that is a marker,
initially positioned at the beginning of the buffer shown. The value
read is the symbol @code{This}.
@example
@group
---------- Buffer: foo ----------
This is the contents of foo.
---------- Buffer: foo ----------
@end group
@group
(setq m (set-marker (make-marker) 1 (get-buffer "foo")))
@result{} #<marker at 1 in foo>
@end group
@group
(read m)
@result{} This
@end group
@group
m
@result{} #<marker at 5 in foo> ;; @r{Before the first space.}
@end group
@end example
Here we read from the contents of a string:
@example
@group
(read "(When in) the course")
@result{} (When in)
@end group
@end example
The following example reads from the minibuffer. The
prompt is: @w{@samp{Lisp expression: }}. (That is always the prompt
used when you read from the stream @code{t}.) The user's input is shown
following the prompt.
@example
@group
(read t)
@result{} 23
---------- Buffer: Minibuffer ----------
Lisp expression: @kbd{23 @key{RET}}
---------- Buffer: Minibuffer ----------
@end group
@end example
Finally, here is an example of a stream that is a function, named
@code{useless-stream}. Before we use the stream, we initialize the
variable @code{useless-list} to a list of characters. Then each call to
the function @code{useless-stream} obtains the next character in the list
or unreads a character by adding it to the front of the list.
@example
@group
(setq useless-list (append "XY()" nil))
@result{} (88 89 40 41)
@end group
@group
(defun useless-stream (&optional unread)
(if unread
(setq useless-list (cons unread useless-list))
(prog1 (car useless-list)
(setq useless-list (cdr useless-list)))))
@result{} useless-stream
@end group
@end example
@noindent
Now we read using the stream thus constructed:
@example
@group
(read 'useless-stream)
@result{} XY
@end group
@group
useless-list
@result{} (40 41)
@end group
@end example
@noindent
Note that the open and close parentheses remain in the list. The Lisp
reader encountered the open parenthesis, decided that it ended the
input, and unread it. Another attempt to read from the stream at this
point would read @samp{()} and return @code{nil}.
@defun get-file-char
This function is used internally as an input stream to read from the
input file opened by the function @code{load}. Don't use this function
yourself.
@end defun
@node Input Functions
@section Input Functions
This section describes the Lisp functions and variables that pertain
to reading.
In the functions below, @var{stream} stands for an input stream (see
the previous section). If @var{stream} is @code{nil} or omitted, it
defaults to the value of @code{standard-input}.
@kindex end-of-file
An @code{end-of-file} error is signaled if reading encounters an
unterminated list, vector, or string.
@defun read &optional stream
This function reads one textual Lisp expression from @var{stream},
returning it as a Lisp object. This is the basic Lisp input function.
@end defun
@defun read-from-string string &optional start end
@cindex string to object
This function reads the first textual Lisp expression from the text in
@var{string}. It returns a cons cell whose @sc{car} is that expression,
and whose @sc{cdr} is an integer giving the position of the next
remaining character in the string (i.e., the first one not read).
If @var{start} is supplied, then reading begins at index @var{start} in
the string (where the first character is at index 0). If you specify
@var{end}, then reading is forced to stop just before that index, as if
the rest of the string were not there.
For example:
@example
@group
(read-from-string "(setq x 55) (setq y 5)")
@result{} ((setq x 55) . 11)
@end group
@group
(read-from-string "\"A short string\"")
@result{} ("A short string" . 16)
@end group
@group
;; @r{Read starting at the first character.}
(read-from-string "(list 112)" 0)
@result{} ((list 112) . 10)
@end group
@group
;; @r{Read starting at the second character.}
(read-from-string "(list 112)" 1)
@result{} (list . 5)
@end group
@group
;; @r{Read starting at the seventh character,}
;; @r{and stopping at the ninth.}
(read-from-string "(list 112)" 6 8)
@result{} (11 . 8)
@end group
@end example
@end defun
@defvar standard-input
This variable holds the default input stream---the stream that
@code{read} uses when the @var{stream} argument is @code{nil}.
The default is @code{t}, meaning use the minibuffer.
@end defvar
@node Output Streams
@section Output Streams
@cindex stream (for printing)
@cindex output stream
An output stream specifies what to do with the characters produced
by printing. Most print functions accept an output stream as an
optional argument. Here are the possible types of output stream:
@table @asis
@item @var{buffer}
@cindex buffer output stream
The output characters are inserted into @var{buffer} at point.
Point advances as characters are inserted.
@item @var{marker}
@cindex marker output stream
The output characters are inserted into the buffer that @var{marker}
points into, at the marker position. The marker position advances as
characters are inserted. The value of point in the buffer has no effect
on printing when the stream is a marker, and this kind of printing
does not move point (except that if the marker points at or before the
position of point, point advances with the surrounding text, as
usual).
@item @var{function}
@cindex function output stream
The output characters are passed to @var{function}, which is responsible
for storing them away. It is called with a single character as
argument, as many times as there are characters to be output, and
is responsible for storing the characters wherever you want to put them.
@item @code{t}
@cindex @code{t} output stream
The output characters are displayed in the echo area.
@item @code{nil}
@cindex @code{nil} output stream
@code{nil} specified as an output stream means to use the value of
@code{standard-output} instead; that value is the @dfn{default output
stream}, and must not be @code{nil}.
@item @var{symbol}
A symbol as output stream is equivalent to the symbol's function
definition (if any).
@end table
Many of the valid output streams are also valid as input streams. The
difference between input and output streams is therefore more a matter
of how you use a Lisp object, than of different types of object.
Here is an example of a buffer used as an output stream. Point is
initially located as shown immediately before the @samp{h} in
@samp{the}. At the end, point is located directly before that same
@samp{h}.
@cindex print example
@example
@group
---------- Buffer: foo ----------
This is t@point{}he contents of foo.
---------- Buffer: foo ----------
@end group
(print "This is the output" (get-buffer "foo"))
@result{} "This is the output"
@group
---------- Buffer: foo ----------
This is t
"This is the output"
@point{}he contents of foo.
---------- Buffer: foo ----------
@end group
@end example
Now we show a use of a marker as an output stream. Initially, the
marker is in buffer @code{foo}, between the @samp{t} and the @samp{h} in
the word @samp{the}. At the end, the marker has advanced over the
inserted text so that it remains positioned before the same @samp{h}.
Note that the location of point, shown in the usual fashion, has no
effect.
@example
@group
---------- Buffer: foo ----------
This is the @point{}output
---------- Buffer: foo ----------
@end group
@group
(setq m (copy-marker 10))
@result{} #<marker at 10 in foo>
@end group
@group
(print "More output for foo." m)
@result{} "More output for foo."
@end group
@group
---------- Buffer: foo ----------
This is t
"More output for foo."
he @point{}output
---------- Buffer: foo ----------
@end group
@group
m
@result{} #<marker at 34 in foo>
@end group
@end example
The following example shows output to the echo area:
@example
@group
(print "Echo Area output" t)
@result{} "Echo Area output"
---------- Echo Area ----------
"Echo Area output"
---------- Echo Area ----------
@end group
@end example
Finally, we show the use of a function as an output stream. The
function @code{eat-output} takes each character that it is given and
conses it onto the front of the list @code{last-output} (@pxref{Building
Lists}). At the end, the list contains all the characters output, but
in reverse order.
@example
@group
(setq last-output nil)
@result{} nil
@end group
@group
(defun eat-output (c)
(setq last-output (cons c last-output)))
@result{} eat-output
@end group
@group
(print "This is the output" 'eat-output)
@result{} "This is the output"
@end group
@group
last-output
@result{} (10 34 116 117 112 116 117 111 32 101 104
116 32 115 105 32 115 105 104 84 34 10)
@end group
@end example
@noindent
Now we can put the output in the proper order by reversing the list:
@example
@group
(concat (nreverse last-output))
@result{} "
\"This is the output\"
"
@end group
@end example
@noindent
Calling @code{concat} converts the list to a string so you can see its
contents more clearly.
@node Output Functions
@section Output Functions
This section describes the Lisp functions for printing Lisp
objects---converting objects into their printed representation.
@cindex @samp{"} in printing
@cindex @samp{\} in printing
@cindex quoting characters in printing
@cindex escape characters in printing
Some of the Emacs printing functions add quoting characters to the
output when necessary so that it can be read properly. The quoting
characters used are @samp{"} and @samp{\}; they distinguish strings from
symbols, and prevent punctuation characters in strings and symbols from
being taken as delimiters when reading. @xref{Printed Representation},
for full details. You specify quoting or no quoting by the choice of
printing function.
If the text is to be read back into Lisp, then you should print with
quoting characters to avoid ambiguity. Likewise, if the purpose is to
describe a Lisp object clearly for a Lisp programmer. However, if the
purpose of the output is to look nice for humans, then it is usually
better to print without quoting.
Lisp objects can refer to themselves. Printing a self-referential
object in the normal way would require an infinite amount of text, and
the attempt could cause infinite recursion. Emacs detects such
recursion and prints @samp{#@var{level}} instead of recursively printing
an object already being printed. For example, here @samp{#0} indicates
a recursive reference to the object at level 0 of the current print
operation:
@example
(setq foo (list nil))
@result{} (nil)
(setcar foo foo)
@result{} (#0)
@end example
In the functions below, @var{stream} stands for an output stream.
(See the previous section for a description of output streams.) If
@var{stream} is @code{nil} or omitted, it defaults to the value of
@code{standard-output}.
@defun print object &optional stream
@cindex Lisp printer
The @code{print} function is a convenient way of printing. It outputs
the printed representation of @var{object} to @var{stream}, printing in
addition one newline before @var{object} and another after it. Quoting
characters are used. @code{print} returns @var{object}. For example:
@example
@group
(progn (print 'The\ cat\ in)
(print "the hat")
(print " came back"))
@print{}
@print{} The\ cat\ in
@print{}
@print{} "the hat"
@print{}
@print{} " came back"
@result{} " came back"
@end group
@end example
@end defun
@defun prin1 object &optional stream
This function outputs the printed representation of @var{object} to
@var{stream}. It does not print newlines to separate output as
@code{print} does, but it does use quoting characters just like
@code{print}. It returns @var{object}.
@example
@group
(progn (prin1 'The\ cat\ in)
(prin1 "the hat")
(prin1 " came back"))
@print{} The\ cat\ in"the hat"" came back"
@result{} " came back"
@end group
@end example
@end defun
@defun princ object &optional stream
This function outputs the printed representation of @var{object} to
@var{stream}. It returns @var{object}.
This function is intended to produce output that is readable by people,
not by @code{read}, so it doesn't insert quoting characters and doesn't
put double-quotes around the contents of strings. It does not add any
spacing between calls.
@example
@group
(progn
(princ 'The\ cat)
(princ " in the \"hat\""))
@print{} The cat in the "hat"
@result{} " in the \"hat\""
@end group
@end example
@end defun
@defun terpri &optional stream
@cindex newline in print
This function outputs a newline to @var{stream}. The name stands
for ``terminate print.''
@end defun
@defun write-char character &optional stream
This function outputs @var{character} to @var{stream}. It returns
@var{character}.
@end defun
@defun prin1-to-string object &optional noescape
@cindex object to string
This function returns a string containing the text that @code{prin1}
would have printed for the same argument.
@example
@group
(prin1-to-string 'foo)
@result{} "foo"
@end group
@group
(prin1-to-string (mark-marker))
@result{} "#<marker at 2773 in strings.texi>"
@end group
@end example
If @var{noescape} is non-@code{nil}, that inhibits use of quoting
characters in the output. (This argument is supported in Emacs versions
19 and later.)
@example
@group
(prin1-to-string "foo")
@result{} "\"foo\""
@end group
@group
(prin1-to-string "foo" t)
@result{} "foo"
@end group
@end example
See @code{format}, in @ref{Formatting Strings}, for other ways to obtain
the printed representation of a Lisp object as a string.
@end defun
@defmac with-output-to-string body@dots{}
This macro executes the @var{body} forms with @code{standard-output} set
up to feed output into a string. Then it returns that string.
For example, if the current buffer name is @samp{foo},
@example
(with-output-to-string
(princ "The buffer is ")
(princ (buffer-name)))
@end example
@noindent
returns @code{"The buffer is foo"}.
@end defmac
@node Output Variables
@section Variables Affecting Output
@cindex output-controlling variables
@defvar standard-output
The value of this variable is the default output stream---the stream
that print functions use when the @var{stream} argument is @code{nil}.
The default is @code{t}, meaning display in the echo area.
@end defvar
@defvar print-quoted
If this is non-@code{nil}, that means to print quoted forms using
abbreviated reader syntax. @code{(quote foo)} prints as @code{'foo},
@code{(function foo)} as @code{#'foo}, and backquoted forms print
using modern backquote syntax.
@end defvar
@defvar print-escape-newlines
@cindex @samp{\n} in print
@cindex escape characters
If this variable is non-@code{nil}, then newline characters in strings
are printed as @samp{\n} and formfeeds are printed as @samp{\f}.
Normally these characters are printed as actual newlines and formfeeds.
This variable affects the print functions @code{prin1} and @code{print}
that print with quoting. It does not affect @code{princ}. Here is an
example using @code{prin1}:
@example
@group
(prin1 "a\nb")
@print{} "a
@print{} b"
@result{} "a
b"
@end group
@group
(let ((print-escape-newlines t))
(prin1 "a\nb"))
@print{} "a\nb"
@result{} "a
b"
@end group
@end example
@noindent
In the second expression, the local binding of
@code{print-escape-newlines} is in effect during the call to
@code{prin1}, but not during the printing of the result.
@end defvar
@defvar print-escape-nonascii
If this variable is non-@code{nil}, then unibyte non-@acronym{ASCII}
characters in strings are unconditionally printed as backslash sequences
by the print functions @code{prin1} and @code{print} that print with
quoting.
Those functions also use backslash sequences for unibyte non-@acronym{ASCII}
characters, regardless of the value of this variable, when the output
stream is a multibyte buffer or a marker pointing into one.
@end defvar
@defvar print-escape-multibyte
If this variable is non-@code{nil}, then multibyte non-@acronym{ASCII}
characters in strings are unconditionally printed as backslash sequences
by the print functions @code{prin1} and @code{print} that print with
quoting.
Those functions also use backslash sequences for multibyte
non-@acronym{ASCII} characters, regardless of the value of this variable,
when the output stream is a unibyte buffer or a marker pointing into
one.
@end defvar
@defvar print-length
@cindex printing limits
The value of this variable is the maximum number of elements to print in
any list, vector or bool-vector. If an object being printed has more
than this many elements, it is abbreviated with an ellipsis.
If the value is @code{nil} (the default), then there is no limit.
@example
@group
(setq print-length 2)
@result{} 2
@end group
@group
(print '(1 2 3 4 5))
@print{} (1 2 ...)
@result{} (1 2 ...)
@end group
@end example
@end defvar
@defvar print-level
The value of this variable is the maximum depth of nesting of
parentheses and brackets when printed. Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis. A value of
@code{nil} (which is the default) means no limit.
@end defvar
@defopt eval-expression-print-length
@defoptx eval-expression-print-level
These are the values for @code{print-length} and @code{print-level}
used by @code{eval-expression}, and thus, indirectly, by many
interactive evaluation commands (@pxref{Lisp Eval,, Evaluating
Emacs-Lisp Expressions, emacs, The GNU Emacs Manual}).
@end defopt
These variables are used for detecting and reporting circular
and shared structure:
@defvar print-circle
If non-@code{nil}, this variable enables detection of circular
and shared structure in printing.
@end defvar
@defvar print-gensym
If non-@code{nil}, this variable enables detection of uninterned symbols
(@pxref{Creating Symbols}) in printing. When this is enabled,
uninterned symbols print with the prefix @samp{#:}, which tells the Lisp
reader to produce an uninterned symbol.
@end defvar
@defvar print-continuous-numbering
If non-@code{nil}, that means number continuously across print calls.
This affects the numbers printed for @samp{#@var{n}=} labels and
@samp{#@var{m}#} references.
Don't set this variable with @code{setq}; you should only bind it
temporarily to @code{t} with @code{let}. When you do that, you should
also bind @code{print-number-table} to @code{nil}.
@end defvar
@defvar print-number-table
This variable holds a vector used internally by printing to implement
the @code{print-circle} feature. You should not use it except
to bind it to @code{nil} when you bind @code{print-continuous-numbering}.
@end defvar
@defvar float-output-format
This variable specifies how to print floating point numbers. Its
default value is @code{nil}, meaning use the shortest output
that represents the number without losing information.
To control output format more precisely, you can put a string in this
variable. The string should hold a @samp{%}-specification to be used
in the C function @code{sprintf}. For further restrictions on what
you can use, see the variable's documentation string.
@end defvar
@ignore
arch-tag: 07636b8c-c4e3-4735-9e06-2e864320b434
@end ignore

1163
doc/lispref/strings.texi Normal file
View file

File diff suppressed because it is too large Load diff

598
doc/lispref/symbols.texi Normal file
View file

@ -0,0 +1,598 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
@c 2002, 2003, 2004, 2005, 2006, 2007 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/symbols
@node Symbols, Evaluation, Hash Tables, Top
@chapter Symbols
@cindex symbol
A @dfn{symbol} is an object with a unique name. This chapter
describes symbols, their components, their property lists, and how they
are created and interned. Separate chapters describe the use of symbols
as variables and as function names; see @ref{Variables}, and
@ref{Functions}. For the precise read syntax for symbols, see
@ref{Symbol Type}.
You can test whether an arbitrary Lisp object is a symbol
with @code{symbolp}:
@defun symbolp object
This function returns @code{t} if @var{object} is a symbol, @code{nil}
otherwise.
@end defun
@menu
* Symbol Components:: Symbols have names, values, function definitions
and property lists.
* Definitions:: A definition says how a symbol will be used.
* Creating Symbols:: How symbols are kept unique.
* Property Lists:: Each symbol has a property list
for recording miscellaneous information.
@end menu
@node Symbol Components, Definitions, Symbols, Symbols
@section Symbol Components
@cindex symbol components
Each symbol has four components (or ``cells''), each of which
references another object:
@table @asis
@item Print name
@cindex print name cell
The @dfn{print name cell} holds a string that names the symbol for
reading and printing. See @code{symbol-name} in @ref{Creating Symbols}.
@item Value
@cindex value cell
The @dfn{value cell} holds the current value of the symbol as a
variable. When a symbol is used as a form, the value of the form is the
contents of the symbol's value cell. See @code{symbol-value} in
@ref{Accessing Variables}.
@item Function
@cindex function cell
The @dfn{function cell} holds the function definition of the symbol.
When a symbol is used as a function, its function definition is used in
its place. This cell is also used to make a symbol stand for a keymap
or a keyboard macro, for editor command execution. Because each symbol
has separate value and function cells, variables names and function names do
not conflict. See @code{symbol-function} in @ref{Function Cells}.
@item Property list
@cindex property list cell
The @dfn{property list cell} holds the property list of the symbol. See
@code{symbol-plist} in @ref{Property Lists}.
@end table
The print name cell always holds a string, and cannot be changed. The
other three cells can be set individually to any specified Lisp object.
The print name cell holds the string that is the name of the symbol.
Since symbols are represented textually by their names, it is important
not to have two symbols with the same name. The Lisp reader ensures
this: every time it reads a symbol, it looks for an existing symbol with
the specified name before it creates a new one. (In GNU Emacs Lisp,
this lookup uses a hashing algorithm and an obarray; see @ref{Creating
Symbols}.)
The value cell holds the symbol's value as a variable
(@pxref{Variables}). That is what you get if you evaluate the symbol as
a Lisp expression (@pxref{Evaluation}). Any Lisp object is a legitimate
value. Certain symbols have values that cannot be changed; these
include @code{nil} and @code{t}, and any symbol whose name starts with
@samp{:} (those are called @dfn{keywords}). @xref{Constant Variables}.
We often refer to ``the function @code{foo}'' when we really mean
the function stored in the function cell of the symbol @code{foo}. We
make the distinction explicit only when necessary. In normal
usage, the function cell usually contains a function
(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and
autoload objects (@pxref{Autoloading}) are also sometimes stored in
the function cells of symbols.
The property list cell normally should hold a correctly formatted
property list (@pxref{Property Lists}), as a number of functions expect
to see a property list there.
The function cell or the value cell may be @dfn{void}, which means
that the cell does not reference any object. (This is not the same
thing as holding the symbol @code{void}, nor the same as holding the
symbol @code{nil}.) Examining a function or value cell that is void
results in an error, such as @samp{Symbol's value as variable is void}.
The four functions @code{symbol-name}, @code{symbol-value},
@code{symbol-plist}, and @code{symbol-function} return the contents of
the four cells of a symbol. Here as an example we show the contents of
the four cells of the symbol @code{buffer-file-name}:
@example
(symbol-name 'buffer-file-name)
@result{} "buffer-file-name"
(symbol-value 'buffer-file-name)
@result{} "/gnu/elisp/symbols.texi"
(symbol-function 'buffer-file-name)
@result{} #<subr buffer-file-name>
(symbol-plist 'buffer-file-name)
@result{} (variable-documentation 29529)
@end example
@noindent
Because this symbol is the variable which holds the name of the file
being visited in the current buffer, the value cell contents we see are
the name of the source file of this chapter of the Emacs Lisp Manual.
The property list cell contains the list @code{(variable-documentation
29529)} which tells the documentation functions where to find the
documentation string for the variable @code{buffer-file-name} in the
@file{DOC-@var{version}} file. (29529 is the offset from the beginning
of the @file{DOC-@var{version}} file to where that documentation string
begins---see @ref{Documentation Basics}.) The function cell contains
the function for returning the name of the file.
@code{buffer-file-name} names a primitive function, which has no read
syntax and prints in hash notation (@pxref{Primitive Function Type}). A
symbol naming a function written in Lisp would have a lambda expression
(or a byte-code object) in this cell.
@node Definitions, Creating Symbols, Symbol Components, Symbols
@section Defining Symbols
@cindex definitions of symbols
A @dfn{definition} in Lisp is a special form that announces your
intention to use a certain symbol in a particular way. In Emacs Lisp,
you can define a symbol as a variable, or define it as a function (or
macro), or both independently.
A definition construct typically specifies a value or meaning for the
symbol for one kind of use, plus documentation for its meaning when used
in this way. Thus, when you define a symbol as a variable, you can
supply an initial value for the variable, plus documentation for the
variable.
@code{defvar} and @code{defconst} are special forms that define a
symbol as a global variable. They are documented in detail in
@ref{Defining Variables}. For defining user option variables that can
be customized, use @code{defcustom} (@pxref{Customization}).
@code{defun} defines a symbol as a function, creating a lambda
expression and storing it in the function cell of the symbol. This
lambda expression thus becomes the function definition of the symbol.
(The term ``function definition,'' meaning the contents of the function
cell, is derived from the idea that @code{defun} gives the symbol its
definition as a function.) @code{defsubst} and @code{defalias} are two
other ways of defining a function. @xref{Functions}.
@code{defmacro} defines a symbol as a macro. It creates a macro
object and stores it in the function cell of the symbol. Note that a
given symbol can be a macro or a function, but not both at once, because
both macro and function definitions are kept in the function cell, and
that cell can hold only one Lisp object at any given time.
@xref{Macros}.
In Emacs Lisp, a definition is not required in order to use a symbol
as a variable or function. Thus, you can make a symbol a global
variable with @code{setq}, whether you define it first or not. The real
purpose of definitions is to guide programmers and programming tools.
They inform programmers who read the code that certain symbols are
@emph{intended} to be used as variables, or as functions. In addition,
utilities such as @file{etags} and @file{make-docfile} recognize
definitions, and add appropriate information to tag tables and the
@file{DOC-@var{version}} file. @xref{Accessing Documentation}.
@node Creating Symbols, Property Lists, Definitions, Symbols
@section Creating and Interning Symbols
@cindex reading symbols
To understand how symbols are created in GNU Emacs Lisp, you must know
how Lisp reads them. Lisp must ensure that it finds the same symbol
every time it reads the same set of characters. Failure to do so would
cause complete confusion.
@cindex symbol name hashing
@cindex hashing
@cindex obarray
@cindex bucket (in obarray)
When the Lisp reader encounters a symbol, it reads all the characters
of the name. Then it ``hashes'' those characters to find an index in a
table called an @dfn{obarray}. Hashing is an efficient method of
looking something up. For example, instead of searching a telephone
book cover to cover when looking up Jan Jones, you start with the J's
and go from there. That is a simple version of hashing. Each element
of the obarray is a @dfn{bucket} which holds all the symbols with a
given hash code; to look for a given name, it is sufficient to look
through all the symbols in the bucket for that name's hash code. (The
same idea is used for general Emacs hash tables, but they are a
different data type; see @ref{Hash Tables}.)
@cindex interning
If a symbol with the desired name is found, the reader uses that
symbol. If the obarray does not contain a symbol with that name, the
reader makes a new symbol and adds it to the obarray. Finding or adding
a symbol with a certain name is called @dfn{interning} it, and the
symbol is then called an @dfn{interned symbol}.
Interning ensures that each obarray has just one symbol with any
particular name. Other like-named symbols may exist, but not in the
same obarray. Thus, the reader gets the same symbols for the same
names, as long as you keep reading with the same obarray.
Interning usually happens automatically in the reader, but sometimes
other programs need to do it. For example, after the @kbd{M-x} command
obtains the command name as a string using the minibuffer, it then
interns the string, to get the interned symbol with that name.
@cindex symbol equality
@cindex uninterned symbol
No obarray contains all symbols; in fact, some symbols are not in any
obarray. They are called @dfn{uninterned symbols}. An uninterned
symbol has the same four cells as other symbols; however, the only way
to gain access to it is by finding it in some other object or as the
value of a variable.
Creating an uninterned symbol is useful in generating Lisp code,
because an uninterned symbol used as a variable in the code you generate
cannot clash with any variables used in other Lisp programs.
In Emacs Lisp, an obarray is actually a vector. Each element of the
vector is a bucket; its value is either an interned symbol whose name
hashes to that bucket, or 0 if the bucket is empty. Each interned
symbol has an internal link (invisible to the user) to the next symbol
in the bucket. Because these links are invisible, there is no way to
find all the symbols in an obarray except using @code{mapatoms} (below).
The order of symbols in a bucket is not significant.
In an empty obarray, every element is 0, so you can create an obarray
with @code{(make-vector @var{length} 0)}. @strong{This is the only
valid way to create an obarray.} Prime numbers as lengths tend
to result in good hashing; lengths one less than a power of two are also
good.
@strong{Do not try to put symbols in an obarray yourself.} This does
not work---only @code{intern} can enter a symbol in an obarray properly.
@cindex CL note---symbol in obarrays
@quotation
@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
several obarrays.
@end quotation
Most of the functions below take a name and sometimes an obarray as
arguments. A @code{wrong-type-argument} error is signaled if the name
is not a string, or if the obarray is not a vector.
@defun symbol-name symbol
This function returns the string that is @var{symbol}'s name. For example:
@example
@group
(symbol-name 'foo)
@result{} "foo"
@end group
@end example
@strong{Warning:} Changing the string by substituting characters does
change the name of the symbol, but fails to update the obarray, so don't
do it!
@end defun
@defun make-symbol name
This function returns a newly-allocated, uninterned symbol whose name is
@var{name} (which must be a string). Its value and function definition
are void, and its property list is @code{nil}. In the example below,
the value of @code{sym} is not @code{eq} to @code{foo} because it is a
distinct uninterned symbol whose name is also @samp{foo}.
@example
(setq sym (make-symbol "foo"))
@result{} foo
(eq sym 'foo)
@result{} nil
@end example
@end defun
@defun intern name &optional obarray
This function returns the interned symbol whose name is @var{name}. If
there is no such symbol in the obarray @var{obarray}, @code{intern}
creates a new one, adds it to the obarray, and returns it. If
@var{obarray} is omitted, the value of the global variable
@code{obarray} is used.
@example
(setq sym (intern "foo"))
@result{} foo
(eq sym 'foo)
@result{} t
(setq sym1 (intern "foo" other-obarray))
@result{} foo
(eq sym1 'foo)
@result{} nil
@end example
@end defun
@cindex CL note---interning existing symbol
@quotation
@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
in an obarray. In Emacs Lisp, you cannot do this, because the argument
to @code{intern} must be a string, not a symbol.
@end quotation
@defun intern-soft name &optional obarray
This function returns the symbol in @var{obarray} whose name is
@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
Therefore, you can use @code{intern-soft} to test whether a symbol with
a given name is already interned. If @var{obarray} is omitted, the
value of the global variable @code{obarray} is used.
The argument @var{name} may also be a symbol; in that case,
the function returns @var{name} if @var{name} is interned
in the specified obarray, and otherwise @code{nil}.
@smallexample
(intern-soft "frazzle") ; @r{No such symbol exists.}
@result{} nil
(make-symbol "frazzle") ; @r{Create an uninterned one.}
@result{} frazzle
@group
(intern-soft "frazzle") ; @r{That one cannot be found.}
@result{} nil
@end group
@group
(setq sym (intern "frazzle")) ; @r{Create an interned one.}
@result{} frazzle
@end group
@group
(intern-soft "frazzle") ; @r{That one can be found!}
@result{} frazzle
@end group
@group
(eq sym 'frazzle) ; @r{And it is the same one.}
@result{} t
@end group
@end smallexample
@end defun
@defvar obarray
This variable is the standard obarray for use by @code{intern} and
@code{read}.
@end defvar
@defun mapatoms function &optional obarray
@anchor{Definition of mapatoms}
This function calls @var{function} once with each symbol in the obarray
@var{obarray}. Then it returns @code{nil}. If @var{obarray} is
omitted, it defaults to the value of @code{obarray}, the standard
obarray for ordinary symbols.
@smallexample
(setq count 0)
@result{} 0
(defun count-syms (s)
(setq count (1+ count)))
@result{} count-syms
(mapatoms 'count-syms)
@result{} nil
count
@result{} 1871
@end smallexample
See @code{documentation} in @ref{Accessing Documentation}, for another
example using @code{mapatoms}.
@end defun
@defun unintern symbol &optional obarray
This function deletes @var{symbol} from the obarray @var{obarray}. If
@code{symbol} is not actually in the obarray, @code{unintern} does
nothing. If @var{obarray} is @code{nil}, the current obarray is used.
If you provide a string instead of a symbol as @var{symbol}, it stands
for a symbol name. Then @code{unintern} deletes the symbol (if any) in
the obarray which has that name. If there is no such symbol,
@code{unintern} does nothing.
If @code{unintern} does delete a symbol, it returns @code{t}. Otherwise
it returns @code{nil}.
@end defun
@node Property Lists,, Creating Symbols, Symbols
@section Property Lists
@cindex property list
@cindex plist
A @dfn{property list} (@dfn{plist} for short) is a list of paired
elements stored in the property list cell of a symbol. Each of the
pairs associates a property name (usually a symbol) with a property or
value. Property lists are generally used to record information about a
symbol, such as its documentation as a variable, the name of the file
where it was defined, or perhaps even the grammatical class of the
symbol (representing a word) in a language-understanding system.
Character positions in a string or buffer can also have property lists.
@xref{Text Properties}.
The property names and values in a property list can be any Lisp
objects, but the names are usually symbols. Property list functions
compare the property names using @code{eq}. Here is an example of a
property list, found on the symbol @code{progn} when the compiler is
loaded:
@example
(lisp-indent-function 0 byte-compile byte-compile-progn)
@end example
@noindent
Here @code{lisp-indent-function} and @code{byte-compile} are property
names, and the other two elements are the corresponding values.
@menu
* Plists and Alists:: Comparison of the advantages of property
lists and association lists.
* Symbol Plists:: Functions to access symbols' property lists.
* Other Plists:: Accessing property lists stored elsewhere.
@end menu
@node Plists and Alists
@subsection Property Lists and Association Lists
@cindex plist vs. alist
@cindex alist vs. plist
@cindex property lists vs association lists
Association lists (@pxref{Association Lists}) are very similar to
property lists. In contrast to association lists, the order of the
pairs in the property list is not significant since the property names
must be distinct.
Property lists are better than association lists for attaching
information to various Lisp function names or variables. If your
program keeps all of its associations in one association list, it will
typically need to search that entire list each time it checks for an
association. This could be slow. By contrast, if you keep the same
information in the property lists of the function names or variables
themselves, each search will scan only the length of one property list,
which is usually short. This is why the documentation for a variable is
recorded in a property named @code{variable-documentation}. The byte
compiler likewise uses properties to record those functions needing
special treatment.
However, association lists have their own advantages. Depending on
your application, it may be faster to add an association to the front of
an association list than to update a property. All properties for a
symbol are stored in the same property list, so there is a possibility
of a conflict between different uses of a property name. (For this
reason, it is a good idea to choose property names that are probably
unique, such as by beginning the property name with the program's usual
name-prefix for variables and functions.) An association list may be
used like a stack where associations are pushed on the front of the list
and later discarded; this is not possible with a property list.
@node Symbol Plists
@subsection Property List Functions for Symbols
@defun symbol-plist symbol
This function returns the property list of @var{symbol}.
@end defun
@defun setplist symbol plist
This function sets @var{symbol}'s property list to @var{plist}.
Normally, @var{plist} should be a well-formed property list, but this is
not enforced. The return value is @var{plist}.
@smallexample
(setplist 'foo '(a 1 b (2 3) c nil))
@result{} (a 1 b (2 3) c nil)
(symbol-plist 'foo)
@result{} (a 1 b (2 3) c nil)
@end smallexample
For symbols in special obarrays, which are not used for ordinary
purposes, it may make sense to use the property list cell in a
nonstandard fashion; in fact, the abbrev mechanism does so
(@pxref{Abbrevs}).
@end defun
@defun get symbol property
This function finds the value of the property named @var{property} in
@var{symbol}'s property list. If there is no such property, @code{nil}
is returned. Thus, there is no distinction between a value of
@code{nil} and the absence of the property.
The name @var{property} is compared with the existing property names
using @code{eq}, so any object is a legitimate property.
See @code{put} for an example.
@end defun
@defun put symbol property value
This function puts @var{value} onto @var{symbol}'s property list under
the property name @var{property}, replacing any previous property value.
The @code{put} function returns @var{value}.
@smallexample
(put 'fly 'verb 'transitive)
@result{}'transitive
(put 'fly 'noun '(a buzzing little bug))
@result{} (a buzzing little bug)
(get 'fly 'verb)
@result{} transitive
(symbol-plist 'fly)
@result{} (verb transitive noun (a buzzing little bug))
@end smallexample
@end defun
@node Other Plists
@subsection Property Lists Outside Symbols
These functions are useful for manipulating property lists
that are stored in places other than symbols:
@defun plist-get plist property
This returns the value of the @var{property} property
stored in the property list @var{plist}. For example,
@example
(plist-get '(foo 4) 'foo)
@result{} 4
(plist-get '(foo 4 bad) 'foo)
@result{} 4
(plist-get '(foo 4 bad) 'bar)
@result{} @code{wrong-type-argument} error
@end example
It accepts a malformed @var{plist} argument and always returns @code{nil}
if @var{property} is not found in the @var{plist}. For example,
@example
(plist-get '(foo 4 bad) 'bar)
@result{} nil
@end example
@end defun
@defun plist-put plist property value
This stores @var{value} as the value of the @var{property} property in
the property list @var{plist}. It may modify @var{plist} destructively,
or it may construct a new list structure without altering the old. The
function returns the modified property list, so you can store that back
in the place where you got @var{plist}. For example,
@example
(setq my-plist '(bar t foo 4))
@result{} (bar t foo 4)
(setq my-plist (plist-put my-plist 'foo 69))
@result{} (bar t foo 69)
(setq my-plist (plist-put my-plist 'quux '(a)))
@result{} (bar t foo 69 quux (a))
@end example
@end defun
You could define @code{put} in terms of @code{plist-put} as follows:
@example
(defun put (symbol prop value)
(setplist symbol
(plist-put (symbol-plist symbol) prop value)))
@end example
@defun lax-plist-get plist property
Like @code{plist-get} except that it compares properties
using @code{equal} instead of @code{eq}.
@end defun
@defun lax-plist-put plist property value
Like @code{plist-put} except that it compares properties
using @code{equal} instead of @code{eq}.
@end defun
@defun plist-member plist property
This returns non-@code{nil} if @var{plist} contains the given
@var{property}. Unlike @code{plist-get}, this allows you to distinguish
between a missing property and a property with the value @code{nil}.
The value is actually the tail of @var{plist} whose @code{car} is
@var{property}.
@end defun
@ignore
arch-tag: 8750b7d2-de4c-4923-809a-d35fc39fd8ce
@end ignore

1185
doc/lispref/syntax.texi Normal file
View file

File diff suppressed because it is too large Load diff

4303
doc/lispref/text.texi Normal file
View file

File diff suppressed because it is too large Load diff

127
doc/lispref/tindex.pl Executable file
View file

@ -0,0 +1,127 @@
#! /usr/bin/perl
# Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005,
# 2006, 2007 Free Software Foundation, Inc.
#
# This file is part of GNU Emacs.
#
# GNU Emacs is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# GNU Emacs is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with GNU Emacs; see the file COPYING. If not, write to the
# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
require 5;
use Getopt::Long;
my $USAGE = <<ENDUSAGE;
Remove \@tindex lines from files that were already present in previous
versions.
Usage: $0 [--old=EXT] FILE...
$0 --help
$0 --version
--help display this help and exit
--version print version and exit
--old=DIR find old files in DIR
The script performs two passes. In the first pass, Texinfo files from
DIR are scanned for \@tindex lines, and identifiers in them are
recorded. In a second pass, Texinfo files in the current directory
are scanned, and \@tindex lines for identifiers that were recorded in
the first pass are removed. Old file contents are saved in files
with extension ".orig". A list of modified files and removed \@tindex
identifiers is printed to stdout at the end.
ENDUSAGE
sub fatal {
print STDERR "$0: ", @_, ".\n";
exit 1;
}
my $help = 0;
my $version = 0;
my $old;
my $rc = GetOptions ('help' => \$help, 'version' => \$version,
'old=s' => \$old);
if ($version) {
print "0.1\n";
exit 0;
} elsif (!$rc || !$old || @ARGV) {
print $USAGE;
exit 1;
} elsif ($help) {
print $USAGE;
exit 0;
}
# Fill the hash %tindex with associations VAR -> COUNT where
# the keys VAR are identifiers mentioned in @tindex lines in the older
# files to process and COUNT is the number of times they are seen in
# the files.
my %tindex;
my %removed;
my @old_files = glob "$old/*.texi";
my @new_files = glob "*.texi";
fatal ("No Texinfo files found in `$old'") unless @old_files;
fatal ("No Texinfo files found in current directory") unless @new_files;
print "Scanning old files for \@tindex lines\n";
foreach $file (@old_files) {
open (IN, "<$file") or fatal "Cannot open $file: $!";
while (<IN>) {
++$tindex{$1} if /^\s*\@tindex\s+(\S+)/;
}
close IN;
}
# Process current files and remove those @tindex lines which we
# know were already present in the files scanned above.
print "Removing old \@tindex lines\n";
foreach $file (@new_files) {
my $modified = 0;
my $contents = "";
open (IN, "< $file") or fatal "Cannot open $file.orig for reading: $!";
while (<IN>) {
if (/^\s*\@tindex\s+(\S+)/ && $tindex{$1}) {
++$removed{$1};
$modified = 1;
} else {
$contents = $contents . $_;
}
}
close IN;
if ($modified) {
print " $file\n";
system ("cp $file $file.orig") == 0 or fatal "Cannot backup $file: $!";
open (OUT, ">$file") or fatal "Cannot open $file for writing: $!";
print OUT $contents;
close OUT;
}
}
# Print a list of identifiers removed.
print "Removed \@tindex commands for:\n";
my $key;
foreach $key (keys %removed) {
print " $key\n";
}
# arch-tag: f8460df6-6bef-4c98-8555-e2c63a88b0fa

1130
doc/lispref/tips.texi Normal file
View file

File diff suppressed because it is too large Load diff

322
doc/lispref/two-volume-cross-refs.txt Normal file
View file

@ -0,0 +1,322 @@
Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
Free Software Foundation, Inc.
See end for copying conditions.
Two Volume Cross References
===========================
12 June 2007 (karl)
For lispref 2.9 (for Emacs 22, June 2007), I created a very ugly
Makefile, in the file two-volume.make, to encapsulate all the steps
below, without manual intervention. In theory, simply running "make -f
two-volume.make" should create a vol1.pdf and vol2.pdf with all the
niceties worked out.
One issue not explicitly discussed below is getting page numbers right.
It's not enough to go through the whole process. You have to go through
the whole process twice -- otherwise, some index entries and/or toc
entries will be off by one. See two-volume.make for a few more comments.
For future editions, it should suffice to update the usual things in
vol[12].texi (as well as elisp.texi). That was my hope, anyway.
18 March 1992 (bob)
This enables you to create manuals in *two* volumes, with tables of
contents, cross references, and indices in each volume referring to
*both* volumes.
The procedure is tedious. However, the resulting two volumes are
conveniently organized. Each has an index of the whole two volumes.
Each volume starts with page 1. (I don't like multi-volume works
where each volume starts with a higher page number since I find it
harder to go to the right place in the volume.)
References to the same volume are just the page number; references to
the other volume are a volumne number (in Roman numerals) preceding
the page number.
For example, in Volume I:
list length ......... 90
list motion ......II:117
and in Volume II:
list length ....... I:90
list motion .........117
All other references and the table of contents work the same way. I
find this *very* helpful.
In brief: you run tex on a .texi file with
a. redefined @contents and @summarycontents inputting elisp-toc-2vol.toc file
b. redone .aux file
c. redone .fns file
Here are the steps in detail:
% tex vol1.texi
% texindex vol1.??
% tex vol1.texi
% tex vol2.texi
% texindex vol2.??
% tex vol2.texi
### Create .aux files with volume numbers for other volume.
% cp vol1.aux elisp1-aux
% cp vol2.aux elisp2-aux
% cp vol1.aux elisp1-aux-vol-added
% cp vol2.aux elisp2-aux-vol-added
on elisp1-aux-vol-number-added
(volume-aux-markup 1) see defun for volume-aux-markup below.
to create elisp1-aux-vol-added
on elisp2-aux-vol-number-added
(volume-aux-markup 2)
to create elisp2-aux-vol-added
insert elisp2-aux-vol-added into vol1.aux (append)
insert elisp1-aux-vol-added into vol2.aux (prepend)
(so you dont have to do it again)
% cp vol1.aux elisp1-aux-ready
% cp vol2.aux elisp2-aux-ready
### Create .fn files with volume numbers for other volume.
% cp vol1.fn elisp1-fn
% cp vol2.fn elisp2-fn
% cp vol1.fn elisp1-fn-vol-number-added
% cp vol2.fn elisp2-fn-vol-number-added
on elisp1-fn-vol-number-added
(volume-index-markup "I")
to create elisp1-fn-vol-number-added
on elisp2-fn-vol-number-added
(volume-index-markup "II")
to create elisp2-fn-vol-number-added
insert elisp2-fn-vol-number-added into vol1.fn: do following `cat'
insert elisp1-fn-vol-number-added into vol2.fn: do following `cat'
% cat elisp2-fn-vol-number-added >> vol1.fn
% cat elisp1-fn-vol-number-added >> vol2.fn
Be sure to handle special case entries by hand.
Be sure that .fn file has no blank lines.
% texindex vol1.fn
% texindex vol2.fn
(so you dont have to do it again)
% cp vol1.fns elisp1-fns-2vol-ready
% cp vol2.fns elisp2-fns-2vol-ready
### Create merged .toc file with volume number headings.
append vol2.toc to vol1.toc with following `cat'
% cat vol1.toc vol2.toc > elisp-toc-2vol.toc
and edit in Volume titles
\unnumbchapentry {Volume 1}{}
\unnumbchapentry {}{}
\unnumbchapentry {Index}{295}
\unnumbchapentry {}{}
\unnumbchapentry {Volume 2}{}
\unnumbchapentry {}{}
If you want to put in volume numbers for TOC, then do this:
Create volume specific .toc files with volume numbers in them.
% cp elisp-toc-2vol.toc elisp1-toc.toc
% cp elisp-toc-2vol.toc elisp2-toc.toc
Use keyboard macro to put I: in first half of elisp1-toc.toc and
II: in first half of elisp2-toc.toc
Copy the tocs to something you can remember more easily
% cp elisp2-toc.toc elisp1-toc-ready.toc
% cp elisp1-toc.toc elisp2-toc-ready.toc
Then, edit vol1.texi to input elisp1-toc-ready.toc
and vol2.texi to input elisp2-toc-ready.toc
### Now format the two volumes:
% cp elisp1-aux-2vol-ready vol1.aux
% cp elisp2-aux-2vol-ready vol2.aux
% tex vol1.texi
% tex vol2.texi
For every additional run:
### recopy aux files so the correct ones are read:
% cp elisp1-aux-2vol-ready vol1.aux
% cp elisp2-aux-2vol-ready vol2.aux
Do not run texindex. Then proper sorted index will stay.
else do: % cp elisp2-fns-2vol-ready vol2.fns
Do not change the .texi files; they will call the elisp-toc-2vol.toc file.
% tex vol1.texi
% tex vol2.texi
================================================================
(defun volume-aux-markup (arg)
"Append `vol. NUMBER' to page number.
Apply to aux file that you save.
Then insert marked file into other volume's .aux file."
(interactive "sType volume number, 1 or 2: " )
(goto-char (point-min))
(while (search-forward "-pg" nil t)
(end-of-line 1)
(delete-backward-char 1 nil)
(insert ", vol.'tie" arg "}")))
(defun volume-index-markup (arg)
"Prepend `NUMBER:' to page number. Use Roman Numeral.
Apply only to unsorted index file,
Then insert marked file into other volume's unsorted index file.
Then run texindex on that file and save."
(interactive
"sType volume number, roman number I or II: " )
(goto-char (point-min))
(while (search-forward "\\entry" nil t)
(search-forward "}{" (save-excursion (end-of-line) (point)) nil)
(insert arg ":")))
================================================================
The steps:
1. Run TeX, texindex and TeX on file1.
2. Run TeX, texindex and TeX on file2.
3. Copy both .aux files into specially named files
4. In the case of the elisp ref manual,
copy the *unsorted* function index files into specially named files
(no other index used in elisp ref manual)
5. For aux files:
Run a function on the specially named .aux files to label each
entry according to volume. Save these files.
i.e., convert
'xrdef {Special-pg}{7} to 'xrdef {Special-pg}{7, vol.'tie1}
5a.Insert each specially named .aux file into the regular .aux file of
the other volume.
6. For index files:
Run a function on the specially named unsorted index files to label
each entry according to volume. Save these files.
6b.Insert each specially named marked unsorted index file into the
regular unsorted file of the other volume. Run texindex on this
7. Insert the other volumes .toc file into the .toc, edit, and rename to
elisp-toc-2vol.toc
7a. insert special @contents and @summarycontents defs into .texi files.
8. Run TeX on each .texi file.
================
Here is the discursive commentary:
I've been running some small test files, called test1.texi and
test2.texi. As far as I can see, if we run tex on the two test files,
tex creates a .aux for each that includes the names of all the nodes
in that file. The node names are used for cross references.
If you insert the .aux file for the second test file, test2.aux, into
the .aux file for the first test file, test1.aux, then when you next
run TeX on the first test file, test1.texi, the second volume cross
references are inserted.
You can edit the text of the cross reference in test2.aux to include
the volume number.
For example, you can take the following two lines from test1.texi and
insert them into test2.texi:
'xrdef {Special-pg}{7}
'xrdef {Special-snt}{Section'tie1.6}
You can re-edit this to show that the page is in volume 1:
'xrdef {Special-pg}{7, vol.'tie1}
'xrdef {Special-snt}{Section'tie1.6}
(The 'tie is a TeX special command to keep the number tied on one
line to the previous word. I don't know if it works after a period in
the "vol." but figure it is worth trying. {The ' is the @ of .aux files.}
Apparently 'tie is like the tilde in plain tex; in texinfo.tex, the
definition for 'tie is the following:
\def\tie{\penalty 10000\ } % Save plain tex definition of ~.
)
After running tex on the test2.texi file with the augmented test2.aux
file, you can see the following in the resulting DVI file:
See Section 1.6 [Special], page 7, vol. 1
Note that TeX rewrites the .aux file each time TeX is run, so after
running Tex using an .aux file augmented with the .aux file from the
other volume, the new .aux file will *lack* the other volumes cross
references. Save your augmented .aux file in some other name for
another run!
COPYING CONDITIONS
This file is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3, or (at your option)
any later version.
This file is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this file; see the file COPYING. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
Boston, MA 02110-1301, USA.

227
doc/lispref/two-volume.make Normal file
View file

@ -0,0 +1,227 @@
# Copyright 2007 Free Software Foundation, Inc.
# See end for copying conditions.
# although it would be nice to use tex rather than pdftex to avoid
# colors, spurious warnings about names being referenced but not
# existing, etc., dvips | ps2pdf doesn't preserve the page size.
# Instead of creating a special dvips config file, put up with the warnings.
tex = pdftex -interaction=nonstopmode
all: vol1.pdf vol2.pdf
# vol1.texi and vol2.texi specially define \tocreadfilename so we can
# use our premade .toc's.
#
vol1.pdf: elisp1med-fns-ready elisp1med-aux-ready elisp1med-toc-ready
@echo -e "\f Final TeX run for volume 1..."
cp elisp1med-toc-ready elisp1-toc-ready.toc
cp elisp1med-fns-ready vol1.fns
cp elisp1med-aux-ready vol1.aux
$(tex) vol1.texi
#
vol2.pdf: elisp2med-fns-ready elisp2med-aux-ready elisp2med-toc-ready
@echo "Final TeX run for volume 2..."
cp elisp2med-toc-ready elisp2-toc-ready.toc
cp elisp2med-fns-ready vol2.fns
cp elisp2med-aux-ready vol2.aux
$(tex) vol2.texi
# intermediate toc files.
#
# vol1 toc: volume 1, page break, volume 2 (with II: prepended).
elisp1med-toc-ready: elisp1med-init elisp2med-init
echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
cat elisp1med-toc >>$@
echo '@page' >>$@
echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2med-toc >>$@
#
# vol2 toc: volume 1 (with I: prepended), page break, volume 2.
elisp2med-toc-ready: elisp1med-init elisp2med-init
echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1med-toc >>$@
echo '@page' >>$@
echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
cat elisp2med-toc >>$@
# intermediate aux files.
#
# append vol2's fixed aux to normal vol1.
elisp1med-aux-ready: elisp2med-aux-vol-added
cat elisp1med-aux $< >$@
#
# prepend vol1's fixed aux to vol2.
elisp2med-aux-ready: elisp1med-aux-vol-added
cat $< elisp2med-aux >$@
# on -pg entries, append volume number after page number.
elisp1med-aux-vol-added: elisp1med-init
sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1med-aux >$@
#
elisp2med-aux-vol-added: elisp2med-init
sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2med-aux >$@
# intermediate index (fns) file.
#
elisp1med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added
cat elisp2med-fn-vol-added >>vol1.fn
texindex vol1.fn
cp vol1.fns $@
#
elisp2med-fns-ready: elisp1med-fn-vol-added elisp2med-fn-vol-added
cat elisp1med-fn-vol-added >>vol2.fn
texindex vol2.fn
cp vol2.fns $@
# Insert volume number (I: or II:) into index file.
elisp1med-fn-vol-added: elisp1med-init
cp vol1.fn elisp1med-fn
sed 's/}{/}{I:/' elisp1med-fn >$@
#
elisp2med-fn-vol-added: elisp2med-init
cp vol2.fn elisp2med-fn
sed 's/}{/}{II:/' elisp2med-fn >$@
# -----------------------------------------------------------------------------
# everything above is essentially a duplicate of everything below. sorry.
# -----------------------------------------------------------------------------
# intermediate TeX runs.
#
# this generates what would be the final versions -- except the page
# numbers aren't right. The process of adding the I: and II: changes
# the page breaks, so a few index entries, at least are wrong. (In
# 2007, x-meta-keysym in vol.II ended up on page 374 when the index had
# it on page 375 from the initial run.)
#
# So, we start all over again, from these fns/aux/toc files.
#
elisp1med-init: elisp1-fns-ready elisp1-aux-ready elisp1init-toc-ready texinfo.tex
@echo -e "\f Intermediate TeX run for volume 1..."
cp elisp1init-toc-ready elisp1-toc-ready.toc
cp elisp1-fns-ready vol1.fns
cp elisp1-aux-ready vol1.aux
$(tex) vol1.texi
texindex vol1.??
mv vol1.aux elisp1med-aux
mv vol1.toc elisp1med-toc
#
elisp2med-init: elisp2-fns-ready elisp2-aux-ready elisp2init-toc-ready texinfo.tex
@echo "Final TeX run for volume 2..."
cp elisp2init-toc-ready elisp2-toc-ready.toc
cp elisp2-fns-ready vol2.fns
cp elisp2-aux-ready vol2.aux
$(tex) vol2.texi
texindex vol2.??
mv vol2.aux elisp2med-aux
mv vol2.toc elisp2med-toc
# initial toc files.
#
# vol1 toc: volume 1, page break, volume 2 (with II: prepended).
elisp1init-toc-ready: elisp1-init elisp2-init
echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
cat elisp1-toc >>$@
echo '@page' >>$@
echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
sed 's/{\([^}]*\)}$$/{II:\1}/' elisp2-toc >>$@
#
# vol2 toc: volume 1 (with I: prepended), page break, volume 2.
elisp2init-toc-ready: elisp1-init elisp2-init
echo '@unnchapentry{@b{Volume 1}}{10001}{vol1}{}' >$@
sed 's/{\([^}]*\)}$$/{I:\1}/' elisp1-toc >>$@
echo '@page' >>$@
echo '@unnchapentry{@b{Volume 2}}{10001}{vol2}{}' >>$@
cat elisp2-toc >>$@
# initial aux files.
#
# append vol2's fixed aux to normal vol1. The initial runs saved
# elisp1-aux and elisp2-aux.
elisp1-aux-ready: elisp2-aux-vol-added
cat elisp1-aux $< >$@
#
# prepend vol1's fixed aux to vol2.
elisp2-aux-ready: elisp1-aux-vol-added
cat $< elisp2-aux >$@
# on -pg entries, append volume number after page number.
elisp1-aux-vol-added: elisp1-init
sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie1}/' elisp1-aux >$@
#
elisp2-aux-vol-added: elisp2-init
sed 's/-pg}{\(.*\)}$$/-pg}{\1, vol.@tie2}/' elisp2-aux >$@
# initial index (fns) file.
#
# Append other volume's index entries to this one's.
# Index entries in this volume will then take precedence.
elisp1-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added
cat elisp2-fn-vol-added >>vol1.fn
texindex vol1.fn
cp vol1.fns $@
#
elisp2-fns-ready: elisp1-fn-vol-added elisp2-fn-vol-added
cat elisp1-fn-vol-added >>vol2.fn
texindex vol2.fn
cp vol2.fns $@
# Insert volume number (I: or II:) into index file.
elisp1-fn-vol-added: elisp1-init
cp vol1.fn elisp1-fn
sed 's/}{/}{I:/' elisp1-fn >$@
#
elisp2-fn-vol-added: elisp2-init
cp vol2.fn elisp2-fn
sed 's/}{/}{II:/' elisp2-fn >$@
# initial TeX runs.
#
# We use the .fn, .aux, and .toc files created here in subsequent
# processing. The page numbers generated here will not be correct yet,
# but we run texindex and TeX a second time just to get them closer.
# Otherwise it might take even longer for them to converge.
#
elisp1-init: vol1.texi
@echo -e "\f Initial TeX run for volume 1..."
rm -f vol1.aux vol1.toc
$(tex) $<
texindex vol1.??
mv vol1.aux elisp1-aux
mv vol1.toc elisp1-toc
touch $@
#
elisp2-init: vol2.texi
@echo "Initial TeX run for volume 2..."
rm -f vol2.aux vol2.toc
$(tex) $<
texindex vol2.??
mv vol2.aux elisp2-aux
mv vol2.toc elisp2-toc
touch $@
# COPYING CONDITIONS
#
# This file is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; either version 3, or (at your option)
# any later version.
#
# This file is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this file; see the file COPYING. If not, write to
# the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
# Boston, MA 02110-1301, USA.
# arch-tag: 5c258a2e-d4a9-4d0e-b279-fb3a6faa27eb

80
doc/lispref/two.el Normal file
View file

@ -0,0 +1,80 @@
;; Auxiliary functions for preparing a two volume manual.
;; Copyright (C) 2001, 2002, 2003, 2004, 2005, 2006, 2007
;; Free Software Foundation, Inc.
;; --rjc 30mar92
;; This file is free software; you can redistribute it and/or modify
;; it under the terms of the GNU General Public License as published by
;; the Free Software Foundation; either version 3, or (at your option)
;; any later version.
;; This file is distributed in the hope that it will be useful,
;; but WITHOUT ANY WARRANTY; without even the implied warranty of
;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
;; GNU General Public License for more details.
;; You should have received a copy of the GNU General Public License
;; along with this file; see the file COPYING. If not, write to
;; the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
;; Boston, MA 02110-1301, USA.
(defun volume-aux-markup (arg)
"Append `vol. NUMBER' to page number.
Apply to aux file that you save.
Then insert marked file into other volume's .aux file."
(interactive "sType volume number, 1 or 2: " )
(goto-char (point-min))
(while (search-forward "-pg" nil t)
(end-of-line 1)
(delete-backward-char 1 nil)
(insert ", vol.'tie" arg "}")))
(defun volume-index-markup (arg)
"Prepend `NUMBER:' to page number. Use Roman Numeral.
Apply only to unsorted index file,
Then insert marked file into other volume's unsorted index file.
Then run texindex on that file and save."
(interactive
"sType volume number, roman number I or II: " )
(goto-char (point-min))
(while (search-forward "\\entry" nil t)
(search-forward "}{" (save-excursion (end-of-line) (point)) nil)
(insert arg ":")))
(defun volume-numbers-toc-markup (arg)
(interactive
"sType volume number, roman number I or II: " )
(goto-char (point-min))
(while (search-forward "chapentry" nil t)
(end-of-line)
(search-backward "{" nil t)
(forward-char 1)
(insert arg ":")))
(defun volume-header-toc-markup ()
"Insert Volume I and Volume II text into .toc file.
NOTE: this auxilary function is file specific.
This is for the *Elisp Ref Manual*"
(interactive)
(goto-char (point-min))
(insert "\\unnumbchapentry {Volume 1}{}\n\\unnumbchapentry {}{}\n")
(search-forward "\\unnumbchapentry {Index}")
(forward-line 1)
(insert
"\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {}{}\n\\unnumbchapentry {Volume 2}{}\n\\unnumbchapentry {}{}\n"))
;;; In batch mode, you cannot call functions with args; hence this kludge:
(defun volume-aux-markup-1 () (volume-aux-markup "1"))
(defun volume-aux-markup-2 () (volume-aux-markup "2"))
(defun volume-index-markup-I () (volume-index-markup "I"))
(defun volume-index-markup-II () (volume-index-markup "II"))
(defun volume-numbers-toc-markup-I () (volume-numbers-toc-markup "I"))
(defun volume-numbers-toc-markup-II () (volume-numbers-toc-markup "II"))
;;; arch-tag: 848955fe-e9cf-45e7-a2f1-570ef156d6a5

1908
doc/lispref/variables.texi Normal file
View file

File diff suppressed because it is too large Load diff

1507
doc/lispref/vol1.texi Normal file
View file

File diff suppressed because it is too large Load diff

1506
doc/lispref/vol2.texi Normal file
View file

File diff suppressed because it is too large Load diff

2446
doc/lispref/windows.texi Normal file
View file

File diff suppressed because it is too large Load diff