Commit b6954afd authored by Richard M. Stallman's avatar Richard M. Stallman
Browse files

*** empty log message ***

parent b92b7c8d
......@@ -29,6 +29,7 @@ not be displayed in any windows.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
* Buffer Gap:: The gap in the buffer.
@end menu
@node Buffer Basics
......@@ -980,3 +981,26 @@ is not indirect, the value is @code{nil}. Otherwise, the value is
another buffer, which is never an indirect buffer.
@end defun
@node Buffer Gap
@section The Buffer Gap
Emacs buffers are implemented using an invisible @dfn{gap} to make
insertion and deletion faster. Insertion works by filling in part of
the gap, and deletion adds to the gap. Of course, this means that the
gap must first be moved to the locus of the insertion or deletion.
Emacs moves the gap only when you try to insert or delete. This is why
your first editing command in one part of a large buffer, after
previously editing in another far-away part, sometimes involves a
noticeable delay.
This mechanism works invisibly, and Lisp code should never be affected
by the gap's current location, but these functions are available for
getting information about the gap status.
@defun gap-position
This function returns the current gap position in the current buffer.
@end defun
@defun gap-size
This function returns the current gap size of the current buffer.
@end defun
......@@ -727,6 +727,14 @@ 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
@tindex clear-this-command-keys
@defun clear-this-command-keys
This function empties out the table of events for
@code{this-command-keys} to return. This is useful after reading a
password, to prevent the password from echoing inadvertently as part of
the next command in certain cases.
@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.
......@@ -1737,6 +1745,7 @@ can use for translating or modifying input events while reading them.
@menu
* Key Sequence Input:: How to read one key sequence.
* Reading One Event:: How to read just one event.
* Invoking the Input Method:: How reading an event uses the input method.
* Quoted Character Input:: Asking the user to specify a character.
* Event Input Misc:: How to reread or throw away input events.
@end menu
......@@ -1846,21 +1855,22 @@ from the terminal---not counting those generated by keyboard macros.
The lowest level functions for command input are those that read a
single event.
@defun read-event &optional prompt suppress-input-method
@defun read-event &optional prompt inherit-input-method
This function reads and returns the next event of command input, waiting
if necessary until an event is available. Events can come directly from
the user or from a keyboard macro.
If @var{prompt} is non-@code{nil}, it should be a string to display in
the echo area as a prompt. Otherwise, @code{read-event} does not
display any message to indicate it is waiting for input; instead, it
prompts by echoing: it displays descriptions of the events that led to
or were read by the current command. @xref{The Echo Area}.
If the optional argument @var{prompt} is non-@code{nil}, it should be a
string to display in the echo area as a prompt. Otherwise,
@code{read-event} does not display any message to indicate it is waiting
for input; instead, it prompts by echoing: it displays descriptions of
the events that led to or were read by the current command. @xref{The
Echo Area}.
If @var{suppress-input-method} is non-@code{nil}, then the current input
method is disabled for reading this event. If you want to read an event
without input-method processing, always do it this way; don't try binding
@code{input-method-function} (see below).
If @var{inherit-input-method} is non-@code{nil}, then the current input
method (if any) is employed to make it possible to enter a
non-@sc{ASCII} character. Otherwise, input method handling is disabled
for reading this event.
If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
moves the cursor temporarily to the echo area, to the end of any message
......@@ -1883,9 +1893,11 @@ right-arrow function key:
@end example
@end defun
@defun read-char
This function reads and returns a character of command input. It
discards any events that are not characters, until it gets a character.
@defun read-char &optional prompt inherit-input-method
This function reads and returns a character of command input. If the
user generates an event which is not a character (i.e. a mouse click or
function key event), @code{read-char} signals an error. The arguments
work as in @code{read-event}.
In the first example, the user types the character @kbd{1} (@sc{ASCII}
code 49). The second example shows a keyboard macro definition that
......@@ -1913,11 +1925,21 @@ the echo area.
@end example
@end defun
@code{read-event} also invokes the current input method, if any. If
the value of @code{input-method-function} is non-@code{nil}, it should
be a function; when @code{read-event} reads a printing character
(including @key{SPC}) with no modifier bits, it calls that function,
passing the event as an argument.
@defun read-char-exclusive &optional prompt inherit-input-method
This function reads and returns a character of command input. If the
user generates an event which is not a character,
@code{read-char-exclusive} ignores it and reads another event, until it
gets a character. The arguments work as in @code{read-event}.
@end defun
@node Invoking the Input Method
@subsection Invoking the Input Method
The event-reading functions invoke the current input method, if any
(@pxref{Input Methods}). If the value of @code{input-method-function}
is non-@code{nil}, it should be a function; when @code{read-event} reads
a printing character (including @key{SPC}) with no modifier bits, it
calls that function, passing the character as an argument.
@defvar input-method-function
If this is non-@code{nil}, its value specifies the current input method
......@@ -1943,13 +1965,12 @@ bits.
@code{nil} first, to prevent recursion.
The input method function is not called when reading the second and
subsequent event of a key sequence. Thus, these characters are not
subject to input method processing. It is usually a good idea for the
input method processing to test the values of
@code{overriding-local-map} and @code{overriding-terminal-local-map}; if
either of these variables is non-@code{nil}, the input method should put
its argument into a list and return that list with no further
processing.
subsequent events of a key sequence. Thus, these characters are not
subject to input method processing. The input method function should
test the values of @code{overriding-local-map} and
@code{overriding-terminal-local-map}; if either of these variables is
non-@code{nil}, the input method should put its argument into a list and
return that list with no further processing.
@node Quoted Character Input
@subsection Quoted Character Input
......
......@@ -183,12 +183,12 @@ values are legitimate, and how to display the value.
@item :options @var{list}
Specify @var{list} as the list of reasonable values for use in this
option.
option. The user is not restricted to using only these values, 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.
This is meaningful only for certain types, currently including
@code{hook}, @code{plist} and @code{alist}. See the definition of the
individual types for a description of how to use @code{:options}.
@item :version @var{version}
This option specifies that the variable was first introduced, or its
......@@ -267,17 +267,25 @@ Keywords}. Here is an example, from the library @file{paren.el}:
:require 'paren)
@end example
@ignore
Use @code{custom-add-option} to specify that a specific function is
useful as an member of a hook.
If a customization item has a type such as @code{hook} or @code{alist},
which supports @code{:options}, you can add additional options to the
item, outside the @code{defcustom} declaration, by calling
@code{custom-add-option}. For example, if you define a function
@code{my-lisp-mode-initialization} intended to be called from
@code{emacs-lisp-mode-hook}, you might want to add that to the list of
options for @code{emacs-lisp-mode-hook}, but not by editing its
definition. You can do it thus:
@example
(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
@end example
@defun custom-add-option symbol option
To the variable @var{symbol} add @var{option}.
To the customization @var{symbol}, add @var{option}.
If @var{symbol} is a hook variable, @var{option} should be a hook
member. For other types variables, the effect is undefined."
The precise effect of adding @var{option} depends on the customization
type of @var{symbol}.
@end defun
@end ignore
Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the default value,
......@@ -376,6 +384,125 @@ You can use the @code{:options} keyword in a hook variable's
@code{defcustom} to specify a list of functions recommended for use in
the hook; see @ref{Variable Definitions}.
@item alist
The value must be a list of cons-cells, the car of each cell
representing a key, and the cdr of the same cell representing and
associated value. The use can add and a delete key/value pairs, and
edit both the key and the value of each pair.
You can specify the key and value types like this:
@example
(alist :key-type @var{key-type}
:value-type @var{value-type})
@end example
@noindent
where @var{key-type} and @var{value-type} are customization type
specifications. The default key type is @code{sexp}, and the default
value type is @code{sexp}.
The user can add any key matching the specified key type, but you can
give some keys a preferential treatment by specifying them with the
@code{:options} (see @ref{Variable Definitions}). The specified keys
will always be shown in the customize buffer (together with a suitable
value), with a checkbox to include or exclude or disable the key/value
pair from the alist. The user will not be able to edit the keys
specified by the @code{:options} keyword argument.
The argument to the @code{:options} keywords should be a list of option
specifications. Ordinarily, the options are simply atoms, which are the
specified keys. For example:
@example
:options '("foo" "bar" "baz")
@end example
@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
@code{"bar"} and @code{"baz"}, which will always be shown first.
You may want to restrict the value type for specific keys, for example,
the value associated with the @code{"bar"} key can only be an integer.
You can specify this by using a list instead of an atom in the option
specification. The first element will specify the key, like before,
while the second element will specify the value type.
@example
:options '("foo" ("bar" integer) "baz")
@end example
Finally, you may want to change how the key is presented. By default,
the key is simply shown as a @code{const}, since the user cannot change
the special keys specified with the @code{:options} keyword. However,
you may want to use a more specialized type for presenting the key, like
@code{function-item} if you know it is a symbol with a function binding.
This is done by using a customization type specification instead of a
symbol for the key.
@example
:options '("foo" ((function-item some-function) integer) "baz")
@end example
Many alist uses lists with two elements, instead of cons cells. For
example,
@example
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
@end example
@noindent
instead of
@example
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
@end example
Because of the way lists are implemented on top of cons cells, you can
treat @code{list-alist} in the example above as a cons cell alist, where
the value type is a list with a single element containing the real
value.
@example
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
@end example
The @code{group} widget is used here instead of @code{list} only because
the formatting is better suited for the purpose.
Similarily, you can have alists with more values associated with each
key, using variations of this trick:
@example
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
"Alist of people, each element has the form (NAME AGE MALE)."
:type '(alist :value-type (group age boolean)))
(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
"Alist where the KEY is a person, and the VALUE is a list of pets."
:type '(alist :value-type (repeat string)))
@end example
@item plist
The @code{plist} custom type is similar to the @code{alist} (see above),
except that the information is stored as a property list, i.e. a list of
this form:
@example
(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
@end example
The default @code{:key-type} for @code{plist} is @code{symbol},
rather than @code{sexp}.
@item symbol
The value must be a symbol. It appears in the customization buffer as
the name of the symbol.
......
......@@ -179,6 +179,14 @@ Minibuffer depth is 0.
@end example
@end defun
@tindex with-temp-message
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}. It displays @var{message}, executes
@var{body}, then returns the value of the last body form while restoring
the previous echo area contents.
@end defmac
@defun message-or-box string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
......@@ -520,9 +528,16 @@ 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
output they print into the buffer named @var{buffer-name}. The buffer
is then shown in some window for viewing, displayed but not selected.
This function executes @var{forms} while arranging to insert any output
they print into the buffer named @var{buffer-name}, which is first
created if necessary, and put into Help mode. Finally, the buffer is
displayed in some window, but not selected.
If the @var{forms} do not change the major mode in the output buffer, so
that it is still Help mode at the end of their execution, then
@code{with-output-to-temp-buffer} makes this buffer read-only at the
end, and also scans it for function and variable names to make them into
clickable cross-references.
The string @var{buffer-name} specifies the temporary buffer, which
need not already exist. The argument must be a string, not a buffer.
......@@ -536,6 +551,9 @@ that buffer (but screen display and messages in the echo area, although
they are ``output'' in the general sense of the word, are not affected).
@xref{Output Functions}.
Several hooks are available for customizing the behavior
of this construct; they are listed below.
The value of the last form in @var{forms} is returned.
@example
......@@ -568,14 +586,25 @@ function gets one argument, which is the buffer it should display.
It is a good idea for this function to run @code{temp-buffer-show-hook}
just as @code{with-output-to-temp-buffer} normally would, inside of
@code{save-window-excursion} and with the chosen window and buffer
@code{save-selected-window} and with the chosen window and buffer
selected.
@end defvar
@defvar temp-buffer-setup-hook
@tindex temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
evaluating @var{body}. When the hook runs, the help buffer is current.
This hook is normally set up with a function to put the buffer in Help
mode.
@end defvar
@defvar temp-buffer-show-hook
This normal hook is run by @code{with-output-to-temp-buffer} after
displaying the help buffer. When the hook runs, the help buffer is
current, and the window it was displayed in is selected.
current, and the window it was displayed in is selected. This hook is
normally set up with a function to make the buffer read only, and find
function names and variable names in it, provided the major mode is
still Help mode.
@end defvar
@defun momentary-string-display string position &optional char message
......@@ -1443,6 +1472,11 @@ 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 special behavior.
These display rules apply to carriage return (character code 13), when
it appears in the buffer. But that character may not appear in the
buffer where you expect it, if it was eliminated as part of end-of-line
conversion (@xref{Coding System Basics}).
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
they also affect the indentation functions. These variables also affect
......
......@@ -12,8 +12,8 @@
@smallbook
@ifinfo
This version is the edition 2.5 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 20.3
This Info file contains edition 2.5.1 of the GNU Emacs Lisp
Reference Manual, corresponding to Emacs version 20.4.
@c Please REMEMBER to update edition number in *four* places in this file
@c and also in *one* place in intro.texi
......@@ -21,7 +21,8 @@ Published by the Free Software Foundation
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc.
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
......@@ -71,21 +72,22 @@ instead of in the original English.
@titlepage
@title GNU Emacs Lisp Reference Manual
@subtitle For Emacs Version 20.3
@subtitle For Emacs Version 20.4
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
@subtitle Revision 2.5, May 1998
@subtitle Revision 2.5.1, January 1999
@author by Bil Lewis, Dan LaLiberte, Richard Stallman
@author and the GNU Manual Group
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc.
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
Free Software Foundation, Inc.
@sp 2
Edition 2.5 @*
Revised for Emacs Version 20.3,@*
May 1998.@*
Edition 2.5.1 @*
Revised for Emacs Version 20.4,@*
January 1999.@*
@sp 2
ISBN 1-882114-72-8
......@@ -118,8 +120,8 @@ Cover art by Etienne Suvasa.
@node Top, Copying, (dir), (dir)
@ifinfo
This Info file contains edition 2.5 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 20.3.
This Info file contains edition 2.5.1 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 20.4.
@end ifinfo
@menu
......
......@@ -83,7 +83,7 @@ not alter it, the fastest way is to use @code{insert-file-contents} in a
temporary buffer. Visiting the file is not necessary and takes longer.
@xref{Reading from Files}.
@deffn Command find-file filename
@deffn Command find-file filename &optional wildcards
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a
new buffer and reading the file into it. It also returns that buffer.
......@@ -98,17 +98,25 @@ like this:
@noindent
(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file} expands wildcard characters in
@var{filename} and visits all the matching files.
When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn
@defun find-file-noselect filename &optional nowarn rawfile
@defun find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions. It finds
or creates a buffer visiting the file @var{filename}, and returns it.
It uses an existing buffer if there is one, and otherwise creates a new
buffer and reads the file into it. You may make the buffer current or
display it in a window if you wish, but this function does not do so.
If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file-noselect} expands wildcard
characters in @var{filename} and visits all the matching files.
When @code{find-file-noselect} uses an existing buffer, it first
verifies that the file has not changed since it was last visited or
saved in that buffer. If the file has changed, then this function asks
......@@ -146,7 +154,7 @@ visiting the file @var{filename}.
@end example
@end defun
@deffn Command find-file-other-window filename
@deffn Command find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, but
does so in a window other than the selected window. It may use another
existing window or split a window; see @ref{Displaying Buffers}.
......@@ -155,7 +163,7 @@ When this command is called interactively, it prompts for
@var{filename}.
@end deffn
@deffn Command find-file-read-only filename
@deffn Command find-file-read-only filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, like
@code{find-file}, but it marks the buffer as read-only. @xref{Read Only
Buffers}, for related functions and variables.
......@@ -175,6 +183,14 @@ When @code{view-file} is called interactively, it prompts for
@var{filename}.
@end deffn
@tindex find-file-wildcards
@defvar find-file-wildcards
If this variable is non-@code{nil}, then the various @code{find-file}
commands check for wildcard characters and visit all the files that
match them. If this is @code{nil}, then wildcard characters are
not treated specially.
@end defvar
@defvar find-file-hooks
The value of this variable is a list of functions to be called after a
file is visited. The file's local-variables specification (if any) will
......@@ -560,13 +576,16 @@ interfere with each other. Emacs tries to prevent this situation from
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.
The file lock is really a file, a symbolic link with a special name,
stored in the same directory as the file you are editing.
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}.
When you access files using NFS, there may be a small probability that
you and another user will both lock the same file ``simultaneously''.
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will 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
......@@ -583,7 +602,7 @@ some other job.
@end defun
@defun lock-buffer &optional filename
This function locks the file @var{filename}, if the current buffer is
This function locks the file @var{filename}, if the current buffer is
modified. The argument @var{filename} defaults to the current buffer's
visited file. Nothing is done if the current buffer is not visiting a
file, or is not modified.
......@@ -861,7 +880,7 @@ existing directory, @code{nil} otherwise.
@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
a regular file (not a directory, symbolic link, named pipe, terminal, or
a regular file (not a directory, named pipe, terminal, or
other I/O device).
@end defun
......@@ -997,7 +1016,8 @@ The time of last modification as a list of two integers (as above).
The time of last status change as a list of two integers (as above).
@item
The size of the file in bytes.
The size of the file in bytes. If the size is too large to fit in a
Lisp integer, this is a floating point number.
@item
The file's modes, as a string of ten letters or dashes,
......@@ -1902,6 +1922,20 @@ This function returns a list of all versions of the file named
@var{file} in directory @var{dirname}.
@end defun
@tindex file-expand-wildcards
@defun file-expand-wildcards pattern &optional full
This function expands the wildcard pattern @var{pattern}, returning
alist of file names that match it.
If @var{pattern} is written as an absolute relative file name,
the values are absolute also.
If @var{pattern} is written as a relative file name, it is interpreted
relative to the current default directory. The file names returned are
normally also relative to the current default directory. However, if
@var{full} is non-@code{nil}, they are absolute.
@end defun
@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to
......
......@@ -364,7 +364,11 @@ 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 window-system window used by the frame.
The number of the window-system window used by the frame
to contain the actual Emacs windows.
@item outer-window-id
The number of the outermost window-system window used for the whole frame.
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means
......
......@@ -461,18 +461,20 @@ active keymap.
@end group
@end example
@defun define-prefix-command symbol
@defun define-prefix-command symbol &optional mapvar prompt
@cindex prefix command
This function prepares @var{symbol} for use as a prefix key's binding:
it creates a full keymap and stores it as @var{symbol}'s function
definition. Subsequently binding a key sequence to @var{symbol} will
make that key sequence into a prefix key.
make that key sequence into a prefix key. The return value is @code{symbol}.