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

*** empty log message ***

Browse source
This commit is contained in:
Richard M. Stallman 1998-04-20 17:43:57 +00:00
parent b933f645ac
commit 969fe9b569
45 changed files with 3563 additions and 2882 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
lispref/abbrevs.texi
View file

@ -54,7 +54,7 @@ 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 local when set in any fashion.
This variable automatically becomes buffer-local when set in any fashion.
@end defvar
@defvar default-abbrev-mode
@ -337,10 +337,6 @@ it is the local abbrev table in all buffers in Fundamental mode.
This is the local abbrev table used in Text mode.
@end defvar
@defvar c-mode-abbrev-table
This is the local abbrev table used in C mode.
@end defvar
@defvar lisp-mode-abbrev-table
This is the local abbrev table used in Lisp mode and Emacs Lisp mode.
@end defvar

5
lispref/anti.texi
View file

@ -143,6 +143,9 @@ an argument. Also, they do not discard text properties from the result.
This means that if you insert text with text properties into the minibuffer,
the minibuffer value really will contain text properties.
@item
Only the simple menu item format is supported (@pxref{Simple Menu Items}).
@item
You can still bind @code{x-resource-class} around a call to
@code{x-get-resource}, but it won't do anything special.
@ -225,7 +228,7 @@ special events. If you want to hold a party in Emacs, please let us
know.
@item
You can't do date arithmentic with @code{encode-time} any more.
You can't do date arithmetic with @code{encode-time} any more.
@item
The functions @code{command-execute} and @code{call-interactively} no

8
lispref/backups.texi
View file

@ -294,8 +294,7 @@ The standard definition of this function is as follows:
@smallexample
@group
(defun make-backup-file-name (file)
"Create the non-numeric backup file name for FILE.
@dots{}"
"Create the non-numeric backup file name for FILE@enddots{}"
(concat file "~"))
@end group
@end smallexample
@ -442,8 +441,7 @@ The standard definition of this function is as follows:
@group
(defun make-auto-save-file-name ()
"Return file name to use for auto-saves \
of current buffer.
@dots{}"
of current buffer@enddots{}"
(if buffer-file-name
@end group
@group
@ -550,7 +548,7 @@ buffer as of the last time it was 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 -1, that means auto-saving is temporarily shut off in this
If it is @minus{}1, that means auto-saving is temporarily shut off in this
buffer due to a substantial deletion. Explicitly saving the buffer
stores a positive value in this variable, thus reenabling auto-saving.
Turning auto-save mode off or on also alters this variable.

59
lispref/buffers.texi
View file

@ -130,11 +130,11 @@ string abridged):
@end example
@noindent
This function binds a local variable to the current buffer, and then
@code{save-current-buffer} records which buffer that was. Next,
@code{set-buffer} makes another buffer current. Finally,
This function binds a local variable to record the current buffer, and
then @code{save-current-buffer} arranges to make it current again.
Next, @code{set-buffer} makes the specified buffer current. Finally,
@code{insert-buffer-substring} copies the string from the original
current buffer to the new current buffer.
current buffer to the specified (and now current) buffer.
If the buffer appended to happens to be displayed in some window,
the next redisplay will show how its text has changed. Otherwise, you
@ -204,10 +204,10 @@ existing buffer.
@tindex save-current-buffer
@defmac save-current-buffer body...
The @code{save-current-buffer} macro saves the identity of the current
buffer, evaluates the @var{body} forms, and finally restores the buffer.
The return value is the value of the last form in @var{body}. The
current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
buffer, evaluates the @var{body} forms, and finally restores that buffer
as current. The return value is the value of the last form in
@var{body}. The current buffer is restored even in case of an abnormal
exit via @code{throw} or error (@pxref{Nonlocal Exits}).
If the buffer that used to be current has been killed by the time of
exit from @code{save-current-buffer}, then it is not made current again,
@ -383,10 +383,10 @@ buffer-file-name
@end example
It is risky to change this variable's value without doing various other
things. See the definition of @code{set-visited-file-name} in
@file{files.el}; some of the things done there, such as changing the
buffer name, are not strictly necessary, but others are essential to
avoid confusing Emacs.
things. Normally it is better to use @code{set-visited-file-name} (see
below); some of the things done there, such as changing the buffer name,
are not strictly necessary, but others are essential to avoid confusing
Emacs.
@end defvar
@defvar buffer-file-truename
@ -399,7 +399,7 @@ local, unaffected by @code{kill-local-variables}. @xref{Truenames}.
This buffer-local variable holds the file number and directory device
number of the file visited in the current buffer, or @code{nil} if no
file or a nonexistent file is visited. It is a permanent local,
unaffected by @code{kill-local-variables}. @xref{Truenames}.
unaffected by @code{kill-local-variables}.
The value is normally a list of the form @code{(@var{filenum}
@var{devnum})}. This pair of numbers uniquely identifies the file among
@ -443,9 +443,6 @@ the buffer as having no visited file.
@c Wordy to avoid overfull hbox. --rjc 16mar92
When the function @code{set-visited-file-name} is called interactively, it
prompts for @var{filename} in the minibuffer.
See also @code{clear-visited-file-modtime} and
@code{verify-visited-file-modtime} in @ref{Buffer Modification}.
@end deffn
@defvar list-buffers-directory
@ -669,19 +666,23 @@ buried (see @code{bury-buffer}, below). Several functions, notably
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
In addition to the fundamental Emacs buffer list, each frame has its
own version of the buffer list, in which the buffers that have been
selected in that frame come first, starting with the buffers most
recently selected @emph{in that frame}. (This order is recorded in
@var{frame}'s @code{buffer-list} frame parameter; see @ref{Window Frame
Parameters}.) The buffers that were never selected in @var{frame} come
afterward, ordered according to the fundamental Emacs buffer list.
@defun buffer-list &optional frame
This function returns a list of all buffers, including those whose names
begin with a space. The elements are actual buffers, not their names.
This function returns the buffer list, including all buffers, even those
whose names begin with a space. The elements are actual buffers, not
their names.
If @var{frame} is @code{nil}, all the buffers appear in order of most
recent selection, regardless of which frames they were selected in.
If @var{frame} is a frame, then the buffers that have been selected in
@var{frame} all come at the front of the list, ordered by most recent
selection in @var{frame}. (This order is recorded in @var{frame}'s
@code{buffer-list} frame parameter; see @ref{X Frame Parameters}.) The
buffers that were never selected in @var{frame} come afterward, ordered
according to most recent selection in other frames.
If @var{frame} is a frame, this returns @var{frame}'s buffer list. If
@var{frame} is @code{nil}, the fundamental Emacs buffer list is used:
all the buffers appear in order of most recent selection, regardless of
which frames they were selected in.
@example
@group
@ -735,7 +736,7 @@ buffer list that is not now visible in any window in a visible frame.
If the selected frame has a non-@code{nil} @code{buffer-predicate}
parameter, then @code{other-buffer} uses that predicate to decide which
buffers to consider. It calls the predicate once for each buffer, and
if the value is @code{nil}, that buffer is ignored. @xref{X Frame
if the value is @code{nil}, that buffer is ignored. @xref{Window Frame
Parameters}.
@c Emacs 19 feature
@ -946,7 +947,7 @@ themselves.
completely separate. They have different names, different values of
point, different narrowing, different markers and overlays (though
inserting or deleting text in either buffer relocates the markers and
overlays for both), different major modes, and different local
overlays for both), different major modes, and different buffer-local
variables.
An indirect buffer cannot visit a file, but its base buffer can. If

2
lispref/calendar.texi
View file

@ -2,7 +2,7 @@
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Calendar, Tips, Display, Top
@node Calendar, System Interface, Display, Top
@chapter Customizing the Calendar and Diary
There are many customizations that you can use to make the calendar and

290
lispref/commands.texi
View file

@ -385,7 +385,7 @@ one. No I/O.
@item s
Arbitrary text, read in the minibuffer and returned as a string
(@pxref{Text from Minibuffer}). Terminate the input with either
@key{LFD} or @key{RET}. (@kbd{C-q} may be used to include either of
@kbd{C-j} or @key{RET}. (@kbd{C-q} may be used to include either of
these characters in the input.) Prompt.
@item S
@ -401,7 +401,7 @@ Completion, Prompt.
@item x
A Lisp object, specified with its read syntax, terminated with a
@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
@kbd{C-j} or @key{RET}. The object is not evaluated. @xref{Object from
Minibuffer}. Prompt.
@item X
@ -482,7 +482,7 @@ expressions, autoload objects that are declared as interactive
(non-@code{nil} fourth argument to @code{autoload}), and some of the
primitive functions.
A symbol is @code{commandp} if its function definition is
A symbol satisfies @code{commandp} if its function definition satisfies
@code{commandp}.
Keys and keymaps are not commands. Rather, they are used to look up
@ -507,7 +507,7 @@ Otherwise, the command is added only if it uses the minibuffer to read
an argument. @xref{Command History}.
The argument @var{keys}, if given, specifies the sequence of events to
use if the command inquires which events were used to invoke it.
supply if the command inquires which events were used to invoke it.
@end defun
@defun command-execute command &optional record-flag keys
@ -527,7 +527,7 @@ definition is handled by loading the specified library and then
rechecking the definition of the symbol.
The argument @var{keys}, if given, specifies the sequence of events to
use if the command inquires which events were used to invoke it.
supply if the command inquires which events were used to invoke it.
@end defun
@deffn Command execute-extended-command prefix-argument
@ -571,21 +571,22 @@ no difference whether @code{call-interactively} was called from Lisp or
directly from the editor command loop.) If the containing function was
called by Lisp evaluation (or with @code{apply} or @code{funcall}), then
it was not called interactively.
@end defun
The most common use of @code{interactive-p} is for deciding whether to
The most common use of @code{interactive-p} is for deciding whether to
print an informative message. As a special exception,
@code{interactive-p} returns @code{nil} whenever a keyboard macro is
being run. This is to suppress the informative messages and speed
execution of the macro.
For example:
For example:
@example
@group
(defun foo ()
(interactive)
(and (interactive-p)
(message "foo")))
(when (interactive-p)
(message "foo")))
@result{} foo
@end group
@ -611,7 +612,20 @@ foobar
@result{} (nil t)
@end group
@end example
@end defun
The other way to do this sort of job is to make the command take an
argument @code{print-message} which should be non-@code{nil} in an
interactive call, and use the @code{interactive} spec to make sure it is
non-@code{nil}. Here's how:
@example
(defun foo (&optional print-message)
(interactive "p")
(when print-message
(message "foo")))
@end example
The numeric prefix argument, provided by @samp{p}, is never @code{nil}.
@node Command Loop Info
@comment node-name, next, previous, up
@ -687,12 +701,19 @@ if all those events were characters. @xref{Input Events}.
@end example
@end defun
@defun this-command-keys-vector
Like @code{this-command-keys}, except that it always returns
the events in a vector, so you do never need to deal with the complexities
of storing input events in a string (@pxref{Strings of Events}).
@end defun
@defvar last-nonmenu-event
This variable holds the last input event read as part of a key
sequence, not counting events resulting from mouse menus.
This variable holds the last input event read as part of a key sequence,
not counting events resulting from mouse menus.
One use of this variable is for telling @code{x-popup-menu} where to pop
up a menu.
up a menu. It is also used internally by @code{y-or-n-p}
(@pxref{Yes-or-No Queries}).
@end defvar
@defvar last-command-event
@ -765,10 +786,9 @@ A symbol
There are two kinds of input you can get from the keyboard: ordinary
keys, and function keys. Ordinary keys correspond to characters; the
events they generate are represented in Lisp as characters. In Emacs
versions 18 and earlier, characters were the only events. The event
type of a character event is the character itself (an integer);
see @ref{Classifying Events}.
events they generate are represented in Lisp as characters. The event
type of a character event is the character itself (an integer); see
@ref{Classifying Events}.
@cindex modifier bits (of input character)
@cindex basic code (of input character)
@ -778,9 +798,9 @@ An input character event consists of a @dfn{basic code} between 0 and
@table @asis
@item meta
The
@iftex
@tex
$2^{27}$
@end iftex
@end tex
@ifinfo
2**27
@end ifinfo
@ -789,9 +809,9 @@ typed with the meta key held down.
@item control
The
@iftex
@tex
$2^{26}$
@end iftex
@end tex
@ifinfo
2**26
@end ifinfo
@ -805,9 +825,9 @@ Thus, the code for @kbd{C-a} is just 1.
But if you type a control combination not in @sc{ASCII}, such as
@kbd{%} with the control key, the numeric value you get is the code
for @kbd{%} plus
@iftex
@tex
$2^{26}$
@end iftex
@end tex
@ifinfo
2**26
@end ifinfo
@ -816,9 +836,9 @@ control characters).
@item shift
The
@iftex
@tex
$2^{25}$
@end iftex
@end tex
@ifinfo
2**25
@end ifinfo
@ -829,9 +849,9 @@ For letters, the basic code itself indicates upper versus lower case;
for digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within the
@sc{ASCII} character set whenever possible, Emacs avoids using the
@iftex
@tex
$2^{25}$
@end iftex
@end tex
@ifinfo
2**25
@end ifinfo
@ -839,9 +859,9 @@ bit for those characters.
However, @sc{ASCII} provides no way to distinguish @kbd{C-A} from
@kbd{C-a}, so Emacs uses the
@iftex
@tex
$2^{25}$
@end iftex
@end tex
@ifinfo
2**25
@end ifinfo
@ -850,9 +870,9 @@ bit in @kbd{C-A} and not in
@item hyper
The
@iftex
@tex
$2^{24}$
@end iftex
@end tex
@ifinfo
2**24
@end ifinfo
@ -861,9 +881,9 @@ typed with the hyper key held down.
@item super
The
@iftex
@tex
$2^{23}$
@end iftex
@end tex
@ifinfo
2**23
@end ifinfo
@ -872,9 +892,9 @@ typed with the super key held down.
@item alt
The
@iftex
@tex
$2^{22}$
@end iftex
@end tex
@ifinfo
2**22
@end ifinfo
@ -1119,12 +1139,13 @@ events (@pxref{Click Events}), except that the @var{event-type} symbol
name contains the prefix @samp{down-}. The @samp{down-} prefix follows
modifier key prefixes such as @samp{C-} and @samp{M-}.
The function @code{read-key-sequence}, and therefore the Emacs command
loop as well, ignore any button-down events that don't have command
bindings. This means that you need not worry about defining button-down
events unless you want them to do something. The usual reason to define
a button-down event is so that you can track mouse motion (by reading
motion events) until the button is released. @xref{Motion Events}.
The function @code{read-key-sequence} ignores any button-down events
that don't have command bindings; therefore, the Emacs command loop
ignores them too. This means that you need not worry about defining
button-down events unless you want them to do something. The usual
reason to define a button-down event is so that you can track mouse
motion (by reading motion events) until the button is released.
@xref{Motion Events}.
@node Repeat Events
@subsection Repeat Events
@ -1220,8 +1241,7 @@ of the mouse without any button activity. Mouse motion events are
represented by lists that look like this:
@example
(mouse-movement
(@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
(mouse-movement (@var{window} @var{buffer-pos} (@var{x} . @var{y}) @var{timestamp}))
@end example
The second element of the list describes the current position of the
@ -1230,17 +1250,7 @@ mouse, just as in a click event (@pxref{Click Events}).
The special form @code{track-mouse} enables generation of motion events
within its body. Outside of @code{track-mouse} forms, Emacs does not
generate events for mere motion of the mouse, and these events do not
appear.
@defspec track-mouse body@dots{}
This special form executes @var{body}, with generation of mouse motion
events enabled. Typically @var{body} would use @code{read-event}
to read the motion events and modify the display accordingly.
When the user releases the button, that generates a click event.
Typically, @var{body} should return when it sees the click event, and
discard that event.
@end defspec
appear. @xref{Mouse Tracking}.
@node Focus Events
@subsection Focus Events
@ -1454,7 +1464,7 @@ to an event type which specifies all of them. For example,
a mouse button or motion event.
These two functions return the starting or ending position of a
mouse-button event. The position is a list of this form:
mouse-button event, as a list of this form:
@example
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
@ -1477,8 +1487,8 @@ event, the value is actually the starting position, which is the only
position such events have.
@end defun
These five functions take a position as described above, and return
various parts of it.
These five functions take a position list as described above, and
return various parts of it.
@defun posn-window position
Return the window that @var{position} is in.
@ -1503,6 +1513,8 @@ a cons cell @code{(@var{col} . @var{row})}. These are computed from the
Return the timestamp in @var{position}.
@end defun
These functions are useful for decoding scroll bar events.
@defun scroll-bar-event-ratio event
This function returns the fractional vertical position of a scroll bar
event within the scroll bar. The value is a cons cell
@ -1537,28 +1549,59 @@ of a pair of x and y coordinates.
string as containing text characters---the same kind of characters found
in buffers or files. Occasionally Lisp programs use strings that
conceptually contain keyboard characters; for example, they may be key
sequences or keyboard macro definitions. There are special rules for
how to put keyboard characters into a string, because they are not
limited to the range of 0 to 255 as text characters are.
sequences or keyboard macro definitions. However, storing keyboard
characters in a string is a complex matter, for reasons of historical
compatibility, and it is not always possible.
A keyboard character typed using the @key{META} key is called a
@dfn{meta character}. The numeric code for such an event includes the
@iftex
We recommend that new programs avoid dealing with these complexities
by not storing keyboard events in strings. Here is how to do that:
@itemize @bullet
@item
Use vectors instead of strings for key sequences, when you plan to use
them for anything other than as arguments @code{lookup-key} and
@code{define-key}. For example, you can use
@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
@code{this-command-keys-vector} instead of @code{this-command-keys}.
@item
Use vectors to write key sequence constants containing meta characters,
even when passing them directly to @code{define-key}.
@item
When you have to look at the contents of a key sequence that might be a
string, use @code{listify-key-sequence} (@pxref{Event Input Misc})
first, to convert it to a list.
@end itemize
The complexities stem from the modifier bits that keyboard input
characters can include. Aside from the Meta modifier, none of these
modifier bits can be included in a string, and the Meta modifier is
allowed only in special cases.
The earliest GNU Emacs versions represented meta characters as codes
in the range of 128 to 255. At that time, the basic character codes
ranged from 0 to 127, so all keyboard character codes did fit in a
string. Many Lisp programs used @samp{\M-} in string constants to stand
for meta characters, especially in arguments to @code{define-key} and
similar functions, and key sequences and sequences of events were always
represented as strings.
When we added support for larger basic character codes beyond 127, and
additional modifier bits, we had to change the representation of meta
characters. Now the flag that represents the Meta modifier in a
character is
@tex
$2^{27}$
@end iftex
@end tex
@ifinfo
2**27
@end ifinfo
bit; it does not even come close to fitting in a string. However,
earlier Emacs versions used a different representation for these
characters, which gave them codes in the range of 128 to 255. That did
fit in a string, and many Lisp programs contain string constants that
use @samp{\M-} to express meta characters, especially as the argument to
@code{define-key} and similar functions.
and such numbers cannot be included in a string.
We provide backward compatibility to run those programs using special
rules for how to put a keyboard character event in a string. Here are
the rules:
To support programs with @samp{\M-} in string constants, there are
special rules for including certain meta characters in a string.
Here are the rules for interpreting keyboard
@itemize @bullet
@item
@ -1567,36 +1610,39 @@ in the string unchanged.
@item
The meta variants of those characters, with codes in the range of
@iftex
@tex
$2^{27}$
@end iftex
@end tex
@ifinfo
2**27
@end ifinfo
to
@iftex
@tex
$2^{27} + 127$,
@end iftex
@end tex
@ifinfo
2**27+127,
@end ifinfo
can also go in the string, but you must change their
numeric values. You must set the
@iftex
@tex
$2^{7}$
@end iftex
@end tex
@ifinfo
2**7
@end ifinfo
bit instead of the
@iftex
@tex
$2^{27}$
@end iftex
@end tex
@ifinfo
2**27
@end ifinfo
bit,
resulting in a value between 128 and 255.
bit, resulting in a value between 128 and 255. Only a unibyte string
can include these codes.
@item
Non-@sc{ASCII} characters above 256 can be included in a multibyte string.
@item
Other keyboard character events cannot fit in a string. This includes
@ -1613,31 +1659,18 @@ modify the corresponding keyboard event to put it in the string. Thus,
meta events in strings work consistently regardless of how they get into
the strings.
The reason we changed the representation of meta characters as
keyboard events is to make room for basic character codes beyond 127,
and support meta variants of such larger character codes.
New programs can avoid dealing with these special compatibility rules
by using vectors instead of strings for key sequences when there is any
possibility that they might contain meta characters, and by using
@code{listify-key-sequence} to access a string of events.
@defun listify-key-sequence key
This function converts the string or vector @var{key} to a list of
events, which you can put in @code{unread-command-events}. Converting a
vector is simple, but converting a string is tricky because of the
special representation used for meta characters in a string.
@end defun
However, most programs would do well to avoid these issues by
following the recommendations at the beginning of this section.
@node Reading Input
@section Reading Input
The editor command loop reads keyboard input using the function
The editor command loop reads key sequences using the function
@code{read-key-sequence}, which uses @code{read-event}. These and other
functions for keyboard input are also available for use in Lisp
programs. See also @code{momentary-string-display} in @ref{Temporary
Displays}, and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input},
for functions and variables for controlling terminal input modes and
functions for event input are also available for use in Lisp programs.
See also @code{momentary-string-display} in @ref{Temporary Displays},
and @code{sit-for} in @ref{Waiting}. @xref{Terminal Input}, for
functions and variables for controlling terminal input modes and
debugging terminal input. @xref{Translating Input}, for features you
can use for translating or modifying input events while reading them.
@ -1671,10 +1704,6 @@ Otherwise, it returns a vector, since a vector can hold all kinds of
events---characters, symbols, and lists. The elements of the string or
vector are the events in the key sequence.
The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
typed while reading with this function works like any other character,
and does not set @code{quit-flag}. @xref{Quitting}.
The argument @var{prompt} is either a string to be displayed in the echo
area as a prompt, or @code{nil}, meaning not to display a prompt.
@ -1692,6 +1721,16 @@ and the user types @kbd{C-x C-f}.
@result{} "^X^F"
@end group
@end example
The function @code{read-key-sequence} suppresses quitting: @kbd{C-g}
typed while reading with this function works like any other character,
and does not set @code{quit-flag}. @xref{Quitting}.
@end defun
@defun read-key-sequence-vector prompt
This is like @code{read-key-sequence} except that it always
returns the key sequence as a vector, never as a string.
@xref{Strings of Events}.
@end defun
@cindex upper case key sequence
@ -1819,9 +1858,9 @@ The command @code{quoted-insert} uses this function.
@cindex control characters, reading
@cindex nonprinting characters, reading
This function is like @code{read-char}, except that if the first
character read is an octal digit (0-7), it reads up to two more octal digits
(but stopping if a non-octal digit is found) and returns the
character represented by those digits in octal.
character read is an octal digit (0-7), it reads any number of octal
digits (but stopping if a non-octal digit is found), and returns the
character represented by that numeric character code.
Quitting is suppressed when the first character is read, so that the
user can enter a @kbd{C-g}. @xref{Quitting}.
@ -1882,6 +1921,11 @@ Normally you add events to the front of this list, so that the events
most recently unread will be reread first.
@end defvar
@defun listify-key-sequence key
This function converts the string or vector @var{key} to a list of
individual events, which you can put in @code{unread-command-events}.
@end defun
@defvar unread-command-char
This variable holds a character to be read as command input.
A value of -1 means ``empty''.
@ -1900,6 +1944,7 @@ may return @code{t} when no input is available.
@end defun
@defvar last-input-event
@defvarx last-input-char
This variable records the last terminal input event read, whether
as part of a command or explicitly by a Lisp program.
@ -1919,7 +1964,6 @@ this expression) remains the value of @code{last-command-event}.
@end group
@end example
@vindex last-input-char
The alias @code{last-input-char} exists for compatibility with
Emacs version 18.
@end defvar
@ -2049,9 +2093,9 @@ innermost active command loop.
does not cause a quit; it acts as an ordinary input character. In the
simplest case, you cannot tell the difference, because @kbd{C-g}
normally runs the command @code{keyboard-quit}, whose effect is to quit.
However, when @kbd{C-g} follows a prefix key, the result is an undefined
key. The effect is to cancel the prefix key as well as any prefix
argument.
However, when @kbd{C-g} follows a prefix key, they combine to form an
undefined key. The effect is to cancel the prefix key as well as any
prefix argument.
In the minibuffer, @kbd{C-g} has a different definition: it aborts out
of the minibuffer. This means, in effect, that it exits the minibuffer
@ -2104,15 +2148,15 @@ normal quitting is permitted after the first character of input.
@example
(defun read-quoted-char (&optional prompt)
"@dots{}@var{documentation}@dots{}"
(let ((count 0) (code 0) char)
(while (< count 3)
(let ((inhibit-quit (zerop count))
(help-form nil))
(and prompt (message "%s-" prompt))
(setq char (read-char))
(if inhibit-quit (setq quit-flag nil)))
@dots{})
(logand 255 code)))
(let ((message-log-max nil) done (first t) (code 0) char)
(while (not done)
(let ((inhibit-quit first)
@dots{})
(and prompt (message "%s-" prompt))
(setq char (read-event))
(if inhibit-quit (setq quit-flag nil)))
@r{@dots{}set the variable @code{code}@dots{}})
code))
@end example
@defvar quit-flag

99
lispref/compile.texi
View file

@ -3,12 +3,12 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
@node Byte Compilation, Debugging, Loading, Top
@node Byte Compilation, Advising, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation
GNU Emacs Lisp has a @dfn{compiler} that translates functions written
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
@ -21,15 +21,17 @@ transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true. In
particular, if you compile a program with Emacs 19.29, the compiled
code does not run in earlier versions.
by recent earlier versions of Emacs, but the reverse is not true. A
major incompatible change was introduced in Emacs version 19.29, and
files compiled with versions since that one will definitely not run
in earlier versions unless you specify a special option.
@iftex
@xref{Docs and Compilation}.
@end iftex
Files compiled in versions before 19.29 may not work in 19.29 if they
contain character constants with modifier bits, because the bits were
renumbered in Emacs 19.29.
In addition, the modifier bits in keyboard characters were renumbered in
Emacs 19.29; as a result, files compiled in versions before 19.29 will
not work in subsequent versions if they contain character constants with
modifier bits.
@xref{Compilation Errors}, for how to investigate errors occurring in
byte compilation.
@ -99,9 +101,10 @@ 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 byte-compiling code that uses macros. 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}.
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}.
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
@ -200,10 +203,9 @@ This function recompiles every @samp{.el} file in @var{directory} 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, then
@var{flag} says what to do. If it is @code{nil}, these files are
ignored. If it is non-@code{nil}, the user is asked whether to compile
each such file.
When a @samp{.el} file has no corresponding @samp{.elc} file, @var{flag}
says what to do. If it is @code{nil}, these files are ignored. If it
is non-@code{nil}, the user is asked whether to compile each such file.
The returned value of this command is unpredictable.
@end deffn
@ -225,12 +227,13 @@ status code.
@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
this function yourself---only the byte compiler knows how to generate
valid calls to this function.
In newer Emacs versions (19 and up), byte-code is usually executed as
part of a byte-code function object, and only rarely due to an explicit
call to @code{byte-code}.
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
@ -269,13 +272,14 @@ 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.
Byte-compiled files made with Emacs 19.29 will not load into older
versions because the older versions don't support this feature. You can
turn off this feature by setting @code{byte-compile-dynamic-docstrings}
to @code{nil}. Once this is done, you can compile files that will load
into older Emacs versions. You can do this globally, or for one source
file by specifying a file-local binding for the variable. Here's one
way to do that:
Byte-compiled files made with recent versions of Emacs (since 19.29)
will not load into older versions because the older versions don't
support this feature. You can turn off this feature at compile time by
setting @code{byte-compile-dynamic-docstrings} to @code{nil}; then you
can compile files that will load into older Emacs versions. 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;-*-
@ -292,7 +296,9 @@ that are set up for dynamic loading of documentation strings.
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 best not to use these constructs in Lisp source files.
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
@ -309,10 +315,10 @@ 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 commands, provided that using one of them does not imply
you will soon (or ever) 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.
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:
@ -323,19 +329,21 @@ 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 get nonsense
then trying to load any function not already loaded will yield nonsense
results.
@end itemize
If you compile a new version of the file, the best thing to do is
immediately load the new compiled file. That will prevent any future
problems.
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, like this:
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;-*-
@ -363,9 +371,8 @@ 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}. Using @code{require} is
preferable if there is a substantial amount of code to be executed in
this way.
and referring to that file with @code{require}. That method is
preferable when @var{body} is large.
@end defspec
@defspec eval-when-compile body
@ -375,10 +382,10 @@ 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.
At top level, this 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.
@strong{Common Lisp Note:} At top level, this 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 Byte-Code Objects
@ -395,12 +402,8 @@ 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{[}.
In Emacs version 18, there was no byte-code function object data type;
compiled functions used the function @code{byte-code} to run the byte
code.
A byte-code function object must have at least four elements; there is
no maximum number, but only the first six elements are actually used.
no maximum number, but only the first six elements have any normal use.
They are:
@table @var

46
lispref/control.texi
View file

@ -460,8 +460,8 @@ first argument of @code{while}, as shown here:
@noindent
This moves forward one line and continues moving by lines until it
reaches an empty. It is unusual in that the @code{while} has no body,
just the end test (which also does the real work of moving point).
reaches an empty line. It is peculiar in that the @code{while} has no
body, just the end test (which also does the real work of moving point).
@end defspec
@node Nonlocal Exits
@ -718,15 +718,13 @@ These examples show typical uses of @code{error}:
@example
@group
(error "You have committed an error.
Try something else.")
@error{} You have committed an error.
Try something else.
(error "That is an error -- try something else")
@error{} That is an error -- try something else
@end group
@group
(error "You have committed %d errors." 10)
@error{} You have committed 10 errors.
(error "You have committed %d errors" 10)
@error{} You have committed 10 errors
@end group
@end example
@ -752,7 +750,7 @@ errors.
The number and significance of the objects in @var{data} depends on
@var{error-symbol}. For example, with a @code{wrong-type-arg} error,
there are two objects in the list: a predicate that describes the type
there should be two objects in the list: a predicate that describes the type
that was expected, and the object that failed to fit that type.
@xref{Error Symbols}, for a description of error symbols.
@ -772,8 +770,8 @@ it could sometimes return).
@end group
@group
(signal 'no-such-error '("My unknown error condition."))
@error{} peculiar error: "My unknown error condition."
(signal 'no-such-error '("My unknown error condition"))
@error{} peculiar error: "My unknown error condition"
@end group
@end smallexample
@end defun
@ -876,8 +874,8 @@ execution at the point of the error, nor can it examine variable
bindings that were made within the protected form. All it can do is
clean up and proceed.
@code{condition-case} is often used to trap errors that are
predictable, such as failure to open a file in a call to
The @code{condition-case} construct is often used to trap errors that
are predictable, such as failure to open a file in a call to
@code{insert-file-contents}. It is also used to trap errors that are
totally unpredictable, such as when the program evaluates an expression
read from the user.
@ -1159,7 +1157,12 @@ You might think that we could just as well write @code{(kill-buffer
However, the way shown above is safer, if @var{body} happens to get an
error after switching to a different buffer! (Alternatively, you could
write another @code{save-excursion} around the body, to ensure that the
temporary buffer becomes current in time to kill it.)
temporary buffer becomes current again in time to kill it.)
Emacs includes a standard macro called @code{with-temp-buffer} which
expands into more or less the code shown above (@pxref{Current Buffer}).
Several of the macros defined in this manual use @code{unwind-protect}
in this way.
@findex ftp-login
Here is an actual example taken from the file @file{ftp.el}. It
@ -1188,18 +1191,3 @@ quit, and the quit happens immediately after the function
@code{ftp-setup-buffer} returns but before the variable @code{process} is
set, the process will not be killed. There is no easy way to fix this bug,
but at least it is very unlikely.
Here is another example which uses @code{unwind-protect} to make sure
to kill a temporary buffer. In this example, the value returned by
@code{unwind-protect} is used.
@smallexample
(defun shell-command-string (cmd)
"Return the output of the shell command CMD, as a string."
(save-excursion
(set-buffer (generate-new-buffer " OS*cmd"))
(shell-command cmd t)
(unwind-protect
(buffer-string)
(kill-buffer (current-buffer)))))
@end smallexample

344
lispref/customize.texi
View file

@ -6,30 +6,29 @@
@node Customization, Loading, Macros, Top
@chapter Writing Customization Definitions
This chapter describes how to declare customization groups, variables,
and faces. We use the term @dfn{customization item} to include all
three of those. This has few examples, but please look at the file
@file{cus-edit.el}, which contains many declarations you can learn from.
This chapter describes how to declare user options for customization,
and also customization groups for classifying them. We use the term
@dfn{customization item} to include both kinds of customization
definitions---as well as face definitions (@pxref{Defining Faces}).
@menu
* Common Keywords::
* Group Definitions::
* Variable Definitions::
* Face Definitions::
* Customization Types::
@end menu
@node Common Keywords
@section Common Keywords for All Kinds of Items
All three kinds of customization declarations (for groups, variables,
and faces) accept keyword arguments for specifying various information.
This section describes some keywords that apply to all three.
All kinds of customization declarations (for variables and groups, and
for faces) accept keyword arguments for specifying various information.
This section describes some keywords that apply to all kinds.
All of these keywords, except @code{:tag}, can be used more than once in
a given item. Each use of the keyword has an independent effect. The
keyword @code{:tag} is an exception because any given item can only
display one name item.
All of these keywords, except @code{:tag}, can be used more than once
in a given item. Each use of the keyword has an independent effect.
The keyword @code{:tag} is an exception because any given item can only
display one name.
@table @code
@item :group @var{group}
@ -49,6 +48,10 @@ other documentation.
There are three alternatives you can use for @var{link-data}:
@table @code
@item :tag @var{name}
Use @var{name}, a string, instead of the item's name, to label the item
in customization menus and buffers.
@item (custom-manual @var{info-node})
Link to an Info node; @var{info-node} is a string which specifies the
node name, as in @code{"(emacs)Top"}. The link appears as
@ -59,8 +62,8 @@ Like @code{custom-manual} except that the link appears
in the customization buffer with the Info node name.
@item (url-link @var{url})
Link to a web page; @var{url} is a string which specifies the URL. The
link appears in the customization buffer as @var{url}.
Link to a web page; @var{url} is a string which specifies the @sc{url}.
The link appears in the customization buffer as @var{url}.
@end table
You can specify the text to use in the customization buffer by adding
@ -84,30 +87,27 @@ feature. This is done by calling @code{require}.
The most common reason to use @code{:require} is when a variable enables
a feature such as a minor mode, and just setting the variable won't have
any effect unless the code which implements the mode is loaded.
@item :tag @var{name}
Use @var{name}, a string, instead of the item's name, to label the item
in customization menus and buffers.
@end table
@node Group Definitions
@section Defining Custom Groups
Each Emacs Lisp package should have one main customization group which
Each Emacs Lisp package should have one main customization group which
contains all the options, faces and other groups in the package. If the
package has a small number of options and faces, use just one group and
put everything in it. When there are more than twelve or so options and
faces, then you should structure them into subgroups, and put the
subgroups under the package's main customization group. It is ok to
have some of the options and faces in the package's main group alongside
subgroups under the package's main customization group. It is OK to
put some of the options and faces in the package's main group alongside
the subgroups.
The package's main or only group should be a member of one or more of
the standard customization groups. Type press @kbd{C-h p} to display a
list of finder keywords; them choose some of them add your group to each
of them, using the @code{:group} keyword.
The package's main or only group should be a member of one or more of
the standard customization groups. (To display the full list of them,
use @kbd{M-x customize}.) Choose one or more of them (but not too
many), and add your group to each of them using the @code{:group}
keyword.
The way to declare new customization groups is with @code{defgroup}.
The way to declare new customization groups is with @code{defgroup}.
@tindex defgroup
@defmac defgroup group members doc [keyword value]...
@ -116,9 +116,9 @@ Do not quote the symbol @var{group}. The argument @var{doc} specifies
the documentation string for the group.
The arguments @var{members} can be an alist whose elements specify
members of the group; however, normally @var{members} is @code{nil}, and
you specify the group's members by using the @code{:group} keyword when
defining those members.
customization items to be members of the group; however, normally
@var{members} is @code{nil}, and you specify the group's members by
using the @code{:group} keyword when defining those members.
@ignore
@code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
@ -139,40 +139,40 @@ One group can have any number of prefixes.
@end table
@end defmac
The @code{:prefix} feature is currently turned off, which means that
@code{:prefix} currently has no effect. We did this because we found
that discarding the specified prefixes often led to confusing names for
options. This happened because the people who wrote the @code{defgroup}
definitions for various groups added @code{:prefix} keywords whenever
they make logical sense---that is, whenever they say that there was a
common prefix for the option names in a library.
The prefix-discarding feature is currently turned off, which means
that @code{:prefix} currently has no effect. We did this because we
found that discarding the specified prefixes often led to confusing
names for options. This happened because the people who wrote the
@code{defgroup} definitions for various groups added @code{:prefix}
keywords whenever they make logical sense---that is, whenever the
variables in the library have a common prefix.
In order to obtain good results with @code{:prefix}, it is necessary to
check the specific effects of discarding a particular prefix, given the
specific items in a group and their names and documentation. If the
resulting text is not clear, then @code{:prefix} should not be used in
that case.
In order to obtain good results with @code{:prefix}, it would be
necessary to check the specific effects of discarding a particular
prefix, given the specific items in a group and their names and
documentation. If the resulting text is not clear, then @code{:prefix}
should not be used in that case.
It should be possible to recheck all the customization groups, delete
It should be possible to recheck all the customization groups, delete
the @code{:prefix} specifications which give unclear results, and then
turn this feature back on, if someone would like to do the work.
@node Variable Definitions
@section Defining Customization Variables
Use @code{defcustom} to declare user editable variables.
Use @code{defcustom} to declare user-editable variables.
@tindex defcustom
@defmac defcustom option value doc [keyword value]...
Declare @var{option} as a customizable user option variable that
defaults to @var{value}. Do not quote @var{option}. @var{value} should
be an expression to compute the value; it will be be evaluated on more
@defmac defcustom option default doc [keyword value]...
Declare @var{option} as a customizable user option variable. Do not
quote @var{option}. The argument @var{doc} specifies the documentation
string for the variable.
If @var{option} is void, @code{defcustom} initializes it to
@var{default}. @var{default} should be an expression to compute the
value; be careful in writing it, because it can be be evaluated on more
than one occasion.
If @var{option} is void, @code{defcustom} initializes it to @var{value}.
The argument @var{doc} specifies the documentation string for the variable.
The following additional keywords are defined:
@table @code
@ -185,11 +185,10 @@ values are legitimate, and how to display the value.
Specify @var{list} as the list of reasonable values for use in this
option.
Currently this is meaningful only when type is @code{hook}. The
elements of @var{list} are functions that you might likely want to use
as elements of the hook value. The user is not actually restricted to
using only these functions, but they are offered as convenient
alternatives.
Currently this is meaningful only when the type is @code{hook}. In that
case, the elements of @var{list} should be functions that are useful as
elements of the hook value. The user is not restricted to using only
these functions, but they are offered as convenient alternatives.
@item :version @var{version}
This option specifies that the variable's default value was changed in
@ -226,36 +225,48 @@ this way:
@table @code
@item custom-initialize-set
Use the variable's @code{:set} function to initialize the variable. Do
not reinitialize it if it is already non-void. This is the default
Use the variable's @code{:set} function to initialize the variable, but
do not reinitialize it if it is already non-void. This is the default
@code{:initialize} function.
@item custom-initialize-default
Always use @code{set-default} to initialize the variable, even if some
other @code{:set} function has been specified.
Like @code{custom-initialize-set}, but use the function
@code{set-default} to set the variable, instead of the variable's
@code{:set} function. This is the usual choice for a variable whose
@code{:set} function enables or disables a minor mode; with this choice,
defining the variable will not call the minor mode function, but
customizing the variable will do so.
@item custom-initialize-reset
Even if the variable is already non-void, reset it by calling the
@code{:set} function using the current value (returned by the
@code{:get} method).
Always use the @code{:set} function to initialize the variable. If the
variable is already non-void, reset it by calling the @code{:set}
function using the current value (returned by the @code{:get} method).
@item custom-initialize-changed
Like @code{custom-initialize-reset}, except use @code{set-default}
(rather than the @code{:set} function) to initialize the variable if it
is not bound and has not been set already.
Use the @code{:set} function to initialize the variable, if it is
already set or has been customized; otherwise, just use
@code{set-default}.
@end table
@item :require @var{feature}
If the user saves a customized value for this item, them Emacs should do
@code{(require @var{feature})} after installing the saved value.
The place to use this feature is for an option that turns on the
operation of a certain feature. Assuming that the package is coded to
check the value of the option, you still need to arrange for the package
to be loaded. That is what @code{:require} is for.
@end table
@end defmac
The @code{:require} option is useful for an option that turns on the
operation of a certain feature. Assuming that the package is coded to
check the value of the option, you still need to arrange for the package
to be loaded. You can do that with @code{:require}. @xref{Common
Keywords}. Here is an example, from the library @file{paren.el}:
@example
(defcustom show-paren-mode nil
"Toggle Show Paren mode@enddots{}"
:set (lambda (symbol value)
(show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
:type 'boolean
:group 'paren-showing
:require 'paren)
@end example
@ignore
Use @code{custom-add-option} to specify that a specific function is
useful as an member of a hook.
@ -274,103 +285,37 @@ and @code{saved-value} to record the value saved by the user with the
customization buffer. The @code{saved-value} property is actually a
list whose car is an expression which evaluates to the value.
@node Face Definitions
@section Defining Faces
Faces are declared with @code{defface}.
@tindex defface
@defmac defface face spec doc [keyword value]...
Declare @var{face} as a customizable face that defaults according to
@var{spec}. Do not quote the symbol @var{face}.
@var{doc} is the face documentation.
@var{spec} should be an alist whose elements have the form
@code{(@var{display} @var{atts})} (see below). When @code{defface}
executes, it defines the face according to @var{spec}, then uses any
customizations saved in the @file{.emacs} file to override that
specification.
In each element of @var{spec}, @var{atts} is a list of face attributes
and their values. The possible attributes are defined in the variable
@code{custom-face-attributes}.
The @var{display} part of an element of @var{spec} determines which
frames the element applies to. If more than one element of @var{spec}
matches a given frame, the first matching element is the only one used
for that frame.
If @var{display} is @code{t} in a @var{spec} element, that element
matches all frames. (This means that any subsequent elements of
@var{spec} are never used.)
Alternatively, @var{display} can be an alist whose elements have the
form @code{(@var{characteristic} @var{value}@dots{})}. Here
@var{characteristic} specifies a way of classifying frames, and the
@var{value}s are possible classifications which @var{display} should
apply to. Here are the possible values of @var{characteristic}:
@table @code
@item type
The kind of window system the frame uses---either @code{x}, @code{pc}
(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
@code{tty}.
@item class
What kinds of colors the frame supports---either @code{color},
@code{grayscale}, or @code{mono}.
@item background
The kind of background--- either @code{light} or @code{dark}.
@end table
If an element of @var{display} specifies more than one
@var{value} for a given @var{characteristic}, any of those values
is acceptable. If an element of @var{display} has elements for
more than one @var{characteristic}, then @var{each} characteristic
of the frame must match one of the values specified for it.
@end defmac
Internally, @code{defface} uses the symbol property
@code{face-defface-spec} to record the face attributes specified in
@code{defface}, @code{saved-face} for the attributes saved by the user
with the customization buffer, and @code{face-documentation} for the
documentation string.
@node Customization Types
@section Customization Types
When you define a user option with @code{defcustom}, you must specify
its @dfn{customization type}. That is a Lisp object which indictaes (1)
its @dfn{customization type}. That is a Lisp object which describes (1)
which values are legitimate and (2) how to display the value in the
customization buffer for editing.
You specify the customization type in @code{defcustom} with the
@code{:type} keyword. The argument of @code{:type} is evaluated; since
types that vary at run time are rarely useful, normally it is a quoted
types that vary at run time are rarely useful, normally you use a quoted
constant. For example:
@example
(defcustom diff-command "diff"
"*The command to use to run diff."
:type 'string
:type '(string)
:group 'diff)
@end example
In general, a customization type appears is a list whose first element
is a symbol, one of the customization type names defined in the
following sections. After this symbol come a number of arguments,
depending on the symbol. Some of the type symbols do not use any
arguments; those are called @dfn{simple types}.
In general, a customization type is a list whose first element is a
symbol, one of the customization type names defined in the following
sections. After this symbol come a number of arguments, depending on
the symbol. Between the type symbol and its arguments, you can
optionally write keyword-value pairs (@pxref{Type Keywords}).
In between the type symbol and its arguments, you can optionally
write keyword-value pairs. @xref{Type Keywords}.
For a simple type, if you do not use any keyword-value pairs, you can
omit the parentheses around the type symbol. The above example does
this, using just @code{string} as the customization type.
But @code{(string)} would mean the same thing.
Some of the type symbols do not use any arguments; those are called
@dfn{simple types}. For a simple type, if you do not use any
keyword-value pairs, you can omit the parentheses around the type
symbol. For example just @code{string} as a customization type is
equivalent to @code{(string)}.
@menu
* Simple Types::
@ -400,10 +345,12 @@ customization buffer.
@item string
The value must be a string, and the customization buffer shows just the
contents, with no @samp{"} characters or quoting with @samp{\}.
contents, with no delimiting @samp{"} characters and no quoting with
@samp{\}.
@item regexp
The value must be a string which is a valid regular expression.
Like @code{string} except that the string must be a valid regular
expression.
@item character
The value must be a character code. A character code is actually an
@ -435,15 +382,19 @@ The value must be a variable name, and you can do completion with
@kbd{M-@key{TAB}}.
@item boolean
The value is boolean---either @code{nil} or @code{t}.
The value is boolean---either @code{nil} or @code{t}. Note that by
using @code{choice} and @code{const} together (see the next section),
you can specify that the value must be @code{nil} or @code{t}, but also
specify the text to describe each value in a way that fits the specific
meaning of the alternative.
@end table
@node Composite Types
@subsection Composite Types
When none of the simple types is appropriate, you can use composite
types, which build from simple types. Here are several ways of doing
that:
types, which build new types from other types. Here are several ways of
doing that:
@table @code
@item (restricted-sexp :match-alternatives @var{criteria})
@ -459,7 +410,7 @@ are acceptable.
@item
A quoted constant---that is, @code{'@var{object}}. This means that
@var{object} is an acceptable value.
@var{object} itself is an acceptable value.
@end itemize
For example,
@ -480,7 +431,7 @@ its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
In the customization buffeer, the @sc{car} and the @sc{cdr} are
In the customization buffer, the @sc{car} and the @sc{cdr} are
displayed and edited separately, each according to the type
that you specify for it.
@ -493,7 +444,7 @@ For example, @code{(list integer string function)} describes a list of
three elements; the first element must be an integer, the second a
string, and the third a function.
In the customization buffeer, the each element is displayed and edited
In the customization buffer, the each element is displayed and edited
separately, according to the type specified for it.
@item (vector @var{element-types}@dots{})
@ -523,22 +474,37 @@ verbatim, you might write the customization type this way,
@noindent
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
In any alternative for which @code{nil} is not a valid value, other than
a @code{const}, you should specify a valid default for that alternative
using the @code{:value} keyword. @xref{Type Keywords}.
@item (const @var{value})
The value must be @var{value}---nothing else is allowed.
The main use of @code{const} is inside of @code{choice}. For example,
@code{(choice integer (const nil))} allows either an integer or
@code{nil}. @code{:tag} is often used with @code{const}.
@code{nil}.
@code{:tag} is often used with @code{const}, inside of @code{choice}.
For example,
@smallexample
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(const :tag "Ask" foo))
@end smallexample
@item (function-item @var{function})
Like @code{const}, but used for values which are functions. This
displays the documentation string of the function @var{function}
as well as its name.
displays the documentation string as well as the function name.
The documentation string is either the one you specify with
@code{:doc}, or @var{function}'s own documentation string.
@item (variable-item @var{variable})
Like @code{const}, but used for values which are variable names. This
displays the documentation string of the variable @var{variable} as well
as its name.
displays the documentation string as well as the variable name. The
documentation string is either the one you specify with @code{:doc}, or
@var{variable}'s own documentation string.
@item (set @var{elements}@dots{})
The value must be a list and each element of the list must be one of the
@ -611,20 +577,22 @@ meanings:
@table @code
@item :value @var{default}
This is used for a type that appears as an alternative inside of
@code{:choice}; it specifies the default value to use, at first, if and
@code{choice}; it specifies the default value to use, at first, if and
when the user selects this alternative with the menu in the
customization buffer.
Of course, if the actual value of the option fits this alternative, it
will appear showing the actual value, not @var{default}.
If @code{nil} is not a valid value for the alternative, then it is
essential to specify a valid default with @code{:value}.
@item :format @var{format-string}
This string will be inserted in the buffer to represent the value
corresponding to the type. The following @samp{%} escapes are available
for use in @var{format-string}:
@table @samp
@ignore
@item %[@var{button}%]
Display the text @var{button} marked as a button. The @code{:action}
attribute specifies what the button will do if the user invokes it;
@ -632,8 +600,7 @@ its value is a function which takes two arguments---the widget which
the button appears in, and the event.
There is no way to specify two different buttons with different
actions; but perhaps there is no need for one.
@end ignore
actions.
@item %@{@var{sample}%@}
Show @var{sample} in a special face specified by @code{:sample-face}.
@ -658,11 +625,15 @@ keyword.
Display a literal @samp{%}.
@end table
@item :button-face @var{face}
Use face @var{face} for text displayed with @samp{%[@dots{}%]}.
@item :action @var{action}
Perform @var{action} if the user clicks on a button.
@item :button-prefix
@itemx :button-suffix
@item :button-face @var{face}
Use the face @var{face} (a face name or a list of face names) for button
text displayed with @samp{%[@dots{}%]}.
@item :button-prefix @var{prefix}
@itemx :button-suffix @var{suffix}
These specify the text to display before and after a button.
Each can be:
@ -677,11 +648,19 @@ The string is inserted literally.
The symbol's value is used.
@end table
@item :doc @var{doc}
Use @var{doc} as the documentation string for this item.
@item :tag @var{tag}
Use @var{tag} (a string) as the tag for this item.
Use @var{tag} (a string) as the tag for the value (or part of the value)
that corresponds to this type.
@item :doc @var{doc}
Use @var{doc} as the documentation string for this value (or part of the
value) that corresponds to this type. In order for this to work, you
must specify a value for @code{:format}, and use @samp{%d} or @samp{%h}
in that value.
The usual reason to specify a documentation string for a type is to
provide more information about the meanings of alternatives inside a
@code{:choice} type or the parts of some other composite type.
@item :help-echo @var{motion-doc}
When you move to this item with @code{widget-forward} or
@ -689,9 +668,10 @@ When you move to this item with @code{widget-forward} or
in the echo area.
@item :match @var{function}
Specify how to decide whether a value matches the type. @var{function}
should be a function that accepts two arguments, a widget and a value;
it should return non-@code{nil} if the value is acceptable.
Specify how to decide whether a value matches the type. The
corresponding value, @var{function}, should be a function that accepts
two arguments, a widget and a value; it should return non-@code{nil} if
the value is acceptable.
@ignore
@item :indent @var{columns}

86
lispref/debugging.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Byte Compilation, Top
@node Debugging, Read and Print, Advising, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
@ -104,14 +104,18 @@ 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.
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 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 catch the error before the
debugger gets a chance.
words, @code{condition-case} gets a chance to handle the error before
the debugger gets a chance.
If you set @code{debug-on-signal} non-@code{nil}, then the debugger gets
first chance at every error; an error will invoke the debugger
@ -119,7 +123,7 @@ regardless of any @code{condition-case}, if the fits the criterion
specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medecine! Various parts of
@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
@ -132,7 +136,7 @@ enter the debugger.
To debug an error that happens during loading of the @file{.emacs}
file, use the option @samp{-debug-init}, which binds
@code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
inhibits use of @code{condition-case} to catch init file errors.
inhibits use of @code{condition-case} to catch init-file errors.
If your @file{.emacs} file sets @code{debug-on-error}, the effect may
not last past the end of loading @file{.emacs}. (This is an undesirable
@ -190,26 +194,25 @@ 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
This function requests @var{function-name} to invoke the debugger each time
it is called. It works by inserting the form @code{(debug 'debug)} into
the function definition as the first form.
Any function defined as Lisp code may be set to break on entry,
Any function 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't debug primitive functions (i.e., those written in C) this way.
When @code{debug-on-entry} is called interactively, it prompts
for @var{function-name} in the minibuffer.
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}.
If the function is already set up to invoke the debugger on entry,
@code{debug-on-entry} does nothing.
@strong{Note:} if you redefine a function after using
@code{debug-on-entry} on it, the code to enter the debugger is lost.
@code{debug-on-entry} returns @var{function-name}.
@strong{Note:} 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.
@example
@group
@ -252,11 +255,12 @@ Entering:
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
@code{nil} or the empty string, it cancels debugging for all functions.
@code{nil} or the empty string, it cancels break-on-entry for all
functions.
If @code{cancel-debug-on-entry} is called more than once on the same
function, the second call does nothing. @code{cancel-debug-on-entry}
returns @var{function-name}.
Calling @code{cancel-debug-on-entry} does nothing to a function which is
not currently set up to break on entry. It always returns
@var{function-name}.
@end deffn
@node Explicit Debug
@ -326,8 +330,8 @@ 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 file for the function and
type @kbd{C-M-x} on its definition.)
same function. (To do this, visit the source for the function and type
@kbd{C-M-x} on its definition.)
Here is a list of Debugger mode commands:
@ -360,7 +364,8 @@ 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.
cancels a @kbd{b} command on that frame. The visible effect is to
remove the star from the line in the backtrace buffer.
@item e
Read a Lisp expression in the minibuffer, evaluate it, and print the
@ -371,6 +376,10 @@ examine 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.
@ -383,11 +392,11 @@ 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}); 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.
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.
@end table
@ -448,11 +457,11 @@ Beginning evaluation of function call form:
@end smallexample
@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{Return value:} on
the top line of the buffer, followed by the value being returned.
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{Return value:} in the top
line of the buffer, followed by the value being returned.
@item error
@cindex @code{error} in debug
@ -605,8 +614,8 @@ bound to @code{nil}. The debugger can set this variable to leave
information for future debugger invocations during the same command
invocation.
The advantage, for the debugger, of using this variable rather than
another global variable is that the data will never carry over to a
The advantage, for the debugger, 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
@ -671,7 +680,8 @@ close parenthesis, and finally return to the mark.)
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.
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
@ -702,7 +712,7 @@ parenthesis at the beginning of the file, back up over it, and type
insertion of the open parenthesis, and finally return to the mark.)
Then find the actual matching close parenthesis by typing @kbd{C-M-f}
at the beginning of the defun. This will leave you somewhere short of
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.

281
lispref/display.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, Calendar, System Interface, Top
@node Display, Calendar, Processes, Top
@chapter Emacs Display
This chapter describes a number of features related to the display
@ -62,7 +62,7 @@ resumption.
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed. Non-@code{nil} means there is no need
to redraw, @code{nil} means redrawing is needed.
to redraw, @code{nil} means redrawing is needed. The default is @code{nil}.
@end defvar
@node Screen Size
@ -136,9 +136,9 @@ line can either be continued on the next screen line, or truncated to
one screen line. The additional screen lines used to display a long
text line are called @dfn{continuation} lines. Normally, a @samp{$} in
the rightmost column of the window indicates truncation; a @samp{\} on
the rightmost column indicates a line that ``wraps'' or is continued
onto the next line. (The display table can specify alternative
indicators; see @ref{Display Tables}.)
the rightmost column indicates a line that ``wraps'' onto the next line,
which is also called @dfn{continuing} the line. (The display table can
specify alternative indicators; see @ref{Display Tables}.)
Note that continuation is different from filling; continuation happens
on the screen only, not in the buffer contents, and it breaks a line
@ -157,7 +157,7 @@ frame) regardless of the value of @code{truncate-lines}.
@defopt default-truncate-lines
This variable is the default value for @code{truncate-lines}, for
buffers that do not have local values for it.
buffers that do not have buffer-local values for it.
@end defopt
@defopt truncate-partial-width-windows
@ -184,7 +184,7 @@ unless they are modified.
Turning on the cache slows down processing of short lines somewhat.
This variable is automatically local in every buffer.
This variable is automatically buffer-local in every buffer.
@end defvar
@node The Echo Area
@ -242,6 +242,16 @@ This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-@code{nil}, then the cursor
appears at the end of the message. Otherwise, the cursor appears at
point---not in the echo area at all.
The value is normally @code{nil}; Lisp programs bind it to @code{t}
for brief periods of time.
@end defvar
@tindex echo-area-clear-hook
@defvar echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@ -274,16 +284,6 @@ characters in the same command will be echoed as well.
If the value is zero, then command input is not echoed.
@end defvar
@defvar cursor-in-echo-area
This variable controls where the cursor appears when a message is
displayed in the echo area. If it is non-@code{nil}, then the cursor
appears at the end of the message. Otherwise, the cursor appears at
point---not in the echo area at all.
The value is normally @code{nil}; Lisp programs bind it to @code{t}
for brief periods of time.
@end defvar
@node Invisible Text
@section Invisible Text
@ -295,8 +295,7 @@ text property or a property of an overlay.
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
the default value of @code{buffer-invisibility-spec}, this is how the
@code{invisibility} property works. This feature is much like selective
display (@pxref{Selective Display}), but more general and cleaner.
@code{invisible} property works.
More generally, you can use the variable @code{buffer-invisibility-spec}
to control which values of the @code{invisible} property make text
@ -322,17 +321,17 @@ A character is invisible if its @code{invisible} property is
non-@code{nil}. This is the default.
@item a list
Each element of the list makes certain characters invisible.
Ultimately, a character is invisible if any of the elements of this list
applies to it. The list can have two kinds of elements:
Each element of the list specifies a criterion for invisibility; if a
character's @code{invisible} property fits any one of these criteria,
the character is invisible. The list can have two kinds of elements:
@table @code
@item @var{atom}
A character is invisible if its @code{invisible} propery value
A character is invisible if its @code{invisible} property value
is @var{atom} or if it is a list with @var{atom} as a member.
@item (@var{atom} . t)
A character is invisible if its @code{invisible} propery value
A character is invisible if its @code{invisible} property value
is @var{atom} or if it is a list with @var{atom} as a member.
Moreover, if this character is at the end of a line and is followed
by a visible newline, it displays an ellipsis.
@ -360,17 +359,17 @@ that a major mode should use the mode's own name as an element of
property:
@example
;; If we want to display an ellipsis:
;; @r{If you want to display an ellipsis:}
(add-to-invisibility-spec '(my-symbol . t))
;; If you don't want ellipsis:
;; @r{If you don't want ellipsis:}
(add-to-invisibility-spec 'my-symbol)
(overlay-put (make-overlay beginning end)
'invisible 'my-symbol)
;; When done with the overlays:
;; @r{When done with the overlays:}
(remove-from-invisibility-spec '(my-symbol . t))
;; Or respectively:
;; @r{Or respectively:}
(remove-from-invisibility-spec 'my-symbol)
@end example
@ -401,14 +400,13 @@ it invisible again.
@section Selective Display
@cindex selective display
@dfn{Selective display} is a pair of features that hide certain
lines on the screen.
@dfn{Selective display} refers to a pair of related features for
hiding certain lines on the screen.
The first variant, explicit selective display, is designed for use in
a Lisp program. The program controls which lines are hidden by altering
the text. Outline mode has traditionally used this variant. It has
been partially replaced by the invisible text feature (@pxref{Invisible
Text}); there is a new version of Outline mode which uses that instead.
a Lisp program: it controls which lines are hidden by altering the text.
The invisible text feature (@pxref{Invisible Text}) has partially
replaced this feature.
In the second variant, the choice of lines to hide is made
automatically based on indentation. This variant is designed to be a
@ -441,7 +439,8 @@ lines, or portions of lines, may be made invisible.
@itemize @bullet
@item
If the value of @code{selective-display} is @code{t}, then any portion
of a line that follows a control-m is not displayed.
of a line that follows a control-m is not displayed. This is explicit
selective display.
@item
If the value of @code{selective-display} is a positive integer, then
@ -543,15 +542,15 @@ given time.
@c now. Is it?
@end defvar
You can do the same job by creating an overlay with a
You can do a similar job by creating an overlay with a
@code{before-string} property. @xref{Overlay Properties}.
@node Temporary Displays
@section Temporary Displays
Temporary displays are used by commands to put output into a buffer
and then present it to the user for perusal rather than for editing.
Many of the help commands use this feature.
Temporary displays are used by Lisp programs to put output into a
buffer and then present it to the user for perusal rather than for
editing. Many help commands use this feature.
@defspec with-output-to-temp-buffer buffer-name forms@dots{}
This function executes @var{forms} while arranging to insert any
@ -599,9 +598,6 @@ The value of the last form in @var{forms} is returned.
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
In Emacs versions 18 and earlier, this variable was called
@code{temp-buffer-show-hook}.
@end defvar
@defun momentary-string-display string position &optional char message
@ -620,8 +616,9 @@ the display and later (presumably) move point forward. The argument
The return value of @code{momentary-string-display} is not meaningful.
If the string @var{string} does not contain control characters, you can
do the same job in a more general way by creating an overlay with a
@code{before-string} property. @xref{Overlay Properties}.
do the same job in a more general way by creating (and then subsequently
deleting) an overlay with a @code{before-string} property.
@xref{Overlay Properties}.
If @var{message} is non-@code{nil}, it is displayed in the echo area
while @var{string} is displayed in the buffer. If it is @code{nil}, a
@ -685,7 +682,7 @@ not to be part of the text. Thus, copying text between various buffers
and strings preserves text properties, but does not try to preserve
overlays. Changing a buffer's text properties marks the buffer as
modified, while moving an overlay or changing its properties does not.
Unlike text propery changes, overlay changes are not recorded in the
Unlike text property changes, overlay changes are not recorded in the
buffer's undo list.
@table @code
@ -803,8 +800,8 @@ If this property is non-@code{nil}, the overlay is deleted automatically
if it ever becomes empty (i.e., if it spans no characters).
@item local-map
@cindex keymap of character
@kindex local-map @r{(text property)}
@cindex keymap of character (and overlays)
@kindex local-map @r{(overlay property)}
If this property is non-@code{nil}, it specifies a keymap for a portion
of the text. The property's value replaces the buffer's local map, when
the character after point is within the overlay. @xref{Active Keymaps}.
@ -912,10 +909,8 @@ end of an overlay, before @var{pos}.
@section Width
Since not all characters have the same width, these functions let you
check the width of a character. @ref{Primitive Indent}
@xref{Screen Lines}, for related
functions.
check the width of a character. @xref{Primitive Indent}, and
@ref{Screen Lines}, for related functions.
@tindex char-width
@defun char-width char
@ -970,7 +965,7 @@ foreground color, background color, and optional underlining. Faces
control the display of text on the screen.
@cindex face id
Each face has its own @dfn{face id number} which distinguishes faces at
Each face has its own @dfn{face number}, which distinguishes faces at
low levels within Emacs. However, for most purposes, you can refer to
faces in Lisp programs by their names.
@ -986,6 +981,7 @@ face name a special meaning in one frame if you wish.
@menu
* Standard Faces:: The faces Emacs normally comes with.
* Defining Faces:: How to define a face with @code{defface}.
* Merging Faces:: How Emacs decides which face to use for a character.
* Face Functions:: How to define and examine faces.
@end menu
@ -1036,6 +1032,90 @@ This face uses the bold italic variant of the frame's font, if it has
one.
@end table
@node Defining Faces
@section Defining Faces
The way to define a new face is with @code{defface}. This creates a
kind of customization item (@pxref{Customization}) which the user can
customize using the Customization buffer (@pxref{Easy Customization,,,
emacs, The GNU Emacs Manual}).
@tindex defface
@defmac defface face spec doc [keyword value]...
Declare @var{face} as a customizable face that defaults according to
@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
specifies the face documentation.
When @code{defface} executes, it defines the face according to
@var{spec}, then uses any customizations saved in the @file{.emacs} file
to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements have
the form @code{(@var{display} @var{atts})}. The element's @sc{car},
@var{display}, specifies a class of terminals. The @sc{cdr},
@var{atts}, is a list of face attributes and their values; it specifies
what the face should look like on that kind of terminal. The possible
attributes are defined in the value of @code{custom-face-attributes}.
The @var{display} part of an element of @var{spec} determines which
frames the element applies to. If more than one element of @var{spec}
matches a given frame, the first matching element is the only one used
for that frame. There are two possibilities for @var{display}:
@table @asis
@item @code{t}
This element of @var{spec} matches all frames. Therefore, any
subsequent elements of @var{spec} are never used. Normally
@code{t} is used in the last (or only) element of @var{spec}.
@item an list
If @var{display} is alist, each elements should have the form
@code{(@var{characteristic} @var{value}@dots{})}. Here
@var{characteristic} specifies a way of classifying frames, and the
@var{value}s are possible classifications which @var{display} should
apply to. Here are the possible values of @var{characteristic}:
@table @code
@item type
The kind of window system the frame uses---either @code{x}, @code{pc}
(for the MS-DOS console), @code{w32} (for MS Windows 9X/NT), or
@code{tty}.
@item class
What kinds of colors the frame supports---either @code{color},
@code{grayscale}, or @code{mono}.
@item background
The kind of background--- either @code{light} or @code{dark}.
@end table
If an element of @var{display} specifies more than one @var{value} for a
given @var{characteristic}, any of those values is acceptable. If
@var{display} has more than one element, each element should specify a
different @var{characteristic}; then @emph{each} characteristic of the
frame must match one of the @var{value}s specified for it in
@var{display}.
@end table
@end defmac
Here's how the standard face @code{region} could be defined
with @code{defface}:
@example
(defface region
((((class color) (background dark))
(:background "blue"))
(t (:background "gray")))
"Used for displaying the region.")
@end example
Internally, @code{defface} uses the symbol property
@code{face-defface-spec} to record the face attributes specified in
@code{defface}, @code{saved-face} for the attributes saved by the user
with the customization buffer, and @code{face-documentation} for the
documentation string.
@node Merging Faces
@subsection Merging Faces for Display
@ -1043,9 +1123,9 @@ one.
@itemize @bullet
@item
With defaults. Each frame has a @dfn{default face}, whose id number is
zero, which is used for all text that doesn't somehow specify another
face.
With defaults. Each frame has a @dfn{default face}, which is used for
all text that doesn't somehow specify another face. (We may change this
in a forthcoming Emacs version to serve as a default for all text.)
@item
With text properties. A character may have a @code{face} property; if so,
@ -1064,7 +1144,7 @@ With a region that is active. In Transient Mark mode, the region is
highlighted with a particular face (see @code{region-face}, below).
@item
With special glyphs. Each glyph can specify a particular face id
With special glyphs. Each glyph can specify a particular face
number. @xref{Glyphs}.
@end itemize
@ -1147,11 +1227,6 @@ and italic attributes cease to have any effect, because the precise font
that you specified is always used.
@end defun
@defun set-face-underline-p face underline-p &optional frame
This function sets the underline attribute of face @var{face}.
Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
@tindex set-face-bold-p
@defun set-face-bold-p face bold-p &optional frame
This function sets the bold attribute of face @var{face}.
@ -1164,6 +1239,11 @@ This function sets the italic attribute of face @var{face}.
Non-@code{nil} means italic; @code{nil} means non-italic.
@end defun
@defun set-face-underline-p face underline-p &optional frame
This function sets the underline attribute of face @var{face}.
Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
@defun invert-face face &optional frame
Swap the foreground and background colors of face @var{face}. If the
face doesn't specify both foreground and background, then its foreground
@ -1189,10 +1269,6 @@ This function returns the name of the background stipple pattern of face
This function returns the name of the font of face @var{face}.
@end defun
@defun face-underline-p face &optional frame
This function returns the underline attribute of face @var{face}.
@end defun
@tindex face-bold-p
@defun face-bold-p face &optional frame
This function returns the bold attribute of face @var{face}.
@ -1203,8 +1279,12 @@ This function returns the bold attribute of face @var{face}.
This function returns the italic attribute of face @var{face}.
@end defun
@defun face-underline-p face &optional frame
This function returns the underline attribute of face @var{face}.
@end defun
@defun face-id face
This function returns the face id number of face @var{face}.
This function returns the face number of face @var{face}.
@end defun
@tindex face-documentation
@ -1226,13 +1306,13 @@ face if each attribute is either the same as that of the default face or
@end defun
@defvar region-face
This variable's value specifies the face id to use to display characters
This variable's value specifies the face number to use to display characters
in the region when it is active (in Transient Mark mode only). The face
thus specified takes precedence over all faces that come from text
properties and overlays, for characters in the region. @xref{The Mark},
for more information about Transient Mark mode.
Normally, the value is the id number of the face named @code{region}.
Normally, the value is the face number of the face named @code{region}.
@end defvar
@node Blinking
@ -1245,19 +1325,11 @@ Normally, the value is the id number of the face named @code{region}.
This section describes the mechanism by which Emacs shows a matching
open parenthesis when the user inserts a close parenthesis.
@vindex blink-paren-hook
@defvar blink-paren-function
The value of this variable should be a function (of no arguments) to
be called whenever a character with close parenthesis syntax is inserted.
The value of @code{blink-paren-function} may be @code{nil}, in which
case nothing is done.
@quotation
@strong{Please note:} This variable was named @code{blink-paren-hook} in
older Emacs versions, but since it is not called with the standard
convention for hooks, it was renamed to @code{blink-paren-function} in
version 19.
@end quotation
@end defvar
@defvar blink-matching-paren
@ -1321,7 +1393,7 @@ is non-@code{nil}, then mode lines are displayed in inverse video.
Otherwise, mode lines are displayed normally, just like text. The
default is @code{t}.
For X window frames, this displays mode lines using the face named
For window frames, this displays mode lines using the face named
@code{modeline}, which is normally the inverse of the default face
unless you change it.
@end defopt
@ -1356,14 +1428,19 @@ just like the codes in the range 128 to 255.
@item
Character codes 128 through 255 map to sequences of four glyphs, where
the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
digit characters representing the code in octal. (A display table can
specify a glyph to use instead of @samp{\}.)
digit characters representing the charatcer code in octal. (A display
table can specify a glyph to use instead of @samp{\}.)
@item
Multibyte character codes above 256 are displayed as themselves, or as a
question mark or empty box if the terminal cannot display that
character.
@end itemize
The usual display conventions apply even when there is a display
table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
specify the characters for which you want unusual behavior.
specify the characters for which you want special behavior.
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
@ -1397,10 +1474,10 @@ stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
@section Display Tables
@cindex display table
You can use the @dfn{display table} feature to control how all 256
possible character codes display on the screen. This is useful for
displaying European languages that have letters not in the @sc{ASCII}
character set.
You can use the @dfn{display table} feature to control how all possible
character codes display on the screen. This is useful for displaying
European languages that have letters not in the @sc{ASCII} character
set.
The display table maps each character code into a sequence of
@dfn{glyphs}, each glyph being an image that takes up one character
@ -1438,8 +1515,8 @@ display that character according to the usual display conventions
characters, the whole buffer will be displayed as one long ``line.''
The display table also has six ``extra slots'' which serve special
purposes. Here is a table of their meanings; @code{nil} means to use
the default stated below.
purposes. Here is a table of their meanings; @code{nil} in any slot
means to use the default for that slot, as stated below.
@table @asis
@item 0
@ -1514,9 +1591,10 @@ The argument @var{table} should be either a display table or
@end defun
@defvar buffer-display-table
This variable is automatically local in all buffers; its value in a
particular buffer is the display table for that buffer, or @code{nil} if
the buffer does not have an assigned display table.
This variable is automatically buffer-local in all buffers; its value in
a particular buffer specifies the display table for that buffer. If it
is @code{nil}, that means the buffer does not have an assigned display
table.
@end defvar
@defvar standard-display-table
@ -1556,22 +1634,23 @@ below).
@item string
Send the characters in @var{string} to the terminal to output
this glyph. This alternative is available on character terminals,
but not under X.
but not under a window system.
@item integer
Define this glyph code as an alias for code @var{integer}. You can use
an alias to specify a face code for the glyph; see below.
Define this glyph code as an alias for glyph code @var{integer}. You
can use an alias to specify a face code for the glyph; see below.
@item @code{nil}
This glyph is simple. On an ordinary terminal, the glyph code mod 524288
is the character to output. With X, the glyph code mod 524288 is the
character to output, and the glyph code divided by 524288 specifies the
@dfn{face id number} to use while outputting it. (524288 is
This glyph is simple. On an ordinary terminal, the glyph code mod
524288 is the character to output. In a window system, the glyph code
mod 524288 is the character to output, and the glyph code divided by
524288 specifies the face number (@pxref{Face Functions}) to use while
outputting it. (524288 is
@ifinfo
2**19.
2**19.)
@end ifinfo
@tex
$2^{19}$.
$2^{19}$.)
@end tex
@xref{Faces}.
@end table
@ -1604,9 +1683,9 @@ This is a synonym for @code{ding}.
@defvar visible-bell
This variable determines whether Emacs should flash the screen to
represent a bell. Non-@code{nil} means yes, @code{nil} means no. This
is effective under X windows, and on a character-only terminal provided
the terminal's Termcap entry defines the visible bell capability
(@samp{vb}).
is effective on a window system, and on a character-only terminal
provided the terminal's Termcap entry defines the visible bell
capability (@samp{vb}).
@end defvar
@tindex ring-bell-function

164
lispref/edebug.texi
View file

@ -1,8 +1,10 @@
@comment -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@c This file is intended to be used as a section within the Emacs Lisp
@c Reference Manual. It may also be used by an independent Edebug User
@c Manual, edebug.tex, in which case the Edebug node below should be used
@c This file can also be used by an independent Edebug User
@c Manual in which case the Edebug node below should be used
@c with the following links to the Bugs section and to the top level:
@c , Bugs and Todo List, Top, Top
@ -167,9 +169,8 @@ definition @emph{unless} it has a prefix argument. The default value of
edebug-all-defs} toggles the value of the variable
@code{edebug-all-defs}.
@findex edebug-all-forms
@findex eval-region (Edebug)
@findex eval-current-buffer (Edebug)
@findex eval-region @r{(Edebug)}
@findex eval-current-buffer @r{(Edebug)}
If @code{edebug-all-defs} is non-@code{nil}, then the commands
@code{eval-region}, @code{eval-current-buffer}, and @code{eval-buffer}
also instrument any definitions they evaluate. Similarly,
@ -179,16 +180,11 @@ to loading or evaluations in the minibuffer. The command @kbd{M-x
edebug-all-forms} toggles this option.
@findex edebug-eval-top-level-form
Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
instrument any top-level form regardless of the values of
@code{edebug-all-defs} and @code{edebug-all-forms}.
When Edebug is about to instrument code for the first time in a session,
it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}.
You can use this to load up Edebug specifications associated with a
package you are using, but only when you also use Edebug.
While Edebug is active, the command @kbd{I}
While Edebug is active, the command @kbd{I}
(@code{edebug-instrument-callee}) instruments the definition of the
function or macro called by the list form after point, if is not already
instrumented. This is possible only if Edebug knows where to find the
@ -201,7 +197,7 @@ steps into the call after instrumenting the function.
@cindex interactive commands (Edebug)
@cindex anonymous lambda expressions (Edebug)
@cindex Common Lisp (Edebug)
@pindex cl.el (Edebug)
@pindex cl.el @r{(Edebug)}
@pindex cl-specs.el
Edebug knows how to instrument all the standard special forms, an
interactive form with an expression argument, anonymous lambda
@ -209,7 +205,13 @@ expressions, and other defining forms. Edebug cannot know what a
user-defined macro will do with the arguments of a macro call, so you
must tell it; @xref{Instrumenting Macro Calls}, for details.
@findex eval-expression (Edebug)
When Edebug is about to instrument code for the first time in a
session, it runs the hook @code{edebug-setup-hook}, then sets it to
@code{nil}. You can use this to arrange to load Edebug specifications
(@pxref{Instrumenting Macro Calls}) associated with a package you are
using, but actually load them only if you use Edebug.
@findex eval-expression @r{(Edebug)}
To remove instrumentation from a definition, simply reevaluate its
definition in a way that does not instrument. There are two ways of
evaluating forms that never instrument them: from a file with
@ -472,7 +474,7 @@ stop point that has a previously established conditional breakpoint puts
the previous condition expression in the minibuffer so you can edit it.
You can make a conditional or unconditional breakpoint
@dfn{temporary} by using a prefix arg with the command to set the
@dfn{temporary} by using a prefix argument with the command to set the
breakpoint. When a temporary breakpoint stops the program, it is
automatically unset.
@ -504,7 +506,6 @@ depending on the execution mode, as if a breakpoint had been hit. If
evaluating the condition gets an error, execution does not stop.
@findex edebug-set-global-break-condition
@vindex edebug-global-break-condition
The condition expression is stored in
@code{edebug-global-break-condition}. You can specify a new expression
using the @kbd{X} command (@code{edebug-set-global-break-condition}).
@ -533,24 +534,24 @@ line as shown below to stop when the argument reaches zero:
1))
@end example
When the @code{fac} definition is instrumented and the function is
When the @code{fac} definition is instrumented and the function is
called, the call to @code{edebug} acts as a breakpoint. Depending on
the execution mode, Edebug stops or pauses there.
If no instrumented code is being executed when @code{edebug} is called,
If no instrumented code is being executed when @code{edebug} is called,
that function calls @code{debug}.
@c This may not be a good idea anymore.
@node Trapping Errors
@subsection Trapping Errors
Emacs normally displays an error message when an error is signaled and
not handled with @code{condition-case}. While Edebug is active, it
normally responds to all unhandled errors. You can customize this with
the options @code{edebug-on-error} and @code{edebug-on-quit}; see
@ref{Edebug Options}.
Emacs normally displays an error message when an error is signaled and
not handled with @code{condition-case}. While Edebug is active and
executing instrumented code, it normally responds to all unhandled
errors. You can customize this with the options @code{edebug-on-error}
and @code{edebug-on-quit}; see @ref{Edebug Options}.
When Edebug responds to an error, it shows the last stop point
When Edebug responds to an error, it shows the last stop point
encountered before the error. This may be the location of a call to a
function which was not instrumented, within which the error actually
occurred. For an unbound variable error, the last known stop point
@ -558,7 +559,7 @@ might be quite distant from the offending variable reference. In that
case you might want to display a full backtrace (@pxref{Edebug Misc}).
@c Edebug should be changed for the following: -- dan
If you change @code{debug-on-error} or @code{debug-on-quit} while
If you change @code{debug-on-error} or @code{debug-on-quit} while
Edebug is active, these changes will be forgotten when Edebug becomes
inactive. Furthermore, during Edebug's recursive edit, these variables
are bound to the values they had outside of Edebug.
@ -566,7 +567,7 @@ are bound to the values they had outside of Edebug.
@node Edebug Views
@subsection Edebug Views
These Edebug commands let you view aspects of the buffer and window
These Edebug commands let you view aspects of the buffer and window
status that obtained before entry to Edebug. The outside window
configuration is the collection of windows and contents that were in
effect outside of Edebug.
@ -597,12 +598,12 @@ the selected window. To specify a window that is not displaying the
source code buffer, you must use @kbd{C-x X W} from the global keymap.
@end table
You can view the outside window configuration with @kbd{v} or just
You can view the outside window configuration with @kbd{v} or just
bounce to the point in the current buffer with @kbd{p}, even if
it is not normally displayed. After moving point, you may wish to jump
back to the stop point with @kbd{w} from a source code buffer.
Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
Each time you use @kbd{W} to turn saving @emph{off}, Edebug forgets the
saved outside window configuration---so that even if you turn saving
back @emph{on}, the current window configuration remains unchanged when
you next exit Edebug (by continuing the program). However, the
@ -613,7 +614,7 @@ open.
@node Edebug Eval
@subsection Evaluation
While within Edebug, you can evaluate expressions ``as if'' Edebug were
While within Edebug, you can evaluate expressions ``as if'' Edebug were
not running. Edebug tries to be invisible to the expression's
evaluation and printing. Evaluation of expressions that cause side
effects will work as expected except for things that Edebug explicitly
@ -635,16 +636,15 @@ Evaluate the expression before point, in the context outside of Edebug
@end table
@cindex lexical binding (Edebug)
Edebug supports evaluation of expressions containing references to
Edebug supports evaluation of expressions containing references to
lexically bound symbols created by the following constructs in
@file{cl.el} (version 2.03 or later): @code{lexical-let},
@code{macrolet}, and @code{symbol-macrolet}.
@node Eval List
@subsection Evaluation List Buffer
You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
You can use the @dfn{evaluation list buffer}, called @samp{*edebug*}, to
evaluate expressions interactively. You can also set up the
@dfn{evaluation list} of expressions to be evaluated automatically each
time Edebug updates the display.
@ -655,12 +655,12 @@ Switch to the evaluation list buffer @samp{*edebug*}
(@code{edebug-visit-eval-list}).
@end table
In the @samp{*edebug*} buffer you can use the commands of Lisp
In the @samp{*edebug*} buffer you can use the commands of Lisp
Interaction mode (@pxref{Lisp Interaction,,, emacs, The GNU Emacs
Manual}) as well as these special commands:
@table @kbd
@item LFD
@item C-j
Evaluate the expression before point, in the outside context, and insert
the value in the buffer (@code{edebug-eval-print-last-sexp}).
@ -681,40 +681,36 @@ Switch back to the source code buffer at the current stop point
(@code{edebug-where}).
@end table
You can evaluate expressions in the evaluation list window with
@kbd{LFD} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
You can evaluate expressions in the evaluation list window with
@kbd{C-j} or @kbd{C-x C-e}, just as you would in @samp{*scratch*};
but they are evaluated in the context outside of Edebug.
The expressions you enter interactively (and their results) are lost
The expressions you enter interactively (and their results) are lost
when you continue execution; but you can set up an @dfn{evaluation list}
consisting of expressions to be evaluated each time execution stops.
@cindex evaluation list group
To do this, write one or more @dfn{evaluation list groups} in the
To do this, write one or more @dfn{evaluation list groups} in the
evaluation list buffer. An evaluation list group consists of one or
more Lisp expressions. Groups are separated by comment lines.
The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
The command @kbd{C-c C-u} (@code{edebug-update-eval-list}) rebuilds the
evaluation list, scanning the buffer and using the first expression of
each group. (The idea is that the second expression of the group is the
value previously computed and displayed.)
Be careful not to add expressions that execute instrumented code since
that would cause an infinite loop.
@c There ought to be a way to fix this.
Each entry to Edebug redisplays the evaluation list by inserting each
Each entry to Edebug redisplays the evaluation list by inserting each
expression in the buffer, followed by its current value. It also
inserts comment lines so that each expression becomes its own group.
Thus, if you type @kbd{C-c C-u} again without changing the buffer text,
the evaluation list is effectively unchanged.
If an error occurs during an evaluation from the evaluation list, the
If an error occurs during an evaluation from the evaluation list, the
error message is displayed in a string as if it were the result.
Therefore, expressions that use variables not currently valid do not
interrupt your debugging.
Here is an example of what the evaluation list window looks like after
Here is an example of what the evaluation list window looks like after
several expressions have been added to it:
@smallexample
@ -759,8 +755,6 @@ you continue execution, and recreated next time it is needed.
If an expression in your program produces a value containing circular
list structure, you may get an error when Edebug attempts to print it.
@vindex edebug-print-length
@vindex edebug-print-level
One way to cope with circular structure is to set @code{print-length}
or @code{print-level} to truncate the printing. Edebug does this for
you; it binds @code{print-length} and @code{print-level} to 50 if they
@ -768,6 +762,17 @@ were @code{nil}. (Actually, the variables @code{edebug-print-length}
and @code{edebug-print-level} specify the values to use within Edebug.)
@xref{Output Variables}.
@defopt edebug-print-length
If non-@code{nil}, bind @code{print-length} to this while printing
results in Edebug. The default value is @code{50}.
@xref{Printing in Edebug}.
@end defopt
@defopt edebug-print-level
If non-@code{nil}, bind @code{print-level} to this while printing
results in Edebug. The default value is @code{50}.
@end defopt
You can also print circular structures and structures that share
elements more informatively by using the @file{cust-print} package.
@ -790,6 +795,11 @@ Custom printing prints this as @samp{Result: #1=(#1# y)}. The
structure. This notation is used for any shared elements of lists or
vectors.
@defopt edebug-print-circle
If non-@code{nil}, bind @code{print-circle} to this while printing
results in Edebug. The default value is @code{nil}.
@end defopt
Other programs can also use custom printing; see @file{cust-print.el}
for details.
@ -850,7 +860,7 @@ Edebug provides rudimentary coverage testing and display of execution
frequency. All execution of an instrumented function accumulates
frequency counts, both before and after evaluation of each instrumented
expression, even if the execution mode is Go-nonstop. Coverage testing
is more expensive, so it is only done if @code{edebug-test-coverage} is
is more expensive, so it is done only if @code{edebug-test-coverage} is
non-@code{nil}. The command @kbd{M-x edebug-display-freq-count}
displays both the frequency data and the coverage data (if recorded).
@ -858,11 +868,11 @@ displays both the frequency data and the coverage data (if recorded).
This command displays the frequency count data for each line of the
current definition.
The frequency counts appear as comment lines after each line of code, and
you can undo all insertions with one @code{undo} command. The counts
appear under the @kbd{(} before an expression or the @kbd{)} after
an expression, or on the last character of a symbol. Values do not appear if
they are equal to the previous count on the same line.
The frequency counts appear as comment lines after each line of code,
and you can undo all insertions with one @code{undo} command. The
counts appear under the @samp{(} before an expression or the @samp{)}
after an expression, or on the last character of a symbol. Values do
not appear if they are equal to the previous count on the same line.
The character @samp{=} following the count for an expression says that
the expression has returned the same value each time it was evaluated
@ -1035,14 +1045,16 @@ Edebug is active, @code{defining-kbd-macro} is bound to
@node Instrumenting Macro Calls
@subsection Instrumenting Macro Calls
When Edebug instruments an expression that calls a Lisp macro, it needs
additional advice to do the job properly. This is because there is no
way to tell which subexpressions of the macro call are forms to be
evaluated. (Evaluation may occur explicitly in the macro body, or when
the resulting expansion is evaluated, or any time later.) You must
explain the format of calls to each macro to enable Edebug to handle it.
To do this, use @code{def-edebug-spec} to define the format of
calls to a given macro.
When Edebug instruments an expression that calls a Lisp macro, it needs
additional information about the macro to do the job properly. This is
because there is no a-priori way to tell which subexpressions of the
macro call are forms to be evaluated. (Evaluation may occur explicitly
in the macro body, or when the resulting expansion is evaluated, or any
time later.)
Therefore, you must define an Edebug specification for each macro that
Edebug will encounter, to explain the format of calls to that macro. To
do this, use @code{def-edebug-spec}.
@deffn Macro def-edebug-spec macro specification
Specify which expressions of a call to macro @var{macro} are forms to be
@ -1050,7 +1062,7 @@ evaluated. For simple macros, the @var{specification} often looks very
similar to the formal argument list of the macro definition, but
specifications are much more general than macro arguments.
The @var{macro} argument may actually be any symbol, not just a macro
The @var{macro} argument can actually be any symbol, not just a macro
name.
@end deffn
@ -1108,7 +1120,7 @@ as @code{&optional}).
A specification list may contain sublists which match arguments that are
themselves lists, or it may contain vectors used for grouping. Sublists
and groups thus subdivide the specification list into a hierarchy of
levels. Specification keywords only apply to the remainder of the
levels. Specification keywords apply only to the remainder of the
sublist or group they are contained in.
When a specification list involves alternatives or repetition, matching
@ -1262,7 +1274,7 @@ sublist-elements@dots{})}.
@c Need to document extensions with &symbol and :symbol
Here is a list of additional specifications that may only appear after
Here is a list of additional specifications that may appear only after
@code{&define}. See the @code{defun} example below.
@table @code
@ -1304,7 +1316,7 @@ tracing information is not output when the form is executed. See the
@end table
@node Backtracking
@subsubsection Backtracking
@subsubsection Backtracking in Specifications
@cindex backtracking
@cindex syntax error (Edebug)
@ -1473,8 +1485,6 @@ The default value is @code{step}.
@end defopt
@defopt edebug-trace
@findex edebug-print-trace-before
@findex edebug-print-trace-after
Non-@code{nil} means display a trace of function entry and exit.
Tracing output is displayed in a buffer named @samp{*edebug-trace*}, one
function entry or exit per line, indented by the recursion level.
@ -1504,22 +1514,6 @@ debugged.
@xref{Edebug Execution Modes}.
@end defopt
@defopt edebug-print-length
If non-@code{nil}, bind @code{print-length} to this while printing
results in Edebug. The default value is @code{50}.
@xref{Printing in Edebug}.
@end defopt
@defopt edebug-print-level
If non-@code{nil}, bind @code{print-level} to this while printing
results in Edebug. The default value is @code{50}.
@end defopt
@defopt edebug-print-circle
If non-@code{nil}, bind @code{print-circle} to this while printing
results in Edebug. The default value is @code{nil}.
@end defopt
@defopt edebug-on-error
Edebug binds @code{debug-on-error} to this value, if
@code{debug-on-error} was previously @code{nil}. @xref{Trapping

29
lispref/errors.texi
View file

@ -55,8 +55,7 @@ See @code{/} and @code{%} in @ref{Numbers}.
@xref{Read Only Buffers}.
@item cyclic-function-indirection
@code{"Symbol's chain of function indirections contains a@*
loop"}@*
@code{"Symbol's chain of function indirections contains a loop"}@*
@xref{Function Indirection}.
@item end-of-buffer
@ -65,9 +64,14 @@ loop"}@*
@item end-of-file
@code{"End of file during parsing"}@*
This is not a @code{file-error}.@*
Note that this is not a @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 @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
@ -83,10 +87,6 @@ condition @code{file-error} is present.@*
This is a @code{file-error}.@*
@xref{File Locks}.
@item file-already-exists
This is a @code{file-error}.@*
@xref{Writing to Files}.
@item file-supersession
This is a @code{file-error}.@*
@xref{Modification Time}.
@ -103,17 +103,28 @@ This is a @code{file-error}.@*
@code{"Invalid regexp"}@*
@xref{Regular Expressions}.
@item mark-inactive
@code{Mark inactive"}@*
@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}
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}.
@ -138,7 +149,7 @@ may not be changed.@*
@xref{Type Predicates}.
@end table
These error types, which are all classified as special cases of
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.

20
lispref/eval.texi
View file

@ -139,7 +139,7 @@ unchanged.
@example
@group
'123 ; @r{An object, shown without evaluation.}
'123 ; @r{A number, shown without evaluation.}
@result{} 123
@end group
@group
@ -210,7 +210,8 @@ 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.
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
@ -646,15 +647,16 @@ buffer.
@defvar 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 counts
internal uses of those functions, such as for calling the functions
mentioned in Lisp expressions, and recursive evaluation of function call
arguments and function body forms.
This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This limit,
with the associated error when it is exceeded, is one way that Lisp
avoids infinite recursion on an ill-defined function.
@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 200. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.

203
lispref/files.texi
View file

@ -35,7 +35,6 @@ substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
* Magic File Names:: Defining "magic" special handling
for certain file names.
* Format Conversion:: Conversion to and from various file formats.
* Files and MS-DOS:: Distinguishing text and binary files on MS-DOS.
@end menu
@node Visiting Files
@ -116,12 +115,11 @@ saved in that buffer. If the file has changed, then this function asks
the user whether to reread the changed file. If the user says
@samp{yes}, any changes previously made in the buffer are lost.
If @code{find-file-noselect} needs to create a buffer, and there is no
file named @var{filename}, it displays the message @samp{New file} in
the echo area, and leaves the buffer empty.
This function displays warning or advisory messages in various peculiar
cases, unless the optional argument @var{nowarn} is non-@code{nil}.
cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
example, if it needs to create a buffer, and there is no file named
@var{filename}, it displays the message @samp{New file} in the echo
area, and leaves the buffer empty.
The @code{find-file-noselect} function normally calls
@code{after-find-file} after reading the file (@pxref{Subroutines of
@ -297,26 +295,20 @@ the user.
The optional @var{exiting} argument, if non-@code{nil}, requests this
function to offer also to save certain other buffers that are not
visiting files. These are buffers that have a non-@code{nil} local
value of @code{buffer-offer-save}. (A user who says yes to saving one
of these is asked to specify a file name to use.) The
visiting files. These are buffers that have a non-@code{nil}
buffer-local value of @code{buffer-offer-save}. (A user who says yes to
saving one of these is asked to specify a file name to use.) The
@code{save-buffers-kill-emacs} function passes a non-@code{nil} value
for this argument.
@end deffn
@defvar buffer-offer-save
When this variable is non-@code{nil} in a buffer, Emacs offers to save
the buffer on exit even if the buffer is not visiting a file. The
variable is automatically local in all buffers. Normally, Mail mode
(used for editing outgoing mail) sets this to @code{t}.
@end defvar
@deffn Command write-file filename
This function writes the current buffer into file @var{filename}, makes
the buffer visit that file, and marks it not modified. Then it renames
the buffer based on @var{filename}, appending a string like @samp{<2>}
if necessary to make a unique buffer name. It does most of this work by
calling @code{set-visited-file-name} and @code{save-buffer}.
calling @code{set-visited-file-name} (@pxref{Buffer File Name}) and
@code{save-buffer}.
@end deffn
Saving a buffer runs several hooks. It also performs format
@ -352,8 +344,8 @@ Even though this is not a normal hook, you can use @code{add-hook} and
@c Emacs 19 feature
@defvar local-write-file-hooks
This works just like @code{write-file-hooks}, but it is intended to be
made local to particular buffers, and used for hooks that pertain to the
file name or the way the buffer contents were obtained.
made buffer-local in particular buffers, and used for hooks that pertain
to the file name or the way the buffer contents were obtained.
The variable is marked as a permanent local, so that changing the major
mode does not alter a buffer-local value. This is convenient for
@ -372,7 +364,7 @@ This variable automatically becomes buffer-local whenever it is set;
switching to a new major mode always resets this variable. When you use
@code{add-hooks} to add an element to this hook, you should @emph{not}
specify a non-@code{nil} @var{local} argument, since this variable is
used @emph{only} locally.
used @emph{only} buffer-locally.
@end defvar
@c Emacs 19 feature
@ -392,8 +384,8 @@ As a side effect, backups are necessarily made by copying. @xref{Rename
or Copy}. Yet, at the same time, saving a precious file always breaks
all hard links between the file you save and other file names.
Some modes set this variable non-@code{nil} locally in particular
buffers.
Some modes give this variable non-@code{nil} buffer-local value
in particular buffers.
@end defvar
@defopt require-final-newline
@ -410,16 +402,8 @@ doesn't add newlines at all. @code{nil} is the default value, but a few
major modes set it to @code{t} in particular buffers.
@end defopt
@deffn Command set-visited-file-name filename &optional no-query
This function changes the visited file name of the current buffer to
@var{filename}. It also renames the buffer based on @var{filename},
appending a string like @samp{<2>} if necessary to make a unique buffer
name. It marks the buffer as @emph{modified},a since the contents do not
(as far as Emacs knows) match the actual file's contents.
If the specified file already exists, @code{set-visited-file-name}
asks for confirmation unless @var{no-query} is non-@code{nil}.
@end deffn
See also the function @code{set-visited-file-name} (@pxref{Buffer File
Name}).
@node Reading from Files
@comment node-name, next, previous, up
@ -542,15 +526,12 @@ files that the user does not need to know about.
@tindex with-temp-file
@defmac with-temp-file file body...
The @code{with-temp-file} macro evaluates the @var{body} forms
with a temporary buffer as the current buffer; then, at the end, it
writes the buffer contents into file @var{file}. It kills the temporary
buffer when finished, restoring the buffer that was current before the
@code{with-temp-file} form.
The return value is the value of the last form in @var{body}. You can
return the contents of the temporary buffer by using
@code{(buffer-string)} as the last form.
The @code{with-temp-file} macro evaluates the @var{body} forms with a
temporary buffer as the current buffer; then, at the end, it writes the
buffer contents into file @var{file}. It kills the temporary buffer
when finished, restoring the buffer that was current before the
@code{with-temp-file} form. Then it returns the value of the last form
in @var{body}.
The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
@ -568,13 +549,12 @@ arising by recording a @dfn{file lock} when a file is being modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
File locks do not work properly when multiple machines can share
file systems, such as with NFS. Perhaps a better file locking system
will be implemented in the future. When file locks do not work, it is
possible for two users to make changes simultaneously, but Emacs can
still warn the user who saves second. Also, the detection of
modification of a buffer visiting a file changed on disk catches some
cases of simultaneous editing; see @ref{Modification Time}.
File locks are not completely reliable when multiple machines can
share file systems. When file locks do not work, it is possible for two
users to make changes simultaneously, but Emacs can still warn the user
who saves second. Also, the detection of modification of a buffer
visiting a file changed on disk catches some cases of simultaneous
editing; see @ref{Modification Time}.
@defun file-locked-p filename
This function returns @code{nil} if the file @var{filename} is not
@ -1032,18 +1012,12 @@ For example, here are the file attributes for @file{files.texi}:
@example
@group
(file-attributes "files.texi")
@result{} (nil
1
2235
75
@result{} (nil 1 2235 75
(8489 20284)
(8489 20284)
(8489 20285)
14906
"-rw-rw-rw-"
nil
129500
-32252)
14906 "-rw-rw-rw-"
nil 129500 -32252)
@end group
@end example
@ -1614,7 +1588,7 @@ form.
@defvar default-directory
The value of this buffer-local variable is the default directory for the
current buffer. It should be an absolute directory name; it may start
with @samp{~}. This variable is local in every buffer.
with @samp{~}. This variable is buffer-local in every buffer.
@code{expand-file-name} uses the default directory when its second
argument is @code{nil}.
@ -1651,8 +1625,8 @@ the user's home directory name, has value @samp{/xcssun/users/rms}.
@end group
@end example
If a @samp{~} or a @samp{/} appears following a @samp{/}, after
substitution, everything before the following @samp{/} is discarded:
After substitution, if a @samp{~} or a @samp{/} appears following a
@samp{/}, everything before the following @samp{/} is discarded:
@example
@group
@ -1996,18 +1970,21 @@ Here are the operations that a magic file name handler gets to handle:
@noindent
@code{add-name-to-file}, @code{copy-file}, @code{delete-directory},
@code{delete-file},@*
@code{delete-file},
@code{diff-latest-backup-file},
@code{directory-file-name},
@code{directory-files},@*
@code{directory-files},
@code{dired-call-process},
@code{dired-compress-file}, @code{dired-uncache},
@code{expand-file-name},@*
@code{file-accessible-directory-p},
@code{file-attributes}, @code{file-directory-p},@*
@code{file-executable-p}, @code{file-exists-p}, @code{file-local-copy},
@code{file-modes}, @code{file-name-all-completions},
@code{file-name-as-directory}, @code{file-name-completion},@*
@code{expand-file-name},
@code{file-accessible-directory-p},@*
@code{file-attributes},
@code{file-directory-p},
@code{file-executable-p}, @code{file-exists-p},@*
@code{file-local-copy},
@code{file-modes}, @code{file-name-all-completions},@*
@code{file-name-as-directory},
@code{file-name-completion},
@code{file-name-directory},
@code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@ -2015,15 +1992,16 @@ Here are the operations that a magic file name handler gets to handle:
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
@code{get-file-buffer},
@code{insert-directory},@*
@code{get-file-buffer},@*
@code{insert-directory},
@code{insert-file-contents},
@code{load}, @code{make-directory},
@code{make-symbolic-link}, @code{rename-file}, @code{set-file-modes},
@code{set-visited-file-modtime}, @code{shell-command}.
@code{unhandled-file-name-directory},@*
@code{set-visited-file-modtime}, @code{shell-command}.@*
@code{unhandled-file-name-directory},
@code{vc-registered},
@code{verify-visited-file-modtime}, @code{write-region}.
@code{verify-visited-file-modtime},@*
@code{write-region}.
Handlers for @code{insert-file-contents} typically need to clear the
buffer's modified flag, with @code{(set-buffer-modified-p nil)}, if the
@ -2140,10 +2118,13 @@ A regular expression which is used to recognize files represented in
this format.
@item from-fn
A function or shell command to decode data in this format (to convert
A shell command or function to decode data in this format (to convert
file data into the usual Emacs data representation).
If @var{from-fn} is a function, it is called with two args, @var{begin}
A shell command is represented as a string; Emacs runs the command as a
filter to perform the conversion.
If @var{from-fn} is a function, it is called with two arguments, @var{begin}
and @var{end}, which specify the part of the buffer it should convert.
It should convert the text by editing it in place. Since this can
change the length of the text, @var{from-fn} should return the modified
@ -2153,17 +2134,14 @@ One responsibility of @var{from-fn} is to make sure that the beginning
of the file no longer matches @var{regexp}. Otherwise it is likely to
get called again.
If @var{from-fn} is a string, it is a shell command; Emacs runs the
command as a filter to perform the conversion.
@item to-fn
A function or shell command to encode data in this format (to convert
the usual Emacs data representation into this format).
A shell command or function to encode data in this format---that is, to
convert the usual Emacs data representation into this format.
If @var{to-fn} is a string, it is a shell command; Emacs runs the
command as a filter to perform the conversion.
If @var{to-fn} is a function, it is called with two args, @var{begin}
If @var{to-fn} is a function, it is called with two arguments, @var{begin}
and @var{end}, which specify the part of the buffer it should convert.
There are two ways it can do the conversion:
@ -2209,7 +2187,7 @@ buffer-local variable @code{buffer-file-format}.
@defvar buffer-file-format
This variable states the format of the visited file. More precisely,
this is a list of the file format names that were decoded in the course
of visiting the current buffer's file. It is always local in all
of visiting the current buffer's file. It is always buffer-local in all
buffers.
@end defvar
@ -2234,7 +2212,7 @@ The argument @var{format} is a list of format names. If @var{format} is
@key{RET} for @var{format} specifies @code{nil}.
@end deffn
@deffn format-insert-file file format %optional beg end
@deffn Command format-insert-file file format &optional beg end
This command inserts the contents of file @var{file}, converting it
according to format @var{format}. If @var{beg} and @var{end} are
non-@code{nil}, they specify which part of the file to read, as in
@ -2254,62 +2232,5 @@ This variable specifies the format to use for auto-saving. Its value is
a list of format names, just like the value of
@code{buffer-file-format}; but it is used instead of
@code{buffer-file-format} for writing auto-save files. This variable
is always local in all buffers.
is always buffer-local in all buffers.
@end defvar
@node Files and MS-DOS
@section Files and MS-DOS
@cindex MS-DOS file types
@cindex file types on MS-DOS
@cindex text files and binary files
@cindex binary files and text files
@cindex Windows file types
@c ??? This needs to be updated.
Emacs on MS-DOS and on Windows NT or 95 makes a distinction between
text files and binary files. This is necessary because ordinary text
files on MS-DOS use a two character sequence between lines:
carriage-return and linefeed (@sc{crlf}). Emacs expects just a newline
character (a linefeed) between lines. When Emacs reads or writes a text
file on MS-DOS, it needs to convert the line separators. This means it
needs to know which files are text files and which are binary. It makes
this decision when visiting a file, and records the decision in the
variable @code{buffer-file-type} for use when the file is saved.
@xref{MS-DOS Subprocesses}, for a related feature for subprocesses.
@defvar buffer-file-type
This variable, automatically local in each buffer, records the file type
of the buffer's visited file. The value is @code{nil} for text,
@code{t} for binary.
@end defvar
@defun find-buffer-file-type filename
This function determines whether file @var{filename} is a text file
or a binary file. It returns @code{nil} for text, @code{t} for binary.
@end defun
@defopt file-name-buffer-file-type-alist
This variable holds an alist for distinguishing text files from binary
files. Each element has the form (@var{regexp} . @var{type}), where
@var{regexp} is matched against the file name, and @var{type} may be
@code{nil} for text, @code{t} for binary, or a function to call to
compute which. If it is a function, then it is called with a single
argument (the file name) and should return @code{t} or @code{nil}.
@end defopt
@defopt default-buffer-file-type
This variable specifies the default file type for files whose names
don't indicate anything in particular. Its value should be @code{nil}
for text, or @code{t} for binary.
@end defopt
@deffn Command find-file-text filename
Like @code{find-file}, but treat the file as text regardless of its name.
@end deffn
@deffn Command find-file-binary filename
Like @code{find-file}, but treat the file as binary regardless of its
name.
@end deffn

246
lispref/frames.texi
View file

@ -18,10 +18,10 @@ horizontally into smaller windows.
@dfn{terminal frame}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
When Emacs communicates directly with an X server, it does not have a
terminal frame; instead, it starts with a single @dfn{X window frame}.
It can display multiple X window frames at the same time, each in its
own X window.
When Emacs communicates directly with a supported window system, such
as X Windows, it does not have a terminal frame; instead, it starts with
a single @dfn{window frame}, but you can create more, and Emacs can
display several such frames at once as is usual for window systems.
@defun framep object
This predicate returns @code{t} if @var{object} is a frame, and
@ -30,7 +30,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
@menu
* Creating Frames:: Creating additional frames.
* Multiple Displays:: Creating frames on other X displays.
* Multiple Displays:: Creating frames on other displays.
* Frame Parameters:: Controlling frame size, position, font, etc.
* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
@ -40,7 +40,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
* Raising and Lowering:: Raising a frame makes it hide other X windows;
* Raising and Lowering:: Raising a frame makes it hide other windows;
lowering it makes the others hide them.
* Frame Configurations:: Saving the state of all frames.
* Mouse Tracking:: Getting events that say when the mouse moves.
@ -48,7 +48,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* X Selections:: Transferring text to and from other X clients.
* Window System Selections:: Transferring text to and from other X clients.
* Font Names:: Looking up font names.
* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
@ -63,16 +63,17 @@ This predicate returns @code{t} if @var{object} is a frame, and
To create a new frame, call the function @code{make-frame}.
@defun make-frame &optional alist
This function creates a new frame. If you are using X, it makes
an X window frame; otherwise, it makes a terminal frame.
This function creates a new frame. If you are using a supported window
system, it makes a window frame; otherwise, it makes a terminal frame.
The argument is an alist specifying frame parameters. Any parameters
not mentioned in @var{alist} default according to the value of the
variable @code{default-frame-alist}; parameters not specified even there
default from the standard X defaults file and X resources.
default from the standard X resources or whatever is used instead on
your system.
The set of possible parameters depends in principle on what kind of
window system Emacs uses to display its frames. @xref{X Frame
window system Emacs uses to display its frames. @xref{Window Frame
Parameters}, for documentation of individual parameters you can specify.
@end defun
@ -95,7 +96,7 @@ frame just created.
@cindex multiple X terminals
@cindex displays, multiple
A single Emacs can talk to more than one X Windows display.
A single Emacs can talk to more than one X Window display.
Initially, Emacs uses just one display---the one chosen with the
@code{DISPLAY} environment variable or with the @samp{--display} option
(@pxref{Initial Options,,, emacs, The GNU Emacs Manual}). To connect to
@ -108,7 +109,8 @@ have values local to the current terminal (that is, the terminal
corresponding to the currently selected frame): these are
@code{default-minibuffer-frame}, @code{defining-kbd-macro},
@code{last-kbd-macro}, and @code{system-key-alist}. These variables are
always terminal-local and can never be buffer-local.
always terminal-local and can never be buffer-local or frame-local
(@pxref{Buffer-Local Variables}).
A single X server can handle more than one screen. A display name
@samp{@var{host}.@var{server}.@var{screen}} has three parts; the last
@ -163,12 +165,13 @@ uses.
Frame parameters exist for the sake of window systems. A terminal frame
has a few parameters, mostly for compatibility's sake; only the height,
width and @code{buffer-predicate} parameters really do something.
width, @code{name}, @code{title}, @code{buffer-list} and
@code{buffer-predicate} parameters do something special.
@menu
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
* X Frame Parameters:: List of frame parameters.
* Window Frame Parameters:: List of frame parameters for window systems.
* Size and Position:: Changing the size and position of a frame.
@end menu
@ -199,7 +202,7 @@ by setting @code{initial-frame-alist} in your @file{.emacs} file.
@defvar initial-frame-alist
This variable's value is an alist of parameter values used when creating
the initial X window frame. You can set this variable to specify the
the initial window frame. You can set this variable to specify the
appearance of the initial frame without altering subsequent frames.
Each element has the form:
@ -239,8 +242,9 @@ to the parameters for the main initial frame.
@defvar default-frame-alist
This is an alist specifying default values of frame parameters for all
Emacs frames---the first frame, and subsequent frames. In many cases,
you can get the same results by means of X resources.
Emacs frames---the first frame, and subsequent frames. When using the X
Window System, you can get the same results by means of X resources
in many cases.
@end defvar
See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
@ -251,28 +255,34 @@ exception is @samp{-geometry}, which adds the specified position to
@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
The GNU Emacs Manual}.
@node X Frame Parameters
@subsection X Window Frame Parameters
@node Window Frame Parameters
@subsection Window Frame Parameters
Just what parameters a frame has depends on what display mechanism it
uses. Here is a table of the parameters of an X window frame; of these,
@code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
provide meaningful information in non-X frames.
uses. Here is a table of the parameters that have special meanings in a
window frame; of these, @code{name}, @code{title}, @code{height},
@code{width}, @code{buffer-list} and @code{buffer-predicate} provide
meaningful information in terminal frames.
@table @code
@item title
If a frame has a non-@code{nil} title, it appears in the window system's
border for the frame, and also in the mode line of windows in that frame
if @code{mode-line-frame-identification} uses @samp{%F}
(@pxref{%-Constructs}). This is normally the case when Emacs is not
using a window system, and can only display one frame at a time.
@xref{Frame Titles}.
@item name
The name of the frame. Most window managers display the frame's name in
the frame's border, at the top of the frame. If you don't specify a
name, and you have more than one frame, Emacs sets the frame name based
on the buffer displayed in the frame's selected window.
The name of the frame. The frame name serves as a default for the frame
title, if the @code{title} parameter is unspecified or @code{nil}. If
you don't specify a name, Emacs sets the frame name automatically
(@pxref{Frame Titles}).
If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
Since a non-window terminal can display only one frame at a time, the
frame name appears in the mode line.
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@ -287,8 +297,9 @@ negative @var{pos} value.
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the right edge of the
window with respect to the right edge of the screen. A positive value
of @var{pos} counts toward the left. If the parameter is a negative
integer @minus{}@var{pos} then @var{pos} is positive!
of @var{pos} counts toward the left. @strong{Reminder:} if the
parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
positive.
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
@ -303,8 +314,9 @@ negative @var{pos} value.
A negative number @minus{}@var{pos}, or a list of the form @code{(-
@var{pos})}, actually specifies the position of the bottom edge of the
window with respect to the bottom edge of the screen. A positive value
of @var{pos} counts toward the top. If the parameter is a negative
integer @minus{}@var{pos} then @var{pos} is positive!
of @var{pos} counts toward the top. @strong{Reminder:} if the
parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
positive.
Some window managers ignore program-specified positions. If you want to
be sure the position you specify is not ignored, specify a
@ -348,7 +360,7 @@ The width of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
@item window-id
The number of the X window for the frame.
The number of the window-system window used by the frame.
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means
@ -360,12 +372,13 @@ the new frame uses that minibuffer.
The buffer-predicate function for this frame. The function
@code{other-buffer} uses this predicate (from the selected frame) to
decide which buffers it should consider, if the predicate is not
@code{nil}. It calls the predicate with one arg, a buffer, once for
@code{nil}. It calls the predicate with one argument, a buffer, once for
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
@item buffer-list
A list of buffers recently selected in this frame.
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.
@item font
The name of the font for displaying text in the frame. This is a
@ -401,8 +414,8 @@ The name to use in the icon for this frame, when and if the icon
appears. If this is @code{nil}, the frame's title is used.
@item foreground-color
The color to use for the image of a character. This is a string; the X
server defines the meaningful color names.
The color to use for the image of a character. This is a string; the
window system defines the meaningful color names.
@item background-color
The color to use for the background of characters.
@ -507,7 +520,7 @@ Size}.
@defun x-parse-geometry geom
@cindex geometry specification
The function @code{x-parse-geometry} converts a standard X windows
The function @code{x-parse-geometry} converts a standard X Windows
geometry string to an alist that you can use as part of the argument to
@code{make-frame}.
@ -560,24 +573,25 @@ the second.
@node Frame Titles
@section Frame Titles
Every frame has a title; most window managers display the frame title at
the top of the frame. You can specify an explicit title with the
@code{name} frame property. But normally you don't specify this
explicitly, and Emacs computes the title automatically.
Every frame has a @code{name} parameter; this serves as the default
for the frame title which window systems typically display at the top of
the frame. You can specify a name explicitly by setting the @code{name}
frame property.
Emacs computes the frame title based on a template stored in the
variable @code{frame-title-format}.
Normally you don't specify the name explicitly, and Emacs computes the
frame name automatically based on a template stored in the variable
@code{frame-title-format}. Emacs recomputes the name each time the
frame is redisplayed.
@defvar frame-title-format
This variable specifies how to compute a title for a frame
when you have not explicitly specified one.
The variable's value is actually a mode line construct, just like
@code{mode-line-format}. @xref{Mode Line Data}.
This variable specifies how to compute a name for a frame when you have
not explicitly specified one. The variable's value is actually a mode
line construct, just like @code{mode-line-format}. @xref{Mode Line
Data}.
@end defvar
@defvar icon-title-format
This variable specifies how to compute the title for an iconified frame,
This variable specifies how to compute the name for an iconified frame,
when you have not explicitly specified the frame title. This title
appears in the icon itself.
@end defvar
@ -694,11 +708,11 @@ This function returns the window on @var{frame} that is selected within
@var{frame}.
@end defun
Conversely, selecting a window for Emacs with @code{select-window} also
Conversely, selecting a window for Emacs with @code{select-window} also
makes that window selected within its frame. @xref{Selecting Windows}.
Another function that (usually) returns one of the windows in a frame is
@code{minibuffer-window}. @xref{Minibuffer Misc}.
Another function that (usually) returns one of the windows in a given
frame is @code{minibuffer-window}. @xref{Minibuffer Misc}.
@node Minibuffers and Frames
@section Minibuffers and Frames
@ -736,23 +750,23 @@ window always resides on the selected frame.
This function returns the selected frame.
@end defun
The X server normally directs keyboard input to the X window that the
mouse is in. Some window managers use mouse clicks or keyboard events
to @dfn{shift the focus} to various X windows, overriding the normal
behavior of the server.
Some window systems and window managers direct keyboard input to the
window object that the mouse is in; others require explicit clicks or
commands to @dfn{shift the focus} to various window objects. Either
way, Emacs automatically keeps track of which frame has the focus.
Lisp programs can switch frames ``temporarily'' by calling
the function @code{select-frame}. This does not override the window
manager; rather, it escapes from the window manager's control until
that control is somehow reasserted.
Lisp programs can also switch frames ``temporarily'' by calling the
function @code{select-frame}. This does not alter the window system's
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.
When using a text-only terminal, there is no window manager; therefore,
@code{switch-frame} is the only way to switch frames, and the effect
lasts until overridden by a subsequent call to @code{switch-frame}.
Only the selected terminal frame is actually displayed on the terminal.
Each terminal screen except for the initial one has a number, and the
number of the selected frame appears in the mode line after the word
@samp{Emacs} (@pxref{Mode Line Variables}).
When using a text-only terminal, only the selected terminal frame is
actually displayed on the terminal. @code{switch-frame} is the only way
to switch frames, and the change lasts until overridden by a subsequent
call to @code{switch-frame}. Each terminal screen except for the
initial one has a number, and the number of the selected frame appears
in the mode line after the word @samp{Emacs} (@pxref{Mode Line
Variables}).
@c ??? This is not yet implemented properly.
@defun select-frame frame
@ -762,10 +776,10 @@ the next time the user does something to select a different frame, or
until the next time this function is called.
@end defun
Emacs cooperates with the X server and the window managers by arranging
to select frames according to what the server and window manager ask
for. It does so by generating a special kind of input event, called a
@dfn{focus} event. The command loop handles a focus event by calling
Emacs cooperates with the window system by arranging to select frames as
the server and window manager request. It does so by generating a
special kind of input event, called a @dfn{focus} event, when
appropriate. The command loop handles a focus event by calling
@code{handle-switch-frame}. @xref{Focus Events}.
@deffn Command handle-switch-frame frame
@ -806,6 +820,14 @@ The redirection lasts until @code{redirect-frame-focus} is called to
change it.
@end defun
@tindex focus-follows-mouse
@defopt focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a
position consistent with the new selected frame.
@end defopt
@node Visibility of Frames
@section Visibility of Frames
@cindex visible frame
@ -813,7 +835,7 @@ change it.
@cindex iconified frame
@cindex frame visibility
An X window frame may be @dfn{visible}, @dfn{invisible}, or
A window frame may be @dfn{visible}, @dfn{invisible}, or
@dfn{iconified}. If it is visible, you can see its contents. If it is
iconified, the frame's contents do not appear on the screen, but an icon
does. If the frame is invisible, it doesn't show on the screen, not
@ -844,7 +866,7 @@ This returns the visibility status of frame @var{frame}. The value is
@end defun
The visibility status of a frame is also available as a frame
parameter. You can read or change it as such. @xref{X Frame
parameter. You can read or change it as such. @xref{Window Frame
Parameters}.
The user can iconify and deiconify frames with the window manager.
@ -855,23 +877,23 @@ changes. @xref{Misc Events}.
@node Raising and Lowering
@section Raising and Lowering Frames
The X Window System uses a desktop metaphor. Part of this metaphor is
Most window systems use a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
to ``lowest''. Where two X windows overlap, the one higher up covers
the one underneath. Even an X window at the bottom of the stack can be
seen if no other X window overlaps it.
to ``lowest''. Where two windows overlap, the one higher up covers
the one underneath. Even a window at the bottom of the stack can be
seen if no other window overlaps it.
@cindex raising a frame
@cindex lowering a frame
An X window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. @dfn{Raising} an X window means moving
it ``up'', to the top of the stack. @dfn{Lowering} an X window means
A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. @dfn{Raising} a window means moving
it ``up'', to the top of the stack. @dfn{Lowering} a window means
moving it to the bottom of the stack. This motion is in the notional
third dimension only, and does not change the position of the X window
third dimension only, and does not change the position of the window
on the screen.
You can raise and lower Emacs's X windows with these functions:
You can raise and lower Emacs frame Windows with these functions:
@deffn Command raise-frame frame
This function raises frame @var{frame}.
@ -888,7 +910,7 @@ that the minibuffer window is in.
You can also enable auto-raise (raising automatically when a frame is
selected) or auto-lower (lowering automatically when it is deselected)
for any frame using frame parameters. @xref{X Frame Parameters}.
for any frame using frame parameters. @xref{Window Frame Parameters}.
@node Frame Configurations
@section Frame Configurations
@ -896,6 +918,7 @@ for any frame using frame parameters. @xref{X Frame Parameters}.
A @dfn{frame configuration} records the current arrangement of frames,
all their properties, and the window configuration of each one.
(@xref{Window Configurations}.)
@defun current-frame-configuration
This function returns a frame configuration list that describes
@ -925,12 +948,15 @@ mouse forever---only until some other event, such as the release of a
button.
@defspec track-mouse body@dots{}
Execute @var{body}, meanwhile generating input events for mouse motion.
The code in @var{body} can read these events with @code{read-event} or
@code{read-key-sequence}. @xref{Motion Events}, for the format of mouse
motion events.
This special form executes @var{body}, with generation of mouse motion
events enabled. Typically @var{body} would use @code{read-event} to
read the motion events and modify the display accordingly. @xref{Motion
Events}, for the format of mouse motion events.
The value of @code{track-mouse} is that of the last form in @var{body}.
You should design @var{body} to return when it sees the up-event that
indicates the release of the button, or whatever kind of event means
it is time to stop tracking.
@end defspec
The usual purpose of tracking mouse motion is to indicate on the screen
@ -947,7 +973,7 @@ Lisp-level mouse tracking.
These functions change the screen appearance instantaneously. The
effect is transient, only until the next ordinary Emacs redisplay. That
is ok for mouse tracking, since it doesn't make sense for mouse tracking
is OK for mouse tracking, since it doesn't make sense for mouse tracking
to change the text, and the body of @code{track-mouse} normally reads
the events itself and does not do redisplay.
@ -1015,8 +1041,8 @@ characters. These coordinates are not required to be within the frame.
@node Pop-Up Menus
@section Pop-Up Menus
When using X windows, a Lisp program can pop up a menu which the
user can choose from with the mouse.
When using a window system, a Lisp program can pop up a menu so that
the user can choose an alternative with the mouse.
@defun x-popup-menu position menu
This function displays a pop-up menu and returns an indication of
@ -1083,13 +1109,13 @@ the menu keymap as necessary.
@section Dialog Boxes
@cindex dialog boxes
A dialog box is a variant of a pop-up menu. It looks a little
different (if Emacs uses an X toolkit), it always appears in the center
of a frame, and it has just one level and one pane. The main use of
dialog boxes is for asking questions that the user can answer with
``yes'', ``no'', and a few other alternatives. The functions
@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
keyboard, when called from commands invoked by mouse clicks.
A dialog box is a variant of a pop-up menu---it looks a little
different, it always appears in the center of a frame, and it has just
one level and one pane. The main use of dialog boxes is for asking
questions that the user can answer with ``yes'', ``no'', and a few other
alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
dialog boxes instead of the keyboard, when called from commands invoked
by mouse clicks.
@defun x-popup-dialog position contents
This function displays a pop-up dialog box and returns an indication of
@ -1121,9 +1147,9 @@ Dialog boxes always appear in the center of a frame; the argument
@code{x-popup-menu}, but the precise coordinates don't matter; only the
frame matters.
If your Emacs executable does not use an X toolkit, then it cannot
display a real dialog box; so instead it displays the same items in a
pop-up menu in the center of the frame.
In some configurations, Emacs cannot display a real dialog box; so
instead it displays the same items in a pop-up menu in the center of the
frame.
@end defun
@node Pointer Shapes
@ -1132,7 +1158,7 @@ pop-up menu in the center of the frame.
@cindex mouse pointer shape
These variables specify which shape to use for the mouse pointer in
various situations:
various situations, when using the X Window System:
@table @code
@item x-pointer-shape
@ -1149,14 +1175,14 @@ is over mouse-sensitive text.
These variables affect newly created frames. They do not normally
affect existing frames; however, if you set the mouse color of a frame,
that also updates its pointer shapes based on the current values of
these variables. @xref{X Frame Parameters}.
these variables. @xref{Window Frame Parameters}.
The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
@key{RET} x-pointer @key{RET}} to see a list of them.
@node X Selections
@section X Selections
@node Window System Selections
@section Window System Selections
@cindex selection (for X windows)
The X server records a set of @dfn{selections} which permit transfer of
@ -1221,9 +1247,9 @@ like the way successive kills in Emacs move down the kill ring.
@defun x-list-font pattern &optional face frame maximum
This function returns a list of available font names that match
@var{pattern}. If the optional arguments FACE and FRAME are specified,
then the list is limited to fonts that are the same size as @var{face}
currently is on @var{frame}.
@var{pattern}. If the optional arguments @var{face} and @var{frame} are
specified, then the list is limited to fonts that are the same size as
@var{face} currently is on @var{frame}.
The argument @var{pattern} should be a string, perhaps with wildcard
characters: the @samp{*} character matches any substring, and the

92
lispref/functions.texi
View file

@ -112,8 +112,8 @@ byte compiler. @xref{Byte-Code Type}.
@tindex functionp
@defun functionp object
This function returns @code{t} if @var{object} is any kind of function;
that is, anything that could be called as a function.
This function returns @code{t} if @var{object} is any kind of function,
or a special form or macro.
@end defun
@defun subrp object
@ -386,7 +386,7 @@ facilities. @xref{Documentation}, for how the @var{documentation-string} is
accessed.
It is a good idea to provide documentation strings for all the
functions in your program, even those that are only called from within
functions in your program, even those that are called only from within
your program. Documentation strings are like comments, except that they
are easier to access.
@ -419,7 +419,7 @@ as the return value and as the documentation.
In most computer languages, every function has a name; the idea of a
function without a name is nonsensical. In Lisp, a function in the
strictest sense has no name. It is simply a list whose first element is
@code{lambda}, or a primitive subr-object.
@code{lambda}, a byte-code function object, or a primitive subr-object.
However, a symbol can serve as the name of a function. This happens
when you put the function in the symbol's @dfn{function cell}
@ -580,7 +580,8 @@ name it calls is written in your program. This means that you choose
which function to call, and how many arguments to give it, when you
write the program. Usually that's just what you want. Occasionally you
need to compute at run time which function to call. To do that, use the
functions @code{funcall} and @code{apply}.
function @code{funcall}. When you also need to determine at run time
how may arguments to pass, use @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
@ -690,15 +691,19 @@ This function ignores any arguments and returns @code{nil}.
list or other collection. Emacs Lisp has several such functions;
@code{mapcar} and @code{mapconcat}, which scan a list, are described
here. @xref{Creating Symbols}, for the function @code{mapatoms} which
maps over the symbols in an obarray. @xref{Char-Tables}, for the
function @code{map-char-table}, which maps over the elements in a
char-table.
maps over the symbols in an obarray.
These mapping functions do not allow char-tables because a char-table
is a sparse array whose nominal range of indices is very large. To map
over a char-table in a way that deals properly with its sparse nature,
use the function @code{map-char-table} (@pxref{Char-Tables}).
@defun mapcar function sequence
@code{mapcar} applies @var{function} to each element of @var{sequence}
in turn, and returns a list of the results.
The argument @var{sequence} may be a list, a vector, or a string. The
The argument @var{sequence} can be any kind of sequence except a
char-table; that is, a list, a vector, a bool-vector, or a string. The
result is always a list. The length of the result is the same as the
length of @var{sequence}.
@ -720,14 +725,14 @@ length of @var{sequence}.
@end group
@group
(defun mapcar* (f &rest args)
(defun mapcar* (function &rest args)
"Apply FUNCTION to successive cars of all ARGS.
Return the list of results."
;; @r{If no list is exhausted,}
(if (not (memq 'nil args))
;; @r{apply function to @sc{CAR}s.}
(cons (apply f (mapcar 'car args))
(apply 'mapcar* f
;; @r{apply function to @sc{car}s.}
(cons (apply function (mapcar 'car args))
(apply 'mapcar* function
;; @r{Recurse for rest of elements.}
(mapcar 'cdr args)))))
@end group
@ -747,7 +752,9 @@ Between each pair of result strings, @code{mapconcat} inserts the string
other suitable punctuation.
The argument @var{function} must be a function that can take one
argument and return a string.
argument and return a string. The argument @var{sequence} can be any
kind of sequence except a char-table; that is, a list, a vector, a
bool-vector, or a string.
@smallexample
@group
@ -823,7 +830,7 @@ uses a function as its third argument:
@noindent
Here we define a function that uses @code{change-property},
passing a function that doubles its argument:
passing it a function to double a number:
@example
@group
@ -978,15 +985,18 @@ There are three normal uses of this function:
@itemize @bullet
@item
Copying one symbol's function definition to another. (In other words,
making an alternate name for a function.)
Copying one symbol's function definition to another---in other words,
making an alternate name for a function. (If you think of this as the
definition of the new name, you should use @code{defalias} instead of
@code{fset}; see @ref{Defining Functions}.)
@item
Giving a symbol a function definition that is not a list and therefore
cannot be made with @code{defun}. For example, you can use @code{fset}
to give a symbol @code{s1} a function definition which is another symbol
@code{s2}; then @code{s1} serves as an alias for whatever definition
@code{s2} presently has.
@code{s2} presently has. (Once again use @code{defalias} instead of
@code{fset} if you think of this as the definition of @code{s1}.)
@item
In constructs for defining or altering functions. If @code{defun}
@ -994,21 +1004,17 @@ were not a primitive, it could be written in Lisp (as a macro) using
@code{fset}.
@end itemize
Here are examples of the first two uses:
Here are examples of these uses:
@example
@group
;; @r{Give @code{first} the same definition @code{car} has.}
(fset 'first (symbol-function 'car))
@result{} #<subr car>
@end group
@group
(first '(1 2 3))
@result{} 1
;; @r{Save @code{foo}'s definition in @code{old-foo}.}
(fset 'old-foo (symbol-function 'foo))
@end group
@group
;; @r{Make the symbol @code{car} the function definition of @code{xfirst}.}
;; @r{(Most likely, @code{defalias} would be better than @code{fset} here.)}
(fset 'xfirst 'car)
@result{} car
@end group
@ -1030,10 +1036,14 @@ Here are examples of the first two uses:
(fset 'kill-two-lines "\^u2\^k")
@result{} "\^u2\^k"
@end group
@end example
See also the related function @code{defalias}, in @ref{Defining
Functions}.
@group
;; @r{Here is a function that alters other functions.}
(defun copy-function-definition (new old)
"Define NEW with the same function definition as OLD."
(fset new (symbol-function old)))
@end group
@end example
@end defun
When writing a function that extends a previously defined function,
@ -1058,7 +1068,8 @@ proper results. The only way to avoid this problem is to make sure the
file is loaded before moving aside the old definition of @code{foo}.
But it is unmodular and unclean, in any case, for a Lisp file to
redefine a function defined elsewhere.
redefine a function defined elsewhere. It is cleaner to use the advice
facility (@pxref{Advising Functions}).
@node Inline Functions
@section Inline Functions
@ -1083,15 +1094,14 @@ advantage of inline functions is greatest for small functions, you
generally should not make large functions inline.
It's possible to define a macro to expand into the same code that an
inline function would execute. But the macro would have a limitation:
you can use it only explicitly---a macro cannot be called with
inline function would execute. (@xref{Macros}.) But the macro would be
limited to direct use in expressions---a macro cannot be called with
@code{apply}, @code{mapcar} and so on. Also, it takes some work to
convert an ordinary function into a macro. (@xref{Macros}.) To convert
it into an inline function is very easy; simply replace @code{defun}
with @code{defsubst}. Since each argument of an inline function is
evaluated exactly once, you needn't worry about how many times the
body uses the arguments, as you do for macros. (@xref{Argument
Evaluation}.)
convert an ordinary function into a macro. To convert it into an inline
function is very easy; simply replace @code{defun} with @code{defsubst}.
Since each argument of an inline function is evaluated exactly once, you
needn't worry about how many times the body uses the arguments, as you
do for macros. (@xref{Argument Evaluation}.)
Inline functions can be used and open-coded later on in the same file,
following the definition, just like macros.
@ -1127,6 +1137,9 @@ See @ref{Eval}.
@item funcall
See @ref{Calling Functions}.
@item function
See @ref{Anonymous Functions}.
@item ignore
See @ref{Calling Functions}.
@ -1145,6 +1158,9 @@ See @ref{Creating Symbols}.
@item mapcar
See @ref{Mapping Functions}.
@item map-char-table
See @ref{Char-Tables}.
@item mapconcat
See @ref{Mapping Functions}.

94
lispref/help.texi
View file

@ -50,11 +50,11 @@ documentation string follows the initial value of the variable.
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 you have one, because that looks odd when you use @kbd{C-h f}
(@code{describe-function}) or @kbd{C-h v} (@code{describe-variable}).
@xref{Documentation Tips}.
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. @xref{Documentation Tips}.
Documentation strings may contain several special substrings, which
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
@ -132,7 +132,7 @@ non-@code{nil}) it calls @code{substitute-command-keys}, 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
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
@ -255,7 +255,7 @@ for in the directory @code{doc-directory}. Usually @var{filename} is
@c Emacs 19 feature
@defvar doc-directory
This variable holds the name of the directory which should contion the
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.
@ -288,12 +288,12 @@ 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 value of @var{mapvar}. The value should be
a keymap. The summary is made by @code{describe-bindings}.
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} as the keymap for any following
specifies @var{mapvar}'s value as the keymap for any following
@samp{\[@var{command}]} sequences in this documentation string.
@item \=
@ -331,7 +331,7 @@ user's own customized key bindings.
? minibuffer-completion-help
SPC minibuffer-complete-word
TAB minibuffer-complete
LFD minibuffer-complete-and-exit
C-j minibuffer-complete-and-exit
RET minibuffer-complete-and-exit
C-g abort-recursive-edit
"
@ -372,7 +372,7 @@ 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, linefeed, etc.@: appear as @samp{SPC}, @samp{LFD}, etc. A
and space, tab, etc.@: appear as @samp{SPC}, @samp{TAB}, etc. A
function key symbol appears as itself. An event that is a list appears
as the name of the symbol in the @sc{car} of the list.
@ -383,7 +383,7 @@ as the name of the symbol in the @sc{car} of the list.
@end group
@group
(key-description "\C-x \M-y \n \t \r \f123")
@result{} "C-x SPC M-y SPC LFD SPC TAB SPC RET SPC C-l 1 2 3"
@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 'C-mouse-1)
@ -423,7 +423,7 @@ 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 regexp &optional do-all predicate
@deffn Command apropos regexp &optional do-all
This function finds all symbols whose names contain a match for the
regular expression @var{regexp}, and returns a list of them
(@pxref{Regular Expressions}). It also displays the symbols in a buffer
@ -434,15 +434,9 @@ beginning of its documentation string.
If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
key bindings for the functions that are found.
If @var{predicate} is non-@code{nil}, it should be a function to be
called on each symbol that has matched @var{regexp}. Only symbols for
which @var{predicate} returns a non-@code{nil} value are listed or
displayed.
In the first of the following examples, @code{apropos} finds all the
symbols with names containing @samp{exec}. In the second example, it
finds and returns only those symbols that are also commands. (We don't
show here the output that results in the @samp{*Help*} buffer.)
symbols with names containing @samp{exec}. (We don't show here the
output that results in the @samp{*Help*} buffer.)
@smallexample
@group
@ -451,42 +445,7 @@ show here the output that results in the @samp{*Help*} buffer.)
exec-path execute-extended-command execute-kbd-macro
executing-kbd-macro executing-macro)
@end group
@group
(apropos "exec" nil 'commandp)
@result{} (Buffer-menu-execute execute-extended-command)
@end group
@ignore
@group
---------- Buffer: *Help* ----------
Buffer-menu-execute
Function: Save and/or delete buffers marked with
M-x Buffer-menu-save or M-x Buffer-menu-delete commands.
execute-extended-command ESC x
Function: Read function name, then read its
arguments and call it.
---------- Buffer: *Help* ----------
@end group
@end ignore
@end smallexample
The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
but specifies a @var{predicate} that restricts the output to symbols
that are commands. The call to @code{apropos} looks like this:
@smallexample
(apropos string t 'commandp)
@end smallexample
@end deffn
@c Emacs 19 feature
@deffn Command super-apropos regexp &optional do-all
This function differs from @code{apropos} in that it searches
documentation strings as well as symbol names for matches for
@var{regexp}. By default, it searches the documentation strings for
preloaded functions and variables only. If @var{do-all} is
non-@code{nil}, it scans the names and documentation strings of all
functions and variables.
@end deffn
@defvar help-map
@ -522,7 +481,7 @@ Documentation}.
@defvar help-char
The value of this variable is the help character---the character that
Emacs recognizes as meaning Help. By default, it is 8, which is
Emacs recognizes as meaning Help. By default, it stands for 8, which is
@kbd{C-h}. When Emacs reads this character, if @code{help-form} is
non-@code{nil} Lisp expression, it evaluates that expression, and
displays the result in a window if it is a string.
@ -539,6 +498,13 @@ binding as a subcommand of the prefix key, it runs
subcommands of the prefix key.
@end defvar
@tindex help-event-list
@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
@ -546,19 +512,19 @@ 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 exception is when @kbd{C-h} is meaningful input.)
Evaluating this expression should result in a string that explains what
the input is for and how to enter it properly.
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{Minibuffer Misc}).
@end defvar
@defvar prefix-help-command
This variable holds a function to print help for a prefix character.
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}.
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

228
lispref/internals.texi
View file

@ -12,14 +12,15 @@ the preloaded Lisp libraries in it, how storage is allocated, and some
internal aspects of GNU Emacs that may be of interest to C programmers.
@menu
* Building Emacs:: How to preload Lisp libraries into Emacs.
* Building Emacs:: How to the dumped Emacs is made.
* Pure Storage:: A kludge to make preloaded Lisp functions sharable.
* Garbage Collection:: Reclaiming space for Lisp objects no longer used.
* Memory Usage:: Info about total size of Lisp objects made so far.
* Writing Emacs Primitives:: Writing C code for Emacs.
* Object Internals:: Data formats of buffers, windows, processes.
@end menu
@node Building Emacs, Pure Storage, GNU Emacs Internals, GNU Emacs Internals
@node Building Emacs
@appendixsec Building Emacs
@cindex building Emacs
@pindex temacs
@ -118,54 +119,7 @@ If you want to use this function in an Emacs that was already dumped,
you must run Emacs with @samp{-batch}.
@end defun
@deffn Command emacs-version
This function returns a string describing the version of Emacs that is
running. It is useful to include this string in bug reports.
@example
@group
(emacs-version)
@result{} "GNU Emacs 20.2.5 (i486-pc-linux-gnulibc1, X toolkit)
of Sat Feb 14 1998 on psilocin.gnu.org"
@end group
@end example
Called interactively, the function prints the same information in the
echo area.
@end deffn
@defvar emacs-build-time
The value of this variable is the time at which Emacs was built at the
local site.
@example
@group
emacs-build-time
@result{} "Tue Jun 6 14:55:57 1995"
@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.
@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.2, the value is 20.
@end defvar
@defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
20.2, the value is 2.
@end defvar
@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
@node Pure Storage
@appendixsec Pure Storage
@cindex pure storage
@ -221,7 +175,7 @@ before and after dumping.
You should not change this flag in a running Emacs.
@end defvar
@node Garbage Collection, Writing Emacs Primitives, Pure Storage, GNU Emacs Internals
@node Garbage Collection
@appendixsec Garbage Collection
@cindex garbage collector
@ -291,11 +245,16 @@ information:
((@var{used-conses} . @var{free-conses})
(@var{used-syms} . @var{free-syms})
@end group
(@var{used-markers} . @var{free-markers})
(@var{used-miscs} . @var{free-miscs})
@var{used-string-chars}
@var{used-vector-slots}
(@var{used-floats} . @var{free-floats})
(@var{used-intervals} . @var{free-intervals}))
@end example
Here is an example:
@example
@group
(garbage-collect)
@result{} ((106886 . 13184) (9769 . 0)
@ -321,12 +280,13 @@ The number of symbols in use.
The number of symbols for which space has been obtained from the
operating system, but that are not currently being used.
@item used-markers
The number of markers in use.
@item used-miscs
The number of miscellaneous objects in use. These include markers and
overlays, plus certain objects not visible to users.
@item free-markers
The number of markers for which space has been obtained from the
operating system, but that are not currently being used.
@item free-miscs
The number of miscellaneous objects for which space has been obtained
from the operating system, but that are not currently being used.
@item used-string-chars
The total size of all strings, in characters.
@ -373,6 +333,11 @@ until the subsequent garbage collection, at which time
@code{garbage-collect} will set the threshold back to 10,000.
@end defopt
The value return by @code{garbage-collect} describes the amount of
memory used by Lisp data, broken down by data type. By contrast, the
function @code{memory-limit} provides information on the total amount of
memory Emacs is currently using.
@c Emacs 19 feature
@defun memory-limit
This function returns the address of the last byte Emacs has allocated,
@ -383,7 +348,53 @@ You can use this to get a general idea of how your actions affect the
memory usage.
@end defun
@node Writing Emacs Primitives, Object Internals, Garbage Collection, GNU Emacs Internals
@node Memory Usage
@section Memory Usage
These functions and variables give information about the total amount
of memory allocation that Emacs has done, broken down by data type.
Note the difference between these and the values returned by
@code{(garbage-collect)}; those count objects that currently exist, but
these count the number or size of all allocations, including those for
objects that have since been freed.
@defvar cons-cells-consed
The total number of cons cells that have been allocated so far
in this Emacs session.
@end defvar
@defvar floats-consed
The total number of floats that have been allocated so far
in this Emacs session.
@end defvar
@defvar vector-cells-consed
The total number of vector cells that have been allocated so far
in this Emacs session.
@end defvar
@defvar symbols-consed
The total number of symbols that have been allocated so far
in this Emacs session.
@end defvar
@defvar string-chars-consed
The total number of string characters that have been allocated so far
in this Emacs session.
@end defvar
@defvar misc-objects-consed
The total number of miscellaneous objects that have been allocated so
far in this Emacs session. These include markers and overlays, plus
certain objects not visible to users.
@end defvar
@defvar intervals-consed
The total number of intervals that have been allocated so far
in this Emacs session.
@end defvar
@node Writing Emacs Primitives
@appendixsec Writing Emacs Primitives
@cindex primitive function internals
@ -576,57 +587,69 @@ visible in Lisp with a value that is always an integer.
@code{DEFVAR_BOOL} makes a C variable of type @code{int} visible in Lisp
with a value that is either @code{t} or @code{nil}.
If you define a file-scope C variable of type @code{Lisp_Object},
you must protect it for garbage-collection by calling @code{staticpro}
in @code{syms_of_@var{filename}}, like this:
@example
staticpro (&@var{variable});
@end example
Here is another example function, with more complicated arguments.
This comes from the code for the X Window System, and it demonstrates
the use of macros and functions to manipulate Lisp objects.
This comes from the code in @file{window.c}, and it demonstrates the use
of macros and functions to manipulate Lisp objects.
@smallexample
@group
DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
Scoordinates_in_window_p, 2, 2,
"xSpecify coordinate pair: \nXExpression which evals to window: ",
"Return non-nil if POSITIONS is in WINDOW.\n\
\(POSITIONS is a list, (SCREEN-X SCREEN-Y)\)\n\
"Return non-nil if COORDINATES is in WINDOW.\n\
COORDINATES is a cons of the form (X . Y), X and Y being distances\n\
...
@end group
@group
Returned value is list of positions expressed\n\
relative to window upper left corner.")
(coordinate, window)
register Lisp_Object coordinate, window;
If they are on the border between WINDOW and its right sibling,\n\
`vertical-line' is returned.")
(coordinates, window)
register Lisp_Object coordinates, window;
@{
register Lisp_Object xcoord, ycoord;
int x, y;
@end group
@group
if (!CONSP (coordinate)) wrong_type_argument (Qlistp, coordinate);
CHECK_WINDOW (window, 2);
xcoord = Fcar (coordinate);
ycoord = Fcar (Fcdr (coordinate));
CHECK_NUMBER (xcoord, 0);
CHECK_NUMBER (ycoord, 1);
CHECK_LIVE_WINDOW (window, 0);
CHECK_CONS (coordinates, 1);
x = XINT (Fcar (coordinates));
y = XINT (Fcdr (coordinates));
@end group
@group
if ((XINT (xcoord) < XINT (XWINDOW (window)->left))
|| (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
+ XINT (XWINDOW (window)->width))))
return Qnil;
/* @r{Subtracting from XFASTINT (xcoord) is safe}
@r{as long as we know the result is not negative.} */
XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
switch (coordinates_in_window (XWINDOW (window), &x, &y))
@{
case 0: /* NOT in window at all. */
return Qnil;
@end group
@group
if (XINT (ycoord) == (screen_height - 1))
return Qnil;
case 1: /* In text part of window. */
return Fcons (make_number (x), make_number (y));
@end group
@group
if ((XINT (ycoord) < XINT (XWINDOW (window)->top))
|| (XINT (ycoord) >= (XINT (XWINDOW (window)->top)
+ XINT (XWINDOW (window)->height)) - 1))
return Qnil;
case 2: /* In mode line of window. */
return Qmode_line;
@end group
@group
XFASTINT (ycoord) -= XFASTINT (XWINDOW (window)->top);
return (Fcons (xcoord, Fcons (ycoord, Qnil)));
case 3: /* On right border of window. */
return Qvertical_line;
@end group
@group
default:
abort ();
@}
@}
@end group
@end smallexample
@ -650,7 +673,7 @@ number of arguments. They work by calling @code{Ffuncall}.
@file{lisp.h} contains the definitions for some important macros and
functions.
@node Object Internals, , Writing Emacs Primitives, GNU Emacs Internals
@node Object Internals
@appendixsec Object Internals
@cindex object internals
@ -678,7 +701,7 @@ explicitly using a suitable predicate (@pxref{Type Predicates}).
* Process Internals:: Components of a process structure.
@end menu
@node Buffer Internals, Window Internals, Object Internals, Object Internals
@node Buffer Internals
@appendixsubsec Buffer Internals
@cindex internals, of buffer
@cindex buffer internals
@ -717,19 +740,19 @@ This field contains the syntax table for the buffer. @xref{Syntax Tables}.
@item downcase_table
This field contains the conversion table for converting text to lower case.
@xref{Case Table}.
@xref{Case Tables}.
@item upcase_table
This field contains the conversion table for converting text to upper case.
@xref{Case Table}.
@xref{Case Tables}.
@item case_canon_table
This field contains the conversion table for canonicalizing text for
case-folding search. @xref{Case Table}.
case-folding search. @xref{Case Tables}.
@item case_eqv_table
This field contains the equivalence table for case-folding search.
@xref{Case Table}.
@xref{Case Tables}.
@item display_table
This field contains the buffer's display table, or @code{nil} if it doesn't
@ -753,10 +776,11 @@ hence it is also included on the list @code{markers}. @xref{The Mark}.
This field is non-@code{nil} if the buffer's mark is active.
@item local_var_alist
This field contains the association list describing the variables local
in this buffer, and their values, with the exception of local variables
that have special slots in the buffer object. (Those slots are omitted
from this table.) @xref{Buffer-Local Variables}.
This field contains the association list describing the buffer-local
variable bindings of this buffer, not including the built-in
buffer-local bindings that that have special slots in the buffer object.
(Those slots are omitted from this table.) @xref{Buffer-Local
Variables}.
@item base_buffer
This field holds the buffer's base buffer (if it is an indirect buffer),
@ -777,9 +801,13 @@ decreasing end position.
This field holds a list of the overlays in this buffer that end after
the current overlay center position. They are sorted in order of
increasing beginning position.
@item enable_multibyte_characters
This field holds the buffer's local value of
@code{enable-multibyte-characters}---either @code{t} or @code{nil}.
@end table
@node Window Internals, Process Internals, Buffer Internals, Object Internals
@node Window Internals
@appendixsubsec Window Internals
@cindex internals, of window
@cindex window internals
@ -886,7 +914,7 @@ holds the mark position that made one end of that region. Otherwise,
this field is @code{nil}.
@end table
@node Process Internals, , Window Internals, Object Internals
@node Process Internals
@appendixsubsec Process Internals
@cindex internals, of process
@cindex process internals

109
lispref/intro.texi
View file

@ -504,7 +504,9 @@ for other purposes as well, such as writing editing commands.
with its own idiosyncrasies. Many of them were inspired by Maclisp,
which was written in the 1960's at MIT's Project MAC. Eventually the
implementors of the descendants of Maclisp came together and developed a
standard for Lisp systems, called Common Lisp.
standard for Lisp systems, called Common Lisp. In the mean time, 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.
@ -515,6 +517,10 @@ 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.
Emacs Lisp is not at all influenced by Scheme; but the GNU project has
an implementation of Scheme, called Guile. We use Guile for
extensibility in all new GNU software that calls for extensibility.
@node Conventions
@section Conventions
@ -529,6 +535,7 @@ manual. You may want to skip this section and refer back to it later.
* 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.
* Version Info:: Which Emacs version is running?
@end menu
@node Some Terms
@ -544,8 +551,9 @@ including those you write.
@cindex fonts
Examples of Lisp code appear in this font or form: @code{(list 1 2
3)}. Names that represent arguments or metasyntactic variables appear
in this font or form: @var{first-number}.
3)}. Names that represent metasyntactic variables, or arguments to a
function being described, appear in this font or form:
@var{first-number}.
@node nil and t
@subsection @code{nil} and @code{t}
@ -587,7 +595,8 @@ choosing, use @code{t}. The symbol @code{t} always has value @code{t}.
In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
evaluate to themselves. This is so that you do not need to quote them
to use them as constants in a program. An attempt to change their
values results in a @code{setting-constant} error. @xref{Accessing
values results in a @code{setting-constant} error. The same is true of
any symbol whose name starts with a colon (@samp{:}). @xref{Constant
Variables}.
@node Evaluation Notation
@ -675,7 +684,7 @@ 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
located.)
currently located.)
@example
---------- Buffer: foo ----------
@ -723,18 +732,18 @@ The description follows on succeeding lines, sometimes with examples.
@cindex special form descriptions
In a function description, the name of the function being described
appears first. It is followed on the same line by a list of parameters.
The names used for the parameters are also used in the body of the
description.
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 parameter list
indicates that the arguments for subsequent parameters may be omitted
(omitted parameters default to @code{nil}). Do not write
@code{&optional} when you call the function.
The 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 will always be followed by a single
parameter) indicates that any number of arguments can follow. The value
of the single following parameter will be a list of all these arguments.
argument name) indicates that any number of arguments can follow. The value
of the single following arguments name will be a list of all these arguments.
Do not write @code{&rest} when you call the function.
Here is a description of an imaginary function @code{foo}:
@ -760,15 +769,15 @@ More generally,
@end example
@end defun
Any parameter whose name contains the name of a type (e.g.,
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. Parameters named @var{object} may be of any type.
(@xref{Lisp Data Types}, for a list of Emacs object types.)
Parameters with other sorts of names (e.g., @var{new-file}) are
discussed specifically in the description of the function. In some
sections, features common to parameters of several functions are
described at the beginning.
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.
@ -780,7 +789,7 @@ interactively; macros process their arguments differently from functions
(the arguments are not evaluated), but are presented the same way.
Special form descriptions use a more complex notation to specify
optional and repeated parameters because they can break the argument
optional and repeated arguments because they can break the argument
list down into separate arguments in more complicated ways.
@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is
optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
@ -798,7 +807,8 @@ if @var{var} equals @var{to}. Here is an example:
@example
(count-loop (i 0 10)
(prin1 i) (princ " ")
(prin1 (aref vector i)) (terpri))
(prin1 (aref vector i))
(terpri))
@end example
If @var{from} and @var{to} are omitted, then @var{var} is bound to
@ -842,6 +852,59 @@ have not yet thought about executing.
User option descriptions have the same format, but `Variable' is
replaced by `User Option'.
@node Version Info
@section Version Information
These functions and variables provide information about which
version of Emacs is in use.
@deffn Command emacs-version
This function returns a string describing the version of Emacs that is
running. It is useful to include this string in bug reports.
@example
@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 example
Called interactively, the function prints the same information in the
echo area.
@end deffn
@defvar emacs-build-time
The value of this variable is the time at which Emacs was built at the
local site.
@example
@group
emacs-build-time
@result{} "Tue Jun 6 14:55:57 1995"
@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.
@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

301
lispref/keymaps.texi
View file

@ -44,9 +44,8 @@ found. The whole process is called @dfn{key lookup}.
A @dfn{keymap} is a table mapping event types to definitions (which
can be any Lisp objects, though only certain types are meaningful for
execution by the command loop). Given an event (or an event type) and a
keymap, Emacs can get the event's definition. Events include ordinary
@sc{ASCII} characters, function keys, and mouse actions (@pxref{Input
Events}).
keymap, Emacs can get the event's definition. Events include
characters, function keys, and mouse actions (@pxref{Input Events}).
A sequence of input events that form a unit is called a
@dfn{key sequence}, or @dfn{key} for short. A sequence of one event
@ -125,19 +124,20 @@ completely masks any lower-precedence keymap.
@item @var{vector}
If an element of a keymap is a vector, the vector counts as bindings for
all the @sc{ASCII} characters; vector element @var{n} is the binding for
the character with code @var{n}. This is a compact way to record lots
of bindings. A keymap with such a vector is called a @dfn{full keymap}.
Other keymaps are called @dfn{sparse keymaps}.
all the @sc{ASCII} characters, codes 0 through 127; vector element
@var{n} is the binding for the character with code @var{n}. This is a
compact way to record lots of bindings. A keymap with such a vector is
called a @dfn{full keymap}. Other keymaps are called @dfn{sparse
keymaps}.
When a keymap contains a vector, it always defines a binding for each
@sc{ASCII} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default binding
in the keymap. However, default bindings are still meaningful for
events that are not @sc{ASCII} characters. A binding of @code{nil} does
@emph{not} override lower-precedence keymaps; thus, if the local map
gives a binding of @code{nil}, Emacs uses the binding from the global
map.
character. Such a binding of @code{nil} overrides any default key
binding in the keymap. However, default bindings are still meaningful
for events that are not @sc{ASCII} characters. A binding of @code{nil}
does @emph{not} override lower-precedence keymaps; thus, if the local
map gives a binding of @code{nil}, Emacs uses the binding from the
global map.
@item @var{string}
@cindex keymap prompt string
@ -333,7 +333,7 @@ from @code{text-mode-map}:
@cindex prefix key
A @dfn{prefix key} is a key sequence whose binding is a keymap. The
keyamp defines what to do with key sequences that extend the prefix key.
keymap defines what to do with key sequences that extend the prefix key.
For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
also stored in the variable @code{ctl-x-map}. This keymap defines
bindings for key sequences starting with @kbd{C-x}.
@ -481,29 +481,27 @@ minor mode keymaps.
All the active keymaps are used together to determine what command to
execute when a key is entered. Emacs searches these maps one by one, in
order of decreasing precedence, until it finds a binding in one of the maps.
order of decreasing precedence, until it finds a binding in one of the
maps. The procedure for searching a single keymap is called @dfn{key
lookup}; see @ref{Key Lookup}.
Normally, Emacs @emph{first} searches for the key in the minor mode
Normally, Emacs first searches for the key in the minor mode
maps (one map at a time); if they do not supply a binding for the key,
Emacs searches the local map; if that too has no binding, Emacs then
searches the global map. However, if @code{overriding-local-map} is
non-@code{nil}, Emacs searches that map first, before the global map.
The procedure for searching a single keymap is called
@dfn{key lookup}; see @ref{Key Lookup}.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
same local keymap, you can think of the keymap as local to the mode. A
change to the local keymap of a buffer (using @code{local-set-key}, for
example) is seen also in the other buffers that share that keymap.
The local keymaps that are used for Lisp mode, C mode, and several
other major modes exist even if they have not yet been used. These
local maps are the values of the variables @code{lisp-mode-map},
@code{c-mode-map}, and so on. For most other modes, which are less
frequently used, the local keymap is constructed only when the mode is
used for the first time in a session.
The local keymaps that are used for Lisp mode and some other major
modes exist even if they have not yet been used. These local maps are
the values of variables such as @code{lisp-mode-map}. For most major
modes, which are less frequently used, the local keymap is constructed
only when the mode is used for the first time in a session.
The minibuffer has local keymaps, too; they contain various completion
and exit commands. @xref{Intro to Minibuffers}.
@ -593,11 +591,8 @@ enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
Note that elements of @code{minor-mode-map-alist} do not have the same
structure as elements of @code{minor-mode-alist}. The map must be the
@sc{cdr} of the element; a list with the map as the @sc{cadr} will not
do.
What's more, the keymap itself must appear in the @sc{cdr}. It does not
work to store a variable in the @sc{cdr} and make the map the value of
that variable.
do. The @sc{cadr} can be either a keymap (a list) or a symbol
whose function definition is a keymap.
When more than one minor mode keymap is active, their order of priority
is the order of @code{minor-mode-map-alist}. But you should design
@ -614,12 +609,12 @@ Lookup}).
This variable allows major modes to override the key bindings for
particular minor modes. The elements of this alist look like the
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
. @var{keymap})}. If a variable has an element
@code{minor-mode-overriding-map-alist}. that map overrides the one in
@code{minor-mode-map-alist}.
. @var{keymap})}. If a variable appears an element
@code{minor-mode-overriding-map-alist}, that element overrides any
element for the same variable in @code{minor-mode-map-alist}.
@code{minor-mode-overriding-map-alist} is automatically local in all
buffers.
@code{minor-mode-overriding-map-alist} is automatically buffer-local in
all buffers.
@end defvar
@defvar overriding-local-map
@ -688,10 +683,10 @@ keymap.
Let's use the term @dfn{keymap entry} to describe the value found by
looking up an event type in a keymap. (This doesn't include the item
string and other extra elements in menu key bindings because
string and other extra elements in menu key bindings, because
@code{lookup-key} and other key lookup functions don't include them in
the returned value.) While any Lisp object may be stored in a keymap as
a keymap entry, not all make sense for key lookup. Here is a list of
a keymap entry, not all make sense for key lookup. Here is a table of
the meaningful kinds of keymap entries:
@table @asis
@ -702,11 +697,6 @@ undefined key. When a keymap fails to mention an event type at all, and
has no default binding, that is equivalent to a binding of @code{nil}
for that event type.
@item @var{keymap}
@cindex keymap in keymap
The events used so far in the lookup form a prefix key. The next
event of the key sequence is looked up in @var{keymap}.
@item @var{command}
@cindex command in keymap
The events used so far in the lookup form a complete key,
@ -718,6 +708,11 @@ The array (either a string or a vector) is a keyboard macro. The events
used so far in the lookup form a complete key, and the array is its
binding. See @ref{Keyboard Macros}, for more information.
@item @var{keymap}
@cindex keymap in keymap
The events used so far in the lookup form a prefix key. The next
event of the key sequence is looked up in @var{keymap}.
@item @var{list}
@cindex list in keymap
The meaning of a list depends on the types of the elements of the list.
@ -807,23 +802,9 @@ of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
Here are the functions and variables pertaining to key lookup.
@defun lookup-key keymap key &optional accept-defaults
This function returns the definition of @var{key} in @var{keymap}. If
the string or vector @var{key} is not a valid key sequence according to
the prefix keys specified in @var{keymap}, it must be ``too long'' and
have extra events at the end that do not fit into a single key sequence.
Then the value is a number, the number of events at the front of
@var{key} that compose a complete key.
@c Emacs 19 feature
If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
considers default bindings as well as bindings for the specific events
in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
the specific sequence @var{key}, ignoring default bindings except when
you explicitly ask about them. (To do this, supply @code{t} as an
element of @var{key}; see @ref{Format of Keymaps}.)
All the other functions described in this chapter that look up keys use
@code{lookup-key}.
This function returns the definition of @var{key} in @var{keymap}. All
the other functions described in this chapter that look up keys use
@code{lookup-key}. Here are examples:
@example
@group
@ -836,7 +817,21 @@ All the other functions described in this chapter that look up keys use
@end group
@end example
If @var{key} contains a meta character, that character is implicitly
If the string or vector @var{key} is not a valid key sequence according
to the prefix keys specified in @var{keymap}, it must be ``too long''
and have extra events at the end that do not fit into a single key
sequence. Then the value is a number, the number of events at the front
of @var{key} that compose a complete key.
@c Emacs 19 feature
If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
considers default bindings as well as bindings for the specific events
in @var{key}. Otherwise, @code{lookup-key} reports only bindings for
the specific sequence @var{key}, ignoring default bindings except when
you explicitly ask about them. (To do this, supply @code{t} as an
element of @var{key}; see @ref{Format of Keymaps}.)
If @var{key} contains a meta character, that character is implicitly
replaced by a two-character sequence: the value of
@code{meta-prefix-char}, followed by the corresponding non-meta
character. Thus, the first example below is handled by conversion into
@ -932,7 +927,7 @@ lookup translates @kbd{M-b} into @kbd{@key{ESC} b}, which is normally
defined as the @code{backward-word} command. However, if you set
@code{meta-prefix-char} to 24, the code for @kbd{C-x}, then Emacs will
translate @kbd{M-b} into @kbd{C-x b}, whose standard binding is the
@code{switch-to-buffer} command.
@code{switch-to-buffer} command. Here is an illustration:
@smallexample
@group
@ -995,11 +990,8 @@ event types in a key sequence that is a vector: you can use a list
containing modifier names plus one base event (a character or function
key name). For example, @code{(control ?a)} is equivalent to
@code{?\C-a} and @code{(hyper control left)} is equivalent to
@code{C-H-left}.
One advantage of using a list to represent the event type is that the
precise numeric codes for the modifier bits don't appear in compiled
files.
@code{C-H-left}. One advantage of such lists is that the precise
numeric codes for the modifier bits don't appear in compiled files.
For the functions below, an error is signaled if @var{keymap} is not a
keymap or if @var{key} is not a string or vector representing a key
@ -1016,12 +1008,10 @@ The value returned by @code{define-key} is @var{binding}.
@cindex invalid prefix key error
@cindex key sequence error
Every prefix of @var{key} must be a prefix key (i.e., bound to a
keymap) or undefined; otherwise an error is signaled.
If some prefix of @var{key} is undefined, then @code{define-key} defines
it as a prefix key so that the rest of @var{key} may be defined as
specified.
Every prefix of @var{key} must be a prefix key (i.e., bound to a keymap)
or undefined; otherwise an error is signaled. If some prefix of
@var{key} is undefined, then @code{define-key} defines it as a prefix
key so that the rest of @var{key} can be defined as specified.
If there was previously no binding for @var{key} in @var{keymap}, the
new binding is added at the beginning of @var{keymap}. The order of
@ -1383,7 +1373,7 @@ of a window.
@end smallexample
@noindent
These are not all the keymaps you would see in an actual case.
These are not all the keymaps you would see in actuality.
@end defun
@defun where-is-internal command &optional keymap firstonly noindirect
@ -1425,9 +1415,9 @@ an indirect definition itself.
@end defun
@deffn Command describe-bindings prefix
This function creates a listing of all defined keys and their
definitions. It writes the listing in a buffer named @samp{*Help*} and
displays it in a window.
This function creates a listing of all current key bindings, and
displays it in a buffer named @samp{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
If @var{prefix} is non-@code{nil}, it should be a prefix key; then the
listing includes only keys that start with @var{prefix}.
@ -1484,21 +1474,29 @@ moving to the top, if you care about the order. When you add an item to
an existing menu, you can specify its position in the menu using
@code{define-key-after} (@pxref{Modifying Menus}).
The individual bindings in the menu keymap should have item
strings; these strings become the items displayed in the menu. A
binding with an item string looks like this:
@menu
* Simple Menu Items::
* Extended Menu Items::
@end menu
@node Simple Menu Items
@subsubsection Simple Menu Items
The simpler and older way to define a menu keymap binding
looks like this:
@example
(@var{string} . @var{real-binding})
(@var{item-string} . @var{real-binding})
@end example
The item string for a binding should be short---one or two words. It
should describe the action of the command it corresponds to.
The @sc{car}, @var{item-string}, is the string to be displayed in the
menu. It should be short---preferably one to three words. It should
describe the action of the command it corresponds to.
You can also supply a second string, called the help string, as follows:
@example
(@var{string} @var{help-string} . @var{real-binding})
(@var{item-string} @var{help-string} . @var{real-binding})
@end example
Currently Emacs does not actually use @var{help-string}; it knows only
@ -1506,13 +1504,13 @@ how to ignore @var{help-string} in order to extract @var{real-binding}.
In the future we may use @var{help-string} as extended documentation for
the menu item, available on request.
As far as @code{define-key} is concerned, @var{string} and
As far as @code{define-key} is concerned, @var{item-string} and
@var{help-string} are part of the event's binding. However,
@code{lookup-key} returns just @var{real-binding}, and only
@var{real-binding} is used for executing the key.
If @var{real-binding} is @code{nil}, then @var{string} appears in the
menu but cannot be selected.
If @var{real-binding} is @code{nil}, then @var{item-string} appears in
the menu but cannot be selected.
If @var{real-binding} is a symbol and has a non-@code{nil}
@code{menu-enable} property, that property is an expression that
@ -1520,7 +1518,7 @@ controls whether the menu item is enabled. Every time the keymap is
used to display a menu, Emacs evaluates the expression, and it enables
the menu item only if the expression's value is non-@code{nil}. When a
menu item is disabled, it is displayed in a ``fuzzy'' fashion, and
cannot be selected with the mouse.
cannot be selected.
The menu bar does not recalculate which items are enabled every time you
look at a menu. This is because the X toolkit requires the whole tree
@ -1534,12 +1532,13 @@ binding, like this:
@c This line is not too long--rms.
@example
(@var{string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
(@var{item-string} @r{[}@var{help-string}@r{]} (@var{key-binding-data}) . @var{real-binding})
@end example
@noindent
Don't put these sublists in the menu item yourself; menu display
calculates them automatically. Don't add keyboard equivalents to the
item strings in a mouse menu, since that is redundant.
calculates them automatically. Don't mention keyboard equivalents in
the item strings themselves, since that is redundant.
Sometimes it is useful to make menu items that use the ``same'' command
but with different enable conditions. You can do this by defining alias
@ -1568,23 +1567,82 @@ itself). To request this, give the alias symbol a non-@code{nil}
causes menu items for @code{make-read-only} and @code{make-writable} to
show the keyboard bindings for @code{toggle-read-only}.
@node Extended Menu Items
@subsubsection Extended Menu Items
An extended-format menu item is a more flexible and also cleaner
alternative to the simple format. It consists of a list that starts
with the symbol @code{menu-item}. To define a non-selectable string,
the item looks like this:
@example
(menu-item @var{item-name})
@end example
@noindent
where a string consisting of two or more dashes specifies a separator line.
To define a real menu item which can be selected, the extended format
item looks like this:
@example
(menu-item @var{item-name} @var{real-binding}
. @var{item-property-list})
@end example
@noindent
Here, @var{item-name} is an expression which evaluates to the menu item
string. Thus, the string need not be a constant. The third element,
@var{real-binding}, is the command to execute. The tail of the list,
@var{item-property-list}, has the form of a property list which contains
other information. Here is a table of the properties that are supported:
@table @code
@item :enable FORM
The result of evaluating @var{form} determines whether the item is
enabled (non-@code{nil} means yes).
@item :visible FORM
The result of evaluating @var{form} determines whether the item should
actually appear in the menu (non-@code{nil} means yes). If the item
does not appear, then the menu is displayed as if this item were
not defined at all.
@item :help @var{help}
The value of this property, @var{help}, is the extra help string (not
currently used).
@item :button (@var{type} . @var{selected})
This property provides a way to define radio buttons and toggle buttons.
The @sc{car}, @var{type}, says which: is should be @code{:toggle} or
@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
result of evaluating it says whether this button is currently selected.
@item :filter @var{filter-fn}
This property provides a way to compute the menu item dynamically.
The property value @var{filter-fn} should be a function of one argument;
when it is called, its argument will be @var{real-binding}. The
function should return the binding to use instead.
@end table
@node Mouse Menus
@subsection Menus and the Mouse
The way to make a menu keymap produce a menu is to make it the
definition of a prefix key.
The usual way to make a menu keymap produce a menu is to make it the
definition of a prefix key. (A Lisp program can explicitly pop up a
menu and receive the user's choice---see @ref{Pop-Up Menus}.)
If the prefix key ends with a mouse event, Emacs handles the menu keymap
If the prefix key ends with a mouse event, Emacs handles the menu keymap
by popping up a visible menu, so that the user can select a choice with
the mouse. When the user clicks on a menu item, the event generated is
whatever character or symbol has the binding that brought about that
menu item. (A menu item may generate a series of events if the menu has
multiple levels or comes from the menu bar.)
It's often best to use a button-down event to trigger the menu. Then
It's often best to use a button-down event to trigger the menu. Then
the user can select a menu item by releasing the button.
A single keymap can appear as multiple menu panes, if you explicitly
A single keymap can appear as multiple menu panes, if you explicitly
arrange for this. The way to do this is to make a keymap for each pane,
then create a binding for each of those maps in the main keymap of the
menu. Give each of these bindings an item string that starts with
@ -1594,24 +1652,19 @@ bindings with @samp{@@}-less item strings are grouped into one pane,
which appears along with the other panes explicitly created for the
submaps.
X toolkit menus don't have panes; instead, they can have submenus.
X toolkit menus don't have panes; instead, they can have submenus.
Every nested keymap becomes a submenu, whether the item string starts
with @samp{@@} or not. In a toolkit version of Emacs, the only thing
special about @samp{@@} at the beginning of an item string is that the
@samp{@@} doesn't appear in the menu item.
You can also get multiple panes from separate keymaps. The full
definition of a prefix key always comes from merging the definitions
supplied by the various active keymaps (minor mode, local, and
global). When more than one of these keymaps is a menu, each of them
makes a separate pane or panes. @xref{Active Keymaps}.
In toolkit versions of Emacs, menus don't have panes, so submenus are
used to represent the separate keymaps. Each keymap's contribution
becomes one submenu.
A Lisp program can explicitly pop up a menu and receive the user's
choice. You can use keymaps for this also. @xref{Pop-Up Menus}.
You can also produce multiple panes or submenus from separate keymaps.
The full definition of a prefix key always comes from merging the
definitions supplied by the various active keymaps (minor mode, local,
and global). When more than one of these keymaps is a menu, each of
them makes a separate pane or panes (when Emacs does not use an
X-toolkit) or a separate submenu (when using an X-toolkit).
@xref{Active Keymaps}.
@node Keyboard Menus
@subsection Menus and the Keyboard
@ -1661,7 +1714,8 @@ menu bar. First we create the keymap, and give it a name:
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
@end example
Next we define the menu items:
@noindent
Next we define the menu items:
@example
(define-key menu-bar-print-menu [ps-print-region]
@ -1714,7 +1768,7 @@ item would be meaningless because @code{menu-bar-print-menu} is not a
command.
If you wanted to attach the same print menu to a mouse click, you
might do it this way:
can do it this way:
@example
(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
@ -1736,9 +1790,9 @@ so that pressing a button on the menu bar item leads to another menu.
When more than one active keymap defines the same fake function key
for the menu bar, the item appears just once. If the user clicks on
that menu bar item, it brings up a single, combined submenu containing
that menu bar item, it brings up a single, combined menu containing
all the subcommands of that item---the global subcommands, the local
subcommands, and the minor mode subcommands, all together.
subcommands, and the minor mode subcommands.
The variable @code{overriding-local-map} is normally ignored when
determining the menu bar contents. That is, the menu bar is computed
@ -1749,7 +1803,7 @@ were @code{nil}. @xref{Active Keymaps}.
parameter must be greater than zero. Emacs uses just one line for the
menu bar itself; if you specify more than one line, the other lines
serve to separate the menu bar from the windows in the frame. We
recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{X Frame
recommend 1 or 2 as the value of @code{menu-bar-lines}. @xref{Window Frame
Parameters}.
Here's an example of setting up a menu bar item:
@ -1768,7 +1822,7 @@ Parameters}.
@end group
@group
;; @r{Define specific subcommands in the item's menu.}
;; @r{Define specific subcommands in this menu.}
(define-key global-map
[menu-bar words forward]
'("Forward word" . forward-word))
@ -1800,7 +1854,7 @@ local maps.
This variable holds a list of fake function keys for items to display at
the end of the menu bar rather than in normal sequence. The default
value is @code{(help)}; thus, the @samp{Help} menu item normally appears
value is @code{(help-menu)}; thus, the @samp{Help} menu item normally appears
at the end of the menu bar, following local menu items.
@end defvar
@ -1823,9 +1877,12 @@ Define a binding in @var{map} for @var{key}, with value @var{binding},
just like @code{define-key}, but position the binding in @var{map} after
the binding for the event @var{after}. The argument @var{key} should be
of length one---a vector or string with just one element. But
@var{after} should be an event type---a symbol or a character.
@var{after} should be a single event type---a symbol or a character, not
a sequence. The new binding goes after the binding for @var{after}. If
@var{after} is @code{t}, then the new binding goes last, at the end of
the keymap.
For example,
Here is an example:
@example
(define-key-after my-menu [drink]
@ -1833,11 +1890,8 @@ For example,
@end example
@noindent
makes a binding for the fake function key @key{drink} and puts it
right after the binding for @key{eat}.
If @var{after} is @code{t}, then the new binding goes last---at the end
of the keymap.
makes a binding for the fake function key @key{DRINK} and puts it
right after the binding for @key{EAT}.
Here is how to insert an item called @samp{Work} in the @samp{Signals}
menu of Shell mode, after the item @code{break}:
@ -1847,7 +1901,4 @@ menu of Shell mode, after the item @code{break}:
(lookup-key shell-mode-map [menu-bar signals])
[work] '("Work" . work-command) 'break)
@end example
Note that @var{key} is a sequence containing just one event type, but
@var{after} is just an event type (not a sequence).
@end defun

87
lispref/lists.texi
View file

@ -92,8 +92,9 @@ like this:
@example
@group
___ ___ ___ ___
|___|___|--> |___|___|--> nil
--- --- --- ---
| | |--> | | |--> nil
--- --- --- ---
| |
| |
--> tulip --> lily
@ -106,14 +107,16 @@ two-element list:
@example
@group
___ ___ ___ ___ ___ ___
|___|___|--> |___|___|--> |___|___|--> nil
--- --- --- --- --- ---
| | |--> | | |--> | | |--> nil
--- --- --- --- --- ---
| | |
| | |
| --> oak --> maple
|
| ___ ___ ___ ___
--> |___|___|--> |___|___|--> nil
| --- --- --- ---
--> | | |--> | | |--> nil
--- --- --- ---
| |
| |
--> pine --> needles
@ -323,6 +326,10 @@ If @var{n} is negative, @code{nth} returns the first element of
(nth n x) @equiv{} (car (nthcdr n x))
@end group
@end example
The function @code{elt} is similar, but applies to any kind of sequence.
For historical reasons, it takes its arguments in the opposite order.
@xref{Sequence Functions}.
@end defun
@defun nthcdr n list
@ -351,7 +358,7 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
@end defun
@tindex safe-length
@defun safe-length sequence
@defun safe-length list
This function returns the length of @var{list}, with no risk
of either an error or an infinite loop.
@ -360,26 +367,30 @@ If @var{list} is not really a list, @code{safe-length} returns 0. If
number of distinct elements.
@end defun
The most common way to compute the length of a list, when you are not
worried that it may be circular, is with @code{length}. @xref{Sequence
Functions}.
@tindex caar
@defun caar list
This is the same as @code{(car (car @var{list}))}.
@defun caar cons-cell
This is the same as @code{(car (car @var{cons-cell}))}.
@end defun
@tindex cadr
@defun cadr list
This is the same as @code{(car (cdr @var{list}))}
or @code{(nth 1 @var{list})}.
@defun cadr cons-cell
This is the same as @code{(car (cdr @var{cons-cell}))}
or @code{(nth 1 @var{cons-cell})}.
@end defun
@tindex cdar
@defun cdar list
This is the same as @code{(cdr (car @var{list}))}.
@defun cdar cons-cell
This is the same as @code{(cdr (car @var{cons-cell}))}.
@end defun
@tindex cddr
@defun cddr list
This is the same as @code{(cdr (cdr @var{list}))}
or @code{(nthcdr 2 @var{list})}.
@defun cddr cons-cell
This is the same as @code{(cdr (cdr @var{cons-cell}))}
or @code{(nthcdr 2 @var{cons-cell})}.
@end defun
@node Building Lists
@ -470,9 +481,11 @@ elements have the identical value @var{object}. Compare
@defun append &rest sequences
@cindex copying lists
This function returns a list containing all the elements of
@var{sequences}. The @var{sequences} may be lists, vectors, or strings,
but the last one should usually be a list. All arguments except the
last one are copied, so none of the arguments is altered.
@var{sequences}. The @var{sequences} may be lists, vectors,
bool-vectors, or strings, but the last one should usually be a list.
All arguments except the last one are copied, so none of the arguments
is altered. (See @code{nconc} in @ref{Rearrangement}, for a way to join
lists with no copying.)
More generally, the final argument to @code{append} may be any Lisp
object. The final argument is not copied or converted; it becomes the
@ -482,9 +495,6 @@ result list. If the final element is not a list, the result is a
``dotted list'' since its final @sc{cdr} is not @code{nil} as required
in a true list.
See @code{nconc} in @ref{Rearrangement}, for a way to join lists with no
copying.
Here is an example of using @code{append}:
@example
@ -517,8 +527,9 @@ original list:
@group
more-trees trees
| |
| ___ ___ ___ ___ -> ___ ___ ___ ___
--> |___|___|--> |___|___|--> |___|___|--> |___|___|--> nil
| --- --- --- --- -> --- --- --- ---
--> | | |--> | | |--> | | |--> | | |--> nil
--- --- --- --- --- --- --- ---
| | | |
| | | |
--> maple -->birch --> pine --> oak
@ -535,7 +546,7 @@ trees
@result{} (pine oak)
@end group
@group
(setq wood (append trees ()))
(setq wood (append trees nil))
@result{} (pine oak)
@end group
@group
@ -552,6 +563,15 @@ wood
This once was the usual way to copy a list, before the function
@code{copy-sequence} was invented. @xref{Sequences Arrays Vectors}.
Here we show the use of vectors and strings as arguments to @code{append}:
@example
@group
(append [a b] "cd" nil)
@result{} (a b 99 100)
@end group
@end example
With the help of @code{apply}, we can append all the lists in a list of
lists:
@ -707,14 +727,16 @@ changes them both:
@example
@group
___ ___ ___ ___ ___ ___
x1---> |___|___|----> |___|___|--> |___|___|--> nil
--- --- --- --- --- ---
x1---> | | |----> | | |--> | | |--> nil
--- --- --- --- --- ---
| --> | |
| | | |
--> a | --> b --> c
|
___ ___ |
x2--> |___|___|--
--- --- |
x2--> | | |--
--- ---
|
|
--> z
@ -904,6 +926,8 @@ x
@end group
@end example
However, the other arguments (all but the last) must be lists.
A common pitfall is to use a quoted constant list as a non-last
argument to @code{nconc}. If you do this, your program will change
each time you run it! Here is what happens:
@ -1157,7 +1181,8 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
@end example
The following two functions are like @code{memq} and @code{delq} but use
@code{equal} rather than @code{eq} to compare elements.
@code{equal} rather than @code{eq} to compare elements. @xref{Equality
Predicates}.
@defun member object list
The function @code{member} tests to see whether @var{object} is a member

78
lispref/loading.texi
View file

@ -88,6 +88,10 @@ 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}.
@ -170,13 +174,6 @@ 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.
The command line options @samp{-l} or @samp{-load} specify a Lisp
library to load as part of Emacs startup. Since this file might be in
the current directory, Emacs 18 temporarily adds the current directory
to the front of @code{load-path} so the file can be found there. Newer
Emacs versions also find such files in the current directory, but
without altering @code{load-path}.
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
@ -233,7 +230,7 @@ Normally, the variable's value is @code{nil}, which means those
functions should use @code{read}.
@end defvar
To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
@ -265,11 +262,11 @@ as if it had been loaded all along.
@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 do nothing on their own; 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. Magic
comments are the most convenient way to make a function autoload, but
only for packages installed along with Emacs.
any time. Magic comments are the most convenient way to make a function
autoload, for packages installed along with Emacs. They 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
@ -287,10 +284,10 @@ in the function definition itself. 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.
If @var{interactive} is non-@code{nil}, then the function can be called
interactively. This lets completion in @kbd{M-x} work without loading
the function's real definition. The complete interactive specification
is not given here; it's not needed unless the user actually calls
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 its 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.
@ -365,8 +362,9 @@ function definition, it is copied verbatim. 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 @code{update-file-autoloads} copies
it to @file{loaddefs.el}, where it is executed while building Emacs.
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:
@ -400,7 +398,7 @@ documentation string in the @file{etc/DOC} file. @xref{Building Emacs}.
@section Repeated Loading
@cindex repeated loading
You may load one file more than once in an Emacs session. For
You can load one 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.
@ -411,8 +409,8 @@ 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 says, ``(compiled; source is newer'', to
remind you to recompile.
displayed when loading the file includes, @samp{(compiled; 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
@ -445,17 +443,17 @@ already been loaded. Here's one way to test, in a library, whether it
has been loaded before:
@example
(defvar foo-was-loaded)
(defvar foo-was-loaded nil)
(if (not (boundp 'foo-was-loaded))
@var{execute-first-time-only})
(setq foo-was-loaded t)
(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} to test whether the library has been loaded.
use @code{featurep} earlier in the file to test whether the
@code{provide} call has been executed before.
@ifinfo
@xref{Named Features}.
@end ifinfo
@ -486,9 +484,6 @@ 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
Features are normally named after the files that provide them, so that
@code{require} need not be given the file name.
For example, in @file{emacs/lisp/prolog.el},
the definition for @code{run-prolog} includes the following code:
@ -504,7 +499,8 @@ the definition for @code{run-prolog} includes the following code:
@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.
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:
@ -541,7 +537,7 @@ feature, as in the following example.
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 while loading.
does nothing when the file is loaded.
@defun provide feature
This function announces that @var{feature} is now loaded, or being
@ -589,7 +585,7 @@ provided}.
@defun featurep feature
This function returns @code{t} if @var{feature} has been provided in the
current Emacs session (i.e., @var{feature} is a member of
current Emacs session (i.e., if @var{feature} is a member of
@code{features}.)
@end defun
@ -612,10 +608,10 @@ reclaim memory for other Lisp objects. To do this, use the function
@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{defconst}, @code{defvar}, @code{defun},
@code{defmacro}, @code{defsubst} and @code{defalias}. It then restores
any autoloads formerly associated with those symbols. (Loading
saves these in the @code{autoload} property of the symbol.)
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.)
Ordinarily, @code{unload-feature} refuses to unload a library on which
other loaded libraries depend. (A library @var{a} depends on library
@ -686,9 +682,9 @@ 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 of programs to be
released.
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
An alist of expressions to evaluate if and when particular libraries are

104
lispref/locals.texi
View file

@ -8,143 +8,151 @@
@c The title "Standard Buffer-Local Variables" is too long for
@c smallbook. --rjc 30mar92
The table below lists the general-purpose Emacs variables that are
automatically local (when set) in each buffer. Many Lisp packages
define such variables for their internal use; we don't list them here.
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.
@table @code
@item abbrev-mode
@pxref{Abbrevs}
@xref{Abbrevs}.
@item auto-fill-function
@pxref{Auto Filling}
@xref{Auto Filling}.
@item buffer-auto-save-file-name
@pxref{Auto-Saving}
@xref{Auto-Saving}.
@item buffer-backed-up
@pxref{Backup Files}
@xref{Backup Files}.
@item buffer-display-count
@xref{Displaying Buffers}.
@item buffer-display-table
@pxref{Display Tables}
@xref{Display Tables}.
@item buffer-file-format
@pxref{Format Conversion}
@xref{Format Conversion}.
@item buffer-file-name
@pxref{Buffer File Name}
@xref{Buffer File Name}.
@item buffer-file-number
@pxref{Buffer File Name}
@xref{Buffer File Name}.
@item buffer-file-truename
@pxref{Buffer File Name}
@xref{Buffer File Name}.
@item buffer-file-type
@pxref{Files and MS-DOS}
@xref{MS-DOS File Types}.
@item buffer-invisibility-spec
@pxref{Invisible Text}
@xref{Invisible Text}.
@item buffer-offer-save
@pxref{Saving Buffers}
@xref{Saving Buffers}.
@item buffer-read-only
@pxref{Read Only Buffers}
@xref{Read Only Buffers}.
@item buffer-saved-size
@pxref{Point}
@xref{Point}.
@item buffer-undo-list
@pxref{Undo}
@xref{Undo}.
@item cache-long-line-scans
@pxref{Text Lines}
@xref{Text Lines}.
@item case-fold-search
@pxref{Searching and Case}
@xref{Searching and Case}.
@item ctl-arrow
@pxref{Usual Display}
@xref{Usual Display}.
@item comment-column
@pxref{Comments,,, emacs, The GNU Emacs Manual}
@xref{Comments,,, emacs, The GNU Emacs Manual}.
@item default-directory
@pxref{System Environment}
@xref{System Environment}.
@item defun-prompt-regexp
@pxref{List Motion}
@xref{List Motion}.
@item enable-multibyte-characters
@ref{Non-ASCII Characters}.
@item fill-column
@pxref{Auto Filling}
@xref{Auto Filling}.
@item goal-column
@pxref{Moving Point,,, emacs, The GNU Emacs Manual}
@xref{Moving Point,,, emacs, The GNU Emacs Manual}.
@item left-margin
@pxref{Indentation}
@xref{Indentation}.
@item local-abbrev-table
@pxref{Abbrevs}
@xref{Abbrevs}.
@item local-write-file-hooks
@pxref{Saving Buffers}
@xref{Saving Buffers}.
@item major-mode
@pxref{Mode Help}
@xref{Mode Help}.
@item mark-active
@pxref{The Mark}
@xref{The Mark}.
@item mark-ring
@pxref{The Mark}
@xref{The Mark}.
@item minor-modes
@pxref{Minor Modes}
@xref{Minor Modes}.
@item mode-line-buffer-identification
@pxref{Mode Line Variables}
@xref{Mode Line Variables}.
@item mode-line-format
@pxref{Mode Line Data}
@xref{Mode Line Data}.
@item mode-line-modified
@pxref{Mode Line Variables}
@xref{Mode Line Variables}.
@item mode-line-process
@pxref{Mode Line Variables}
@xref{Mode Line Variables}.
@item mode-name
@pxref{Mode Line Variables}
@xref{Mode Line Variables}.
@item overwrite-mode
@pxref{Insertion}
@xref{Insertion}.
@item paragraph-separate
@pxref{Standard Regexps}
@xref{Standard Regexps}.
@item paragraph-start
@pxref{Standard Regexps}
@xref{Standard Regexps}.
@item point-before-scroll
Used for communication between mouse commands and scroll-bar commands.
Ued for communication between mouse commands and scroll-bar commands..
@item require-final-newline
@pxref{Insertion}
@xref{Insertion}.
@item selective-display
@pxref{Selective Display}
@xref{Selective Display}.
@item selective-display-ellipses
@pxref{Selective Display}
@xref{Selective Display}.
@item tab-width
@pxref{Usual Display}
@xref{Usual Display}.
@item truncate-lines
@pxref{Truncation}
@xref{Truncation}.
@item vc-mode
@pxref{Mode Line Variables}
@xref{Mode Line Variables}.
@end table

81
lispref/macros.texi
View file

@ -48,11 +48,12 @@ Here's a macro definition that does the job:
@end group
@end example
When this is called with @code{(inc x)}, the argument @code{var} has
the value @code{x}---@emph{not} the @emph{value} of @code{x}. 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}.
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
@ -192,6 +193,7 @@ like this:
(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.
@ -210,8 +212,8 @@ called interactively.
@findex `
Macros often need to construct large list structures from a mixture of
constants and nonconstant parts. To make this easier, use the macro
@samp{`} (often called @dfn{backquote}).
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
@ -299,18 +301,16 @@ Here are some examples:
@end group
@end example
@quotation
Before Emacs 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{,@@} substition 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.
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 we recommend not using it in new programs.
@end quotation
@node Problems with Macros
@section Common Problems Using Macros
@ -371,10 +371,10 @@ For example, (for i from 1 to 10 do (print i))."
@end smallexample
@noindent
(The arguments @code{from}, @code{to}, and @code{do} in this macro are
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.)
in those positions in the macro call.
Here's an equivalent definition simplified through use of backquote:
@ -428,10 +428,8 @@ Here is a macro definition that creates this expansion:
@end group
@end smallexample
Unfortunately, this introduces another problem.
@ifinfo
Proceed to the following node.
@end ifinfo
Unfortunately, this fix introduces another problem,
described in the following section.
@node Surprising Local Vars
@subsection Local Variables in Macro Expansions
@ -536,17 +534,18 @@ it. Here is an example:
@code{x}, because @code{a} conflicts with the macro argument variable
@code{a}.
Another reason not to call @code{eval} in a macro definition is that
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.
The safe way to work with the run-time value of an expression is to
put the expression into the macro expansion, so that its value is
computed as part of executing the expansion. This is what the other
examples in this chapter do.
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?
@ -557,15 +556,25 @@ 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.
In particular, constructing objects is a kind of side effect. If the
macro is called once, then the objects are constructed only once. In
other words, the same structure of objects is used each time the macro
call is executed. In interpreted operation, the macro is reexpanded
each time, producing a fresh collection of objects each time. Usually
this does not matter---the objects have the same contents whether they
are shared or not. But if the surrounding program does side effects
on the objects, it makes a difference whether they are shared. Here is
an example:
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

15
lispref/maps.texi
View file

@ -29,15 +29,12 @@ A sparse keymap used by C mode.
A full keymap used by Command History mode.
@item ctl-x-4-map
@vindex ctl-x-4-map
A sparse keymap for subcommands of the prefix @kbd{C-x 4}.
@item ctl-x-5-map
@vindex ctl-x-5-map
A sparse keymap for subcommands of the prefix @kbd{C-x 5}.
@item ctl-x-map
@vindex ctl-x-map
A full keymap for @kbd{C-x} commands.
@item debugger-mode-map
@ -101,9 +98,9 @@ The keymap that displays the Special Props submenu of the Text
Properties menu.
@item function-key-map
@vindex function-key-map
The keymap for translating keypad and function keys.@*
If there are none, then it contains an empty sparse keymap.
@xref{Translating Input}.
@item fundamental-mode-map
@vindex fundamental-mode-map
@ -130,9 +127,8 @@ A keymap that defines the characters you can type within incremental
search.
@item key-translation-map
@vindex key-translation-map
A keymap for translating keys. This one overrides ordinary key
bindings, unlike @code{function-key-map}.
bindings, unlike @code{function-key-map}. @xref{Translating Input}.
@item lisp-interaction-mode-map
@vindex lisp-interaction-mode-map
@ -154,6 +150,11 @@ The keymap which displays the Files menu in the menu bar.
@vindex menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.
@tindex menu-bar-mule-menu
@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.
@ -163,7 +164,6 @@ The keymap which displays the Search menu in the menu bar.
The keymap which displays the Tools menu in the menu bar.
@item mode-specific-map
@vindex 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}),
@ -174,7 +174,6 @@ where it describes the main use of the @kbd{C-c} prefix key.
A local keymap used by Occur mode.
@item query-replace-map
@vindex query-replace-map
A local 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

42
lispref/markers.texi
View file

@ -44,9 +44,10 @@ 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 in front of
the new text---unless it is inserted with @code{insert-before-markers}
(@pxref{Insertion}).
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
@ -306,7 +307,9 @@ if they both point nowhere.
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}.
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.
@tindex set-marker-insertion-type
@defun set-marker-insertion-type marker type
@ -396,11 +399,12 @@ absence of a mark in that buffer.''
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 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).
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.
@ -529,20 +533,30 @@ consequence of this is that commands that modify the buffer normally
make the mark inactive.
@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, but only if
Transient Mark mode is enabled.
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.
@end defvar
@defun deactivate-mark
This function deactivates the mark, but only if Transient Mark mode
is enabled.
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 local in each buffer.
is always buffer-local in each buffer.
@end defvar
@defvar activate-mark-hook

159
lispref/minibuf.texi
View file

@ -13,8 +13,8 @@
arguments more complicated than the single numeric prefix argument.
These arguments include file names, buffer names, and command names (as
in @kbd{M-x}). The minibuffer is displayed on the bottom line of the
screen, in the same place as the echo area, but only while it is in
use for reading an argument.
frame, in the same place as the echo area, but only while it is in use
for reading an argument.
@menu
* Intro to Minibuffers:: Basic information about minibuffers.
@ -100,26 +100,25 @@ string; however, if @var{read} is non-@code{nil}, then it uses
@code{read} to convert the text into a Lisp object (@pxref{Input
Functions}).
The first thing this function does is to activate a minibuffer and
The first thing this function does is to activate a minibuffer and
display it with @var{prompt-string} as the prompt. This value must be a
string.
string. Then the user can edit text in the minibuffer.
Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end. The
minibuffer appears with this text as its contents.
When the user types a command to exit the minibuffer,
@code{read-from-minibuffer} constructs the return value from the text in
the minibuffer. Normally it returns a string containing that text.
However, if @var{read} is non-@code{nil}, @code{read-from-minibuffer}
reads the text and returns the resulting Lisp object, unevaluated.
(@xref{Input Functions}, for information about reading.)
@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for the same job.
It usually does not make sense to use both at once. In most cases, you
should use @var{default}, since this permits the user to insert the
default value but does not burden the user with deleting it from the
minibuffer.
@c Emacs 19 feature
The value of @var{initial-contents} may also be a cons cell of the form
@code{(@var{string} . @var{position})}. This means to insert
@var{string} in the minibuffer but put point @var{position} characters
from the beginning, rather than at the end.
The argument @var{default} specifies a default value to make available
through the history commands. It should be a string, or @code{nil}. If
@var{read} is non-@code{nil}, then @var{default} is also used as the
input to @code{read}, if the user enters empty input. However, in the
usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
does not return @var{default} when the user enters empty input; it
returns an empty string, @code{""}. In this respect, it is different
from all the other minibuffer input functions in this chapter.
If @var{keymap} is non-@code{nil}, that keymap is the local keymap to
use in the minibuffer. If @var{keymap} is omitted or @code{nil}, the
@ -131,30 +130,33 @@ The argument @var{hist} specifies which history list variable to use
for saving the input and for history commands used in the minibuffer.
It defaults to @code{minibuffer-history}. @xref{Minibuffer History}.
When the user types a command to exit the minibuffer,
@code{read-from-minibuffer} uses the text in the minibuffer to produce
its return value. Normally it simply makes a string containing that
text. However, if @var{read} is non-@code{nil},
@code{read-from-minibuffer} reads the text and returns the resulting
Lisp object, unevaluated. (@xref{Input Functions}, for information
about reading.)
If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
The argument @var{default} specifies a default value to make available
through the history list. It should be a string, or @code{nil}. If
@var{read} is non-@code{nil}, then @var{default} is passed through
@code{read}, just as ordinary user input would be. Unlike many other
minibuffer functions, this function does @emph{not} return @var{default}
if the user enters empty input. It returns @code{""} in that case.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.
If @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end, before the
user starts to edit the text. The minibuffer appears with this text as
its initial contents.
Alternatively, @var{initial-contents} can be a cons cell of the form
@code{(@var{string} . @var{position})}. This means to insert
@var{string} in the minibuffer but put point @var{position} characters
from the beginning, rather than at the end.
@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for more or less the
same job. It does not make sense to use both features in a single call
to @code{read-from-minibuffer}. In general, we recommend using
@var{default}, since this permits the user to insert the default value
when it is wanted, but does not burden the user with deleting it from
the minibuffer on other occasions.
@end defun
@defun read-string prompt &optional initial history default inherit-input-method
@ -177,8 +179,12 @@ This function is a simplified interface to the
@group
(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil nil
@var{history} @var{default} @var{inherit})
(let ((value
(read-from-minibuffer @var{prompt} @var{initial} nil nil
@var{history} @var{default} @var{inherit})))
(if (equal value "")
@var{default}
value))
@end group
@end smallexample
@end defun
@ -195,7 +201,7 @@ This is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@table @asis
@item @key{LFD}
@item @kbd{C-j}
@code{exit-minibuffer}
@item @key{RET}
@ -368,16 +374,16 @@ expression, thus moving point forward one word.
@cindex minibuffer history
@cindex history list
A @dfn{minibuffer history list} records previous minibuffer inputs so
A @dfn{minibuffer history list} records previous minibuffer inputs so
the user can reuse them conveniently. A history list is actually a
symbol, not a list; it is a variable whose value is a list of strings
(previous inputs), most recent first.
There are many separate history lists, used for different kinds of
There are many separate history lists, used for different kinds of
inputs. It's the Lisp programmer's job to specify the right history
list for each use of the minibuffer.
The basic minibuffer input functions @code{read-from-minibuffer} and
The basic minibuffer input functions @code{read-from-minibuffer} and
@code{completing-read} both accept an optional argument named @var{hist}
which is how you specify the history list. Here are the possible
values:
@ -395,18 +401,20 @@ If you specify @var{startpos}, then you should also specify that element
of the history as the initial minibuffer contents, for consistency.
@end table
If you don't specify @var{hist}, then the default history list
If you don't specify @var{hist}, then the default history list
@code{minibuffer-history} is used. For other standard history lists,
see below. You can also create your own history list variable; just
initialize it to @code{nil} before the first use.
Both @code{read-from-minibuffer} and @code{completing-read} add new
Both @code{read-from-minibuffer} and @code{completing-read} add new
elements to the history list automatically, and provide commands to
allow the user to reuse items on the list. The only thing your program
needs to do to use a history list is to initialize it and to pass its
name to the input functions when you wish. But it is safe to modify the
list by hand when the minibuffer input functions are not using it.
Here are some of the standard minibuffer history list variables:
@defvar minibuffer-history
The default history list for minibuffer history input.
@end defvar
@ -580,7 +588,7 @@ too short). Both of those begin with the string @samp{foobar}.
@defun all-completions string collection &optional predicate nospace
This function returns a list of all possible completions of
@var{string}. The parameters to this function are the same as to
@var{string}. The arguments to this function are the same as those of
@code{try-completion}.
If @var{collection} is a function, it is called with three arguments:
@ -624,10 +632,7 @@ minibuffer with completion.
@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
providing completion. It activates the minibuffer with prompt
@var{prompt}, which must be a string. If @var{initial} is
non-@code{nil}, @code{completing-read} inserts it into the minibuffer as
part of the input. Then it allows the user to edit the input, providing
several commands to attempt completion.
@var{prompt}, which must be a string.
The actual completion is done by passing @var{collection} and
@var{predicate} to the function @code{try-completion}. This happens in
@ -642,7 +647,8 @@ input already in the buffer matches an element of @var{collection}.
However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns
@var{default}.
@var{default}. The value of @var{default} (if non-@code{nil}) is also
available to the user through the history commands.
The user can exit with null input by typing @key{RET} with an empty
minibuffer. Then @code{completing-read} returns @code{""}. This is how
@ -661,8 +667,10 @@ The argument @var{hist} specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
The optional argument @var{default} specifies a default value to return
if the user enters null input; it should be a string.
If @var{initial} is non-@code{nil}, @code{completing-read} inserts it
into the minibuffer as part of the input. Then it allows the user to
edit the input, providing several commands to attempt completion.
In most cases, we recommend using @var{default}, and not @var{initial}.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@ -750,7 +758,7 @@ bindings:
@item @key{TAB}
@code{minibuffer-complete}
@item @key{LFD}
@item @kbd{C-j}
@code{minibuffer-complete-and-exit}
@item @key{RET}
@ -903,10 +911,10 @@ which @code{commandp} returns @code{t}, and a command name is a symbol
for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
The argument @var{default} specifies what to return if the user enters
null input. It can be a symbol or a string, but the value returned by
@code{read-command} is always a symbol. If @var{default} is @code{nil},
that means no default has been specified; then if the user enters null
input, the return value is @code{nil}.
null input. It can be a symbol or a string; if it is a string,
@code{read-command} interns it before returning it. If @var{default} is
@code{nil}, that means no default has been specified; then if the user
enters null input, the return value is @code{nil}.
@example
(read-command "Command name? ")
@ -948,10 +956,10 @@ This function reads the name of a user variable and returns it as a
symbol.
The argument @var{default} specifies what to return if the user enters
null input. It can be a symbol or a string, but the value returned by
@code{read-variable} is always a symbol. If @var{default} is
@code{nil}, that means no default has been specified; then if the user
enters null input, the return value is @code{nil}.
null input. It can be a symbol or a string; if it is a string,
@code{read-variable} interns it before returning it. If @var{default}
is @code{nil}, that means no default has been specified; then if the
user enters null input, the return value is @code{nil}.
@example
@group
@ -988,21 +996,8 @@ predicate @code{user-variable-p} instead of @code{commandp}:
@end example
@end defun
@tindex read-coding-system
@defun read-coding-system prompt default
This function reads a coding system using the minibuffer, prompting with
string @var{prompt}, and returns the coding system name as a symbol. If
the user tries to enter null input, it asks the user to try again.
@xref{Coding Systems}.
@end defun
@tindex read-non-nil-coding-system
@defun read-non-nil-coding-system prompt
This function reads a coding system using the minibuffer, prompting with
string @var{prompt},and returns the coding system name as a symbol. If
the user enters null input, it returns @var{default-coding-system}.
which should be a symbol or a string. @xref{Coding Systems}.
@end defun
See also the functions @code{read-coding-system} and
@code{read-non-nil-coding-system}, in @ref{Lisp and Coding Systems}.
@node Reading File Names
@subsection Reading File Names
@ -1037,7 +1032,8 @@ If you specify @var{initial}, that is an initial file name to insert in
the buffer (after with @var{directory}, if that is inserted). In this
case, point goes at the beginning of @var{initial}. The default for
@var{initial} is @code{nil}---don't insert any file name. To see what
@var{initial} does, try the command @kbd{C-x C-v}.
@var{initial} does, try the command @kbd{C-x C-v}. @strong{Note:} we
recommend using @var{default} rather than @var{initial} in most cases.
Here is an example:
@ -1153,7 +1149,7 @@ string is a unique and exact match already, or @code{nil} if the string
matches no possibility.
If the string is an exact match for one possibility, but also matches
other longer possibilities, the function shuold return the string, not
other longer possibilities, the function should return the string, not
@code{t}.
@item
@ -1533,15 +1529,14 @@ returns zero.
@defopt enable-recursive-minibuffers
If this variable is non-@code{nil}, you can invoke commands (such as
@code{find-file}) that use minibuffers even while in the minibuffer
window. Such invocation produces a recursive editing level for a new
@code{find-file}) that use minibuffers even while the minibuffer window
is active. Such invocation produces a recursive editing level for a new
minibuffer. The outer-level minibuffer is invisible while you are
editing the inner one.
This variable only affects invoking the minibuffer while the
minibuffer window is selected. If you switch windows while in the
minibuffer, you can always invoke minibuffer commands while some other
window is selected.
If this variable is @code{nil}, you cannot invoke minibuffer
commands when the minibuffer window is active, not even if you switch to
another window to do it.
@end defopt
@c Emacs 19 feature

607
lispref/modes.texi
View file

File diff suppressed because it is too large Load diff

215
lispref/nonascii.texi
View file

@ -20,9 +20,12 @@ characters and how they are stored in strings and buffers.
* Scanning Charsets::
* Chars and Bytes::
* Coding Systems::
* Lisp and Coding System::
* Default Coding Systems::
* Specifying Coding Systems::
* Explicit Encoding::
* MS-DOS File Types::
* MS-DOS Subprocesses::
@end menu
@node Text Representations
@ -41,8 +44,8 @@ attention to the difference.
In unibyte representation, each character occupies one byte and
therefore the possible character codes range from 0 to 255. Codes 0
through 127 are @sc{ASCII} characters; the codes from 128 through 255
are used for one non-@sc{ASCII} character set (you can choose which one
by setting the variable @code{nonascii-insert-offset}).
are used for one non-@sc{ASCII} character set (you can choose which
character set by setting the variable @code{nonascii-insert-offset}).
@cindex leading code
@cindex multibyte text
@ -67,9 +70,8 @@ This variable specifies the current buffer's text representation.
If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
it contains unibyte text.
@strong{Warning:} do not set this variable directly; instead, use the
function @code{set-buffer-multibyte} to change a buffer's
representation.
You cannot set this variable directly; instead, use the function
@code{set-buffer-multibyte} to change a buffer's representation.
@end defvar
@tindex default-enable-multibyte-characters
@ -112,17 +114,17 @@ to unibyte, even though this conversion cannot in general preserve all
the characters that might be in the multibyte text. The other natural
alternative, to convert the buffer contents to multibyte, is not
acceptable because the buffer's representation is a choice made by the
user that cannot simply be overrided.
user that cannot be overridden automatically.
Converting unibyte text to multibyte text leaves @sc{ASCII} characters
unchanged. It converts the non-@sc{ASCII} codes 128 through 255 by
adding the value @code{nonascii-insert-offset} to each character code.
By setting this variable, you specify which character set the unibyte
characters correspond to. For example, if @code{nonascii-insert-offset}
is 2048, which is @code{(- (make-char 'latin-iso8859-1 0) 128)}, then
the unibyte non-@sc{ASCII} characters correspond to Latin 1. If it is
2688, which is @code{(- (make-char 'greek-iso8859-7 0) 128)}, then they
correspond to Greek letters.
unchanged, and likewise 128 through 159. It converts the non-@sc{ASCII}
codes 160 through 255 by adding the value @code{nonascii-insert-offset}
to each character code. By setting this variable, you specify which
character set the unibyte characters correspond to. For example, if
@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
'latin-iso8859-1 0) 128)}, then the unibyte non-@sc{ASCII} characters
correspond to Latin 1. If it is 2688, which is @code{(- (make-char
'greek-iso8859-7 0) 128)}, then they correspond to Greek letters.
Converting multibyte text to unibyte is simpler: it performs
logical-and of each character code with 255. If
@ -150,22 +152,21 @@ This variable provides a more general alternative to
@code{nonascii-insert-offset}. You can use it to specify independently
how to translate each code in the range of 128 through 255 into a
multibyte character. The value should be a vector, or @code{nil}.
If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
@end defvar
@tindex string-make-unibyte
@defun string-make-unibyte string
This function converts the text of @var{string} to unibyte
representation, if it isn't already, and return the result. If
conversion does not change the contents, the value may be @var{string}
itself.
@var{string} is a unibyte string, it is returned unchanged.
@end defun
@tindex string-make-multibyte
@defun string-make-multibyte string
This function converts the text of @var{string} to multibyte
representation, if it isn't already, and return the result. If
conversion does not change the contents, the value may be @var{string}
itself.
@var{string} is a multibyte string, it is returned unchanged.
@end defun
@node Selecting a Representation
@ -188,8 +189,8 @@ representation.
This function sets @code{enable-multibyte-characters} to record which
representation is in use. It also adjusts various data in the buffer
(including its overlays, text properties and markers) so that they
cover or fall between the same text as they did before.
(including overlays, text properties and markers) so that they cover the
same text as they did before.
@end defun
@tindex string-as-unibyte
@ -198,7 +199,7 @@ This function returns a string with the same bytes as @var{string} but
treating each byte as a character. This means that the value may have
more characters than @var{string} has.
If @var{string} is unibyte already, then the value may be @var{string}
If @var{string} is unibyte already, then the value is @var{string}
itself.
@end defun
@ -208,7 +209,7 @@ This function returns a string with the same bytes as @var{string} but
treating each multibyte sequence as one character. This means that the
value may have fewer characters than @var{string} has.
If @var{string} is multibyte already, then the value may be @var{string}
If @var{string} is multibyte already, then the value is @var{string}
itself.
@end defun
@ -221,8 +222,9 @@ codes. The valid character codes for unibyte representation range from
0 to 255---the values that can fit in one byte. The valid character
codes for multibyte representation range from 0 to 524287, but not all
values in that range are valid. In particular, the values 128 through
255 are not valid in multibyte text. Only the @sc{ASCII} codes 0
through 127 are used in both representations.
255 are not legitimate in multibyte text (though they can occur in ``raw
bytes''; @pxref{Explicit Encoding}). Only the @sc{ASCII} codes 0
through 127 are fully legitimate in both representations.
@defun char-valid-p charcode
This returns @code{t} if @var{charcode} is valid for either one of the two
@ -249,11 +251,11 @@ only one character set.
In general, there is one character set for each distinct script. For
example, @code{latin-iso8859-1} is one character set,
@code{greek-iso8859-7} is another, and @code{ascii} is another. An
Emacs character set can hold at most 9025 characters; therefore. in some
cases, a set of characters that would logically be grouped together are
split into several character sets. For example, one set of Chinese
characters is divided into eight Emacs character sets,
@code{chinese-cns11643-1} through @code{chinese-cns11643-7}.
Emacs character set can hold at most 9025 characters; therefore, in some
cases, characters that would logically be grouped together are split
into several character sets. For example, one set of Chinese characters
is divided into eight Emacs character sets, @code{chinese-cns11643-1}
through @code{chinese-cns11643-7}.
@tindex charsetp
@defun charsetp object
@ -299,14 +301,17 @@ that appear in the string @var{string}.
In multibyte representation, each character occupies one or more
bytes. The functions in this section convert between characters and the
byte values used to represent them.
byte values used to represent them. For most purposes, there is no need
to be concerned with the number of bytes used to represent a character
because Emacs translates automatically when necessary.
@tindex char-bytes
@defun char-bytes character
This function returns the number of bytes used to represent the
character @var{character}. In most cases, this is the same as
@code{(length (split-char @var{character}))}; the only exception is for
ASCII characters, which use just one byte.
ASCII characters and the codes used in unibyte text, which use just one
byte.
@example
(char-bytes 2248)
@ -378,17 +383,18 @@ cases, Emacs supports several alternative encodings for the same
characters; for example, there are three coding systems for the Cyrillic
(Russian) alphabet: ISO, Alternativnyj, and KOI8.
@cindex end of line conversion
@dfn{End of line conversion} handles three different conventions used
on various systems for end of line. The Unix convention is to use the
linefeed character (also called newline). The DOS convention is to use
the two character sequence, carriage-return linefeed, at the end of a
line. The Mac convention is to use just carriage-return.
Most coding systems specify a particular character code for
conversion, but some of them leave this unspecified---to be chosen
heuristically based on the data.
@cindex end of line conversion
@dfn{End of line conversion} handles three different conventions used
on various systems for representing end of line in files. The Unix
convention is to use the linefeed character (also called newline). The
DOS convention is to use the two character sequence, carriage-return
linefeed, at the end of a line. The Mac convention is to use just
carriage-return.
@cindex base coding system
@cindex variant coding system
@dfn{Base coding systems} such as @code{latin-1} leave the end-of-line
@ -398,6 +404,9 @@ coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
well. Each base coding system has three corresponding variants whose
names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
@node Lisp and Coding Systems
@subsection Coding Systems in Lisp
Here are Lisp facilities for working with coding systems;
@tindex coding-system-list
@ -420,11 +429,21 @@ If that is valid, it returns @var{coding-system}.
Otherwise it signals an error with condition @code{coding-system-error}.
@end defun
@tindex find-safe-coding-system
@defun find-safe-coding-system from to
Return a list of proper coding systems to encode a text between
@var{from} and @var{to}. All coding systems in the list can safely
encode any multibyte characters in the text.
If the text contains no multibyte characters, return a list of a single
element @code{undecided}.
@end defun
@tindex detect-coding-region
@defun detect-coding-region start end highest
This function chooses a plausible coding system for decoding the text
from @var{start} to @var{end}. This text should be ``raw bytes''
(@pxref{Specifying Coding Systems}).
(@pxref{Explicit Encoding}).
Normally this function returns is a list of coding systems that could
handle decoding the text that was scanned. They are listed in order of
@ -471,6 +490,25 @@ This function looks up the target in @code{file-coding-system-alist},
@code{process-coding-system-alist}, or
@code{network-coding-system-alist}, depending on @var{operation}.
@xref{Default Coding Systems}.
@end defun
Here are two functions you can use to let the user specify a coding
system, with completion. @xref{Completion}.
@tindex read-coding-system
@defun read-coding-system prompt default
This function reads a coding system using the minibuffer, prompting with
string @var{prompt}, and returns the coding system name as a symbol. If
the user enters null input, @var{default} specifies which coding system
to return. It should be a symbol or a string.
@end defun
@tindex read-non-nil-coding-system
@defun read-non-nil-coding-system prompt
This function reads a coding system using the minibuffer, prompting with
string @var{prompt},and returns the coding system name as a symbol. If
the user tries to enter null input, it asks the user to try again.
@xref{Coding Systems}.
@end defun
@node Default Coding Systems
@ -480,9 +518,9 @@ This function looks up the target in @code{file-coding-system-alist},
certain files or when running certain subprograms. The idea of these
variables is that you set them once and for all to the defaults you
want, and then do not change them again. To specify a particular coding
system for a particular operation, don't change these variables;
instead, override them using @code{coding-system-for-read} and
@code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
system for a particular operation in a Lisp program, don't change these
variables; instead, override them using @code{coding-system-for-read}
and @code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
@tindex file-coding-system-alist
@defvar file-coding-system-alist
@ -519,7 +557,7 @@ other coding systems later using @code{set-process-coding-system}.
@defvar network-coding-system-alist
This variable is an alist that specifies the coding system to use for
network streams. It works much like @code{file-coding-system-alist},
with the difference that the @var{pattern} in an elemetn may be either a
with the difference that the @var{pattern} in an element may be either a
port number or a regular expression. If it is a regular expression, it
is matched against the network service name used to open the network
stream.
@ -561,7 +599,7 @@ of the right way to use the variable:
@example
;; @r{Read the file with no character code conversion.}
;; @r{Assume CRLF represents end-of-line.}
;; @r{Assume @sc{crlf} represents end-of-line.}
(let ((coding-system-for-write 'emacs-mule-dos))
(insert-file-contents filename))
@end example
@ -587,7 +625,7 @@ affect it.
@tindex last-coding-system-used
@defvar last-coding-system-used
All operations that use a coding system set this variable
All I/O operations that use a coding system set this variable
to the coding system name that was used.
@end defvar
@ -646,32 +684,34 @@ text. They are ``raw bytes''---bytes that represent text in the same
way that an external file would. When a buffer contains raw bytes, it
is most natural to mark that buffer as using unibyte representation,
using @code{set-buffer-multibyte} (@pxref{Selecting a Representation}),
but this is not required.
but this is not required. If the buffer's contents are only temporarily
raw, leave the buffer multibyte, which will be correct after you decode
them.
The usual way to get raw bytes in a buffer, for explicit decoding, is
to read them with from a file with @code{insert-file-contents-literally}
to read them from a file with @code{insert-file-contents-literally}
(@pxref{Reading from Files}) or specify a non-@code{nil} @var{rawfile}
arguments when visiting a file with @code{find-file-noselect}.
argument when visiting a file with @code{find-file-noselect}.
The usual way to use the raw bytes that result from explicitly
encoding text is to copy them to a file or process---for example, to
write it with @code{write-region} (@pxref{Writing to Files}), and
write them with @code{write-region} (@pxref{Writing to Files}), and
suppress encoding for that @code{write-region} call by binding
@code{coding-system-for-write} to @code{no-conversion}.
@tindex encode-coding-region
@defun encode-coding-region start end coding-system
This function encodes the text from @var{start} to @var{end} according
to coding system @var{coding-system}. The encoded text replaces
the original text in the buffer. The result of encoding is
``raw bytes.''
to coding system @var{coding-system}. The encoded text replaces the
original text in the buffer. The result of encoding is ``raw bytes,''
but the buffer remains multibyte if it was multibyte before.
@end defun
@tindex encode-coding-string
@defun encode-coding-string string coding-system
This function encodes the text in @var{string} according to coding
system @var{coding-system}. It returns a new string containing the
encoded text. The result of encoding is ``raw bytes.''
encoded text. The result of encoding is a unibyte string of ``raw bytes.''
@end defun
@tindex decode-coding-region
@ -689,3 +729,72 @@ system @var{coding-system}. It returns a new string containing the
decoded text. To make explicit decoding useful, the contents of
@var{string} ought to be ``raw bytes.''
@end defun
@node MS-DOS File Types
@section MS-DOS File Types
@cindex DOS file types
@cindex MS-DOS file types
@cindex Windows file types
@cindex file types on MS-DOS and Windows
@cindex text files and binary files
@cindex binary files and text files
Emacs on MS-DOS and on MS-Windows recognizes certain file names as
text files or binary files. For a text file, Emacs always uses DOS
end-of-line conversion. For a binary file, Emacs does no end-of-line
conversion and no character code conversion.
@defvar buffer-file-type
This variable, automatically buffer-local in each buffer, records the
file type of the buffer's visited file. The value is @code{nil} for
text, @code{t} for binary. When a buffer does not specify a coding
system with @code{buffer-file-coding-system}, this variable is used by
the function @code{find-buffer-file-type-coding-system} to determine
which coding system to use when writing the contents of the buffer.
@end defvar
@defopt file-name-buffer-file-type-alist
This variable holds an alist for recognizing text and binary files.
Each element has the form (@var{regexp} . @var{type}), where
@var{regexp} is matched against the file name, and @var{type} may be
@code{nil} for text, @code{t} for binary, or a function to call to
compute which. If it is a function, then it is called with a single
argument (the file name) and should return @code{t} or @code{nil}.
Emacs when running on MS-DOS or MS-Windows checks this alist to decide
which coding system to use when reading a file. For a text file,
@code{undecided-dos} is used. For a binary file, @code{no-conversion}
is used.
If no element in this alist matches a given file name, then
@code{default-buffer-file-type} says how to treat the file.
@end defopt
@defopt default-buffer-file-type
This variable says how to handle files for which
@code{file-name-buffer-file-type-alist} says nothing about the type.
If this variable is non-@code{nil}, then these files are treated as
binary. Otherwise, nothing special is done for them---the coding system
is deduced solely from the file contents, in the usual Emacs fashion.
@end defopt
@node MS-DOS Subprocesses
@section MS-DOS Subprocesses
On Microsoft operating systems, these variables provide an alternative
way to specify the kind of end-of-line conversion to use for input and
output. The variable @code{binary-process-input} applies to input sent
to the subprocess, and @code{binary-process-output} applies to output
received from it. A non-@code{nil} value means the data is ``binary,''
and @code{nil} means the data is text.
@defvar binary-process-input
If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
the input to a synchronous subprocess.
@end defvar
@defvar binary-process-output
If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
the output from a synchronous subprocess.
@end defvar

41
lispref/numbers.texi
View file

@ -12,9 +12,9 @@
@dfn{floating point numbers}. Integers are whole numbers such as
@minus{}3, 0, 7, 13, and 511. Their values are exact. Floating point
numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
2.71828. They can also be expressed in exponential notation:
1.5e2 equals 150; in this example, @samp{e2} stands for ten to the
second power, and is multiplied by 1.5. Floating point values are not
2.71828. They can also be expressed in exponential notation: 1.5e2
equals 150; in this example, @samp{e2} stands for ten to the second
power, and that is multiplied by 1.5. Floating point values are not
exact; they have a fixed, limited amount of precision.
@menu
@ -149,9 +149,9 @@ values. It also provides for a class of values called NaN or
there is no correct answer. For example, @code{(sqrt -1.0)} returns a
NaN. For practical purposes, there's no significant difference between
different NaN values in Emacs Lisp, and there's no rule for precisely
which NaN value should be used in a particular case, so this manual
which NaN value should be used in a particular case, so Emacs Lisp
doesn't try to distinguish them. Here are the read syntaxes for
these numbers:
these special floating point values:
@table @asis
@item positive infinity
@ -162,6 +162,10 @@ these numbers:
@samp{0.0e+NaN}.
@end table
In addition, the value @code{-0.0} is distinguishable from ordinary
zero in IEEE floating point (although @code{equal} and @code{=} consider
them equal values).
You can use @code{logb} to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
@ -323,6 +327,10 @@ This function returns the smallest of its arguments.
@end example
@end defun
@defun abs number
This returns the absolute value of @var{number}.
@end defun
@node Numeric Conversions
@section Numeric Conversions
@cindex rounding in conversions
@ -378,7 +386,7 @@ commonly used.
All of these functions except @code{%} return a floating point value
if any argument is floating.
It is important to note that in GNU Emacs Lisp, arithmetic functions
It is important to note that in Emacs Lisp, arithmetic functions
do not check for overflow. Thus @code{(1+ 134217727)} may evaluate to
@minus{}134217728, depending on your hardware.
@ -414,10 +422,6 @@ like this:
This function returns @var{number-or-marker} minus 1.
@end defun
@defun abs number
This returns the absolute value of @var{number}.
@end defun
@defun + &rest numbers-or-markers
This function adds its arguments together. When given no arguments,
@code{+} returns 0.
@ -478,8 +482,10 @@ permits machine-dependent rounding. As a practical matter, all known
machines round in the standard fashion.
@cindex @code{arith-error} in division
If you divide by 0, an @code{arith-error} error is signaled.
(@xref{Errors}.)
If you divide an integer by 0, an @code{arith-error} error is signaled.
(@xref{Errors}.) Floating point division by zero returns either
infinity or a NaN if your machine supports IEEE floating point;
otherwise, it signals an @code{arith-error} error.
@example
@group
@ -488,6 +494,12 @@ If you divide by 0, an @code{arith-error} error is signaled.
@end group
(/ 5 2)
@result{} 2
(/ 5.0 2)
@result{} 2.5
(/ 5 2.0)
@result{} 2.5
(/ 5.0 2.0)
@result{} 2.5
(/ 25 3 2)
@result{} 4
(/ -17 6)
@ -925,9 +937,8 @@ bit is one in the result if, and only if, the @var{n}th bit is zero in
@cindex transcendental functions
@cindex mathematical functions
These mathematical functions are available if floating point is
supported. They allow integers as well as floating point numbers
as arguments.
These mathematical functions allow integers as well as floating point
numbers as arguments.
@defun sin arg
@defunx cos arg

327
lispref/objects.texi
View file

@ -25,7 +25,7 @@ but not for ``the'' type of an object.
which all other types are constructed, are called @dfn{primitive
types}. Each object belongs to one and only one primitive type. These
types include @dfn{integer}, @dfn{float}, @dfn{cons}, @dfn{symbol},
@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, and
@dfn{string}, @dfn{vector}, @dfn{subr}, @dfn{byte-code function}, plus
several special types, such as @dfn{buffer}, that are related to
editing. (@xref{Editing Types}.)
@ -69,8 +69,9 @@ input accepted by the Lisp reader (the function @code{read}) for that
object. @xref{Read and Print}.
Most objects have more than one possible read syntax. Some types of
object have no read syntax; except for these cases, the printed
representation of an object is also a read syntax for it.
object have no read syntax, since it may not make sense to enter objects
of these types directly in a Lisp program. Except for these cases, the
printed representation of an object is also a read syntax for it.
In other languages, an expression is text; it has no other form. In
Lisp, an expression is primarily a Lisp object and only secondarily the
@ -80,14 +81,12 @@ mind, or you will occasionally be very confused.
@cindex hash notation
Every type has a printed representation. Some types have no read
syntax, since it may not make sense to enter objects of these types
directly in a Lisp program. For example, the buffer type does not have
a read syntax. Objects of these types are printed in @dfn{hash
notation}: the characters @samp{#<} followed by a descriptive string
(typically the type name followed by the name of the object), and closed
with a matching @samp{>}. Hash notation cannot be read at all, so the
Lisp reader signals the error @code{invalid-read-syntax} whenever it
encounters @samp{#<}.
syntax---for example, the buffer type has none. Objects of these types
are printed in @dfn{hash notation}: the characters @samp{#<} followed by
a descriptive string (typically the type name followed by the name of
the object), and closed with a matching @samp{>}. Hash notation cannot
be read at all, so the Lisp reader signals the error
@code{invalid-read-syntax} whenever it encounters @samp{#<}.
@kindex invalid-read-syntax
@example
@ -190,8 +189,7 @@ leading @samp{+} or a final @samp{.}.
1 ; @r{The integer 1.}
1. ; @r{Also The integer 1.}
+1 ; @r{Also the integer 1.}
268435457 ; @r{Also the integer 1!}
; @r{ (on a 28-bit implementation)}
268435457 ; @r{Also the integer 1 on a 28-bit implementation.}
@end group
@end example
@ -226,9 +224,10 @@ characters. @xref{String Type}.
Characters in strings, buffers, and files are currently limited to the
range of 0 to 524287---nineteen bits. But not all values in that range
are valid character codes. Characters that represent keyboard input
have a much wider range, so they can modifier keys such as Control, Meta
and Shift.
are valid character codes. Codes 0 through 127 are ASCII codes; the
rest are non-ASCII (@pxref{Non-ASCII Characters}). Characters that represent
keyboard input have a much wider range, to encode modifier keys such as
Control, Meta and Shift.
@cindex read syntax for characters
@cindex printed representation for characters
@ -283,7 +282,7 @@ respectively. Thus,
?\a @result{} 7 ; @r{@kbd{C-g}}
?\b @result{} 8 ; @r{backspace, @key{BS}, @kbd{C-h}}
?\t @result{} 9 ; @r{tab, @key{TAB}, @kbd{C-i}}
?\n @result{} 10 ; @r{newline, @key{LFD}, @kbd{C-j}}
?\n @result{} 10 ; @r{newline, @kbd{C-j}}
?\v @result{} 11 ; @r{vertical tab, @kbd{C-k}}
?\f @result{} 12 ; @r{formfeed character, @kbd{C-l}}
?\r @result{} 13 ; @r{carriage return, @key{RET}, @kbd{C-m}}
@ -314,9 +313,9 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
any character into a control character with @samp{C-}. The character
codes for these non-@sc{ASCII} control characters include the
@iftex
@tex
$2^{26}$
@end iftex
@end tex
@ifinfo
2**26
@end ifinfo
@ -334,21 +333,22 @@ the control equivalent of @kbd{?}:
@noindent
As a result, it is currently not possible to represent the character
@kbd{Control-?}, which is a meaningful input character under X. It is
not easy to change this as various Lisp files refer to @key{DEL} in this
way.
@kbd{Control-?}, which is a meaningful input character under X, using
@samp{\C-}. It is not easy to change this, as various Lisp files refer
to @key{DEL} in this way.
For representing control characters to be found in files or strings,
we recommend the @samp{^} syntax; for control characters in keyboard
input, we prefer the @samp{C-} syntax. This does not affect the meaning
of the program, but may guide the understanding of people who read it.
input, we prefer the @samp{C-} syntax. Which one you use does not
affect the meaning of the program, but may guide the understanding of
people who read it.
@cindex meta characters
A @dfn{meta character} is a character typed with the @key{META}
modifier key. The integer that represents such a character has the
@iftex
@tex
$2^{27}$
@end iftex
@end tex
@ifinfo
2**27
@end ifinfo
@ -357,9 +357,9 @@ use high bits for this and other modifiers to make possible a wide range
of basic character codes.
In a string, the
@iftex
@tex
$2^{7}$
@end iftex
@end tex
@ifinfo
2**7
@end ifinfo
@ -380,15 +380,15 @@ or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
for example, @sc{ASCII} distinguishes between the characters @samp{a}
and @samp{A}. But @sc{ASCII} has no way to represent whether a control
character is upper case or lower case. Emacs uses the
@iftex
@tex
$2^{25}$
@end iftex
@end tex
@ifinfo
2**25
@end ifinfo
bit to indicate that the shift key was used for typing a control
bit to indicate that the shift key was used in typing a control
character. This distinction is possible only when you use X terminals
or other special terminals; ordinary terminals do not indicate the
or other special terminals; ordinary terminals do not report the
distinction to the computer in any way.
@cindex hyper characters
@ -398,10 +398,10 @@ distinction to the computer in any way.
in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
@iftex
@tex
Numerically, the
bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
@end iftex
@end tex
@ifinfo
Numerically, the
bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
@ -434,7 +434,7 @@ digits, so you can represent any character code in this way.
Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
character @kbd{C-a}, and @code{?\x8c0} for the character
@iftex
@`a.
@samp{@`a}.
@end iftex
@ifinfo
@samp{a} with grave accent.
@ -478,7 +478,7 @@ backslash. In contrast to its use in strings, however, a backslash in
the name of a symbol simply quotes the single character that follows the
backslash. For example, in a string, @samp{\t} represents a tab
character; in the name of a symbol, however, @samp{\t} merely quotes the
letter @kbd{t}. To have a symbol with a tab character in its name, you
letter @samp{t}. To have a symbol with a tab character in its name, you
must actually use a tab (preceded with a backslash). But it's rare to
do such a thing.
@ -525,26 +525,28 @@ elements. There are two kinds of sequence in Emacs Lisp, lists and
arrays. Thus, an object of type list or of type array is also
considered a sequence.
Arrays are further subdivided into strings and vectors. Vectors can
hold elements of any type, but string elements must be characters in the
range from 0 to 255. However, the characters in a string can have text
properties like characters in a buffer (@pxref{Text Properties});
vectors do not support text properties even when their elements happen
to be characters.
Arrays are further subdivided into strings, vectors, char-tables and
bool-vectors. Vectors can hold elements of any type, but string
elements must be characters, and bool-vector elements must be @code{t}
or @code{nil}. The characters in a string can have text properties like
characters in a buffer (@pxref{Text Properties}); vectors and
bool-vectors do not support text properties even when their elements
happen to be characters. Char-tables are like vectors except that they
are indexed by any valid character code.
Lists, strings and vectors are different, but they have important
similarities. For example, all have a length @var{l}, and all have
elements which can be indexed from zero to @var{l} minus one. Also,
several functions, called sequence functions, accept any kind of
Lists, strings and the other array types are different, but they have
important similarities. For example, all have a length @var{l}, and all
have elements which can be indexed from zero to @var{l} minus one.
Several functions, called sequence functions, accept any kind of
sequence. For example, the function @code{elt} can be used to extract
an element of a sequence, given its index. @xref{Sequences Arrays
Vectors}.
It is impossible to read the same sequence twice, since sequences are
always created anew upon reading. If you read the read syntax for a
sequence twice, you get two sequences with equal contents. There is one
exception: the empty list @code{()} always stands for the same object,
@code{nil}.
It is generally impossible to read the same sequence twice, since
sequences are always created anew upon reading. If you read the read
syntax for a sequence twice, you get two sequences with equal contents.
There is one exception: the empty list @code{()} always stands for the
same object, @code{nil}.
@node Cons Cell Type
@subsection Cons Cell and List Types
@ -596,8 +598,9 @@ violet buttercup)}:
@example
@group
___ ___ ___ ___ ___ ___
|___|___|--> |___|___|--> |___|___|--> nil
--- --- --- --- --- ---
| | |--> | | |--> | | |--> nil
--- --- --- --- --- ---
| | |
| | |
--> rose --> violet --> buttercup
@ -653,8 +656,9 @@ depicted with boxes and arrows:
@example
@group
___ ___ ___ ___
|___|___|--> |___|___|--> nil
--- --- --- ---
| | |--> | | |--> nil
--- --- --- ---
| |
| |
--> A --> nil
@ -688,8 +692,9 @@ shows the pair @code{(rose . violet)}:
@example
@group
___ ___
|___|___|--> violet
--- ---
| | |--> violet
--- ---
|
|
--> rose
@ -703,8 +708,9 @@ chain of cons cells with a non-@code{nil} final @sc{cdr}. For example,
@example
@group
___ ___ ___ ___
|___|___|--> |___|___|--> buttercup
--- --- --- ---
| | |--> | | |--> buttercup
--- --- --- ---
| |
| |
--> rose --> violet
@ -720,8 +726,9 @@ and looks like this:
@example
@group
___ ___ ___ ___
|___|___|--> |___|___|--> nil
--- --- --- ---
| | |--> | | |--> nil
--- --- --- ---
| |
| |
--> rose --> violet
@ -735,8 +742,9 @@ It looks like this:
@example
@group
___ ___ ___ ___ ___ ___
|___|___|--> |___|___|--> |___|___|--> nil
--- --- --- --- --- ---
| | |--> | | |--> | | |--> nil
--- --- --- --- --- ---
| | |
| | |
--> rose --> violet --> buttercup
@ -775,27 +783,35 @@ functions that work on alists.
An @dfn{array} is composed of an arbitrary number of slots for
referring to other Lisp objects, arranged in a contiguous block of
memory. Accessing any element of an array takes the same amount of
time. In contrast, accessing an element of a list requires time
proportional to the position of the element in the list. (Elements at
the end of a list take longer to access than elements at the beginning
of a list.)
memory. Accessing any element of an array takes approximately the same
amount of time. In contrast, accessing an element of a list requires
time proportional to the position of the element in the list. (Elements
at the end of a list take longer to access than elements at the
beginning of a list.)
Emacs defines two types of array, strings and vectors. A string is an
array of characters and a vector is an array of arbitrary objects. Both
are one-dimensional. (Most other programming languages support
multidimensional arrays, but they are not essential; you can get the
same effect with an array of arrays.) Each type of array has its own
read syntax; see @ref{String Type}, and @ref{Vector Type}.
Emacs defines four types of array: strings, vectors, bool-vectors, and
char-tables.
An array may have any length up to the largest integer; but once
created, it has a fixed size. 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}.
A string is an array of characters and a vector is an array of
arbitrary objects. A bool-vector can hold only @code{t} or @code{nil}.
These kinds of array may have any length up to the largest integer.
Char-tables are sparse arrays indexed by any valid character code; they
can hold arbitrary objects.
The array type is contained in the sequence type and contains both the
string type and the vector type.
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}. The
largest possible index value is one less than the length of the array.
Once an array is created, its length is fixed.
All Emacs Lisp arrays are one-dimensional. (Most other programming
languages support multidimensional arrays, but they are not essential;
you can get the same effect with an array of arrays.) Each type of
array has its own read syntax; see the following sections for details.
The array type is contained in the sequence type and
contains the string type, the vector type, the bool-vector type, and the
char-table type.
@node String Type
@subsection String Type
@ -854,10 +870,13 @@ but the newline is ignored if escaped."
constant by writing it literally. There are two text representations
for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
and multibyte. If the string constant is read from a multibyte source,
then the character is read as a multibyte character, and that makes the
string multibyte. If the string constant is read from a unibyte source,
then the character is read as unibyte and that makes the string unibyte.
such as a multibyte buffer or string, or a file that would be visited as
multibyte, then the character is read as a multibyte character, and that
makes the string multibyte. If the string constant is read from a
unibyte source, then the character is read as unibyte and that makes the
string unibyte.
@c ??? Change this?
You can also represent a multibyte non-@sc{ASCII} character with its
character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
@ -895,9 +914,9 @@ characters.
If you use the @samp{\M-} syntax to indicate a meta character in a
string constant, this sets the
@iftex
@tex
$2^{7}$
@end iftex
@end tex
@ifinfo
2**7
@end ifinfo
@ -975,9 +994,24 @@ special purposes. A char-table can also specify a single value for
a whole character set.
The printed representation of a char-table is like a vector
except that there is an extra @samp{#} at the beginning.
except that there is an extra @samp{#^} at the beginning.
@xref{Char-Tables}, for special functions to operate on char-tables.
Uses of char-tables include:
@itemize @bullet
@item
Case tables (@pxref{Case Tables}).
@item
Character category tables (@pxref{Categories}).
@item
Display Tables (@pxref{Display Tables}).
@item
Syntax tables (@pxref{Syntax Tables}).
@end itemize
@node Bool-Vector Type
@subsection Bool-Vector Type
@ -999,6 +1033,9 @@ make no difference.
@result{} #&3"\377"
(make-bool-vector 3 nil)
@result{} #&3"\0""
;; @r{These are equal since only the first 3 bits are used.}
(equal #&3"\377" #&3"\340")
@result{} t
@end example
@node Function Type
@ -1027,7 +1064,7 @@ functions @code{funcall} and @code{apply}. @xref{Calling Functions}.
A @dfn{Lisp macro} is a user-defined construct that extends the Lisp
language. It is represented as an object much like a function, but with
different parameter-passing semantics. A Lisp macro has the form of a
different argument-passing semantics. A Lisp macro has the form of a
list whose first element is the symbol @code{macro} and whose @sc{cdr}
is a Lisp function object, including the @code{lambda} symbol.
@ -1053,12 +1090,12 @@ not evaluate all its arguments is called a @dfn{special form}
(@pxref{Special Forms}).@refill
It does not matter to the caller of a function whether the function is
primitive. However, this does matter if you try to substitute a
function written in Lisp for a primitive of the same name. The reason
is that the primitive function may be called directly from C code.
Calls to the redefined function from Lisp will use the new definition,
but calls from C code may still use the built-in definition. Therefore,
@strong{we discourage redefinition of primitive functions}.
primitive. However, this does matter if you try to redefine a primitive
with a function written in Lisp. The reason is that the primitive
function may be called directly from C code. Calls to the redefined
function from Lisp will use the new definition, but calls from C code
may still use the built-in definition. Therefore, @strong{we discourage
redefinition of primitive functions}.
The term @dfn{function} refers to all Emacs functions, whether written
in Lisp or C. @xref{Function Type}, for information about the
@ -1114,9 +1151,10 @@ symbol. @xref{Autoload}, for more details.
@section Editing Types
@cindex editing types
The types in the previous section are common to many Lisp dialects.
Emacs Lisp provides several additional data types for purposes connected
with editing.
The types in the previous section used for general programming
purposes, and most of them are common to most Lisp dialects. Emacs Lisp
provides several additional data types for purposes connected with
editing.
@menu
* Buffer Type:: The basic object of editing.
@ -1124,11 +1162,10 @@ with editing.
* Window Type:: Buffers are displayed in windows.
* Frame Type:: Windows subdivide frames.
* Window Configuration Type:: Recording the way a frame is subdivided.
* Frame Configuration Type:: Recording the status of all frames.
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
* Syntax Table Type:: What a character means.
* Display Table Type:: How display tables are represented.
* Overlay Type:: How an overlay is represented.
@end menu
@ -1144,8 +1181,8 @@ buffer need not be displayed in any window.
The contents of a buffer are much like a string, but buffers are not
used like strings in Emacs Lisp, and the available operations are
different. For example, insertion of text into a buffer is very
efficient, whereas ``inserting'' text into a string requires
different. For example, you can insert text efficiently into an
existing buffer, whereas ``inserting'' text into a string requires
concatenating substrings, and the result is an entirely new string
object.
@ -1167,10 +1204,10 @@ a local syntax table (@pxref{Syntax Tables});
a local keymap (@pxref{Keymaps}); and,
@item
a local variable binding list (@pxref{Buffer-Local Variables}).
a list of buffer-local variable bindings (@pxref{Buffer-Local Variables}).
@item
a list of overlays (@pxref{Overlays}).
overlays (@pxref{Overlays}).
@item
text properties for the text in the buffer (@pxref{Text Properties}).
@ -1183,7 +1220,7 @@ behavior of programs in different buffers, without actually changing the
programs.
A buffer may be @dfn{indirect}, which means it shares the text
of another buffer. @xref{Indirect Buffers}.
of another buffer, but presents it differently. @xref{Indirect Buffers}.
Buffers have no read syntax. They print in hash notation, showing the
buffer name.
@ -1263,7 +1300,7 @@ uniquely).
@example
@group
(selected-frame)
@result{} #<frame xemacs@@mole.gnu.ai.mit.edu 0xdac80>
@result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
@end group
@end example
@ -1282,6 +1319,19 @@ looks like @samp{#<window-configuration>}. @xref{Window
Configurations}, for a description of several functions related to
window configurations.
@node Frame Configuration Type
@subsection Frame Configuration Type
@cindex screen layout
A @dfn{frame configuration} stores information about the positions,
sizes, and contents of the windows in all frames. It is actually
a list whose @sc{car} is @code{frame-configuration} and whose
@sc{cdr} is an alist. Each alist element describes one frame,
which appears as the @sc{car} of that element.
@xref{Frame Configurations}, for a description of several functions
related to frame configurations.
@node Process Type
@subsection Process Type
@ -1343,36 +1393,6 @@ a list whose @sc{car} is the symbol @code{keymap}.
@xref{Keymaps}, for information about creating keymaps, handling prefix
keys, local as well as global keymaps, and changing key bindings.
@node Syntax Table Type
@subsection Syntax Table Type
A @dfn{syntax table} is a char-table which specifies the syntax of
each character, for word and list parsing. Each element of the syntax
table defines how one character is interpreted when it appears in a
buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
character is punctuation, but in Lisp mode it is a valid character in a
symbol. These modes specify different interpretations by changing the
syntax table entry for @samp{+}, at index 43 in the syntax table.
Syntax tables are used only to control primitives that scan text in
buffers, not for reading Lisp expressions. The syntax that the Lisp
interpreter uses to read expressions is built into the Emacs source code
and cannot be changed; thus, to change the list delimiters to be
@samp{@{} and @samp{@}} instead of @samp{(} and @samp{)} would be
impossible. (Some Lisp systems provide ways to redefine the read
syntax, but we decided to leave this feature out of Emacs Lisp for
simplicity.)
@xref{Syntax Tables}, for details about syntax classes and how to make
and modify syntax tables.
@node Display Table Type
@subsection Display Table Type
A @dfn{display table} specifies how to display each character code.
Each buffer and each window can have its own display table. A display
table is actually a char-table. @xref{Display Tables}.
@node Overlay Type
@subsection Overlay Type
@ -1437,7 +1457,7 @@ a list and @code{symbolp} to check for a symbol.
(setq list (append x list)))
@need 3000
(t
;; We only handle symbols and lists.
;; We handle only symbols and lists.
(error "Invalid argument %s in add-on" x))))
@end example
@ -1451,6 +1471,9 @@ with references to further information.
@item arrayp
@xref{Array Functions, arrayp}.
@item bool-vector-p
@xref{Bool-Vectors, bool-vector-p}.
@item bufferp
@xref{Buffer Basics, bufferp}.
@ -1458,20 +1481,29 @@ with references to further information.
@xref{Byte-Code Type, byte-code-function-p}.
@item case-table-p
@xref{Case Table, case-table-p}.
@xref{Case Tables, case-table-p}.
@item char-or-string-p
@xref{Predicates for Strings, char-or-string-p}.
@item char-table-p
@xref{Char-Tables, char-table-p}.
@item commandp
@xref{Interactive Call, commandp}.
@item consp
@xref{List-related Predicates, consp}.
@item display-table-p
@xref{Display Tables, display-table-p}.
@item floatp
@xref{Predicates on Numbers, floatp}.
@item frame-configuration-p
@xref{Frame Configurations, frame-configuration-p}.
@item frame-live-p
@xref{Deleting Frames, frame-live-p}.
@ -1556,8 +1588,9 @@ types. In most cases, it is more convenient to use type predicates than
This function returns a symbol naming the primitive type of
@var{object}. The value is one of the symbols @code{symbol},
@code{integer}, @code{float}, @code{string}, @code{cons}, @code{vector},
@code{marker}, @code{overlay}, @code{window}, @code{buffer},
@code{subr}, @code{compiled-function}, @code{process}, or
@code{char-table}, @code{bool-vector}, @code{subr},
@code{compiled-function}, @code{marker}, @code{overlay}, @code{window},
@code{buffer}, @code{frame}, @code{process}, or
@code{window-configuration}.
@example
@ -1594,11 +1627,6 @@ arguments with the same contents or elements are not necessarily
@code{eq} to each other: they are @code{eq} only if they are the same
object.
(The @code{make-symbol} function returns an uninterned symbol that is
not interned in the standard @code{obarray}. When uninterned symbols
are in use, symbol names are no longer unique. Distinct symbols with
the same name are not @code{eq}. @xref{Creating Symbols}.)
@example
@group
(eq 'foo 'foo)
@ -1640,6 +1668,17 @@ the same name are not @code{eq}. @xref{Creating Symbols}.)
@end group
@end example
(The @code{make-symbol} function returns an uninterned symbol that is
not interned in the standard @code{obarray}. When uninterned symbols
are in use, symbol names are no longer unique. Distinct symbols with
the same name are not @code{eq}. @xref{Creating Symbols}.)
@example
@group
(eq (make-symbol "foo") 'foo)
@result{} nil
@end group
@end example
@end defun
@defun equal object1 object2

219
lispref/os.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
@node System Interface, Display, Processes, Top
@node System Interface, Tips, Calendar, Top
@chapter Operating System Interface
This chapter is about starting and getting out of Emacs, access to
@ -64,7 +64,7 @@ It processes the initial options. (Some of them are handled
even earlier than this.)
@item
It initializes the X window frame and faces, if appropriate.
It initializes the window frame and faces, if appropriate.
@item
It runs the normal hook @code{before-init-hook}.
@ -76,13 +76,13 @@ It loads the library @file{site-start}, unless the option
@cindex @file{site-start.el}
@item
It loads the file @file{~/.emacs} unless @samp{-q} was specified on
the command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
option can specify the user name whose home directory should be used
It loads the file @file{~/.emacs}, unless @samp{-q} was specified on the
command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
option can specify another user name whose home directory should be used
instead of @file{~}.
@item
It loads the library @file{default} unless @code{inhibit-default-init}
It loads the library @file{default}, unless @code{inhibit-default-init}
is non-@code{nil}. (This is not done in @samp{-batch} mode or if
@samp{-q} was specified on the command line.) The library's file name
is usually @file{default.el}.
@ -461,11 +461,11 @@ likely @code{fg}.
systems, ``suspension'' actually creates a new shell temporarily as a
subprocess of Emacs. Then you would exit the shell to return to Emacs.
Suspension is not useful with window systems such as X, because the
Emacs job may not have a parent that can resume it again, and in any
case you can give input to some other job such as a shell merely by
moving to a different window. Therefore, suspending is not allowed
when Emacs is an X client.
Suspension is not useful with window systems, because the Emacs job
may not have a parent that can resume it again, and in any case you can
give input to some other job such as a shell merely by moving to a
different window. Therefore, suspending is not allowed when Emacs is using
a window system.
@defun suspend-emacs string
This function stops Emacs and returns control to the superior process.
@ -478,10 +478,7 @@ as terminal input by Emacs's superior shell. The characters in
appear.
Before suspending, @code{suspend-emacs} runs the normal hook
@code{suspend-hook}. In Emacs version 18, @code{suspend-hook} was not a
normal hook; its value was a single function, and if its value was
non-@code{nil}, then @code{suspend-emacs} returned immediately without
actually suspending anything.
@code{suspend-hook}.
After the user resumes Emacs, @code{suspend-emacs} runs the normal hook
@code{suspend-resume-hook}. @xref{Hooks}.
@ -553,6 +550,12 @@ This variable is a normal hook run after suspending.
through various functions. These variables include the name of the
system, the user's @sc{uid}, and so on.
@defvar system-configuration
This variable holds the GNU configuration name for the hardware/software
configuration of your system, as a string. The convenient way to test
parts of this string is with @code{string-match}.
@end defvar
@defvar system-type
The value of this variable is a symbol indicating the type of operating
system Emacs is operating on. Here is a table of the possible values:
@ -568,10 +571,12 @@ Berkeley BSD.
Data General DGUX operating system.
@item gnu
A GNU system (using the GNU kernel, which consists of the HURD and Mach).
the GNU system (using the GNU kernel, which consists of the HURD and Mach).
@item gnu/linux
A variant GNU system using the Linux kernel.
A GNU/Linux system---that is, a variant GNU system, using the Linux
kernel. (These systems are the ones people often call ``Linux,'' but
actually Linux is just the kernel, not the whole system.)
@item hpux
Hewlett-Packard HPUX operating system.
@ -611,12 +616,6 @@ alternatives in the future. We recommend using
systems.
@end defvar
@defvar system-configuration
This variable holds the GNU configuration name for the hardware/software
configuration of your system, as a string. The convenient way to test
parts of this string is with @code{string-match}.
@end defvar
@defun system-name
This function returns the name of the machine you are running on.
@example
@ -944,7 +943,7 @@ in the past or future.
Time conversion functions always use the Gregorian calendar, even for
dates before the Gregorian calendar was introduced. Year numbers count
the number of years since the year 1 B.C., and do not skip zero as
traditional Gregorian years do; for example, the year number -37
traditional Gregorian years do; for example, the year number @minus{}37
represents the Gregorian year 38 B.C@.
@defun format-time-string format-string time
@ -1012,11 +1011,11 @@ This stands for the numeric day of week (0-6). Sunday is day 0.
This stands for the week of the year (01-52), assuming that weeks
start on Monday.
@item %x
This has a locale-specific meaning. In the default locale (named C), it
is equivalent to @samp{%D}.
This has a locale-specific meaning. In the default locale (named
@samp{C}), it is equivalent to @samp{%D}.
@item %X
This has a locale-specific meaning. In the default locale (named C), it
is equivalent to @samp{%T}.
This has a locale-specific meaning. In the default locale (named
@samp{C}), it is equivalent to @samp{%T}.
@item %y
This stands for the year without century (00-99).
@item %Y
@ -1026,8 +1025,8 @@ This stands for the time zone abbreviation.
@end table
You can also specify the field width and type of padding for any of
these @samp{%}-constructs. This works as in @code{printf}: you write
the field width as digits in the middle of a @samp{%}-construct. If you
these @samp{%}-sequences. This works as in @code{printf}: you write
the field width as digits in the middle of a @samp{%}-sequences. If you
start the field width with 0, it means to pad with zeros.
For example, @samp{%S} specifies the number of seconds since the minute;
@ -1069,8 +1068,8 @@ An integer indicating the time zone, as the number of seconds east of
Greenwich.
@end table
Note that Common Lisp has different meanings for @var{dow} and
@var{zone}.
@strong{Common Lisp Note:} Common Lisp has different meanings for
@var{dow} and @var{zone}.
@end defun
@defun encode-time seconds minutes hour day month year &optional @dots{}zone
@ -1111,7 +1110,7 @@ arguments; for example, day 0 means the day preceding the given month.
You can set up a @dfn{timer} to call a function at a specified future time or
after a certain length of idleness.
Emacs cannot run a timer at any arbitrary point in a Lisp program; it
Emacs cannot run timers at any arbitrary point in a Lisp program; it
can run them only when Emacs could accept output from a subprocess:
namely, while waiting or inside certain primitive functions such as
@code{sit-for} or @code{read-char} which @emph{can} wait. Therefore, a
@ -1124,10 +1123,11 @@ at time @var{time}. The argument @var{function} is a function to call
later, and @var{args} are the arguments to give it when it is called.
The time @var{time} is specified as a string.
Absolute times may be specified in a variety of formats; The form
Absolute times may be specified in a wide variety of formats, and tries
to accept all common date formats. One valid format is
@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
@var{month}/@var{day}/@var{year}}, where all fields are numbers, works;
the format that @code{current-time-string} returns is also allowed.
@var{month}/@var{day}/@var{year}}, where all fields are numbers; the
format that @code{current-time-string} returns is also allowed.
To specify a relative time, use numbers followed by units.
For example:
@ -1208,12 +1208,12 @@ idleness will continue to increase and will not go down to five seconds
again.
Emacs can do various things while idle: garbage collect, autosave or
handle data from a subprocess. But these interludes during idleness
have little effect on idle timers. An idle timer set for 600 seconds
will run when ten minutes have elapsed since the last user command was
finished, even if subprocess output has been accepted thousands of times
within those ten minutes, even if there have been garbage collections
and autosaves.
handle data from a subprocess. But these interludes during idleness do
not interfere with idle timers, because they do not reset the clock of
idleness to zero. An idle timer set for 600 seconds will run when ten
minutes have elapsed since the last user command was finished, even if
subprocess output has been accepted thousands of times within those ten
minutes, even if there have been garbage collections and autosaves.
When the user supplies input, Emacs becomes non-idle while executing the
input. Then it becomes idle again, and all the idle timers that are
@ -1249,16 +1249,16 @@ functions.
@defun set-input-mode interrupt flow meta quit-char
This function sets the mode for reading keyboard input. If
@var{interrupt} is non-null, then Emacs uses input interrupts. If it is
@code{nil}, then it uses @sc{cbreak} mode. When Emacs communicates
directly with X, it ignores this argument and uses interrupts if that is
the way it knows how to communicate.
@code{nil}, then it uses @sc{cbreak} mode. The default setting is
system dependent. Some systems always use @sc{cbreak} mode regardless
of what is specified.
If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff} (@kbd{C-q},
@kbd{C-s}) flow control for output to the terminal. This has no effect except
in @sc{cbreak} mode. @xref{Flow Control}.
When Emacs communicates directly with X, it ignores this argument and
uses interrupts if that is the way it knows how to communicate.
The default setting is system dependent. Some systems always use
@sc{cbreak} mode regardless of what is specified.
If @var{flow} is non-@code{nil}, then Emacs uses @sc{xon/xoff}
(@kbd{C-q}, @kbd{C-s}) flow control for output to the terminal. This
has no effect except in @sc{cbreak} mode. @xref{Flow Control}.
@c Emacs 19 feature
The argument @var{meta} controls support for input character codes
@ -1267,7 +1267,7 @@ the 8th bit set into Meta characters. If @var{meta} is @code{nil},
Emacs disregards the 8th bit; this is necessary when the terminal uses
it as a parity bit. If @var{meta} is neither @code{t} nor @code{nil},
Emacs uses all 8 bits of input unchanged. This is good for terminals
using European 8-bit character sets.
that use 8-bit character sets.
@c Emacs 19 feature
If @var{quit-char} is non-@code{nil}, it specifies the character to
@ -1290,8 +1290,8 @@ is non-@code{nil} when Emacs is using interrupt-driven input. If
@code{nil}, Emacs is using @sc{cbreak} mode.
@item flow
is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
flow control for output to the terminal. This value has no effect
unless @var{interrupt} is non-@code{nil}.
flow control for output to the terminal. This value has effect when
unless @var{interrupt} is @code{nil}.
@item meta
is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
@ -1310,10 +1310,11 @@ is the character Emacs currently uses for quitting, usually @kbd{C-g}.
other input events before they become part of key sequences. These
features apply to each event in the order they are described here: each
event is first modified according to @code{extra-keyboard-modifiers},
then translated through @code{keyboard-translate-table} (if applicable).
If it is being read as part of a key sequence, it is then added to the
sequece being read; then subsequences containing it are checked first
with @code{function-key-map} and then with @code{key-translation-map}.
then translated through @code{keyboard-translate-table} (if applicable),
and finally decoded with the specified keyboard coding system. If it is
being read as part of a key sequence, it is then added to the sequence
being read; then subsequences containing it are checked first with
@code{function-key-map} and then with @code{key-translation-map}.
@c Emacs 19 feature
@defvar extra-keyboard-modifiers
@ -1334,9 +1335,9 @@ The @key{META} key.
Each time the user types a keyboard key, it is altered as if the
modifier keys specified in the bit mask were held down.
When using X windows, the program can ``press'' any of the modifier
keys in this way. Otherwise, only the @key{CTL} and @key{META} keys can
be virtually pressed.
When using a window system, the program can ``press'' any of the
modifier keys in this way. Otherwise, only the @key{CTL} and @key{META}
keys can be virtually pressed.
@end defvar
@defvar keyboard-translate-table
@ -1392,7 +1393,7 @@ the keyboard translate table if necessary.
The remaining translation features translate subsequences of key
sequences being read. They are implemented in @code{read-key-sequence}
and have no effect on @code{read-char}.
and have no effect on input read with @code{read-event}.
@defvar function-key-map
This variable holds a keymap that describes the character sequences sent
@ -1406,7 +1407,7 @@ If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
key sequence, it is replaced with the events in @var{v}.
For example, VT100 terminals send @kbd{@key{ESC} O P} when the
keypad PF1 key is pressed. Therefore, we want Emacs to translate
keypad @key{PF1} key is pressed. Therefore, we want Emacs to translate
that sequence of events into the single event @code{pf1}. We accomplish
this by ``binding'' @kbd{@key{ESC} O P} to @code{[pf1]} in
@code{function-key-map}, when using a VT100.
@ -1419,7 +1420,8 @@ this back into @kbd{C-c @key{PF1}}, which it returns as the vector
Entries in @code{function-key-map} are ignored if they conflict with
bindings made in the minor mode, local, or global keymaps. The intent
is that the character sequences that function keys send should not have
command bindings in their own right.
command bindings in their own right---but if they do, the ordinary
bindings take priority.
The value of @code{function-key-map} is usually set up automatically
according to the terminal's Terminfo or Termcap entry, but sometimes
@ -1427,9 +1429,6 @@ those need help from terminal-specific Lisp files. Emacs comes with
terminal-specific files for many common terminals; their main purpose is
to make entries in @code{function-key-map} beyond those that can be
deduced from Termcap and Terminfo. @xref{Terminal-Specific}.
Emacs versions 18 and earlier used totally different means of detecting
the character sequences that represent function keys.
@end defvar
@defvar key-translation-map
@ -1494,21 +1493,21 @@ to turn the character that follows into a Hyper character:
@end group
@end example
@pindex iso-transl
@cindex Latin-1 character set (input)
@cindex ISO Latin-1 characters (input)
The @file{iso-transl} library uses this feature to provide a way of
inputting non-ASCII Latin-1 characters.
Finally, if you have enabled keyboard character set decoding using
@code{set-keyboard-coding-system}, decoding is done after the
translations listed above. @xref{Specifying Coding Systems}. In future
Emacs versions, character set decoding may be done before the other
translations.
@node Recording Input
@subsection Recording Input
@defun recent-keys
This function returns a vector containing the last 100 input events
from the keyboard or mouse. All input events are included, whether or
not they were used as parts of key sequences. Thus, you always get the
last 100 inputs, not counting keyboard macros. (Events from keyboard
macros are excluded because they are less interesting for debugging; it
This function returns a vector containing the last 100 input events from
the keyboard or mouse. All input events are included, whether or not
they were used as parts of key sequences. Thus, you always get the last
100 input events, not counting events generated by keyboard macros.
(These are excluded because they are less interesting for debugging; it
should be enough to see the events that invoked the macros.)
@end defun
@ -1565,9 +1564,8 @@ not. If Emacs has the wrong value, it makes decisions that are less
than optimal. To fix the problem, set @code{baud-rate}.
@defun baud-rate
This function returns the value of the variable @code{baud-rate}. In
Emacs versions 18 and earlier, this was the only way to find out the
terminal speed.
This obsolete function returns the value of the variable
@code{baud-rate}.
@end defun
@defun send-string-to-terminal string
@ -1619,15 +1617,28 @@ To define system-specific X11 keysyms, set the variable
This variable's value should be an alist with one element for each
system-specific keysym. An element has this form: @code{(@var{code}
. @var{symbol})}, where @var{code} is the numeric keysym code (not
including the ``vendor specific'' bit, 1 << 28), and @var{symbol} is the
name for the function key.
including the ``vendor specific'' bit,
@ifinfo
-2**28,
@end ifinfo
@tex
$-2^{28}$,
@end tex
and @var{symbol} is the name for the function key.
For example @code{(168 . mute-acute)} defines a system-specific key used
by HP X servers whose numeric code is (1 << 28) + 168.
by HP X servers whose numeric code is
@ifinfo
-2**28
@end ifinfo
@tex
$-2^{28}$
@end tex
+ 168.
It is not a problem if the alist defines keysyms for other X servers, as
long as they don't conflict with the ones used by the X server actually
in use.
It is not crucial to exclude from the alist the keysyms of other X
servers; those do no harm, as long as they don't conflict with the ones
used by the X server actually in use.
The variable is always local to the current X terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@ -1637,9 +1648,9 @@ buffer-local. @xref{Multiple Displays}.
@section Flow Control
@cindex flow control characters
This section attempts to answer the question ``Why does Emacs choose
to use flow-control characters in its command character set?'' For a
second view on this issue, read the comments on flow control in the
This section attempts to answer the question ``Why does Emacs use
flow-control characters in its command character set?'' For a second
view on this issue, read the comments on flow control in the
@file{emacs/INSTALL} file from the distribution; for help with Termcap
entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
@ -1647,20 +1658,20 @@ entries and DEC terminal concentrators, see @file{emacs/etc/TERMS}.
@cindex @kbd{C-q}
At one time, most terminals did not need flow control, and none used
@code{C-s} and @kbd{C-q} for flow control. Therefore, the choice of
@kbd{C-s} and @kbd{C-q} as command characters was uncontroversial.
Emacs, for economy of keystrokes and portability, used nearly all the
@sc{ASCII} control characters, with mnemonic meanings when possible;
thus, @kbd{C-s} for search and @kbd{C-q} for quote.
@kbd{C-s} and @kbd{C-q} as command characters for searching and quoting
was natural and uncontroversial. With so many commands needing key
assignments. of course we assigned meanings to nearly all @sc{ASCII}
control characters.
Later, some terminals were introduced which required these characters
for flow control. They were not very good terminals for full-screen
editing, so Emacs maintainers did not pay attention. In later years,
flow control with @kbd{C-s} and @kbd{C-q} became widespread among
terminals, but by this time it was usually an option. And the majority
of users, who can turn flow control off, were unwilling to switch to
less mnemonic key bindings for the sake of flow control.
editing, so Emacs maintainers ignored them. In later years, flow
control with @kbd{C-s} and @kbd{C-q} became widespread among terminals,
but by this time it was usually an option. And the majority of Emacs
users, who can turn flow control off, did not want to switch to less
mnemonic key bindings for the sake of flow control.
So which usage is ``right'', Emacs's or that of some terminal and
So which usage is ``right''---Emacs's or that of some terminal and
concentrator manufacturers? This question has no simple answer.
One reason why we are reluctant to cater to the problems caused by
@ -1668,13 +1679,13 @@ concentrator manufacturers? This question has no simple answer.
techniques (albeit less common in practice) for flow control that
preserve transparency of the character stream. Note also that their use
for flow control is not an official standard. Interestingly, on the
model 33 teletype with a paper tape punch (which is very old), @kbd{C-s}
and @kbd{C-q} were sent by the computer to turn the punch on and off!
model 33 teletype with a paper tape punch (around 1970), @kbd{C-s} and
@kbd{C-q} were sent by the computer to turn the punch on and off!
As X servers and other window systems replace character-only
terminals, this problem is gradually being cured. For the mean time,
Emacs provides a convenient way of enabling flow control if you want it:
call the function @code{enable-flow-control}.
As window systems and PC terminal emulators replace character-only
terminals, the flow control problem is gradually disappearing. For the
mean time, Emacs provides a convenient way of enabling flow control if
you want it: call the function @code{enable-flow-control}.
@deffn Command enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow

9
lispref/positions.texi
View file

@ -241,7 +241,7 @@ puts point @var{n} tenths of the way from the beginning of the buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
Don't use this function in Lisp programs!
@strong{Warning:} Don't use this function in Lisp programs!
@end deffn
@deffn Command end-of-buffer &optional n
@ -253,7 +253,7 @@ point @var{n} tenths of the way from the end of the buffer.
In an interactive call, @var{n} is the numeric prefix argument,
if provided; otherwise @var{n} defaults to @code{nil}.
Don't use this function in Lisp programs!
@strong{Warning:} Don't use this function in Lisp programs!
@end deffn
@node Text Lines
@ -759,6 +759,11 @@ The value returned by @code{save-excursion} is the result of the last of
@end example
@end defspec
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
@code{deactivate-mark}, and thus causing the deactivation of the mark
after the command finishes. @xref{The Mark}.
@node Narrowing
@section Narrowing
@cindex narrowing

107
lispref/processes.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
@node Processes, System Interface, Abbrevs, Top
@node Processes, Display, Abbrevs, Top
@chapter Processes
@cindex child process
@cindex parent process
@ -35,8 +35,6 @@ This function returns @code{t} if @var{object} is a process,
@menu
* Subprocess Creation:: Functions that start subprocesses.
* Synchronous Processes:: Details of using synchronous subprocesses.
* MS-DOS Subprocesses:: On MS-DOS, you must indicate text vs binary
for data sent to and from a subprocess.
* Asynchronous Processes:: Starting up an asynchronous subprocess.
* Deleting Processes:: Eliminating an asynchronous subprocess.
* Process Information:: Accessing run-status and other attributes.
@ -127,6 +125,46 @@ The value of @code{exec-path} is used by @code{call-process} and
file name.
@end defopt
@node Shell Arguments
@section Shell Arguments
Lisp programs sometimes need to run a shell and give it a command
which contains file names that were specified by the user. These
programs ought to be able to support any valid file name. But the shell
gives special treatment to certain characters, and if these characters
occur in the file name, they will confuse the shell. To handle these
characters, use the function @code{shell-quote-argument}:
@defun shell-quote-argument argument
This function returns a string which represents, in shell syntax,
an argument whose actual contents are @var{argument}. It should
work reliably to concatenate the return value into a shell command
and then pass it to a shell for execution.
Precisely what this function does depends on your operating system. The
function is designed to work with the usual shell syntax; if you use an
unusual shell, you will need to redefine this function. On MS-DOS, the
function returns @var{argument} unchanged; while this is not really
correct, it is the best one can do, since the MS-DOS shell has no
quoting features.
@example
;; @r{This example shows the behavior on GNU and Unix systems.}
(shell-quote-argument "foo > bar")
@result{} "foo\\ \\>\\ bar"
@end example
Here's an example of using @code{shell-quote-argument} to construct
a shell command:
@example
(concat "diff -c "
(shell-quote-argument oldfile)
" "
(shell-quote-argument newfile))
@end example
@end defun
@node Synchronous Processes
@section Creating a Synchronous Process
@cindex synchronous subprocess
@ -145,13 +183,15 @@ subprocess actually terminates before quitting. If during that time the
user types another @kbd{C-g}, that kills the subprocess instantly with
@code{SIGKILL} and quits immediately. @xref{Quitting}.
The synchronous subprocess functions returned @code{nil} in version
18. Now they return an indication of how the process terminated.
The synchronous subprocess functions return an indication of how the
process terminated.
The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file. The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file. @xref{Coding Systems}.
On Microsoft operating systems, additional variables control
the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
@ -168,8 +208,7 @@ Insert the output in that buffer, before point. This includes both the
standard output stream and the standard error stream of the process.
@item a string
Find the buffer with that name, then insert the output in that buffer,
before point.
Insert the output in a buffer with that name, before point.
@item @code{t}
Insert the output in the current buffer, before point.
@ -190,9 +229,9 @@ function returns.
Keep the standard output stream separate from the standard error stream;
deal with the ordinary output as specified by @var{real-destination},
and dispose of the error output according to @var{error-destination}.
The value @code{nil} means discard it, @code{t} means mix it with the
ordinary output, and a string specifies a file name to redirect error
output into.
If @var{error-destination} is @code{nil}, that means to discard the
error output, @code{t} means mix it with the ordinary output, and a
string specifies a file name to redirect error output into.
You can't directly specify a buffer to put the error output in; that is
too difficult to implement. But you can achieve this result by sending
@ -237,12 +276,12 @@ lewis:5LTsHm66CSWKg:398:21:Bil Lewis:/user/lewis:/bin/csh
@end group
@end smallexample
The @code{insert-directory} function contains a good example of the use
of @code{call-process}:
Here is a good example of the use of @code{call-process}, which used to
be found in the definition of @code{insert-directory}:
@smallexample
@group
(call-process insert-directory-program nil t nil switches
(call-process insert-directory-program nil t nil @var{switches}
(if full-directory-p
(concat (file-name-as-directory file) ".")
file))
@ -318,32 +357,6 @@ This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
@node MS-DOS Subprocesses
@section MS-DOS Subprocesses
On MS-DOS, you must indicate whether the data going to and from
a synchronous subprocess are text or binary. Text data requires
translation between the end-of-line convention used within Emacs
(a single newline character) and the convention used outside Emacs
(the two-character sequence, @sc{crlf}).
The variable @code{binary-process-input} applies to input sent to the
subprocess, and @code{binary-process-output} applies to output received
from it. A non-@code{nil} value means the data is non-text; @code{nil}
means the data is text, and calls for conversion.
@defvar binary-process-input
If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
the input to a synchronous subprocess.
@end defvar
@defvar binary-process-output
If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
the output from a synchronous subprocess.
@end defvar
@xref{Files and MS-DOS}, for related information.
@node Asynchronous Processes
@section Creating an Asynchronous Process
@cindex asynchronous subprocess
@ -403,6 +416,14 @@ to execute the specified command. The argument @var{command} is a shell
command name, and @var{command-args} are the arguments for the shell
command. The variable @code{shell-file-name} specifies which shell to
use.
The point of running a program through the shell, rather than directly
with @code{start-process}, is so that you can employ shell features such
as wildcards in the arguments. It follows that if you include an
arbitrary user-specified filename in the command, you should quote it
with @code{shell-quote-argument} first, so that any special shell
characters in the file name do @emph{not} have their special shell
meanings. @xref{Shell Arguments}.
@end defun
@defvar process-connection-type
@ -602,9 +623,6 @@ x
For a network connection, @code{process-status} returns one of the symbols
@code{open} or @code{closed}. The latter means that the other side
closed the connection, or Emacs did @code{delete-process}.
In Emacs version 18, the status of a network connection was @code{run}
if open, and @code{exit} if closed.
@end defun
@defun process-exit-status process
@ -628,8 +646,7 @@ for decoding output from @var{process} and for encoding input to
@var{process} (@pxref{Coding Systems}). The value has this form:
@example
(@var{coding-system-for-decoding}
. @var{coding-system-for-encoding})
(@var{coding-system-for-decoding} . @var{coding-system-for-encoding})
@end example
@end defun
@ -789,7 +806,7 @@ This function stops the process @var{process-name} by sending the
signal @code{SIGTSTP}. Use @code{continue-process} to resume its
execution.
On systems with job control, outside of Emacs)\, the ``stop character''
Outside of Emacs, on systems with job control, the ``stop character''
(usually @kbd{C-z}) normally sends this signal. When
@var{current-group} is non-@code{nil}, you can think of this function as
``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the

245
lispref/searching.texi
View file

@ -199,15 +199,15 @@ the string @samp{fo}. Still trivial. To do something more powerful, you
need to use one of the special characters. Here is a list of them:
@need 1200
@table @kbd
@item .@: @r{(Period)}
@table @asis
@item @samp{.}@: @r{(Period)}
@cindex @samp{.} in regexp
is a special character that matches any single character except a newline.
Using concatenation, we can make regular expressions like @samp{a.b}, which
matches any three-character string that begins with @samp{a} and ends with
@samp{b}.@refill
@item *
@item @samp{*}
@cindex @samp{*} in regexp
is not a construct by itself; it is a postfix operator that means to
match the preceding regular expression repetitively as many times as
@ -237,35 +237,35 @@ Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
concluding that none of them can work. To make sure your regular
expressions run fast, check nested repetitions carefully.
@item +
@item @samp{+}
@cindex @samp{+} in regexp
is a postfix operator, similar to @samp{*} except that it must match
the preceding expression at least once. So, for example, @samp{ca+r}
matches the strings @samp{car} and @samp{caaaar} but not the string
@samp{cr}, whereas @samp{ca*r} matches all three strings.
@item ?
@item @samp{?}
@cindex @samp{?} in regexp
is a postfix operator, similar to @samp{*} except that it must match the
preceding expression either once or not at all. For example,
@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
@item [ @dots{} ]
@cindex character set (in regexp)
@item @samp{[ @dots{} ]}
@cindex character alternative (in regexp)
@cindex @samp{[} in regexp
@cindex @samp{]} in regexp
is a @dfn{character set}, which begins with @samp{[} and is terminated
by @samp{]}. In the simplest case, the characters between the two
brackets are what this set can match.
is a @dfn{character alternative}, which begins with @samp{[} and is
terminated by @samp{]}. In the simplest case, the characters between
the two brackets are what this character alternative can match.
Thus, @samp{[ad]} matches either one @samp{a} or one @samp{d}, and
@samp{[ad]*} matches any string composed of just @samp{a}s and @samp{d}s
(including the empty string), from which it follows that @samp{c[ad]*r}
matches @samp{cr}, @samp{car}, @samp{cdr}, @samp{caddaar}, etc.
You can also include character ranges in a character set, by writing the
starting and ending characters with a @samp{-} between them. Thus,
@samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
You can also include character ranges in a character alternative, by
writing the starting and ending characters with a @samp{-} between them.
Thus, @samp{[a-z]} matches any lower-case ASCII letter. Ranges may be
intermixed freely with individual characters, as in @samp{[a-z$%.]},
which matches any lower case ASCII letter or @samp{$}, @samp{%} or
period.
@ -284,33 +284,33 @@ The beginning and end of a range must be in the same character set
(@samp{a} with grave accent) is in the Latin-1 character set.
Note that the usual regexp special characters are not special inside a
character set. A completely different set of special characters exists
inside character sets: @samp{]}, @samp{-} and @samp{^}.
character alternative. A completely different set of characters are
special inside character alternatives: @samp{]}, @samp{-} and @samp{^}.
To include a @samp{]} in a character set, you must make it the first
character. For example, @samp{[]a]} matches @samp{]} or @samp{a}. To
include a @samp{-}, write @samp{-} as the first or last character of the
set, or put it after a range. Thus, @samp{[]-]} matches both @samp{]}
and @samp{-}.
To include a @samp{]} in a character alternative, you must make it the
first character. For example, @samp{[]a]} matches @samp{]} or @samp{a}.
To include a @samp{-}, write @samp{-} as the first or last character of
the character alternative, or put it after a range. Thus, @samp{[]-]}
matches both @samp{]} and @samp{-}.
To include @samp{^} in a set, put it anywhere but at the beginning of
the set.
To include @samp{^} in a character alternative, put it anywhere but at
the beginning.
@item [^ @dots{} ]
@item @samp{[^ @dots{} ]}
@cindex @samp{^} in regexp
@samp{[^} begins a @dfn{complemented character set}, which matches any
@samp{[^} begins a @dfn{complemented character alternative}, which matches any
character except the ones specified. Thus, @samp{[^a-z0-9A-Z]} matches
all characters @emph{except} letters and digits.
@samp{^} is not special in a character set unless it is the first
@samp{^} is not special in a character alternative unless it is the first
character. The character following the @samp{^} is treated as if it
were first (in other words, @samp{-} and @samp{]} are not special there).
A complemented character set can match a newline, unless newline is
A complemented character alternative can match a newline, unless newline is
mentioned as one of the characters not to match. This is in contrast to
the handling of regexps in programs such as @code{grep}.
@item ^
@item @samp{^}
@cindex @samp{^} in regexp
@cindex beginning of line in regexp
is a special character that matches the empty string, but only at the
@ -321,7 +321,7 @@ the beginning of a line.
When matching a string instead of a buffer, @samp{^} matches at the
beginning of the string or after a newline character @samp{\n}.
@item $
@item @samp{$}
@cindex @samp{$} in regexp
is similar to @samp{^} but matches only at the end of a line. Thus,
@samp{x+$} matches a string of one @samp{x} or more at the end of a line.
@ -329,7 +329,7 @@ is similar to @samp{^} but matches only at the end of a line. Thus,
When matching a string instead of a buffer, @samp{$} matches at the end
of the string or before a newline character @samp{\n}.
@item \
@item @samp{\}
@cindex @samp{\} in regexp
has two functions: it quotes the special characters (including
@samp{\}), and it introduces additional special constructs.
@ -360,7 +360,7 @@ sequences starting with @samp{\} which have special meanings. The
second character in the sequence is always an ordinary character on
their own. Here is a table of @samp{\} constructs.
@table @kbd
@table @samp
@item \|
@cindex @samp{|} in regexp
@cindex regexp alternative
@ -454,7 +454,7 @@ matches any character whose syntax is not @var{code}.
they don't use up any characters---but whether they match depends on the
context.
@table @kbd
@table @samp
@item \`
@cindex @samp{\`} in regexp
matches the empty string, but only at the beginning
@ -519,7 +519,7 @@ string match when calling a function that wants a regular expression.
One use of @code{regexp-quote} is to combine an exact string match with
context described as a regular expression. For example, this searches
for the string that is the value of @code{string}, surrounded by
for the string that is the value of @var{string}, surrounded by
whitespace:
@example
@ -558,7 +558,7 @@ regular expression which is equivalent to the actual value
@tindex regexp-opt-depth
@defun regexp-opt-depth regexp
This function returns the total number of grouping constructs
(parenthesised expressions) in @var{regexp}.
(parenthesized expressions) in @var{regexp}.
@end defun
@node Regexp Example
@ -579,14 +579,14 @@ tab and @samp{\n} for a newline.
"[.?!][]\"')@}]*\\($\\| $\\|\t\\| \\)[ \t\n]*"
@end example
In contrast, if you evaluate the variable @code{sentence-end}, you
@noindent
In contrast, if you evaluate the variable @code{sentence-end}, you
will see the following:
@example
@group
sentence-end
@result{}
"[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
@result{} "[.?!][]\"')@}]*\\($\\| $\\| \\| \\)[
]*"
@end group
@end example
@ -599,16 +599,16 @@ deciphered as follows:
@table @code
@item [.?!]
The first part of the pattern is a character set that matches any one of
three characters: period, question mark, and exclamation mark. The
match must begin with one of these three characters.
The first part of the pattern is a character alternative that matches
any one of three characters: period, question mark, and exclamation
mark. The match must begin with one of these three characters.
@item []\"')@}]*
The second part of the pattern matches any closing braces and quotation
marks, zero or more of them, that may follow the period, question mark
or exclamation mark. The @code{\"} is Lisp syntax for a double-quote in
a string. The @samp{*} at the end indicates that the immediately
preceding regular expression (a character set, in this case) may be
preceding regular expression (a character alternative, in this case) may be
repeated zero or more times.
@item \\($\\|@ $\\|\t\\|@ @ \\)
@ -630,11 +630,11 @@ beyond the minimum needed to end a sentence.
@cindex regexp searching
@cindex searching for regexp
In GNU Emacs, you can search for the next match for a regexp either
incrementally or not. For incremental search commands, see @ref{Regexp
Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here
we describe only the search functions useful in programs. The principal
one is @code{re-search-forward}.
In GNU Emacs, you can search for the next match for a regular
expression either incrementally or not. For incremental search
commands, see @ref{Regexp Search, , Regular Expression Search, emacs,
The GNU Emacs Manual}. Here we describe only the search functions
useful in programs. The principal one is @code{re-search-forward}.
These search functions convert the regular expression to multibyte if
the buffer is multibyte; they convert the regular expression to unibyte
@ -704,8 +704,8 @@ matching a regular expression at a given spot always works from
beginning to end, and starts at a specified beginning position.
A true mirror-image of @code{re-search-forward} would require a special
feature for matching regexps from end to beginning. It's not worth the
trouble of implementing that.
feature for matching regular expressions from end to beginning. It's
not worth the trouble of implementing that.
@end deffn
@defun string-match regexp string &optional start
@ -1001,13 +1001,76 @@ can't avoid another intervening search, you must save and restore the
match data around it, to prevent it from being overwritten.
@menu
* Replacing Match:: Replacing a substring that was matched.
* Simple Match Data:: Accessing single items of match data,
such as where a particular subexpression started.
* Replacing Match:: Replacing a substring that was matched.
* Entire Match Data:: Accessing the entire match data at once, as a list.
* Saving Match Data:: Saving and restoring the match data.
@end menu
@node Replacing Match
@subsection Replacing the Text That Matched
This function replaces the text matched by the last search with
@var{replacement}.
@cindex case in replacements
@defun replace-match replacement &optional fixedcase literal string subexp
This function replaces the text in the buffer (or in @var{string}) that
was matched by the last search. It replaces that text with
@var{replacement}.
If you did the last search in a buffer, you should specify @code{nil}
for @var{string}. Then @code{replace-match} does the replacement by
editing the buffer; it leaves point at the end of the replacement text,
and returns @code{t}.
If you did the search in a string, pass the same string as @var{string}.
Then @code{replace-match} does the replacement by constructing and
returning a new string.
If @var{fixedcase} is non-@code{nil}, then the case of the replacement
text is not changed; otherwise, the replacement text is converted to a
different case depending upon the capitalization of the text to be
replaced. If the original text is all upper case, the replacement text
is converted to upper case. If the first word of the original text is
capitalized, then the first word of the replacement text is capitalized.
If the original text contains just one word, and that word is a capital
letter, @code{replace-match} considers this a capitalized first word
rather than all upper case.
If @code{case-replace} is @code{nil}, then case conversion is not done,
regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
exactly as it is, the only alterations being case changes as needed.
If it is @code{nil} (the default), then the character @samp{\} is treated
specially. If a @samp{\} appears in @var{replacement}, then it must be
part of one of the following sequences:
@table @asis
@item @samp{\&}
@cindex @samp{&} in replacement
@samp{\&} stands for the entire text being replaced.
@item @samp{\@var{n}}
@cindex @samp{\@var{n}} in replacement
@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
matched the @var{n}th subexpression in the original regexp.
Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
@item @samp{\\}
@cindex @samp{\} in replacement
@samp{\\} stands for a single @samp{\} in the replacement text.
@end table
If @var{subexp} is non-@code{nil}, that says to replace just
subexpression number @var{subexp} of the regexp that was matched, not
the entire match. For example, after matching @samp{foo \(ba*r\)},
calling @code{replace-match} with 1 as @var{subexp} means to replace
just the text that matched @samp{\(ba*r\)}.
@end defun
@node Simple Match Data
@subsection Simple Match Data Access
@ -1038,7 +1101,7 @@ range, or if that subexpression didn't match anything, the value is
If the last such operation was done against a string with
@code{string-match}, then you should pass the same string as the
argument @var{in-string}. Otherwise, after a buffer search or match,
argument @var{in-string}. After a buffer search or match,
you should omit @var{in-string} or pass @code{nil} for it; but you
should make sure that the current buffer when you call
@code{match-string} is the one in which you did the searching or
@ -1056,7 +1119,7 @@ last regular expression searched for, or a subexpression of it.
If @var{count} is zero, then the value is the position of the start of
the entire match. Otherwise, @var{count} specifies a subexpression in
the regular expresion, and the value of the function is the starting
the regular expression, and the value of the function is the starting
position of the match for that subexpression.
The value is @code{nil} for a subexpression inside a @samp{\|}
@ -1136,69 +1199,6 @@ I read "The cat @point{}in the hat comes back" twice.
(In this case, the index returned is a buffer position; the first
character of the buffer counts as 1.)
@node Replacing Match
@subsection Replacing the Text That Matched
This function replaces the text matched by the last search with
@var{replacement}.
@cindex case in replacements
@defun replace-match replacement &optional fixedcase literal string subexp
This function replaces the text in the buffer (or in @var{string}) that
was matched by the last search. It replaces that text with
@var{replacement}.
If you did the last search in a buffer, you should specify @code{nil}
for @var{string}. Then @code{replace-match} does the replacement by
editing the buffer; it leaves point at the end of the replacement text,
and returns @code{t}.
If you did the search in a string, pass the same string as @var{string}.
Then @code{replace-match} does the replacement by constructing and
returning a new string.
If @var{fixedcase} is non-@code{nil}, then the case of the replacement
text is not changed; otherwise, the replacement text is converted to a
different case depending upon the capitalization of the text to be
replaced. If the original text is all upper case, the replacement text
is converted to upper case. If the first word of the original text is
capitalized, then the first word of the replacement text is capitalized.
If the original text contains just one word, and that word is a capital
letter, @code{replace-match} considers this a capitalized first word
rather than all upper case.
If @code{case-replace} is @code{nil}, then case conversion is not done,
regardless of the value of @var{fixed-case}. @xref{Searching and Case}.
If @var{literal} is non-@code{nil}, then @var{replacement} is inserted
exactly as it is, the only alterations being case changes as needed.
If it is @code{nil} (the default), then the character @samp{\} is treated
specially. If a @samp{\} appears in @var{replacement}, then it must be
part of one of the following sequences:
@table @asis
@item @samp{\&}
@cindex @samp{&} in replacement
@samp{\&} stands for the entire text being replaced.
@item @samp{\@var{n}}
@cindex @samp{\@var{n}} in replacement
@samp{\@var{n}}, where @var{n} is a digit, stands for the text that
matched the @var{n}th subexpression in the original regexp.
Subexpressions are those expressions grouped inside @samp{\(@dots{}\)}.
@item @samp{\\}
@cindex @samp{\} in replacement
@samp{\\} stands for a single @samp{\} in the replacement text.
@end table
If @var{subexp} is non-@code{nil}, that says to replace just
subexpression number @var{subexp} of the regexp that was matched, not
the entire match. For example, after matching @samp{foo \(ba*r\)},
calling @code{replace-match} with 1 as @var{subexp} means to replace
just the text that matched @samp{\(ba*r\)}.
@end defun
@node Entire Match Data
@subsection Accessing the Entire Match Data
@ -1230,9 +1230,7 @@ corresponds to @code{(match-end @var{n})}.
All the elements are markers or @code{nil} if matching was done on a
buffer, and all are integers or @code{nil} if matching was done on a
string with @code{string-match}. (In Emacs 18 and earlier versions,
markers were used even for matching on a string, except in the case
of the integer 0.)
string with @code{string-match}.
As always, there must be no possibility of intervening searches between
the call to a search function and the call to @code{match-data} that is
@ -1258,7 +1256,7 @@ If @var{match-list} refers to a buffer that doesn't exist, you don't get
an error; that sets the match data in a meaningless but harmless way.
@findex store-match-data
@code{store-match-data} is an alias for @code{set-match-data}.
@code{store-match-data} is a semi-obsolete alias for @code{set-match-data}.
@end defun
@node Saving Match Data
@ -1287,9 +1285,9 @@ This special form executes @var{body}, saving and restoring the match
data around it.
@end defmac
You can use @code{set-match-data} together with @code{match-data} to
imitate the effect of the special form @code{save-match-data}. This is
useful for writing code that can run in Emacs 18. Here is how:
You could use @code{set-match-data} together with @code{match-data} to
imitate the effect of the special form @code{save-match-data}. Here is
how:
@example
@group
@ -1384,9 +1382,10 @@ same as @code{(default-value 'case-fold-search)}.
used for certain purposes in editing:
@defvar page-delimiter
This is the regexp describing line-beginnings that separate pages. The
default value is @code{"^\014"} (i.e., @code{"^^L"} or @code{"^\C-l"});
this matches a line that starts with a formfeed character.
This is the regular expression describing line-beginnings that separate
pages. The default value is @code{"^\014"} (i.e., @code{"^^L"} or
@code{"^\C-l"}); this matches a line that starts with a formfeed
character.
@end defvar
The following two regular expressions should @emph{not} assume the

272
lispref/sequences.texi
View file

@ -7,16 +7,15 @@
@chapter Sequences, Arrays, and Vectors
@cindex sequence
Recall that the @dfn{sequence} type is the union of three other Lisp
types: lists, vectors, and strings. In other words, any list is a
sequence, any vector is a sequence, and any string is a sequence. The
common property that all sequences have is that each is an ordered
collection of elements.
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
elements. All the elements are accessible in constant time, but the
length of an existing array cannot be changed. Strings and vectors are
the two types of arrays.
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
@ -28,18 +27,22 @@ But it is possible to add elements to the list, or remove elements.
@example
@group
___________________________________
| |
| Sequence |
| ______ ______________________ |
| | | | | |
| | List | | Array | |
| | | | ________ _______ | |
| |______| | | | | | | |
| | | Vector | | String| | |
| | |________| |_______| | |
| |______________________| |
|___________________________________|
_____________________________________________
| |
| Sequence |
| ______ ________________________________ |
| | | | | |
| | List | | Array | |
| | | | ________ ________ | |
| |______| | | | | | | |
| | | Vector | | String | | |
| | |________| |________| | |
| | ____________ _____________ | |
| | | | | | | |
| | | Char-table | | Bool-vector | | |
| | |____________| |_____________| | |
| |________________________________| |
|_____________________________________________|
@end group
@end example
@ -59,16 +62,88 @@ elements of strings are all characters.
@node Sequence Functions
@section Sequences
In Emacs Lisp, a @dfn{sequence} is either a list, a vector or a
string. The common property that all sequences have is that each is an
ordered collection of elements. This section describes functions that
accept any kind of sequence.
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, or
string, @code{nil} otherwise.
@end defun
@defun length sequence
@cindex string length
@cindex list length
@cindex vector length
@cindex sequence length
This function returns the number of elements in @var{sequence}. If
@var{sequence} is a cons cell that is not a list (because the final
@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
signaled.
@xref{List Elements}, for the related function @code{safe-list}.
@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
@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, then out-of-range values of @var{index} return @code{nil};
otherwise, they 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{List Elements}).
@end defun
@defun copy-sequence sequence
@cindex copying sequences
Returns a copy of @var{sequence}. The copy is the same type of object
@ -133,72 +208,6 @@ y @result{} [foo (69 2)]
@end example
@end defun
@defun length sequence
@cindex string length
@cindex list length
@cindex vector length
@cindex sequence length
Returns the number of elements in @var{sequence}. If @var{sequence} is
a cons cell that is not a list (because the final @sc{cdr} is not
@code{nil}), a @code{wrong-type-argument} error is signaled.
@xref{List Elements}, for the related function @code{safe-list}.
@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
@end example
@end defun
@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, then out-of-range values of @var{index} return @code{nil};
otherwise, they 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
(char-to-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{List Elements}).
@end defun
@node Arrays
@section Arrays
@cindex array
@ -209,20 +218,14 @@ 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.
When you create an array, you must specify how many elements it has.
The amount of space allocated depends on the number of elements.
Therefore, it is impossible to change the size of an array once it is
created; you cannot add or remove elements. However, you can replace an
element with a different value.
Emacs defines four types of array, both of which are 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 (i.e.,
integers between 0 and 255). Each type of array has its own read
syntax. @xref{String Type}, and @ref{Vector Type}.
Emacs defines two types of array, both of which are one-dimensional:
@dfn{strings} and @dfn{vectors}. A vector is a general array; its
elements can be any Lisp objects. A string is a specialized array; its
elements must be characters (i.e., integers between 0 and 255). Each
type of array has its own read syntax. @xref{String Type}, and
@ref{Vector Type}.
Both kinds of array share these characteristics:
All four kinds of array share these characteristics:
@itemize @bullet
@item
@ -230,14 +233,26 @@ 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
The array is a constant, for evaluation---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
In principle, if you wish to have 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:
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
@ -274,9 +289,11 @@ vector, a string, a bool-vector or a char-table).
@example
@group
(arrayp [a])
@result{} t
@result{} t
(arrayp "asdf")
@result{} t
@result{} t
(arrayp (syntax-table)) ;; @r{A char-table.}
@result{} t
@end group
@end example
@end defun
@ -292,10 +309,7 @@ first element is at index zero.
@result{} [2 3 5 7 11 13]
(aref primes 4)
@result{} 11
(elt primes 4)
@result{} 11
@end group
@group
(aref "abcdefg" 1)
@result{} 98 ; @r{@samp{b} is @sc{ASCII} code 98.}
@ -371,11 +385,11 @@ are often useful for objects known to be arrays. @xref{Sequence Functions}.
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; 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
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
@ -405,7 +419,7 @@ not evaluate or even examine the elements of the vector.
@end example
@node Vector Functions
@section Functions That Operate on Vectors
@section Functions for Vectors
Here are some functions that relate to vectors:
@ -473,6 +487,10 @@ existing vector.
@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}.
The @code{vconcat} function also allows integers as arguments. It
converts them to strings of digits, making up the decimal print
representation of the integer, and then uses the strings instead of the
@ -505,8 +523,9 @@ list with the same elements (@pxref{Building Lists}):
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 with
@code{aref} and @code{aset}, just like a vector.
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.
Char-tables are constants when evaluated.
@cindex extra slots of char-table
@cindex subtype of char-table
@ -534,11 +553,14 @@ 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
@tindex char-table-p
@defun char-table-p object
This function returns @code{t} if @code{object} is a char-table,
This function returns @code{t} if @var{object} is a char-table,
otherwise @code{nil}.
@end defun
@ -628,9 +650,9 @@ 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}, and the
value is @code{(char-table-range @var{char-table} @var{key})}. Invalid
character codes are never used as the key.
character codes are never used as @var{key}.
Overall, the keys-value pairs passed to @var{function} describe all the
Overall, the key-value pairs passed to @var{function} describe all the
values stored in @var{char-table}.
@end defun
@ -640,8 +662,10 @@ values stored in @var{char-table}.
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, that actually stores @code{t}
there.
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

69
lispref/streams.texi
View file

@ -103,17 +103,21 @@ 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}, one character per
call. Normally @var{function} is called with no arguments, and should
return a character.
The input characters are generated by @var{function}, which must support
two kinds of calls:
@cindex unreading
Occasionally @var{function} is called with one argument (always a
character). When that happens, @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.
@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
@ -163,13 +167,6 @@ This is the@point{} contents of foo.
Note that the first read skips a space. Reading skips any amount of
whitespace preceding the significant text.
In Emacs 18, reading a symbol discarded the delimiter terminating the
symbol. Thus, point would end up at the beginning of @samp{contents}
rather than after @samp{the}. The current behavior is superior because
it correctly handles input such as @samp{bar(foo)}, where the
open-parenthesis that ends one object is needed as the beginning of
another object.
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}.
@ -296,9 +293,9 @@ 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 @var{end} is
also supplied, then reading stops just before that index, as if the rest
of the string were not there.
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:
@ -381,8 +378,8 @@ 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 mostly one of
how you use a Lisp object, not a distinction of types of object.
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
@ -532,18 +529,18 @@ 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 it is best to 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 better
to print without quoting.
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.
Printing a self-referent Lisp object requires an infinite amount of
text. In certain cases, trying to produce this text leads to a stack
overflow. 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:
Printing a self-referent Lisp object in the normal way would require
an infinite amount of text, and could even result in stack overflow.
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))
@ -696,9 +693,9 @@ 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},
as well as everything that uses them. It does not affect @code{princ}.
Here is an example using @code{prin1}:
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

127
lispref/strings.texi
View file

@ -29,8 +29,8 @@ keyboard character events.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}.
* Character Case:: Case conversion functions.
* Case Table:: Customizing case conversion.
* Case Conversion:: Case conversion functions.
* Case Tables:: Customizing case conversion.
@end menu
@node String Basics
@ -38,19 +38,19 @@ keyboard character events.
Strings in Emacs Lisp are arrays that contain an ordered sequence of
characters. Characters are represented in Emacs Lisp as integers;
whether an integer was intended as a character or not is determined only
by how it is used. Thus, strings really contain integers.
whether an integer is a character or not is determined only by how it is
used. Thus, strings really contain integers.
The length of a string (like any array) is fixed, and cannot be
altered once the string exists. Strings in Lisp are @emph{not}
terminated by a distinguished character code. (By contrast, strings in
C are terminated by a character with @sc{ASCII} code 0.)
Since strings are considered arrays, you can operate on them with the
general array functions. (@xref{Sequences Arrays Vectors}.) For
example, you can access or change individual characters in a string
using the functions @code{aref} and @code{aset} (@pxref{Array
Functions}).
Since strings are arrays, and therefore sequences as well, you can
operate on them with the general array and sequence functions.
(@xref{Sequences Arrays Vectors}.) For example, you can access or
change individual characters in a string using the functions @code{aref}
and @code{aset} (@pxref{Array Functions}).
There are two text representations for non-@sc{ASCII} characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
@ -62,8 +62,8 @@ representations.
Sometimes key sequences are represented as strings. When a string is
a key sequence, string elements in the range 128 to 255 represent meta
characters (which are extremely large integers) rather than keyboard
events in the range 128 to 255.
characters (which are extremely large integers) rather than character
codes in the range 128 to 255.
Strings cannot hold characters that have the hyper, super or alt
modifiers; they can hold @sc{ASCII} control characters, but no other
@ -201,14 +201,19 @@ Functions}).
If the characters copied from @var{string} have text properties, the
properties are copied into the new string also. @xref{Text Properties}.
@code{substring} also allows vectors for the first argument.
For example:
@example
(substring [a b (c) "d"] 1 3)
@result{} [b (c)]
@end example
A @code{wrong-type-argument} error is signaled if either @var{start} or
@var{end} is not an integer or @code{nil}. An @code{args-out-of-range}
error is signaled if @var{start} indicates a character following
@var{end}, or if either integer is out of range for @var{string}.
@code{substring} actually allows vectors as well as strings for
the first argument.
Contrast this function with @code{buffer-substring} (@pxref{Buffer
Contents}), which returns a string containing a portion of the text in
the current buffer. The beginning of a string is at index 0, but the
@ -313,7 +318,7 @@ Empty matches do count, when not adjacent to another match:
@var{idx} @var{char})} stores @var{char} into @var{string} at index
@var{idx}. Each character occupies one or more bytes, and if @var{char}
needs a different number of bytes from the character already present at
that index, @code{aset} gets an error.
that index, @code{aset} signals an error.
A more powerful function is @code{store-substring}:
@ -325,8 +330,8 @@ may be either a character or a (smaller) string.
Since it is impossible to change the length of an existing string, it is
an error if @var{obj} doesn't fit within @var{string}'s actual length,
or if it requires a different number of bytes from the characters
currently present at that point in @var{string}.
of if any new character requires a different number of bytes from the
character currently present at that point in @var{string}.
@end defun
@need 2000
@ -365,7 +370,7 @@ The function @code{string=} ignores the text properties of the two
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
If the arguments contain non-@sc{ASCII} characters, and one is unibyte
If the strings contain non-@sc{ASCII} characters, and one is unibyte
while the other is multibyte, then they cannot be equal. @xref{Text
Representations}.
@end defun
@ -385,11 +390,12 @@ function returns @code{t}. If the lesser character is the one from
@var{string2}, then @var{string1} is greater, and this function returns
@code{nil}. If the two strings match entirely, the value is @code{nil}.
Pairs of characters are compared by their @sc{ASCII} codes. Keep in
mind that lower case letters have higher numeric values in the
@sc{ASCII} character set than their upper case counterparts; numbers and
Pairs of characters are compared according to their character codes.
Keep in mind that lower case letters have higher numeric values in the
@sc{ASCII} character set than their upper case counterparts; digits and
many punctuation characters have a lower numeric value than upper case
letters. A unibyte non-@sc{ASCII} character is always less than any
letters. An @sc{ASCII} character is less than any non-@sc{ASCII}
character; a unibyte non-@sc{ASCII} character is always less than any
multibyte non-@sc{ASCII} character (@pxref{Text Representations}).
@example
@ -453,23 +459,9 @@ functions are used primarily for making help messages.
@defun char-to-string character
@cindex character to string
This function returns a new string with a length of one character.
The value of @var{character}, modulo 256, is used to initialize the
element of the string.
This function is similar to @code{make-string} with an integer argument
of 1. (@xref{Creating Strings}.) This conversion can also be done with
@code{format} using the @samp{%c} format specification.
(@xref{Formatting Strings}.)
@example
(char-to-string ?x)
@result{} "x"
(char-to-string (+ 256 ?x))
@result{} "x"
(make-string 1 ?x)
@result{} "x"
@end example
This function returns a new string containing one character,
@var{character}. This function is semi-obsolete because the function
@code{string} is more general. @xref{Creating Strings}.
@end defun
@defun string-to-char string
@ -579,7 +571,7 @@ formatting feature described here; they differ from @code{format} only
in how they use the result of formatting.
@defun format string &rest objects
This function returns a new string that is made by copying
This function returns a new string that is made by copying
@var{string} and then replacing any format specification
in the copy with encodings of the corresponding @var{objects}. The
arguments @var{objects} are the computed values to be formatted.
@ -619,7 +611,7 @@ meaningless.
@item %s
Replace the specification with the printed representation of the object,
made without quoting (that is, using @code{princ}, not
@code{print}---@pxref{Output Functions}). Thus, strings are represented
@code{prin1}---@pxref{Output Functions}). Thus, strings are represented
by their contents alone, with no @samp{"} characters, and symbols appear
without @samp{\} characters.
@ -740,12 +732,13 @@ not truncated. In the third case, the padding is on the right.
@end group
@end smallexample
@node Character Case
@node Case Conversion
@comment node-name, next, previous, up
@section Character Case
@section Case Conversion in Lisp
@cindex upper case
@cindex lower case
@cindex character case
@cindex case conversion in Lisp
The character case functions change the case of single characters or
of the contents of strings. The functions convert only alphabetic
@ -827,18 +820,39 @@ has the same result as @code{upcase}.
@end example
@end defun
@node Case Table
@defun upcase-initials string
This function capitalizes the initials of the words in @var{string}.
without altering any letters other than the initials. It returns a new
string whose contents are a copy of @var{string-or-char}, in which each
word has been converted to upper case.
The definition of a word is any sequence of consecutive characters that
are assigned to the word constituent syntax class in the current syntax
table (@xref{Syntax Class Table}).
@example
@group
(upcase-initials "The CAT in the hAt")
@result{} "The CAT In The HAt"
@end group
@end example
@end defun
@node Case Tables
@section The Case Table
You can customize case conversion by installing a special @dfn{case
table}. A case table specifies the mapping between upper case and lower
case letters. It affects both the string and character case conversion
functions (see the previous section) and those that apply to text in the
buffer (@pxref{Case Changes}).
case letters. It affects both the case conversion functions for Lisp
objects (see the previous section) and those that apply to text in the
buffer (@pxref{Case Changes}). Each buffer has a case table; there is
also a standard case table which is used to initialize the case table
of new buffers.
A case table is a char-table whose subtype is @code{case-table}. This
char-table maps each character into the corresponding lower case
character It has three extra slots, which are related tables:
A case table is a char-table (@pxref{Char-Tables}) whose subtype is
@code{case-table}. This char-table maps each character into the
corresponding lower case character. It has three extra slots, which
hold related tables:
@table @var
@item upcase
@ -874,17 +888,13 @@ equivalent). (For ordinary @sc{ASCII}, this would map @samp{a} into
equivalent characters.)
When you construct a case table, you can provide @code{nil} for
@var{canonicalize}; then Emacs fills in this string from the lower case
@var{canonicalize}; then Emacs fills in this slot from the lower case
and upper case mappings. You can also provide @code{nil} for
@var{equivalences}; then Emacs fills in this string from
@var{equivalences}; then Emacs fills in this slot from
@var{canonicalize}. In a case table that is actually in use, those
components are non-@code{nil}. Do not try to specify @var{equivalences}
without also specifying @var{canonicalize}.
Each buffer has a case table. Emacs also has a @dfn{standard case
table} which is copied into each buffer when you create the buffer.
Changing the standard case table doesn't affect any existing buffers.
Here are the functions for working with case tables:
@defun case-table-p object
@ -894,7 +904,7 @@ table.
@defun set-standard-case-table table
This function makes @var{table} the standard case table, so that it will
apply to any buffers created subsequently.
be used in any buffers created subsequently.
@end defun
@defun standard-case-table
@ -912,7 +922,8 @@ This sets the current buffer's case table to @var{table}.
The following three functions are convenient subroutines for packages
that define non-@sc{ASCII} character sets. They modify the specified
case table @var{case-table}; they also modify the standard syntax table.
@xref{Syntax Tables}.
@xref{Syntax Tables}. Normally you would use these functions to change
the standard case table.
@defun set-case-syntax-pair uc lc case-table
This function specifies a pair of corresponding letters, one upper case

23
lispref/symbols.texi
View file

@ -145,7 +145,8 @@ 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}.
@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
@ -229,11 +230,6 @@ 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.
It is possible for two different symbols to have the same name in
different obarrays; these symbols are not @code{eq} or @code{equal}.
However, this normally happens only as part of the abbrev mechanism
(@pxref{Abbrevs}).
@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.
@ -440,10 +436,10 @@ 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 including the name of the library in the property
name.) 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.
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
@ -532,3 +528,10 @@ in the place where you got @var{plist}. For example,
@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

177
lispref/syntax.texi
View file

@ -44,12 +44,16 @@ list motion functions (@pxref{List Motion}) as well as the functions in
this chapter.
@end ifinfo
A syntax table is a char-table (@pxref{Char-Tables}). Each element is
a list that encodes the syntax of the character in question.
A syntax table is a char-table (@pxref{Char-Tables}). The element at
index @var{c} describes the character with code @var{c}. The element's
value should be a list that encodes the syntax of the character in
question.
Syntax tables are used only for moving across text, not for the Emacs
Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp
expressions, and these rules cannot be changed.
expressions, and these rules cannot be changed. (Some Lisp systems
provide ways to redefine the read syntax, but we decided to leave this
feature out of Emacs Lisp for simplicity.)
Each buffer has its own major mode, and each major mode has its own
idea of the syntactic class of various characters. For example, in Lisp
@ -80,12 +84,11 @@ This function returns @code{t} if @var{object} is a syntax table.
This section describes the syntax classes and flags that denote the
syntax of a character, and how they are represented as a @dfn{syntax
descriptor}, which is a Lisp string that you pass to
@code{modify-syntax-entry} to specify the desired syntax.
@code{modify-syntax-entry} to specify the syntax you want.
Emacs defines a number of @dfn{syntax classes}. Each syntax table
puts each character into one class. There is no necessary relationship
between the class of a character in one syntax table and its class in
any other table.
The syntax table specifies a syntax class for each character. There
is no necessary relationship between the class of a character in one
syntax table and its class in any other table.
Each class is designated by a mnemonic character, which serves as the
name of the class when you need to specify a class. Usually the
@ -124,7 +127,8 @@ their meanings, and examples of their use.
separate symbols and words from each other. Typically, whitespace
characters have no other syntactic significance, and multiple whitespace
characters are syntactically equivalent to a single one. Space, tab,
newline and formfeed are almost always classified as whitespace.
newline and formfeed are classified as whitespace in almost all major
modes.
@end deffn
@deffn {Syntax class} @w{word constituent}
@ -384,9 +388,9 @@ prefix (@samp{'}). @xref{Motion and Syntax}.
altering syntax tables.
@defun make-syntax-table
This function creates a new syntax table. Character codes 32 through
127 are set up by copying the syntax from the standard syntax table.
All other codes are set up to inherit from the standard syntax table.
This function creates a new syntax table. It inherits the syntax for
letters and control characters from the standard syntax table. For
other characters, the syntax is copied from the standard syntax table.
Most major mode syntax tables are created in this way.
@end defun
@ -465,20 +469,23 @@ character, @samp{)}.
@example
@group
(char-to-string (char-syntax ?\ ))
(string (char-syntax ?\ ))
@result{} " "
@end group
@group
(char-to-string (char-syntax ?/))
(string (char-syntax ?/))
@result{} "."
@end group
@group
(char-to-string (char-syntax ?\())
(string (char-syntax ?\())
@result{} "("
@end group
@end example
We use @code{string} to make it easier to see the character returned by
@code{char-syntax}.
@end defun
@defun set-syntax-table table
@ -500,7 +507,7 @@ language, you can use @code{syntax-table} text properties to override
the syntax table for specific character occurrences in the buffer.
@xref{Text Properties}.
The valid values of @code{syntax-table} text property are
The valid values of @code{syntax-table} text property are:
@table @asis
@item @var{syntax-table}
@ -527,9 +534,8 @@ table.
@node Motion and Syntax
@section Motion and Syntax
This section describes functions for moving across characters in
certain syntax classes. None of these functions exists in Emacs
version 18 or earlier.
This section describes functions for moving across characters that
have certain syntax classes.
@defun skip-syntax-forward syntaxes &optional limit
This function moves point forward across characters having syntax classes
@ -596,7 +602,7 @@ string, or the of a comment or a string, whichever comes first.
@cindex parse state
The fifth argument @var{state} is a nine-element list of the same form
as the value of this function, described below. (It is ok to omit the
as the value of this function, described below. (It is OK to omit the
last element of the nine.) The return value of one call may be used to
initialize the state of the parse on another call to
@code{parse-partial-sexp}.
@ -758,42 +764,46 @@ a character to match was specified.
This table gives the value of @var{syntax-code} which corresponds
to each syntactic type.
@table @asis
@item @i{Integer}
@i{Class}
@item 0
whitespace
@item 1
punctuation
@item 2
word
@item 3
symbol
@item 4
open parenthesis
@item 5
close parenthesis
@item 6
expression prefix
@item 7
string quote
@item 8
paired delimiter
@item 9
escape
@item 10
character quote
@item 11
comment-start
@item 12
comment-end
@item 13
inherit
@item 14
comment-fence
@item 15
string-fence
@end table
@multitable @columnfractions .05 .3 .3 .3
@item@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
@item@tab
0 @ @ whitespace
@tab
5 @ @ close parenthesis
@tab
10 @ @ character quote
@item@tab
1 @ @ punctuation
@tab
6 @ @ expression prefix
@tab
11 @ @ comment-start
@item@tab
2 @ @ word
@tab
7 @ @ string quote
@tab
12 @ @ comment-end
@item@tab
3 @ @ symbol
@tab
8 @ @ paired delimiter
@tab
13 @ @ inherit
@item@tab
4 @ @ open parenthesis
@tab
9 @ @ escape
@tab
14 @ @ comment-fence
@item@tab
15 @ string-fence
@end multitable
For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
(41 is the character code for @samp{)}.)
@ -802,39 +812,46 @@ string-fence
least significant bit. This table gives the power of two which
corresponds to each syntax flag.
@table @samp
@item @i{Flag}
@i{Bit value}
@item 1
@code{(lsh 1 16)}
@item 2
@code{(lsh 1 17)}
@item 3
@code{(lsh 1 18)}
@item 4
@code{(lsh 1 19)}
@item p
@code{(lsh 1 20)}
@item b
@code{(lsh 1 21)}
@end table
@multitable @columnfractions .05 .3 .3 .3
@item@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
@item@tab
@samp{1} @ @ @code{(lsh 1 16)}
@tab
@samp{3} @ @ @code{(lsh 1 18)}
@tab
@samp{p} @ @ @code{(lsh 1 20)}
@item@tab
@samp{2} @ @ @code{(lsh 1 17)}
@tab
@samp{4} @ @ @code{(lsh 1 19)}
@tab
@samp{b} @ @ @code{(lsh 1 21)}
@end multitable
@node Categories
@section Categories
@cindex categories of characters
@dfn{Categories} provide an alternate way of classifying characters
syntactically. You can define a large number of categories, and then
independently assign each character to one or more of them. Unlike
syntactically. You can define several categories as needed, then
independently assign each character to one or more categories. Unlike
syntax classes, categories are not mutually exclusive; it is normal for
one character to belong to several categories.
Each buffer has a @dfn{category table} which records which categories
are defined and also which characters belong to each category. Each
category table defines its own categories. Each category has a name,
which is an @sc{ASCII} printing character in the range @w{@samp{ }} to
@samp{~}. You specify the name of a category when you define it with
@code{define-category}.
category table defines its own categories, but normally these are
initialized by copying from the standard categories table, so that the
standard categories are available in all modes.
Each category has a name, which is an @sc{ASCII} printing character in
the range @w{@samp{ }} to @samp{~}. You specify the name of a category
when you define it with @code{define-category}.
The category table is actually a char-table (@pxref{Char-Tables}).
The element of the category table at index @var{c} is a @dfn{category
@ -865,8 +882,8 @@ in category table @var{table}.
@defun get-unused-category table
This function returns a category name (a character) which is not
currently defined in @var{table}. If none is still available, it
returns @code{nil},
currently defined in @var{table}. If all possible categories are in use
in @var{table}, it returns @code{nil},
@end defun
@defun category-table

208
lispref/text.texi
View file

@ -79,6 +79,13 @@ buffer is @samp{@@}:
@end example
@end defun
@defun char-before position
This function returns the character in the current buffer immediately
before position @var{position}. If @var{position} is out of range for
this purpose, either before the beginning of the buffer, or at or beyond
the end, then the value is @code{nil}.
@end defun
@defun following-char
This function returns the character following point in the current
buffer. This is similar to @code{(char-after (point))}. However, if
@ -185,19 +192,6 @@ This is the contents of buffer foo
@defun buffer-substring-no-properties start end
This is like @code{buffer-substring}, except that it does not copy text
properties, just the characters themselves. @xref{Text Properties}.
Here's an example of using this function to get a word to look up in an
alist:
@example
(setq flammable
(assoc (buffer-substring-no-properties start end)
'(("wood" . t) ("paper" . t)
("steel" . nil) ("asbestos" . nil))))
@end example
If this were written using @code{buffer-substring} instead, it would not
work reliably; any text properties that happened to be in the word
copied from the buffer would make the comparisons fail.
@end defun
@defun buffer-string
@ -282,23 +276,22 @@ at the second character.
@cindex insertion of text
@cindex text insertion
@cindex insertion before point
@cindex before point, insertion
@dfn{Insertion} means adding new text to a buffer. The inserted text
goes at point---between the character before point and the character
after point.
after point. Some insertion functions leave point before the inserted
text, while other functions leave it after. We call the former
insertion @dfn{after point} and the latter insertion @dfn{before point}.
Insertion relocates markers that point at positions after the
insertion point, so that they stay with the surrounding text
(@pxref{Markers}). When a marker points at the place of insertion,
insertion normally doesn't relocate the marker, so that it points to the
beginning of the inserted text; however, certain special functions such
as @code{insert-before-markers} relocate such markers to point after the
inserted text.
@cindex insertion before point
@cindex before point, insertion
Some insertion functions leave point before the inserted text, while
other functions leave it after. We call the former insertion @dfn{after
point} and the latter insertion @dfn{before point}.
insertion may or may not relocate the marker, depending on the marker's
insertion type (@pxref{Marker Insertion Types}). Certain special
functions such as @code{insert-before-markers} relocate all such markers
to point after the inserted text, regardless of the markers' insertion
type.
Insertion functions signal an error if the current buffer is
read-only.
@ -329,11 +322,11 @@ inserted text falls outside the overlay; if a nonempty overlay ends at
the insertion point, the inserted text falls inside that overlay.
@end defun
@defun insert-char character count &optional inherit
@defun insert-char character &optional count inherit
This function inserts @var{count} instances of @var{character} into the
current buffer before point. The argument @var{count} must be a number,
and @var{character} must be a character. The value is @code{nil}.
@c It's unfortunate that count comes second. Not like make-string, etc.
current buffer before point. The argument @var{count} should be a
number (@code{nil} means 1), and @var{character} must be a character.
The value is @code{nil}.
If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
@ -531,6 +524,16 @@ the kill ring.
The value returned is always @code{nil}.
@end deffn
@tindex backward-delete-char-untabify-method
@defopt backward-delete-char-untabify-method
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace. Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
@code{hungry}, meaning delete all the whitespace characters before point
with one command, and @code{nil}, meaning do nothing special for
whitespace characters.
@end defopt
@node User-Level Deletion
@section User-Level Deletion Commands
@ -668,7 +671,7 @@ A blank line is defined as a line containing only tabs and spaces.
@section The Kill Ring
@cindex kill ring
@dfn{Kill} functions delete text like the deletion functions, but save
@dfn{Kill functions} delete text like the deletion functions, but save
it so that the user can reinsert it by @dfn{yanking}. Most of these
functions have @samp{kill-} in their name. By contrast, the functions
whose names start with @samp{delete-} normally do not save text for
@ -828,10 +831,10 @@ The value is always @code{nil}.
@node Low-Level Kill Ring
@subsection Low-Level Kill Ring
These functions and variables provide access to the kill ring at a lower
level, but still convenient for use in Lisp programs. They take care of
interaction with X Window selections. They do not exist in Emacs
version 18.
These functions and variables provide access to the kill ring at a
lower level, but still convenient for use in Lisp programs, because they
take care of interaction with window system selections
(@pxref{Window System Selections}).
@defun current-kill n &optional do-not-move
The function @code{current-kill} rotates the yanking pointer which
@ -873,9 +876,9 @@ If the value is a function, @code{current-kill} calls it to get the
then that value is used as the ``most recent kill''. If it returns
@code{nil}, then the first element of @code{kill-ring} is used.
The normal use of this hook is to get the X server's primary selection
as the most recent kill, even if the selection belongs to another X
client. @xref{X Selections}.
The normal use of this hook is to get the window system's primary
selection as the most recent kill, even if the selection belongs to
another application. @xref{Window System Selections}.
@end defvar
@defvar interprogram-cut-function
@ -886,8 +889,8 @@ programs, when you are using a window system. Its value should be
If the value is a function, @code{kill-new} and @code{kill-append} call
it with the new first element of the kill ring as an argument.
The normal use of this hook is to set the X server's primary selection
from the newly killed text.
The normal use of this hook is to set the window system's primary
selection from the newly killed text. @xref{Window System Selections}.
@end defvar
@node Internals of Kill Ring
@ -925,10 +928,12 @@ different piece of text" "yet older text")}.
@example
@group
kill-ring kill-ring-yank-pointer
| |
| ___ ___ ---> ___ ___ ___ ___
--> |___|___|------> |___|___|--> |___|___|--> nil
kill-ring ---- kill-ring-yank-pointer
| |
| v
| --- --- --- --- --- ---
--> | | |------> | | |--> | | |--> nil
--- --- --- --- --- ---
| | |
| | |
| | -->"yet older text"
@ -1103,8 +1108,7 @@ has no effect.
This function returns @code{nil}. It cannot be called interactively.
The name @code{buffer-flush-undo} is not considered obsolete, but the
preferred name @code{buffer-disable-undo} is new as of Emacs versions
19.
preferred name is @code{buffer-disable-undo}.
@end defun
As editing continues, undo lists get longer and longer. To prevent
@ -1153,7 +1157,8 @@ If it is non-@code{nil}, that requests some kind of justification. It
can be @code{left}, @code{right}, @code{full}, or @code{center}, to
request a specific style of justification. If it is @code{t}, that
means to use the current justification style for this part of the text
(see @code{current-justification}, below).
(see @code{current-justification}, below). Any other value is treated
as @code{full}.
When you call the filling functions interactively, using a prefix
argument implies the value @code{full} for @var{justify}.
@ -1358,10 +1363,19 @@ whitespace.
@defvar left-margin
This variable specifies the base left margin column. In Fundamental
mode, @key{LFD} indents to this column. This variable automatically
mode, @kbd{C-j} indents to this column. This variable automatically
becomes buffer-local when set in any fashion.
@end defvar
@tindex fill-nobreak-predicate
@defvar fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at
certain places. Its value should be a function. This function is
called during filling, with no arguments and with point located at the
place where a break is being considered. If the function returns
non-@code{nil}, then the line won't be broken there.
@end defvar
@node Auto Filling
@comment node-name, next, previous, up
@section Auto Filling
@ -1395,7 +1409,8 @@ was renamed to @code{auto-fill-function} in version 19.
@defvar normal-auto-fill-function
This variable specifies the function to use for
@code{auto-fill-function}, if and when Auto Fill is turned on. Major
modes can set this locally to alter how Auto Fill works.
modes can set buffer-local values for this variable to alter how Auto
Fill works.
@end defvar
@node Sorting
@ -1485,9 +1500,7 @@ the sort order.
(save-restriction
(narrow-to-region beg end)
(goto-char (point-min))
(sort-subr reverse
'forward-line
'end-of-line)))
(sort-subr reverse 'forward-line 'end-of-line)))
@end group
@end example
@ -1503,8 +1516,7 @@ its @code{sort-subr} call looks like this:
@group
(sort-subr reverse
(function
(lambda ()
(skip-chars-forward "\n \t\f")))
(lambda () (skip-chars-forward "\n \t\f")))
'forward-paragraph)
@end group
@end example
@ -1630,7 +1642,7 @@ containing position @var{beg}, and the entire line containing position
Note that @code{sort-columns} uses the @code{sort} utility program,
and so cannot work properly on text containing tab characters. Use
@kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
@kbd{M-x untabify} to convert tabs to spaces before sorting.
@end deffn
@node Columns
@ -1715,7 +1727,7 @@ count from zero at the left margin.
This section describes the primitive functions used to count and
insert indentation. The functions in the following sections use these
primitives.
primitives. @xref{Width}, for related functions.
@defun current-indentation
@comment !!Type Primitive Function
@ -1745,7 +1757,7 @@ Properties}.
@comment !!SourceFile indent.c
If this variable is non-@code{nil}, indentation functions can insert
tabs as well as spaces. Otherwise, they insert only spaces. Setting
this variable automatically makes it local to the current buffer.
this variable automatically makes it buffer-local in the current buffer.
@end defopt
@node Mode-Specific Indent
@ -2009,11 +2021,11 @@ nonblank character on that line. It returns @code{nil}.
@node Case Changes
@comment node-name, next, previous, up
@section Case Changes
@cindex case changes
@cindex case conversion in buffers
The case change commands described here work on text in the current
buffer. @xref{Character Case}, for case conversion commands that work
on strings and characters. @xref{Case Table}, for how to customize
buffer. @xref{Case Conversion}, for case conversion functions that work
on strings and characters. @xref{Case Tables}, for how to customize
which characters are upper or lower case and how to convert them.
@deffn Command capitalize-region start end
@ -2417,9 +2429,9 @@ for @var{object} is the current buffer.
@subsection Properties with Special Meanings
Here is a table of text property names that have special built-in
meanings. The following section lists a few more special property names
that are used to control filling. All other names have no standard
meaning, and you can use them as you like.
meanings. The following sections list a few additional special property
names that control filling and property inheritance. All other names
have no standard meaning, and you can use them as you like.
@table @code
@cindex category of text character
@ -2813,8 +2825,8 @@ is done by the command definition. Here is how Dired does it:
(save-excursion
(set-buffer (window-buffer (posn-window (event-end event))))
(save-excursion
(goto-char (posn-point (event-end event)))
(setq file (dired-get-filename))))
(goto-char (posn-point (event-end event)))
(setq file (dired-get-filename))))
(select-window (posn-window (event-end event)))
(find-file-other-window (file-name-sans-versions file t))))
@end smallexample
@ -2955,15 +2967,11 @@ translation table.
@cindex registers
A register is a sort of variable used in Emacs editing that can hold a
marker, a string, a rectangle, a window configuration (of one frame), or
a frame configuration (of all frames). Each register is named by a
single character. All characters, including control and meta characters
(but with the exception of @kbd{C-g}), can be used to name registers.
Thus, there are 255 possible registers. A register is designated in
Emacs Lisp by a character that is its name.
The functions in this section return unpredictable values unless
otherwise stated.
variety of different kinds of values. Each register is named by a
single character. All ASCII characters and their meta variants (but
with the exception of @kbd{C-g}) can be used to name registers. Thus,
there are 255 possible registers. A register is designated in Emacs
Lisp by the character that is its name.
@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
@ -2971,13 +2979,47 @@ This variable is an alist of elements of the form @code{(@var{name} .
register that has been used.
The object @var{name} is a character (an integer) identifying the
register. The object @var{contents} is a string, marker, window
configuration, frame configuration, or list representing the register
contents. A string represents text stored in the register. A marker
represents a position. A list represents a rectangle; its elements are
strings, one per line of the rectangle.
register.
@end defvar
The @var{contents} of a register can have several possible types:
@table @asis
@item a number
A number stands for itself. If @code{insert-register} finds a number
in the register, it converts the number to decimal.
@item a marker
A marker represents a buffer position to jump to.
@item a string
A string is text saved in the register.
@item a rectangle
A rectangle is represented by a list of strings.
@item @code{(@var{window-configuration} @var{position})}
This represents a window configuration to restore in one frame, and a
position to jump to in the current buffer.
@item @code{(@var{frame-configuration} @var{position})}
This represents a frame configuration to restore, and a position
to jump to in the current buffer.
@item (file @var{filename})
This represents a file to visit; jumping to this value visits file
@var{filename}.
@item (file-query @var{filename} @var{position})
This represents a file to visit and a position in it; jumping to this
value visits file @var{filename} and goes to buffer position
@var{position}. Restoring this type of position asks the user for
confirmation first.
@end table
The functions in this section return unpredictable values unless
otherwise stated.
@defun get-register reg
This function returns the contents of the register
@var{reg}, or @code{nil} if it has no contents.
@ -3136,11 +3178,18 @@ that seems safe.
If a program makes several text changes in the same area of the buffer,
using the macro @code{combine-after-change-calls} around that part of
the program can make it run considerably faster when after-change hooks
are in use.
are in use. When the after-change hooks are ultimately called, the
arguments specify a portion of the buffer including all of the changes
made within the @code{combine-after-change-calls} body.
@strong{Warning:} You must not alter the values of
@code{after-change-functions} and @code{after-change-function} within
the body of a @code{combine-after-change-calls} form.
@strong{Note:} If the changes you combine occur in widely scattered
parts of the buffer, this will still work, but it is not advisable,
because it may lead to inefficient behavior for some change hook
functions.
@end defmac
@defvar before-change-function
@ -3177,8 +3226,11 @@ to call. Here is an example:
(while list
(funcall (car list) beg end len)
(setq list (cdr list)))))
@group
(add-hooks 'after-change-functions
'indirect-after-change-function)
@end group
@end example
@defvar first-change-hook

68
lispref/tips.texi
View file

@ -3,7 +3,7 @@
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, Calendar, Top
@node Tips, GNU Emacs Internals, System Interface, Top
@appendix Tips and Conventions
@cindex tips
@cindex standards of coding style
@ -37,10 +37,11 @@ names of all global variables, constants, and functions with the chosen
prefix. This helps avoid name conflicts.
This recommendation applies even to names for traditional Lisp
primitives that are not primitives in Emacs Lisp---even to @code{cadr}.
Believe it or not, there is more than one plausible way to define
@code{cadr}. Play it safe; append your name prefix to produce a name
like @code{foo-cadr} or @code{mylib-cadr} instead.
primitives that are not primitives in Emacs Lisp---even to
@code{copy-list}. Believe it or not, there is more than one plausible
way to define @code{copy-list}. Play it safe; append your name prefix
to produce a name like @code{foo-copy-list} or @code{mylib-copy-list}
instead.
If you write a function that you think ought to be added to Emacs under
a certain name, such as @code{twiddle-files}, don't call it by that name
@ -75,11 +76,11 @@ macro:
@end example
@noindent
(And @var{bar} should contain @code{(provide '@var{bar})}, to make the
@code{require} work.) This will cause @var{bar} to be loaded when you
byte-compile @var{foo}. Otherwise, you risk compiling @var{foo} without
the necessary macro loaded, and that would produce compiled code that
won't work right. @xref{Compiling Macros}.
(And the library @var{bar} should contain @code{(provide '@var{bar})},
to make the @code{require} work.) This will cause @var{bar} to be
loaded when you byte-compile @var{foo}. Otherwise, you risk compiling
@var{foo} without the necessary macro loaded, and that would produce
compiled code that won't work right. @xref{Compiling Macros}.
Using @code{eval-when-compile} avoids loading @var{bar} when
the compiled version of @var{foo} is @emph{used}.
@ -111,9 +112,9 @@ Instead, define sequences consisting of @kbd{C-c} followed by a control
character, a digit, or certain punctuation characters. These sequences
are reserved for major modes.
Changing all the major modes in Emacs 18 so they would follow this
convention was a lot of work. Abandoning this convention would make
that work go to waste, and inconvenience users.
Changing all the Emacs major modes to follow this convention was a lot
of work. Abandoning this convention would make that work go to waste,
and inconvenience users.
@item
Sequences consisting of @kbd{C-c} followed by @kbd{@{}, @kbd{@}},
@ -136,7 +137,7 @@ as a help character for listing the subcommands of the prefix character.
@item
Do not bind a key sequence ending in @key{ESC} except following
another @key{ESC}. (That is, it is ok to bind a sequence ending in
another @key{ESC}. (That is, it is OK to bind a sequence ending in
@kbd{@key{ESC} @key{ESC}}.)
The reason for this rule is that a non-prefix binding for @key{ESC} in
@ -251,7 +252,7 @@ user switch back at will. @xref{Recursive Editing}.
In some other systems there is a convention of choosing variable names
that begin and end with @samp{*}. We don't use that convention in Emacs
Lisp, so please don't use it in your programs. (Emacs uses such names
only for program-generated buffers.) The users will find Emacs more
only for special-purpose buffers.) The users will find Emacs more
coherent if all libraries use the same conventions.
@item
@ -273,7 +274,7 @@ default indentation parameters.
Don't make a habit of putting close-parentheses on lines by themselves;
Lisp programmers find this disconcerting. Once in a while, when there
is a sequence of many consecutive close-parentheses, it may make sense
to split them in one or two significant places.
to split the sequence in one or two significant places.
@item
Please put a copyright notice on the file if you give copies to anyone.
@ -366,7 +367,11 @@ the speed. @xref{Inline Functions}.
@node Documentation Tips
@section Tips for Documentation Strings
Here are some tips for the writing of documentation strings.
@tindex checkdoc-minor-mode
@findex checkdoc-minor-mode
Here are some tips and conventions for the writing of documentation
strings. You can check many of these conventions by running the command
@kbd{M-x checkdoc-minor-mode}.
@itemize @bullet
@item
@ -471,10 +476,18 @@ write @code{t} and @code{nil} without single-quotes.
When a documentation string refers to a Lisp symbol, write it as it
would be printed (which usually means in lower case), with single-quotes
around it. For example: @samp{lambda}. There are two exceptions: write
t and nil without single-quotes. (In this manual, we normally do use
single-quotes for those symbols.)
t and nil without single-quotes. (In this manual, we use a different
convention, with single-quotes for all symbols.)
@end ifinfo
For example:
@example
The value of `swim-speed' specifies how fast to swim.
Possible values are t for high speed, nil for low speed,
and `medium' for medium speed.
@end example
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
@ -541,11 +554,12 @@ at that point. For example:
@end group
@end smallexample
Every function that has no documentation string (because it is use only
internally within the package it belongs to), should have instead a
two-semicolon comment right before the function, explaining what the
function does and how to call it properly. Explain precisely what each
argument means and how the function interprets its possible values.
Every function that has no documentation string (presumably one that is
used only internally within the package it belongs to), should have
instead a two-semicolon comment right before the function, explaining
what the function does and how to call it properly. Explain precisely
what each argument means and how the function interprets its possible
values.
@item ;;;
Comments that start with three semicolons, @samp{;;;}, should start at
@ -584,7 +598,7 @@ program. For example:
@noindent
The indentation commands of the Lisp modes in Emacs, such as @kbd{M-;}
(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line})
(@code{indent-for-comment}) and @key{TAB} (@code{lisp-indent-line}),
automatically indent comments according to these conventions,
depending on the number of semicolons. @xref{Comments,,
Manipulating Comments, emacs, The GNU Emacs Manual}.
@ -613,7 +627,9 @@ them. This section explains these conventions. First, an example:
;; Keywords: docs
;; This file is part of GNU Emacs.
@var{copying permissions}@dots{}
@dots{}
;; Free Software Foundation, Inc., 59 Temple Place - Suite 330,
;; Boston, MA 02111-1307, USA.
@end group
@end smallexample

336
lispref/variables.texi
View file

@ -38,6 +38,8 @@ variable.
* Setting Variables:: Storing new values in variables.
* Variable Scoping:: How Lisp chooses among local and global values.
* Buffer-Local Variables:: Variable values in effect only in one buffer.
* Frame-Local Variables:: Variable values in effect only in one frame.
* Future Local Variables:: New kinds of local values we might add some day.
@end menu
@node Global Variables
@ -73,7 +75,8 @@ x @result{} (a b)
@noindent
assuming the @code{setq} form shown above has already been executed.
If you do another @code{setq}, the new value replaces the old one:
If you do set the same variable again, the new value replaces the old
one:
@example
@group
@ -96,14 +99,13 @@ x
@vindex t
@kindex setting-constant
In Emacs Lisp, certain symbols normally evaluate to themselves.
These include @code{nil} and @code{t}, as well as any symbol whose
name starts with @samp{:}.
The symbols @code{nil} and @code{t} @emph{always} evaluate to
themselves. These symbols cannot be rebound, nor can their values be
changed. Any attempt to change the value of @code{nil} or @code{t}
signals a @code{setting-constant} error.
In Emacs Lisp, certain symbols normally evaluate to themselves. These
include @code{nil} and @code{t}, as well as any symbol whose name starts
with @samp{:}. These symbols cannot be rebound, nor can their values be
changed. Any attempt to set or bind @code{nil} or @code{t} signals a
@code{setting-constant} error. The same is true for a symbol whose name
starts with @samp{:}, except that you are allowed to set such symbol to
itself.
@example
@group
@ -116,6 +118,13 @@ nil @equiv{} 'nil
@end group
@end example
@tindex keyword-symbols-constant-flag
@defvar keyword-symbols-constant-flag
If this variable is @code{nil}, you are allowed to set and bind symbols
whose names start with @samp{:} as you wish. This is to make it
possible to run old Lisp programs which do that.
@end defvar
@node Local Variables
@section Local Variables
@cindex binding local variables
@ -125,7 +134,7 @@ nil @equiv{} 'nil
Global variables have values that last until explicitly superseded
with new values. Sometimes it is useful to create variable values that
exist temporarily---only while within a certain part of the program.
exist temporarily---only until a certain part of the program finishes.
These values are called @dfn{local}, and the variables so used are
called @dfn{local variables}.
@ -143,7 +152,7 @@ local values may be shadowed (@pxref{Scope}).
If you set a variable (such as with @code{setq}) while it is local,
this replaces the local value; it does not alter the global value, or
previous local values that are shadowed. To model this behavior, we
previous local values, that are shadowed. To model this behavior, we
speak of a @dfn{local binding} of the variable as well as a local value.
The local binding is a conceptual place that holds a local value.
@ -161,12 +170,12 @@ not create a new binding.
A variable can have more than one local binding at a time (for
example, if there are nested @code{let} forms that bind it). In such a
case, the most recently created local binding that still exists is the
@dfn{current binding} of the variable. (This is called @dfn{dynamic
scoping}; see @ref{Variable Scoping}.) If there are no local bindings,
the variable's global binding is its current binding. We also call the
current binding the @dfn{most-local existing binding}, for emphasis.
Ordinary evaluation of a symbol always returns the value of its current
binding.
@dfn{current binding} of the variable. (This rule is called
@dfn{dynamic scoping}; see @ref{Variable Scoping}.) If there are no
local bindings, the variable's global binding is its current binding.
We sometimes call the current binding the @dfn{most-local existing
binding}, for emphasis. Ordinary evaluation of a symbol always returns
the value of its current binding.
The special forms @code{let} and @code{let*} exist to create
local bindings.
@ -289,8 +298,7 @@ the error @code{void-variable}, unless and until you set it again.
@example
@group
(makunbound 'x) ; @r{Make the global value}
; @r{of @code{x} void.}
(makunbound 'x) ; @r{Make the global value of @code{x} void.}
@result{} x
@end group
@group
@ -304,9 +312,9 @@ local existing binding. This is the only way a symbol can have a void
local binding, since all the constructs that create local bindings
create them with values. In this case, the voidness lasts at most as
long as the binding does; when the binding is removed due to exit from
the construct that made it, the previous or global binding is reexposed
as usual, and the variable is no longer void unless the newly reexposed
binding was void all along.
the construct that made it, the previous local or global binding is
reexposed as usual, and the variable is no longer void unless the newly
reexposed binding was void all along.
@smallexample
@group
@ -439,9 +447,9 @@ Emacs help functions (@pxref{Documentation}) look for this property.
If the first character of @var{doc-string} is @samp{*}, it means that
this variable is considered a user option. This lets users set the
variable conventiently using the commands @code{set-variable} and
variable conveniently using the commands @code{set-variable} and
@code{edit-options}. However, it is better to use @code{defcustom}
instead of @code{defvar}, for user option variables, to specify
instead of @code{defvar} for user option variables, so you can specify
customization information. @xref{Customization}.
Here are some examples. This form defines @code{foo} but does not
@ -580,7 +588,7 @@ entire computation of the value into the @code{defvar}, like this:
@noindent
This method has several benefits. First, if the user quits while
loading the file, the variable is either still uninitialized or
initialized properly, never in-between. If it is uninitialized,
initialized properly, never in-between. If it is still uninitialized,
reloading the file will initialize it properly. Second, reloading the
file once the variable is initialized will not alter it; that is
important if the user has run hooks to alter part of the contents (such
@ -620,11 +628,11 @@ each form, if you do want to reinitialize the variable.
@end example
@noindent
This code sets the variable, then alters it, but only if the variable
had been @code{ni}. If the user quits just after the @code{setq}, that
leaves the variable neither correctly initialized nor void nor
@code{nil}. Once that happens, reloading the file will not initialize
the variable; it will remain incomplete.
This code sets the variable, then alters it, but it does so in more than
one step. If the user quits just after the @code{setq}, that leaves the
variable neither correctly initialized nor void nor @code{nil}. Once
that happens, reloading the file will not initialize the variable; it
will remain incomplete.
@node Accessing Variables
@section Accessing Variable Values
@ -673,8 +681,8 @@ has no local bindings.
@end group
@end example
A @code{void-variable} error is signaled if @var{symbol} has neither a
local binding nor a global one.
A @code{void-variable} error is signaled if the current binding of
@var{symbol} is void.
@end defun
@node Setting Variables
@ -803,6 +811,7 @@ value of @var{symbol} had better be a list already before the call.
The argument @var{symbol} is not implicitly quoted; @code{add-to-list}
is an ordinary function, like @code{set} and unlike @code{setq}. Quote
the argument yourself if that is what you want.
@end defun
Here's a scenario showing how to use @code{add-to-list}:
@ -819,7 +828,6 @@ Here's a scenario showing how to use @code{add-to-list}:
foo ;; @r{@code{foo} was changed.}
@result{} (c a b)
@end example
@end defun
An equivalent expression for @code{(add-to-list '@var{var}
@var{value})} is this:
@ -979,10 +987,11 @@ closures.
works) may help you understand dynamic binding. This technique is
called @dfn{deep binding} and was used in early Lisp systems.
Suppose there is a stack of bindings: variable-value pairs. At entry
to a function or to a @code{let} form, we can push bindings onto the stack
for the arguments or local variables created there. We can pop those
bindings from the stack at exit from the binding construct.
Suppose there is a stack of bindings, which are variable-value pairs.
At entry to a function or to a @code{let} form, we can push bindings
onto the stack for the arguments or local variables created there. We
can pop those bindings from the stack at exit from the binding
construct.
We can find the value of a variable by searching the stack from top to
bottom for a binding for that variable; the value from that binding is
@ -1052,18 +1061,22 @@ use short names like @code{x}.
@cindex buffer-local variables
Global and local variable bindings are found in most programming
languages in one form or another. Emacs also supports another, unusual
kind of variable binding: @dfn{buffer-local} bindings, which apply only
to one buffer. Emacs Lisp is meant for programming editing commands,
and having different values for a variable in different buffers is an
important customization method. (A few variables have bindings that
are local to a given X terminal; see @ref{Multiple Displays}.)
languages in one form or another. Emacs also supports additional,
unusual kinds of variable binding: @dfn{buffer-local} bindings, which
apply only in one buffer, and frame-local bindings, which apply only in
one frame. Having different values for a variable in different buffers
and/or frames is an important customization method.
This section describes buffer-local bindings; for frame-local
bindings, see the following section, @ref{Frame-Local Variables}. (A few
variables have bindings that are local to a X terminal; see
@ref{Multiple Displays}.)
@menu
* Intro to Buffer-Local:: Introduction and concepts.
* Creating Buffer-Local:: Creating and destroying buffer-local bindings.
* Default Value:: The default value is seen in buffers
that don't have their own local values.
that don't have their own buffer-local values.
@end menu
@node Intro to Buffer-Local
@ -1082,22 +1095,25 @@ this is the global binding.
A variable can have buffer-local bindings in some buffers but not in
other buffers. The default binding is shared by all the buffers that
don't have their own bindings for the variable. If you set the variable
in a buffer that does not have a buffer-local binding for it, this sets
the default binding, so the new value is visible in all the buffers that
see the default binding.
don't have their own bindings for the variable. (This includes all
newly created buffers.) If you set the variable in a buffer that does
not have a buffer-local binding for it, this sets the default binding
(assuming there are no frame-local bindings to complicate the matter),
so the new value is visible in all the buffers that see the default
binding.
The most common use of buffer-local bindings is for major modes to change
variables that control the behavior of commands. For example, C mode and
Lisp mode both set the variable @code{paragraph-start} to specify that only
blank lines separate paragraphs. They do this by making the variable
buffer-local in the buffer that is being put into C mode or Lisp mode, and
then setting it to the new value for that mode.
then setting it to the new value for that mode. @xref{Major Modes}.
The usual way to make a buffer-local binding is with
@code{make-local-variable}, which is what major mode commands use. This
affects just the current buffer; all other buffers (including those yet to
be created) continue to share the default value.
@code{make-local-variable}, which is what major mode commands typically
use. This affects just the current buffer; all other buffers (including
those yet to be created) will continue to share the default value unless
they are explicitly given their own buffer-local bindings.
@cindex automatically buffer-local
A more powerful operation is to mark the variable as
@ -1107,11 +1123,11 @@ variable local in all buffers, even those yet to be created. More
precisely, the effect is that setting the variable automatically makes
the variable local to the current buffer if it is not already so. All
buffers start out by sharing the default value of the variable as usual,
but any @code{setq} creates a buffer-local binding for the current
but setting the variable creates a buffer-local binding for the current
buffer. The new value is stored in the buffer-local binding, leaving
the default binding untouched. The default value can no longer be
changed with @code{setq} in this buffer; you need to use
@code{setq-default} to do that.
the default binding untouched. This means that the default value cannot
be changed with @code{setq} in any buffer; the only way to change it is
with @code{setq-default}.
@strong{Warning:} When a variable has buffer-local values in one or
more buffers, you can get Emacs very confused by binding the variable
@ -1161,7 +1177,8 @@ But @code{save-excursion} as shown here avoids the problem:
buffer-local binding of buffer @samp{b}.
When a file specifies local variable values, these become buffer-local
values when you visit the file. @xref{Auto Major Mode}.
values when you visit the file. @xref{File Variables,,, emacs, The
GNU Emacs Manual}.
@node Creating Buffer-Local
@subsection Creating and Deleting Buffer-Local Bindings
@ -1209,9 +1226,10 @@ foo
@end example
Making a variable buffer-local within a @code{let}-binding for that
variable does not work. This is because @code{let} does not distinguish
between different kinds of bindings; it knows only which variable the
binding was made for.
variable does not work reliably, unless the buffer in which you do this
is not current either on entry to or exit from the @code{let}. This is
because @code{let} does not distinguish between different kinds of
bindings; it knows only which variable the binding was made for.
If the variable is terminal-local, this function signals an error. Such
variables cannot have buffer-local bindings as well. @xref{Multiple
@ -1226,16 +1244,24 @@ This function marks @var{variable} (a symbol) automatically
buffer-local, so that any subsequent attempt to set it will make it
local to the current buffer at the time.
A peculiar wrinkle of this feature is that binding the variable (with
@code{let} or other binding constructs) does not create a buffer-local
binding for it. Only setting the variable (with @code{set} or
@code{setq}) does so.
The value returned is @var{variable}.
@strong{Note:} It is a mistake to use @code{make-variable-buffer-local}
for user-option variables, simply because users @emph{might} want to
customize them differently in different buffers. Users can make any
variable local, when they wish to.
@strong{Warning:} Don't assume that you should use
@code{make-variable-buffer-local} for user-option variables, simply
because users @emph{might} want to customize them differently in
different buffers. Users can make any variable local, when they wish
to. It is better to leave the choice to them.
The main use of @code{make-variable-buffer-local} is when a variable is
used for internal purposes, and the Lisp program depends on having
separate values in separate buffers.
The time to use @code{make-variable-buffer-local} is when it is crucial
that no two buffers ever share the same binding. For example, when a
variable is used for internal purposes in a Lisp program which depends
on having separate values in separate buffers, then using
@code{make-variable-buffer-local} can be the best solution.
@end deffn
@defun local-variable-p variable &optional buffer
@ -1246,11 +1272,11 @@ This returns @code{t} if @var{variable} is buffer-local in buffer
@defun buffer-local-variables &optional buffer
This function returns a list describing the buffer-local variables in
buffer @var{buffer}. It returns an association list (@pxref{Association
Lists}) in which each association contains one buffer-local variable and
its value. When a buffer-local variable is void in @var{buffer}, then
it appears directly in the resulting list. If @var{buffer} is omitted,
the current buffer is used.
buffer @var{buffer}. (If @var{buffer} is omitted, the current buffer is
used.) It returns an association list (@pxref{Association Lists}) in
which each element contains one buffer-local variable and its value.
However, when a variable's buffer-local binding in @var{buffer} is void,
then the variable appears directly in the resulting list.
@example
@group
@ -1309,7 +1335,7 @@ value of @code{standard-syntax-table}, and the abbrev table to the value
of @code{fundamental-mode-abbrev-table}.
The very first thing this function does is run the normal hook
@code{change-major-mode-hook} (@pxref{Major Mode Conventions}).
@code{change-major-mode-hook} (see below).
Every major mode command begins by calling this function, which has the
effect of switching to Fundamental mode and erasing most of the effects
@ -1319,6 +1345,15 @@ variables that major modes set should not be marked permanent.
@code{kill-all-local-variables} returns @code{nil}.
@end defun
@defvar change-major-mode-hook
The function @code{kill-all-local-variables} runs this normal hook
before it does anything else. This gives major modes a way to arrange
for something special to be done if the user switches to a different
major mode. For best results, make this variable buffer-local, so that
it will disappear after doing its job and will not interfere with the
subsequent major mode. @xref{Hooks}.
@end defvar
@c Emacs 19 feature
@cindex permanent local variable
A buffer-local variable is @dfn{permanent} if the variable name (a
@ -1332,7 +1367,8 @@ came from or how to save it, rather than with how to edit the contents.
The global value of a variable with buffer-local bindings is also
called the @dfn{default} value, because it is the value that is in
effect except when specifically overridden.
effect whenever neither the current buffer nor the selected frame has
its own binding for the variable.
The functions @code{default-value} and @code{setq-default} access and
change a variable's default value regardless of whether the current
@ -1345,13 +1381,13 @@ this variable.
@c Emacs 19 feature
The special forms @code{defvar} and @code{defconst} also set the
default value (if they set the variable at all), rather than any
buffer-local value.
buffer-local or frame-local value.
@defun default-value symbol
This function returns @var{symbol}'s default value. This is the value
that is seen in buffers that do not have their own values for this
variable. If @var{symbol} is not buffer-local, this is equivalent to
@code{symbol-value} (@pxref{Accessing Variables}).
that is seen in buffers and frames that do not have their own values for
this variable. If @var{symbol} is not buffer-local, this is equivalent
to @code{symbol-value} (@pxref{Accessing Variables}).
@end defun
@c Emacs 19 feature
@ -1379,49 +1415,49 @@ current buffer sees.
@example
@group
;; @r{In buffer @samp{foo}:}
(make-local-variable 'local)
@result{} local
(make-local-variable 'buffer-local)
@result{} buffer-local
@end group
@group
(setq local 'value-in-foo)
(setq buffer-local 'value-in-foo)
@result{} value-in-foo
@end group
@group
(setq-default local 'new-default)
(setq-default buffer-local 'new-default)
@result{} new-default
@end group
@group
local
buffer-local
@result{} value-in-foo
@end group
@group
(default-value 'local)
(default-value 'buffer-local)
@result{} new-default
@end group
@group
;; @r{In (the new) buffer @samp{bar}:}
local
buffer-local
@result{} new-default
@end group
@group
(default-value 'local)
(default-value 'buffer-local)
@result{} new-default
@end group
@group
(setq local 'another-default)
(setq buffer-local 'another-default)
@result{} another-default
@end group
@group
(default-value 'local)
(default-value 'buffer-local)
@result{} another-default
@end group
@group
;; @r{Back in buffer @samp{foo}:}
local
buffer-local
@result{} value-in-foo
(default-value 'local)
(default-value 'buffer-local)
@result{} another-default
@end group
@end example
@ -1442,3 +1478,123 @@ an ordinary evaluated argument.
@end group
@end example
@end defun
@node Frame-Local Variables
@section Frame-Local Variables
Just as variables can have buffer-local bindings, they can also have
frame-local bindings. These bindings belong to one frame, and are in
effect when that frame is selected. Frame-local bindings are actually
frame parameters: you create a frame-local binding in a specific frame
by calling @code{modify-frame-parameters} and specifying the variable
name as the parameter name.
To enable frame-local bindings for a certain variable, call the function
@code{make-variable-frame-local}.
@defun make-variable-frame-local variable
Enable the use of frame-local bindings for @var{variable}. This does
not in itself create any frame-local bindings for the variable; however,
if some frame already has a value for @var{variable} as a frame
parameter, that value automatically becomes a frame-local binding.
If the variable is terminal-local, this function signals an error. Such
variables cannot have buffer-local bindings as well. @xref{Multiple
Displays}. A few variables that are implemented specially in Emacs
can be (and usually are) buffer-local, but can never be frame-local.
@end defun
Buffer-local bindings take precedence over frame-local bindings. Thus,
consider a variable @code{foo}: if the current buffer has a buffer-local
binding for @code{foo}, that binding is active; otherwise, if the
selected frame has a frame-local binding for @code{foo}, that binding is
active; otherwise, the default binding of @code{foo} is active.
Here is an example. First we prepare a few bindings for @code{foo}:
@example
(setq f1 (selected-frame))
(make-variable-frame-local 'foo)
;; @r{Make a buffer-local binding for @code{foo} in @samp{b1}.}
(set-buffer (get-buffer-create "b1"))
(make-local-variable 'foo)
(setq foo '(b 1))
;; @r{Make a frame-local binding for @code{foo} in a new frame.}
;; @r{Store that frame in @code{f2}.}
(setq f2 (make-frame))
(modify-frame-parameters f2 '((foo . (f 2))))
@end example
Now we examine @code{foo} in various contexts. Whenever the
buffer @samp{b1} is current, its buffer-local binding is in effect,
regardless of the selected frame:
@example
(select-frame f1)
(set-buffer (get-buffer-create "b1"))
foo
@result{} (b 1)
(select-frame f2)
(set-buffer (get-buffer-create "b1"))
foo
@result{} (b 1)
@end example
@noindent
Otherwise, the frame gets a chance to provide the binding; when frame
@code{f2} is selected, its frame-local binding is in effect:
@example
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
foo
@result{} (f 2)
@end example
@noindent
When neither the current buffer nor the selected frame provides
a binding, the default binding is used:
@example
(select-frame f1)
(set-buffer (get-buffer "*scratch*"))
foo
@result{} nil
@end example
@noindent
When the active binding of a variable is a frame-local binding, setting
the variable changes that binding. You can observe the result with
@code{frame-parameters}:
@example
(select-frame f2)
(set-buffer (get-buffer "*scratch*"))
(setq foo 'nobody)
(assq 'foo (frame-parameters f2))
@result{} (foo . nobody)
@end example
@node Future Local Variables
@section Possible Future Local Variables
We have considered the idea of bindings that are local to a category
of frames---for example, all color frames, or all frames with dark
backgrounds. We have not implemented them because it is not clear that
this feature is really useful. You can get more or less the same
results by adding a function to @code{after-make-frame-hook}, set up to
define a particular frame parameter according to the appropriate
conditions for each frame.
It would also be possible to implement window-local bindings. We
don't know of many situations where they would be useful, and it seems
that indirect buffers (@pxref{Indirect Buffers}) with buffer-local
bindings offer a way to handle these situations more robustly.
If sufficient application is found for either of these two kinds of
local bindings, we will provide it in a subsequent Emacs version.

117
lispref/windows.texi
View file

@ -246,7 +246,7 @@ Now, the screen looks like this:
@end smallexample
Normally, Emacs indicates the border between two side-by-side windows
with a scroll bar (@pxref{X Frame Parameters,Scroll Bars}) or @samp{|}
with a scroll bar (@pxref{Window Frame Parameters,Scroll Bars}) or @samp{|}
characters. The display table can specify alternative border
characters; see @ref{Display Tables}.
@end deffn
@ -328,8 +328,7 @@ of a window aside from restoring a saved window configuration
deletes any windows that aren't part of that configuration.
When you delete a window, the space it took up is given to one
adjacent sibling. (In Emacs version 18, the space was divided evenly
among all the siblings.)
adjacent sibling.
@c Emacs 19 feature
@defun window-live-p window
@ -341,14 +340,10 @@ using a deleted window as if it were live.
@end defun
@deffn Command delete-window &optional window
This function removes @var{window} from the display. If @var{window}
is omitted, then the selected window is deleted. An error is signaled
if there is only one window when @code{delete-window} is called.
This function returns @code{nil}.
When @code{delete-window} is called interactively, @var{window}
defaults to the selected window.
This function removes @var{window} from display, and returns @code{nil}.
If @var{window} is omitted, then the selected window is deleted. An
error is signaled if there is only one window when @code{delete-window}
is called.
@end deffn
@deffn Command delete-other-windows &optional window
@ -356,7 +351,7 @@ This function makes @var{window} the only window on its frame, by
deleting the other windows in that frame. If @var{window} is omitted or
@code{nil}, then the selected window is used by default.
The result is @code{nil}.
The return value is @code{nil}.
@end deffn
@deffn Command delete-windows-on buffer &optional frame
@ -426,7 +421,7 @@ or contents of windows; therefore, if the @var{forms} change them,
the change persists.
Each frame, at any time, has a window selected within the frame. This
macro only saves @emph{the} selected window; it does not save anything
macro saves only @emph{the} selected window; it does not save anything
about other frames. If the @var{forms} select some other frame and
alter the window selected within it, the change persists.
@end defmac
@ -565,8 +560,8 @@ include in the cycle, as in @code{next-window}.
@deffn Command other-window count
This function selects the @var{count}th following window in the cyclic
order. If count is negative, then it selects the @minus{}@var{count}th
preceding window. It returns @code{nil}.
order. If count is negative, then it moves back @minus{}@var{count}
windows in the cycle, rather than forward. It returns @code{nil}.
In an interactive call, @var{count} is the numeric prefix argument.
@end deffn
@ -695,7 +690,7 @@ low-level functions that give you more precise control.
Do not use the functions in this section in order to make a buffer
current so that a Lisp program can access or modify it; they are too
drastic for that purpose, since they change the display of buffers in
windows, which is gratuitous and will surprise the user. Instead, use
windows, which would be gratuitous and surprise the user. Instead, use
@code{set-buffer} (@pxref{Current Buffer}) and @code{save-excursion}
(@pxref{Excursions}), which designate buffers as current for programmed
access without affecting the display of buffers in windows.
@ -713,8 +708,9 @@ buffer by that name is created. The major mode for the new buffer is
set according to the variable @code{default-major-mode}. @xref{Auto
Major Mode}.
Normally the specified buffer is put at the front of the buffer list.
This affects the operation of @code{other-buffer}. However, if
Normally the specified buffer is put at the front of the buffer list
(both the selected frame's buffer list and the frame-independent buffer
list). This affects the operation of @code{other-buffer}. However, if
@var{norecord} is non-@code{nil}, this is not done. @xref{The Buffer
List}.
@ -792,7 +788,7 @@ This function returns @code{nil}.
@tindex buffer-display-count
@defvar buffer-display-count
This variable is always local in each buffer. When the buffer is
This variable is always buffer-local in each buffer. When the buffer is
created, @code{buffer-display-count} has value 0. Each time the buffer
is displayed in a window, that increments the value of
@code{buffer-display-count}.
@ -965,7 +961,8 @@ described above.
@c Emacs 19 feature
@cindex dedicated window
A window can be marked as ``dedicated'' to its buffer. Then
@code{display-buffer} does not try to use that window.
@code{display-buffer} will not try to use that window to display any
other buffer.
@defun window-dedicated-p window
This function returns @code{t} if @var{window} is marked as dedicated;
@ -1069,32 +1066,23 @@ For a realistic example of using @code{window-start}, see the
description of @code{count-lines} in @ref{Text Lines}.
@end defun
@defun window-end &optional window
@defun window-end &optional window update
This function returns the position of the end of the display in window
@var{window}. If @var{window} is @code{nil}, the selected window is
used.
Simply changing the buffer text or moving point does not update the
value that @code{window-end} returns. The value is updated only when
Emacs redisplays and redisplay actually finishes.
Emacs redisplays and redisplay completes without being preempted.
If the last redisplay of @var{window} was preempted, and did not finish,
Emacs does not know the position of the end of display in that window.
In that case, this function returns a value that is not correct. In a
future version, @code{window-end} will return @code{nil} in that case.
@ignore
in that case, this function returns @code{nil}. You can compute where
the end of the window @emph{would} have been, if redisplay had finished,
like this:
In that case, this function returns @code{nil}.
@example
(save-excursion
(goto-char (window-start window))
(vertical-motion (1- (window-height window))
window)
(point))
@end example
@end ignore
If you @var{update} is non-@code{nil}, @code{window-end} always returns
an up-to-date value for where the window ends. If the saved value is
valid, @code{window-end} returns that; otherwise it computes the correct
value by scanning the buffer text.
@end defun
@defun set-window-start window position &optional noforce
@ -1428,10 +1416,10 @@ characters that separates side-by-side windows.
The following three functions return size information about a window:
@defun window-height &optional window
This function returns the number of lines in @var{window}, including
its mode line. If @var{window} fills its entire frame, this is one less
than the value of @code{frame-height} on that frame (since the last line
is always reserved for the minibuffer).
This function returns the number of lines in @var{window}, including its
mode line. If @var{window} fills its entire frame, this is typically
one less than the value of @code{frame-height} on that frame (since the
last line is always reserved for the minibuffer).
If @var{window} is @code{nil}, the function uses the selected window.
@ -1654,16 +1642,9 @@ If you omit @var{frame}, the selected frame is used.
This function checks whether a particular frame position falls within
the window @var{window}.
@need 3000
The argument @var{coordinates} is a cons cell of this form:
@example
(@var{x} . @var{y})
@end example
@noindent
The coordinates @var{x} and @var{y} are measured in characters, and
count from the top left corner of the screen or frame.
The argument @var{coordinates} is a cons cell of the form @code{(@var{x}
. @var{y})}. The coordinates @var{x} and @var{y} are measured in
characters, and count from the top left corner of the screen or frame.
The value returned by @code{coordinates-in-window-p} is non-@code{nil}
if the coordinates are inside @var{window}. The value also indicates
@ -1713,7 +1694,9 @@ This function returns a new object representing the selected frame's
current window configuration, including the number of windows, their
sizes and current buffers, which window is the selected window, and for
each window the displayed buffer, the display-start position, and the
positions of point and the mark. An exception is made for point in the
positions of point and the mark. It also includes the values of
@code{window-min-height}, @code{window-min-width} and
@code{minibuffer-scroll-window}. An exception is made for point in the
current buffer, whose value is not saved.
@end defun
@ -1721,14 +1704,17 @@ current buffer, whose value is not saved.
This function restores the configuration of windows and buffers as
specified by @var{configuration}. The argument @var{configuration} must
be a value that was previously returned by
@code{current-window-configuration}. This function operates on the
frame for which @var{configuration} was made, whether that frame is
selected or not.
@code{current-window-configuration}. This configuration is restored in
the frame from which @var{configuration} was made, whether that frame is
selected or not. This always counts as a window size change and
triggers execution of the @code{window-size-change-functions}
(@pxref{Window Hooks}), because @code{set-window-configuration} doesn't
know how to tell whether the new configuration actually differs from the
old one.
This function always counts as a window size change and triggers
execution of the @code{window-size-change-functions}. (It doesn't know
how to tell whether the new configuration actually differs from the old
one.)
If the frame which @var{configuration} was saved from is dead, all this
function does is restore the three variables @code{window-min-height},
@code{window-min-width} and @code{minibuffer-scroll-window}.
Here is a way of using this function to get the same effect
as @code{save-window-excursion}:
@ -1784,6 +1770,17 @@ For example:
@defun window-configuration-p object
This function returns @code{t} if @var{object} is a window configuration.
@end defun
@defun compare-window-configurations config1 config2
This function compares two window configurations as regards the
structure of windows, but ignores the values of point and mark and the
saved scrolling positions---it can return @code{t} even if those
aspects differ.
The function @code{equal} can also compare two window configurations; it
regards configurations as unequal if they differ in any respect, even a
saved point or mark.
@end defun
Primitives to look inside of window configurations would make sense,
@ -1799,8 +1796,8 @@ There are three actions that can change this: scrolling the window,
switching buffers in the window, and changing the size of the window.
The first two actions run @code{window-scroll-functions}; the last runs
@code{window-size-change-functions}. The paradigmatic use of these
hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
Support Modes, emacs, The GNU Emacs Manual}.
hooks is in the implementation of Lazy Lock mode; see @ref{Support
Modes, Lazy Lock, Font Lock Support Modes, emacs, The GNU Emacs Manual}.
@defvar window-scroll-functions
This variable holds a list of functions that Emacs should call before