Commit 2468d0c0 authored by Dave Love's avatar Dave Love

Current version from /gd/gnu/elisp.

parent 602613fe
......@@ -2,7 +2,7 @@
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1999 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Antinews, Tips, System Interface, Top
@node Antinews, Tips, Calendar, Top
@appendix Emacs 20 Antinews
For those users who live backwards in time, here is information about
......
......@@ -18,6 +18,7 @@ are done, and the subroutines that allow Lisp programs to do them.
* Defining Commands:: Specifying how a function should read arguments.
* Interactive Call:: Calling a command, so that it will read arguments.
* Command Loop Info:: Variables set by the command loop for you to examine.
* Adjusting Point:: Adjustment of point after a command.
* Input Events:: What input looks like when you read it.
* Reading Input:: How to read input events from the keyboard or mouse.
* Special Events:: Events processed immediately and individually.
......@@ -726,9 +727,9 @@ if all those events were characters. @xref{Input Events}.
@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}).
Like @code{this-command-keys}, except that it always returns the events
in a vector, so you don't need to deal with the complexities of storing
input events in a string (@pxref{Strings of Events}).
@end defun
@tindex clear-this-command-keys
......@@ -779,6 +780,35 @@ frame, the value is the frame to which the event was redirected.
@xref{Input Focus}.
@end defvar
@node Adjusting Point
@section Adjusting Point After Commands
It is not easy to display a value of point in the middle of a sequence
of text that has the @code{display} or @code{composition} property. So
after a command finishes and returns to the command loop, if point is
within such a sequence, the command loop normally moves point to the
edge of the sequence.
A command can inhibit this feature by setting the variable
@code{disable-point-adjustment}:
@defvar disable-point-adjustment
@tindex disable-point-adjustment
If this variable is non-@code{nil} when a command returns to the command
loop, then the command loop does not check for text properties such as
@code{display} and @code{composition}, and does not move point out of
sequences that have these properties.
The command loop sets this variable to @code{nil} before each command,
so if a command sets it, the effect applies only to that command.
@end defvar
@defvar global-disable-point-adjustment
@tindex global-disable-point-adjustment
If you set this variable to a non-@code{nil} value, the feature of
moving point out of these sequences is completely turned off.
@end defvar
@node Input Events
@section Input Events
@cindex events
......@@ -1192,6 +1222,7 @@ motion (by reading motion events) until the button is released.
@cindex repeat events
@cindex double-click events
@cindex triple-click events
@cindex mouse events, repeated
If you press the same mouse button more than once in quick succession
without moving the mouse, Emacs generates special @dfn{repeat} mouse
......@@ -1529,6 +1560,8 @@ to an event type which specifies all of them. For example,
@node Accessing Events
@subsection Accessing Events
@cindex mouse events, accessing the data
@cindex accessing data of mouse events
This section describes convenient functions for accessing the data in
a mouse button or motion event.
......@@ -1557,6 +1590,7 @@ event, the value is actually the starting position, which is the only
position such events have.
@end defun
@cindex mouse position list, accessing
These five functions take a position list as described above, and
return various parts of it.
......@@ -1579,6 +1613,8 @@ a cons cell @code{(@var{col} . @var{row})}. These are computed from the
@var{x} and @var{y} values actually found in @var{position}.
@end defun
@cindex mouse event, timestamp
@cindex timestamp of a mouse event
@defun posn-timestamp position
Return the timestamp in @var{position}.
@end defun
......@@ -1614,6 +1650,8 @@ of a pair of x and y coordinates.
@node Strings of Events
@subsection Putting Keyboard Events in Strings
@cindex keyboard events in strings
@cindex strings with keyboard events
In most of the places where strings are used, we conceptualize the
string as containing text characters---the same kind of characters found
......@@ -1818,17 +1856,24 @@ button-down events entirely. It also reshuffles focus events and
miscellaneous window events so that they never appear in a key sequence
with any other events.
@cindex @code{header-line} prefix key
@cindex @code{mode-line} prefix key
@cindex @code{vertical-line} prefix key
@cindex @code{horizontal-scroll-bar} prefix key
@cindex @code{vertical-scroll-bar} prefix key
@cindex @code{menu-bar} prefix key
@cindex mouse events, in special parts of frame
When mouse events occur in special parts of a window, such as a mode
line or a scroll bar, the event type shows nothing special---it is the
same symbol that would normally represent that combination of mouse
button and modifier keys. The information about the window part is kept
elsewhere in the event---in the coordinates. But
@code{read-key-sequence} translates this information into imaginary
``prefix keys'', all of which are symbols: @code{mode-line},
@code{vertical-line}, @code{horizontal-scroll-bar} and
@code{vertical-scroll-bar}. You can define meanings for mouse clicks in
special window parts by defining key sequences using these imaginary
prefix keys.
``prefix keys'', all of which are symbols: @code{heder-line},
@code{horizontal-scroll-bar}, @code{menu-bar}, @code{mode-line},
@code{vertical-line}, and @code{vertical-scroll-bar}. You can define
meanings for mouse clicks in special window parts by defining key
sequences using these imaginary prefix keys.
For example, if you call @code{read-key-sequence} and then click the
mouse on the window's mode line, you get two events, like this:
......@@ -1856,6 +1901,8 @@ from the terminal---not counting those generated by keyboard macros.
@node Reading One Event
@subsection Reading One Event
@cindex reading a single event
@cindex event, reading only one
The lowest level functions for command input are those that read a
single event.
......@@ -1960,7 +2007,8 @@ buffer.
The input method function should return a list of events which should
be used as input. (If the list is @code{nil}, that means there is no
input, so @code{read-event} waits for another event.) These events are
processed before the events in @code{unread-command-events}. Events
processed before the events in @code{unread-command-events}
(@pxref{Event Input Misc}). Events
returned by the input method function are not passed to the input method
function again, even if they are printing characters with no modifier
bits.
......
......@@ -919,7 +919,7 @@ current buffer.
The arguments @var{front-advance} and @var{rear-advance} specify the
insertion type for the start of the overlay and for the end of the
overlay. @xref{Marker Insertion Types}.
overlay, respectively. @xref{Marker Insertion Types}.
@end defun
@defun overlay-start overlay
......@@ -938,19 +938,22 @@ This function returns the buffer that @var{overlay} belongs to.
@defun delete-overlay overlay
This function deletes @var{overlay}. The overlay continues to exist as
a Lisp object, but ceases to be attached to the buffer it belonged to,
and ceases to have any effect on display.
a Lisp object, and its property list is unchanged, but it ceases to be
attached to the buffer it belonged to, and ceases to have any effect on
display.
A deleted overlay is not permanently useless. You can give it
a position in a buffer again by calling @code{move-overlay}.
A deleted overlay is not permanently disconnected. You can give it a
position in a buffer again by calling @code{move-overlay}.
@end defun
@defun move-overlay overlay start end &optional buffer
This function moves @var{overlay} to @var{buffer}, and places its bounds
at @var{start} and @var{end}. Both arguments @var{start} and @var{end}
must specify buffer positions; they may be integers or markers. If
@var{buffer} is omitted, @var{overlay} stays in the same buffer;
if @var{overlay} was deleted, it goes into the current buffer.
must specify buffer positions; they may be integers or markers.
If @var{buffer} is omitted, @var{overlay} stays in the same buffer it
was already associated with; if @var{overlay} was deleted, it goes into
the current buffer.
The return value is @var{overlay}.
......@@ -960,11 +963,82 @@ update other vital data structures and can cause some overlays to be
``lost''.
@end defun
Here are some examples:
@example
;; @r{Create an overlay.}
(setq foo (make-overlay 1 10))
@result{} #<overlay from 1 to 10 in display.texi>
(overlay-start foo)
@result{} 1
(overlay-end foo)
@result{} 10
(overlay-buffer foo)
@result{} #<buffer display.texi>
;; @r{Give it a property we can check later.}
(overlay-put foo 'happy t)
@result{} t
;; @r{Verify the property is present.}
(overlay-get foo 'happy)
@result{} t
;; @r{Move the overlay.}
(move-overlay foo 5 20)
@result{} #<overlay from 5 to 20 in display.texi>
(overlay-start foo)
@result{} 5
(overlay-end foo)
@result{} 20
;; @r{Delete the overlay.}
(delete-overlay foo)
@result{} nil
;; @r{Verify it is deleted.}
foo
@result{} #<overlay in no buffer>
;; @r{A deleted overlay has no position.}
(overlay-start foo)
@result{} nil
(overlay-end foo)
@result{} nil
(overlay-buffer foo)
@result{} nil
;; @r{Undelete the overlay.}
(move-overlay foo 1 20)
@result{} #<overlay from 1 to 20 in display.texi>
;; @r{Verify the results.}
(overlay-start foo)
@result{} 1
(overlay-end foo)
@result{} 20
(overlay-buffer foo)
@result{} #<buffer display.texi>
;; @r{Moving and deleting the overlay don't change its properties.}
(overlay-get foo 'happy)
@result{} t
@end example
@node Finding Overlays
@subsection Searching for Overlays
@defun overlays-at pos
This function returns a list of all the overlays that contain position
@var{pos} in the current buffer. The list is in no particular order.
An overlay contains position @var{pos} if it begins at or before
@var{pos}, and ends after @var{pos}.
This function returns a list of all the overlays that cover the
character at position @var{pos} in the current buffer. The list is in
no particular order. An overlay contains position @var{pos} if it
begins at or before @var{pos}, and ends after @var{pos}.
To illustrate usage, here is a Lisp function that returns a list of the
overlays that specify property @var{prop} for the character at point:
@smallexample
(defun find-overlays-specifying (prop)
(let ((overlays (overlays-at (point)))
found)
(while overlays
(let ((overlay (cdr overlays)))
(if (overlay-get overlay prop)
(setq found (cons overlay found))))
(setq overlays (cdr overlays)))
found))
@end smallexample
@end defun
@defun overlays-in beg end
......@@ -973,7 +1047,7 @@ This function returns a list of the overlays that overlap the region
@var{beg} through @var{end}. ``Overlap'' means that at least one
character is contained within the overlay and also contained within the
specified region; however, empty overlays are included in the result if
they are located at @var{beg} or between @var{beg} and @var{end}.
they are located at @var{beg}, or strictly between @var{beg} and @var{end}.
@end defun
@defun next-overlay-change pos
......@@ -986,6 +1060,20 @@ This function returns the buffer position of the previous beginning or
end of an overlay, before @var{pos}.
@end defun
Here's an easy way to use @code{next-overlay-change} to search for the
next character which gets a non-@code{nil} @code{happy} property from
either its overlays or its text properties (@pxref{Property Search}):
@smallexample
(defun find-overlay-prop (prop)
(save-excursion
(while (and (not (eobp))
(not (get-char-property (point) 'happy)))
(goto-char (min (next-overlay-change (point))
(next-single-property-change (point) 'happy))))
(point)))
@end smallexample
@node Width
@section Width
......@@ -1782,7 +1870,6 @@ expression in the list. For example,
@noindent
allows the use of scalable fonts with registry @code{muleindian-2}.
@end example
@end defvar
@defun clear-face-cache &optional unload-p
@tindex clear-face-cache
......@@ -2809,6 +2896,13 @@ The value of this variable is the default value for @code{ctl-arrow} in
buffers that do not override it. @xref{Default Value}.
@end defvar
@defopt indicate-empty-lines
@tindex indicate-empty-lines
When this is non-@code{nil}, Emacs displays a special glyph in
each empty line at the end of the buffer, on terminals that
support it (window systems).
@end defopt
@defopt tab-width
The value of this variable is the spacing between tab stops used for
displaying tab characters in Emacs buffers. The value is in units of
......
......@@ -20,6 +20,12 @@ expand file name arguments by calling @code{expand-file-name}, so that
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
When file I/O functions signal Lisp errors, they usually use the
condition @code{file-error} (@pxref{Handling Errors}). The error
message is in most cases obtained from the operating system, according
to locale @code{system-message-locale}, and decoded using coding system
@code{locale-coding-system} (@pxref{Locales}).
@menu
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
......@@ -250,7 +256,7 @@ This function is used by @code{find-file-noselect}.
It uses @code{generate-new-buffer} (@pxref{Creating Buffers}).
@end defun
@defun after-find-file &optional error warn
@defun after-find-file &optional error warn noauto after-find-file-from-revert-buffer nomodes
This function sets the buffer major mode, and parses local variables
(@pxref{Auto Major Mode}). It is called by @code{find-file-noselect}
and by the default revert function (@pxref{Reverting}).
......@@ -266,6 +272,19 @@ call @code{after-find-file}.
If @var{warn} is non-@code{nil}, then this function issues a warning
if an auto-save file exists and is more recent than the visited file.
If @var{noauto} is non-@code{nil}, that says not to enable or disable
Auto-Save mode. The mode remains enabled if it was enabled before.
If @var{after-find-file-from-revert-buffer} is non-@code{nil}, that
means this call was from @code{revert-buffer}. This has no direct
effect, but some mode functions and hook functions check the value
of this variable.
If @var{nomodes} is non-@code{nil}, that means don't alter the buffer's
major mode, don't process local variables specifications in the file,
and don't run @code{find-file-hooks}. This feature is used by
@code{revert-buffer} in some cases.
The last thing @code{after-find-file} does is call all the functions
in the list @code{find-file-hooks}.
@end defun
......@@ -318,13 +337,16 @@ saving one of these is asked to specify a file name to use.) The
for this argument.
@end deffn
@deffn Command write-file filename
@deffn Command write-file filename &optional confirm
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} (@pxref{Buffer File Name}) and
@code{save-buffer}.
If @var{confirm} is non-@code{nil}, that means to ask for confirmation
before overwriting an existing file.
@end deffn
Saving a buffer runs several hooks. It also performs format
......@@ -512,7 +534,7 @@ An error is signaled if @var{filename} specifies a nonwritable file,
or a nonexistent file in a directory where files cannot be created.
@end deffn
@deffn Command write-region start end filename &optional append visit mustbenew
@deffn Command write-region start end filename &optional append visit lockname mustbenew
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.
......@@ -552,6 +574,10 @@ the buffer as visiting another file (@var{visit}). The argument
to implement @code{file-precious-flag}; don't use it yourself unless you
really know what you're doing.
The optional argument @var{lockname}, if non-@code{nil}, specifies the
file name to use for purposes of locking and unlocking, overriding
@var{filename} and @var{visit} for that purpose.
The function @code{write-region} converts the data which it writes to
the appropriate file formats specified by @code{buffer-file-format}.
@xref{Format Conversion}. It also calls the functions in the list
......@@ -692,10 +718,10 @@ or directories unless otherwise noted.
These functions test for permission to access a file in specific ways.
@defun file-exists-p filename
This function returns @code{t} if a file named @var{filename} appears
to exist. This does not mean you can necessarily read the file, only
that you can find out its attributes. (On Unix, this is true if the
file exists and you have execute permission on the containing
This function returns @code{t} if a file named @var{filename} appears to
exist. This does not mean you can necessarily read the file, only that
you can find out its attributes. (On Unix and GNU/Linux, this is true
if the file exists and you have execute permission on the containing
directories, regardless of the protection of the file itself.)
If the file does not exist, or if fascist access control policies
......@@ -726,10 +752,10 @@ and you can read it. It returns @code{nil} otherwise.
@c Emacs 19 feature
@defun file-executable-p filename
This function returns @code{t} if a file named @var{filename} exists and
you can execute it. It returns @code{nil} otherwise. On Unix, if the
file is a directory, execute permission means you can check the
existence and attributes of files inside the directory, and open those
files if their modes permit.
you can execute it. It returns @code{nil} otherwise. On Unix and
GNU/Linux, if the file is a directory, execute permission means you can
check the existence and attributes of files inside the directory, and
open those files if their modes permit.
@end defun
@defun file-writable-p filename
......@@ -906,19 +932,39 @@ other I/O device).
@c Emacs 19 features
The @dfn{truename} of a file is the name that you get by following
symbolic links until none remain, then simplifying away @samp{.}@: and
@samp{..}@: appearing as components. Strictly speaking, a file need not
have a unique truename; the number of distinct truenames a file has is
equal to the number of hard links to the file. However, truenames are
useful because they eliminate symbolic links as a cause of name
variation.
symbolic links at all levels until none remain, then simplifying away
@samp{.}@: and @samp{..}@: appearing as name components. This results
in a sort of canonical name for the file. A file does not always have a
unique truename; the number of distinct truenames a file has is equal to
the number of hard links to the file. However, truenames are useful
because they eliminate symbolic links as a cause of name variation.
@defun file-truename filename
The function @code{file-truename} returns the true name of the file
@var{filename}. This is the name that you get by following symbolic
links until none remain. The argument must be an absolute file name.
The function @code{file-truename} returns the truename of the file
@var{filename}. The argument must be an absolute file name.
@end defun
@defun file-chase-links filename
This function follows symbolic links, starting with @var{filename},
until it finds a file name which is not the name of a symbolic link.
Then it returns that file name.
@end defun
To illustrate the difference between @code{file-chase-links} and
@code{file-truename}, suppose that @file{/usr/foo} is a symbolic link to
the directory @file{/home/foo}, and @file{/home/foo/hello} is an
ordinary file (or at least, not a symbolic link) or nonexistent. Then
we would have:
@example
(file-chase-links "/usr/foo/hello")
;; @r{This does not follow the links in the parent directories.}
@result{} "/usr/foo/hello"
(file-truename "/usr/foo/hello")
;; @r{Assuming that @file{/home} is not a symbolic link.}
@result{} "/home/foo/hello"
@end example
@xref{Buffer File Name}, for related information.
@node File Attributes
......@@ -1242,9 +1288,9 @@ This command deletes the file @var{filename}, like the shell command
@samp{rm @var{filename}}. If the file has multiple names, it continues
to exist under the other names.
A suitable kind of @code{file-error} error is signaled if the file
does not exist, or is not deletable. (On Unix, a file is deletable if
its directory is writable.)
A suitable kind of @code{file-error} error is signaled if the file does
not exist, or is not deletable. (On Unix and GNU/Linux, a file is
deletable if its directory is writable.)
See also @code{delete-directory} in @ref{Create/Delete Dirs}.
@end deffn
......@@ -1278,8 +1324,8 @@ be an integer). Only the low 12 bits of @var{mode} are used.
@defun set-default-file-modes mode
This function sets the default file protection for new files created by
Emacs and its subprocesses. Every file created with Emacs initially has
this protection. On Unix, the default protection is the bitwise
complement of the ``umask'' value.
this protection. On Unix and GNU/Linux, the default protection is the
bitwise complement of the ``umask'' value.
The argument @var{mode} must be an integer. On most systems, only the
low 9 bits of @var{mode} are meaningful.
......@@ -1406,9 +1452,13 @@ This function returns the nondirectory part of @var{filename}.
@end example
@end defun
@defun file-name-sans-versions filename
@defun file-name-sans-versions filename &optional keep-backup-version
This function returns @var{filename} with any file version numbers,
backup version numbers, or trailing tildes deleted.
backup version numbers, or trailing tildes discarded.
If @var{keep-backup-version} is non-@code{nil}, then true file version
numbers understood as such by the file system are discarded from the
return value, but backup version numbers are kept.
@example
@group
......@@ -1545,12 +1595,12 @@ directory.
root directory. A file name can specify all the directory names
starting from the root of the tree; then it is called an @dfn{absolute}
file name. Or it can specify the position of the file in the tree
relative to a default directory; then it is called a @dfn{relative}
file name. On Unix, an absolute file name starts with a slash or a
tilde (@samp{~}), and a relative one does not. On MS-DOS and
relative to a default directory; then it is called a @dfn{relative} file
name. On Unix and GNU/Linux, an absolute file name starts with a slash
or a tilde (@samp{~}), and a relative one does not. On MS-DOS and
MS-Windows, an absolute file name starts with a slash or a backslash, or
with a drive specification @samp{@var{x}:/}, where @var{x} is the
@dfn{drive letter}. The rules on VMS are complicated.
@dfn{drive letter}. The rules on VMS are complicated.
@defun file-name-absolute-p filename
This function returns @code{t} if file @var{filename} is an absolute
......@@ -1625,10 +1675,11 @@ variables; only @code{substitute-in-file-name} does that.
@end defun
@c Emacs 19 feature
@defun file-relative-name filename directory
@defun file-relative-name filename &optional directory
This function does the inverse of expansion---it tries to return a
relative name that is equivalent to @var{filename} when interpreted
relative to @var{directory}.
relative to @var{directory}. If @var{directory} is omitted or
@code{nil}, it defaults to the current buffer's default directory.
On some operating systems, an absolute file name begins with a device
name. On such systems, @var{filename} has no relative equivalent based
......@@ -2053,8 +2104,10 @@ files that are directories. For example, you cannot delete a directory
with @code{delete-file}. These special functions exist to create and
delete directories.
@defun make-directory dirname
@defun make-directory dirname &optional parents
This function creates a directory named @var{dirname}.
If @var{parents} is non-@code{nil}, that means to create
the parent directories first, if they don't already exist.
@end defun
@defun delete-directory dirname
......
......@@ -18,9 +18,9 @@
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center GNU Emacs Version 19.29
@center for Unix Users
@center Edition 2.3, June 1994
@center Edition 2.4, June 1995
@sp 2
@center @titlefont{Volume 1}
@sp 2
......@@ -39,9 +39,9 @@
@sp 1
@center @titlefont{Manual}
@sp 2
@center GNU Emacs Version 19
@center GNU Emacs Version 19.29
@center for Unix Users
@center Edition 2.3, June 1994
@center Edition 2.4, June 1995
@sp 2
@center @titlefont{Volume 2}
@sp 2
......
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1999 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/locals
@node Standard Buffer-Local Variables, Standard Keymaps, Standard Errors, Top
......@@ -148,7 +148,7 @@ use, but we don't try to list them all here.
@xref{Standard Regexps}.
@item point-before-scroll
Used for communication between mouse commands and scroll-bar commands..
Used for communication between mouse commands and scroll-bar commands.
@item require-final-newline
@xref{Insertion}.
......@@ -177,4 +177,3 @@ Used for communication between mouse commands and scroll-bar commands..
@item vc-mode
@xref{Mode Line Variables}.
@end table
......@@ -45,15 +45,14 @@ nothing but a minibuffer window; see @ref{Minibuffers and Frames}.)
The text in the minibuffer always starts with the @dfn{prompt string},
the text that was specified by the program that is using the minibuffer
to tell the user what sort of input to type. This text is marked
read-only so you won't accidentally delete or change it. In other
respects, it is an ordinary part of the buffer contents, but certain
functions such as @code{erase-buffer}, @code{buffer-string},
@code{beginning-of-line}, @code{forward-word}, @code{forward-sentence},
and @code{forward-paragraph}, treat it a little bit specially. (In
older Emacs versions, the prompt was displayed using a special mechanism
and was not part of the buffer contents.)