mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-28 07:45:00 +00:00
Code Issues Releases Activity

*** empty log message ***

Browse Source
This commit is contained in:
Richard M. Stallman 1994-05-28 15:27:52 +00:00
parent ec221d13b7
commit b22f3a199c
9 changed files with 318 additions and 204 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

274
lispref/commands.texi
View File

@ -71,6 +71,7 @@ character causes @dfn{quitting} (@pxref{Quitting}).
The editor command loop runs this normal hook before each command. At
that time, @code{this-command} contains the command that is about to
run, and @code{last-command} describes the previous command.
@xref{Hooks}.
@end defvar
@defvar post-command-hook
@ -78,9 +79,44 @@ The editor command loop runs this normal hook after each command
(including commands terminated prematurely by quitting or by errors),
and also when the command loop is first entered. At that time,
@code{this-command} describes the command that just ran, and
@code{last-command} describes the command before that.
@code{last-command} describes the command before that. @xref{Hooks}.
@end defvar
An erroneous function in the @code{pre-command-hook} list could easily
make Emacs go into an infinite loop of errors. To protect you from this
sort of painful problem, Emacs sets the hook variable to @code{nil}
temporarily while running the functions in the hook. Thus, if a hook
function gets an error, the hook variable is left as @code{nil}. Emacs
does the same thing for @code{post-command-hook}.
Quitting is suppressed while running @code{pre-command-hook} and
@code{post-command-hook}; this is because otherwise a quit, happening by
chance within one of these hooks, would turn off the hook.
One inconvenient result of these protective features is that you
cannot have a function in @code{post-command-hook} or
@code{pre-command-hook} which changes the value of that variable. But
that's not a real limitation. If you want hook functions to change the
hook, simply add one fixed function to the hook, and code that function
to look in another hook variable for other functions to call. Here is
an example:
@example
;; @r{Set up the mechanism.}
(defvar current-post-command-function nil)
(defun run-current-post-command-function ()
(if current-post-command-function
(funcall current-post-command-function)))
(add-hooks 'post-command-hook
'run-current-post-command-function)
;; @r{Here's a hook function which replaces itself}
;; @r{with a different hook function to run next time.}
(defun first-post-command-function ()
(setq current-post-command-function
'second-post-command-function))
@end example
@node Defining Commands
@section Defining Commands
@cindex defining commands
@ -89,7 +125,7 @@ and also when the command loop is first entered. At that time,
@cindex interactive function
A Lisp function becomes a command when its body contains, at top
level, a form which calls the special form @code{interactive}. This
level, a form that calls the special form @code{interactive}. This
form does nothing when actually executed, but its presence serves as a
flag to indicate that interactive calling is permitted. Its argument
controls the reading of arguments for an interactive call.
@ -165,9 +201,10 @@ You can specify any number of arguments in this way.
@c Emacs 19 feature
The prompt string can use @samp{%} to include previous argument values
in the prompt. This is done using @code{format} (@pxref{Formatting
Strings}). For example, here is how you could read the name of an
existing buffer followed by a new name to give to that buffer:
(starting with the first argument) in the prompt. This is done using
@code{format} (@pxref{Formatting Strings}). For example, here is how
you could read the name of an existing buffer followed by a new name to
give to that buffer:
@smallexample
@group
@ -251,7 +288,7 @@ Select the window mentioned in the first mouse event in the key
sequence that invoked this command. Special.
@item a
A function name (i.e., a symbol which is @code{fboundp}). Existing,
A function name (i.e., a symbol satisfying @code{fboundp}). Existing,
Completion, Prompt.
@item b
@ -262,7 +299,7 @@ Prompt.
@item B
A buffer name. The buffer need not exist. By default, uses the name of
a recently used buffer other than the current buffer. Completion,
Prompt.
Default, Prompt.
@item c
A character. The cursor does not move into the echo area. Prompt.
@ -282,13 +319,13 @@ Existing, Completion, Default, Prompt.
@item e
The first or next mouse event in the key sequence that invoked the command.
More precisely, @samp{e} gets events which are lists, so you can look at
More precisely, @samp{e} gets events that are lists, so you can look at
the data in the lists. @xref{Input Events}. No I/O.
You can use @samp{e} more than once in a single command's interactive
specification. If the key sequence which invoked the command has
specification. If the key sequence that invoked the command has
@var{n} events that are lists, the @var{n}th @samp{e} provides the
@var{n}th such event. Events which are not lists, such as function keys
@var{n}th such event. Events that are not lists, such as function keys
and @sc{ASCII} characters, do not count where @samp{e} is concerned.
@item f
@ -320,16 +357,17 @@ Prompt.
@item N
@cindex raw prefix argument usage
The raw prefix argument. If the prefix argument is @code{nil}, then
read a number as with @kbd{n}. Requires a number. Prompt.
read a number as with @kbd{n}. Requires a number. @xref{Prefix Command
Arguments}. Prompt.
@item p
@cindex numeric prefix argument usage
The numeric prefix argument. (Note that this @samp{p} is lower case.)
No I/O.@refill
No I/O.
@item P
The raw prefix argument. (Note that this @samp{P} is upper case.)
@xref{Prefix Command Arguments}. No I/O.@refill
The raw prefix argument. (Note that this @samp{P} is upper case.) No
I/O.
@item r
@cindex region argument
@ -355,7 +393,7 @@ A variable declared to be a user option (i.e., satisfying the predicate
Completion, Prompt.
@item x
A Lisp object specified in printed representation, terminated with a
A Lisp object, specified with its read syntax, terminated with a
@key{LFD} or @key{RET}. The object is not evaluated. @xref{Object from
Minibuffer}. Prompt.
@ -451,9 +489,10 @@ realistic example of using @code{commandp}.
@defun call-interactively command &optional record-flag
This function calls the interactively callable function @var{command},
reading arguments according to its interactive calling specifications.
An error is signaled if @var{command} cannot be called interactively
(i.e., it is not a command). Note that keyboard macros (strings and
vectors) are not accepted, even though they are considered commands.
An error is signaled if @var{command} is not a function or if it cannot
be called interactively (i.e., is not a command). Note that keyboard
macros (strings and vectors) are not accepted, even though they are
considered commands, because they are not functions.
@cindex record command history
If @var{record-flag} is non-@code{nil}, then this command and its
@ -505,7 +544,7 @@ part of the prompt.
@group
(execute-extended-command 1)
---------- Buffer: Minibuffer ----------
M-x forward-word RET
1 M-x forward-word RET
---------- Buffer: Minibuffer ----------
@result{} t
@end group
@ -622,7 +661,7 @@ if all those events were characters. @xref{Input Events}.
@example
@group
(this-command-keys)
;; @r{Now type @kbd{C-u C-x C-e}.}
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
@result{} "^U^X^E"
@end group
@end example
@ -646,7 +685,7 @@ character to insert.
@example
@group
last-command-event
;; @r{Now type @kbd{C-u C-x C-e}.}
;; @r{Now use @kbd{C-u C-x C-e} to evaluate that.}
@result{} 5
@end group
@end example
@ -781,7 +820,7 @@ function @code{event-modifiers} (@pxref{Classifying Events}).
@subsection Function Keys
@cindex function keys
Most keyboards also have @dfn{function keys}---keys which have names or
Most keyboards also have @dfn{function keys}---keys that have names or
symbols that are not characters. Function keys are represented in Lisp
as symbols; the symbol's name is the function key's label, in lower
case. For example, pressing a key labeled @key{F1} places the symbol
@ -790,7 +829,7 @@ case. For example, pressing a key labeled @key{F1} places the symbol
The event type of a function key event is the event symbol itself.
@xref{Classifying Events}.
Here are a few special cases in the symbol naming convention for
Here are a few special cases in the symbol-naming convention for
function keys:
@table @asis
@ -813,19 +852,25 @@ In @sc{ASCII}, @key{BS} is really @kbd{C-h}. But @code{backspace}
converts into the character code 127 (@key{DEL}), not into code 8
(@key{BS}). This is what most users prefer.
@item @code{left}, @code{up}, @code{right}, @code{down}
Cursor arrow keys
@item @code{kp-add}, @code{kp-decimal}, @code{kp-divide}, @dots{}
Keypad keys (to the right of the regular keyboard).
@item @code{kp-0}, @code{kp-1}, @dots{}
Keypad keys with digits.
@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Keypad PF keys.
@item @code{left}, @code{up}, @code{right}, @code{down}
Cursor arrow keys
@item @code{kp-home}, @code{kp-left}, @code{kp-up}, @code{kp-right}, @code{kp-down}
Keypad arrow keys. Emacs normally translates these
into the non-keypad keys @code{home}, @code{left}, @dots{}
@item @code{kp-prior}, @code{kp-next}, @code{kp-end}, @code{kp-begin}, @code{kp-insert}, @code{kp-delete}
Additional keypad duplicates of keys ordinarily found elsewhere. Emacs
normally translates these into the like-named non-keypad keys.
@end table
You can use the modifier keys @key{CTRL}, @key{META}, @key{HYPER},
@key{SUPER}, @key{ALT} and @key{SHIFT} with function keys. The way
to represent them is with prefixes in the symbol name:
You can use the modifier keys @key{ALT}, @key{CTRL}, @key{HYPER},
@key{META}, @key{SHIFT}, and @key{SUPER} with function keys. The way to
represent them is with prefixes in the symbol name:
@table @samp
@item A-
@ -905,8 +950,8 @@ describe events by their types; thus, if there is a key binding for
This is the window in which the click occurred.
@item @var{x}, @var{y}
These are the pixel-based coordinates of the click, relative to the top
left corner of @var{window}, which is @code{(0 . 0)}.
These are the pixel-denominated coordinates of the click, relative to
the top left corner of @var{window}, which is @code{(0 . 0)}.
@item @var{buffer-pos}
This is the buffer position of the character clicked on.
@ -938,10 +983,10 @@ the symbol @code{mode-line} or @code{vertical-line}. For the mode line,
@var{y} does not have meaningful data. For the vertical line, @var{x}
does not have meaningful data.
@var{buffer-pos} may be a list containing a symbol (one of the symbols
listed above) instead of just the symbol. This is what happens after
the imaginary prefix keys for these events are inserted into the input
stream. @xref{Key Sequence Input}.
In one special case, @var{buffer-pos} is a list containing a symbol (one
of the symbols listed above) instead of just the symbol. This happens
after the imaginary prefix keys for the event are inserted into the
input stream. @xref{Key Sequence Input}.
@node Drag Events
@subsection Drag Events
@ -972,7 +1017,7 @@ no need to distinguish drag events from others.
The @samp{drag-} prefix follows the modifier key prefixes such as
@samp{C-} and @samp{M-}.
If @code{read-key-sequence} receives a drag event which has no key
If @code{read-key-sequence} receives a drag event that has no key
binding, and the corresponding click event does have a binding, it
changes the drag event into a click event at the drag's starting
position. This means that you don't have to distinguish between click
@ -989,17 +1034,17 @@ click from a drag until the button is released.
If you want to take action as soon as a button is pressed, you need to
handle @dfn{button-down} events.@footnote{Button-down is the
conservative antithesis of drag.} These occur as soon as a button is
pressed. They are represented by lists which look exactly like click
pressed. They are represented by lists that look exactly like click
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 the Emacs command loop,
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}, 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}.
@node Repeat Events
@subsection Repeat Events
@ -1039,7 +1084,7 @@ mouse with the button held down, then you get a @dfn{double-drag} event
when you ultimately release the button. Its event type contains
@samp{double-drag} instead of just @samp{drag}. If a double-drag event
has no binding, Emacs looks for an alternate binding as if the event
were an ordinary click.
were an ordinary drag.
Before the double-click or double-drag event, Emacs generates a
@dfn{double-down} event when the user presses the button down for the
@ -1050,8 +1095,9 @@ If it finds no binding that way either, the double-down event is
ignored.
To summarize, when you click a button and then press it again right
away, Emacs generates a double-down event, followed by either a
double-click or a double-drag.
away, Emacs generates a down event and a click event for the first
click, a double-down event when you press the button again, and finally
either a double-click or a double-drag event.
If you click a button twice and then press it again, all in quick
succession, Emacs generates a @dfn{triple-down} event, followed by
@ -1136,14 +1182,14 @@ Focus events are represented in Lisp as lists that look like this:
@noindent
where @var{new-frame} is the frame switched to.
Most X window window managers are set up so that just moving the mouse
into a window is enough to set the focus there. Emacs appears to do
this, because it changes the cursor to solid in the new frame. However,
there is no need for the Lisp program to know about the focus change
until some other kind of input arrives. So Emacs generates a focus
event only when the user actually types a keyboard key or presses a
mouse button in the new frame; just moving the mouse between frames does
not generate a focus event.
Most X window managers are set up so that just moving the mouse into a
window is enough to set the focus there. Emacs appears to do this,
because it changes the cursor to solid in the new frame. However, there
is no need for the Lisp program to know about the focus change until
some other kind of input arrives. So Emacs generates a focus event only
when the user actually types a keyboard key or presses a mouse button in
the new frame; just moving the mouse between frames does not generate a
focus event.
A focus event in the middle of a key sequence would garble the
sequence. So Emacs never generates a focus event in the middle of a key
@ -1188,12 +1234,12 @@ into another window. That produces a pair of events like these:
@subsection Classifying Events
@cindex event type
Every event has an @dfn{event type} which classifies the event for key
binding purposes. For a keyboard event, the event type equals the event
value; thus, the event type for a character is the character, and the
event type for a function key symbol is the symbol itself. For events
which are lists, the event type is the symbol in the @sc{car} of the
list. Thus, the event type is always a symbol or a character.
Every event has an @dfn{event type}, which classifies the event for
key binding purposes. For a keyboard event, the event type equals the
event value; thus, the event type for a character is the character, and
the event type for a function key symbol is the symbol itself. For
events that are lists, the event type is the symbol in the @sc{car} of
the list. Thus, the event type is always a symbol or a character.
Two events of the same type are equivalent where key bindings are
concerned; thus, they always run the same command. That does not
@ -1284,7 +1330,7 @@ a mouse button or motion event.
mouse-button event. The position is a list of this form:
@example
(@var{window} @var{buffer-position} (@var{col} . @var{row}) @var{timestamp})
(@var{window} @var{buffer-position} (@var{x} . @var{y}) @var{timestamp})
@end example
@defun event-start event
@ -1304,8 +1350,8 @@ event, the value is actually the starting position, which is the only
position such events have.
@end defun
These four functions take a position-list as described above, and
return various parts of it.
These four functions take a position as described above, and return
various parts of it.
@defun posn-window position
Return the window that @var{position} is in.
@ -1316,8 +1362,8 @@ Return the buffer position in @var{position}. This is an integer.
@end defun
@defun posn-x-y position
Return the pixel-based x and y coordinates column in @var{position}, as
a cons cell @code{(@var{x} . @var{y})}.
Return the pixel-based x and y coordinates in @var{position}, as a cons
cell @code{(@var{x} . @var{y})}.
@end defun
@defun posn-col-row position
@ -1330,10 +1376,18 @@ a cons cell @code{(@var{col} . @var{row})}. These are computed from the
Return the timestamp in @var{position}.
@end defun
@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
@code{(@var{portion} . @var{whole})} containing two integers whose ratio
is the fractional position.
@end defun
@defun scroll-bar-scale ratio total
This function multiples (in effect) @var{ratio} by @var{total}, rounding
the result to an integer. The argument @var{ratio} is not a number, but
rather a pair @code{(@var{num} . @var{denom})}.
This function multiplies (in effect) @var{ratio} by @var{total},
rounding the result to an integer. The argument @var{ratio} is not a
number, but rather a pair @code{(@var{num} . @var{denom})}---typically a
value returned by @code{scroll-bar-event-ratio}.
This function is handy for scaling a position on a scroll bar into a
buffer position. Here's how to do that:
@ -1341,9 +1395,12 @@ buffer position. Here's how to do that:
@example
(+ (point-min)
(scroll-bar-scale
(posn-col-row (event-start event))
(posn-x-y (event-start event))
(- (point-max) (point-min))))
@end example
Recall that scroll bar events have two integers forming ratio in place
of a pair of x and y coordinates.
@end defun
@node Strings of Events
@ -1351,7 +1408,7 @@ buffer position. Here's how to do that:
In most of the places where strings are used, we conceptualize the
string as containing text characters---the same kind of characters found
in buffers or files. Occasionally Lisp programs use strings which
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
@ -1407,7 +1464,7 @@ possibility that they might contain meta characters, and by using
@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
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
@ -1485,8 +1542,8 @@ and key sequences read from keyboard macros being executed.
@cindex upper case key sequence
@cindex downcasing in @code{lookup-key}
If an input character is an upper case letter and has no key binding,
but its lower case equivalent has one, then @code{read-key-sequence}
If an input character is an upper-case letter and has no key binding,
but its lower-case equivalent has one, then @code{read-key-sequence}
converts the character to lower case. Note that @code{lookup-key} does
not perform case conversion in this way.
@ -1522,7 +1579,7 @@ mouse on the window's mode line, you get an event like this:
@node Reading One Event
@subsection Reading One Event
The lowest level functions for command input are those which read a
The lowest level functions for command input are those that read a
single event.
@defun read-event
@ -1584,10 +1641,10 @@ the echo area.
@subsection Quoted Character Input
@cindex quoted character input
You can use the function @code{read-quoted-char} when to ask the user
to specify a character, and allow the user to specify a control or meta
character conveniently with quoting or as an octal character code. The
command @code{quoted-insert} uses this function.
You can use the function @code{read-quoted-char} to ask the user to
specify a character, and allow the user to specify a control or meta
character conveniently, either literally or as an octal character code.
The command @code{quoted-insert} uses this function.
@defun read-quoted-char &optional prompt
@cindex octal character input
@ -1621,8 +1678,7 @@ What character-@kbd{177}
@end example
@end defun
@need 3000
@need 2000
@node Event Input Misc
@subsection Miscellaneous Event Input Features
@ -1650,8 +1706,8 @@ Likewise, incremental search uses this feature to unread events with no
special meaning in a search, because these events should exit the search
and then execute normally.
The reliable and easy way to extract events from a key sequence to put
them in @code{unread-command-events} is to use
The reliable and easy way to extract events from a key sequence so as to
put them in @code{unread-command-events} is to use
@code{listify-key-sequence} (@pxref{Strings of Events}).
@end defvar
@ -1780,9 +1836,9 @@ Use @code{sleep-for} when you wish to guarantee a delay.
@cindex @kbd{C-g}
@cindex quitting
Typing @kbd{C-g} while the command loop has run a Lisp function causes
Emacs to @dfn{quit} whatever it is doing. This means that control
returns to the innermost active command loop.
Typing @kbd{C-g} while a Lisp function is running causes Emacs to
@dfn{quit} whatever it is doing. This means that control returns to the
innermost active command loop.
Typing @kbd{C-g} while the command loop is waiting for keyboard input
does not cause a quit; it acts as an ordinary input character. In the
@ -1802,13 +1858,13 @@ prefix key is not redefined in the minibuffer, and it has its normal
effect of canceling the prefix key and prefix argument. This too
would not be possible if @kbd{C-g} always quit directly.
When @kbd{C-g} does directly quit, it does so by the variable
When @kbd{C-g} does directly quit, it does so by setting the variable
@code{quit-flag} to @code{t}. Emacs checks this variable at appropriate
times and quits if it is not @code{nil}. Setting @code{quit-flag}
non-@code{nil} in any way thus causes a quit.
At the level of C code, quitting cannot happen just anywhere; only at the
special places which check @code{quit-flag}. The reason for this is
special places that check @code{quit-flag}. The reason for this is
that quitting at other places might leave an inconsistency in Emacs's
internal state. Because quitting is delayed until a safe place, quitting
cannot make Emacs crash.
@ -1828,13 +1884,12 @@ usual result of this---a quit---is prevented. Eventually,
@code{inhibit-quit} will become @code{nil} again, such as when its
binding is unwound at the end of a @code{let} form. At that time, if
@code{quit-flag} is still non-@code{nil}, the requested quit happens
immediately. This behavior is ideal for a ``critical section'', where
you wish to make sure that quitting does not happen within that part of
the program.
immediately. This behavior is ideal when you wish to make sure that
quitting does not happen within a ``critical section'' of the program.
@cindex @code{read-quoted-char} quitting
In some functions (such as @code{read-quoted-char}), @kbd{C-g} is
handled in a special way which does not involve quitting. This is done
handled in a special way that does not involve quitting. This is done
by reading the input with @code{inhibit-quit} bound to @code{t}, and
setting @code{quit-flag} to @code{nil} before @code{inhibit-quit}
becomes @code{nil} again. This excerpt from the definition of
@ -1884,10 +1939,9 @@ See the function @code{set-input-mode} in @ref{Terminal Input}.
Most Emacs commands can use a @dfn{prefix argument}, a number
specified before the command itself. (Don't confuse prefix arguments
with prefix keys.) The prefix argument is represented by a value that
is always available (though it may be @code{nil}, meaning there is no
prefix argument). Each command may use the prefix argument or ignore
it.
with prefix keys.) The prefix argument is at all times represented by a
value, which may be @code{nil}, meaning there is currently no prefix
argument. Each command may use the prefix argument or ignore it.
There are two representations of the prefix argument: @dfn{raw} and
@dfn{numeric}. The editor command loop uses the raw representation
@ -1964,17 +2018,17 @@ commands.
Normally, commands specify which representation to use for the prefix
argument, either numeric or raw, in the @code{interactive} declaration.
(@xref{Interactive Call}.) Alternatively, functions may look at the
(@xref{Using Interactive}.) Alternatively, functions may look at the
value of the prefix argument directly in the variable
@code{current-prefix-arg}, but this is less clean.
@defun prefix-numeric-value arg
This function returns the numeric meaning of a valid raw prefix argument
value, @var{arg}. The argument may be a symbol, a number, or a list.
If it is @code{nil}, the value 1 is returned; if it is any other symbol,
the value @minus{}1 is returned. If it is a number, that number is
returned; if it is a list, the @sc{car} of that list (which should be a
number) is returned.
If it is @code{nil}, the value 1 is returned; if it is @code{-}, the
value @minus{}1 is returned; if it is a number, that number is returned;
if it is a list, the @sc{car} of that list (which should be a number) is
returned.
@end defun
@defvar current-prefix-arg
@ -2064,12 +2118,12 @@ control returns to the command loop one level up. This is called
Most applications should not use recursive editing, except as part of
using the minibuffer. Usually it is more convenient for the user if you
change the major mode of the current buffer temporarily to a special
major mode, which has a command to go back to the previous mode. (The
@kbd{e} command in Rmail uses this technique.) Or, if you wish to give
the user different text to edit ``recursively'', create and select a new
buffer in a special mode. In this mode, define a command to complete
the processing and go back to the previous buffer. (The @kbd{m} command
in Rmail does this.)
major mode, which should have a command to go back to the previous mode.
(The @kbd{e} command in Rmail uses this technique.) Or, if you wish to
give the user different text to edit ``recursively'', create and select
a new buffer in a special mode. In this mode, define a command to
complete the processing and go back to the previous buffer. (The
@kbd{m} command in Rmail does this.)
Recursive edits are useful in debugging. You can insert a call to
@code{debug} into a function definition as a sort of breakpoint, so that
@ -2165,21 +2219,21 @@ programs.
@deffn Command enable-command command
Allow @var{command} to be executed without special confirmation from now
on, and optionally alter the user's @file{.emacs} file so that this will
apply to future sessions.
on, and (if the user confirms) alter the user's @file{.emacs} file so
that this will apply to future sessions.
@end deffn
@deffn Command disable-command command
Require special confirmation to execute @var{command} from now on, and
optionally alter the user's @file{.emacs} file so that this will apply
to future sessions.
(if the user confirms) alter the user's @file{.emacs} file so that this
will apply to future sessions.
@end deffn
@defvar disabled-command-hook
This normal hook is run instead of a disabled command, when the user
invokes the disabled command interactively. The hook functions can use
@code{this-command-keys} to determine what the user typed to run the
command, and thus find the command itself.
command, and thus find the command itself. @xref{Hooks}.
By default, @code{disabled-command-hook} contains a function that asks
the user whether to proceed.

6
lispref/display.texi
View File

@ -193,10 +193,14 @@ string. See @code{format} in @ref{String Conversion}, for the details
on the conversion specifications. @code{message} returns the
constructed string.
In batch mode, @code{message} prints the message text on the standard
error stream, followed by a newline.
@c Emacs 19 feature
If @var{string} is @code{nil}, @code{message} clears the echo area. If
the minibuffer is active, this brings the minibuffer contents back onto
the screen immediately.
@example
@group
(message "Minibuffer depth is %d."
@ -881,7 +885,7 @@ 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
@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.

183
lispref/files.texi
View File

@ -13,6 +13,13 @@ file-related functions of Emacs Lisp, but a few others are described in
@ref{Buffers}, and those related to backups and auto-saving are
described in @ref{Backups and Auto-Saving}.
Many of the file functions take one or more arguments that are file
names. A file name is actually a string. Most of these functions
expand file name arguments using @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
@menu
* Visiting Files:: Reading files into Emacs buffers for editing.
* Saving Buffers:: Writing changed buffers back into files.
@ -52,7 +59,7 @@ back into the file.
In spite of the distinction between files and buffers, people often
refer to a file when they mean a buffer and vice-versa. Indeed, we say,
``I am editing a file,'' rather than, ``I am editing a buffer which I
``I am editing a file,'' rather than, ``I am editing a buffer that I
will soon save as a file of the same name.'' Humans do not usually need
to make the distinction explicit. When dealing with a computer program,
however, it is good to keep the distinction in mind.
@ -153,7 +160,7 @@ When this command is called interactively, it prompts for
@end deffn
@deffn Command view-file filename
This command views @var{filename} in View mode, returning to the
This command visits @var{filename} in View mode, returning to the
previous buffer when done. View mode is a mode that allows you to skim
rapidly through the file but does not let you modify it. Entering View
mode runs the normal hook @code{view-mode-hook}. @xref{Hooks}.
@ -256,9 +263,9 @@ Otherwise it does nothing.
@code{save-buffer} is responsible for making backup files. Normally,
@var{backup-option} is @code{nil}, and @code{save-buffer} makes a backup
file only if this is the first save or if the buffer was previously
modified. Other values for @var{backup-option} request the making of
backup files in other circumstances:
file only if this is the first save since visiting the file. Other
values for @var{backup-option} request the making of backup files in
other circumstances:
@itemize @bullet
@item
@ -479,7 +486,7 @@ Normally, @code{write-region} displays a message @samp{Wrote file
@var{filename}} in the echo area. If @var{visit} is neither @code{t}
nor @code{nil} nor a string, then this message is inhibited. This
feature is useful for programs that use files for internal purposes,
files which the user does not need to know about.
files that the user does not need to know about.
@end deffn
@node File Locks
@ -530,7 +537,7 @@ does nothing if the current buffer is not visiting a file.
@defun ask-user-about-lock file other-user
This function is called when the user tries to modify @var{file}, but it
is locked by another user name @var{other-user}. The value it returns
is locked by another user named @var{other-user}. The value it returns
determines what happens next:
@itemize @bullet
@ -567,19 +574,11 @@ for its usual definition is in @file{userlock.el}.
@node Information about Files
@section Information about Files
The functions described in this section are similar in as much as
they all operate on strings which are interpreted as file names. All
have names that begin with the word @samp{file}. These functions all
return information about actual files or directories, so their
arguments must all exist as actual files or directories unless
otherwise noted.
Most of the file-oriented functions take a single argument,
@var{filename}, which must be a string. The file name is expanded using
@code{expand-file-name}, so @file{~} is handled correctly, as are
relative file names (including @samp{../}). These functions don't
recognize environment variable substitutions such as @samp{$HOME}.
@xref{File Name Expansion}.
The functions described in this section all operate on strings that
designate file names. All the functions have names that begin with the
word @samp{file}. These functions all return information about actual
files or directories, so their arguments must all exist as actual files
or directories unless otherwise noted.
@menu
* Testing Accessibility:: Is a given file readable? Writable?
@ -638,11 +637,11 @@ modes permit.
@end defun
@defun file-writable-p filename
This function returns @code{t} if the file @var{filename} can be written or
created by you. It is writable if the file exists and you can write it.
It is creatable if the file does not exist, but the specified directory
does exist and you can write in that directory. @code{file-writable-p}
returns @code{nil} otherwise.
This function returns @code{t} if the file @var{filename} can be written
or created by you, and @code{nil} otherwise. A file is writable if the
file exists and you can write it. It is creatable if it does not exist,
but the specified directory does exist and you can write in that
directory.
In the third example below, @file{foo} is not writable because the
parent directory does not exist, even though the user could create such
@ -667,9 +666,10 @@ a directory.
@c Emacs 19 feature
@defun file-accessible-directory-p dirname
This function returns @code{t} if you have permission to open existing
files in directory @var{dirname}; otherwise (and if there is no such
directory), it returns @code{nil}. The value of @var{dirname} may be
either a directory name or the file name of a directory.
files in the directory whose name as a file is @var{dirname}; otherwise
(or if there is no such directory), it returns @code{nil}. The value
of @var{dirname} may be either a directory name or the file name of a
directory.
Example: after the following,
@ -686,14 +686,14 @@ give an error.
@defun file-newer-than-file-p filename1 filename2
@cindex file age
@cindex file modification time
This functions returns @code{t} if the file @var{filename1} is
This function returns @code{t} if the file @var{filename1} is
newer than file @var{filename2}. If @var{filename1} does not
exist, it returns @code{nil}. If @var{filename2} does not exist,
it returns @code{t}.
In the following example, assume that the file @file{aug-19} was
written on the 19th, and @file{aug-20} was written on the 20th. The
file @file{no-file} doesn't exist at all.
In the following example, assume that the file @file{aug-19} was written
on the 19th, @file{aug-20} was written on the 20th, and the file
@file{no-file} doesn't exist at all.
@example
@group
@ -729,8 +729,8 @@ links from ordinary files.
@cindex file symbolic links
If the file @var{filename} is a symbolic link, the @code{file-symlink-p}
function returns the file name to which it is linked. This may be the
name of a text file, a directory, or even another symbolic link, or of
no file at all.
name of a text file, a directory, or even another symbolic link, or it
may be a nonexistent file name.
If the file @var{filename} is not a symbolic link (or there is no such file),
@code{file-symlink-p} returns @code{nil}.
@ -822,7 +822,7 @@ and modification.
This function returns the mode bits of @var{filename}, as an integer.
The mode bits are also called the file permissions, and they specify
access control in the usual Unix fashion. If the low-order bit is 1,
then the file is executable by all users, if the second lowest-order bit
then the file is executable by all users, if the second-lowest-order bit
is 1, then the file is writable by all users, etc.
The highest value returnable is 4095 (7777 octal), meaning that
@ -920,7 +920,7 @@ The time of last status change as a list of two integers (as above).
The size of the file in bytes.
@item
The file's modes, as a string of ten letters or dashes
The file's modes, as a string of ten letters or dashes,
as in @samp{ls -l}.
@item
@ -932,9 +932,9 @@ The file's inode number.
@item
The file system number of the file system that the file is in. This
element together with the file's inode number, give enough information
to distinguish any two files on the system---no two files can have the
same values for both of these numbers.
element and the file's inode number together give enough information to
distinguish any two files on the system---no two files can have the same
values for both of these numbers.
@end enumerate
For example, here are the file attributes for @file{files.texi}:
@ -1142,9 +1142,9 @@ This command makes a symbolic link to @var{filename}, named
@var{newname}. This is like the shell command @samp{ln -s
@var{filename} @var{newname}}.
In an interactive call, @var{filename} and @var{newname} are read in the
minibuffer; it requests confirmation if the file @var{newname} already
exists.
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@var{newname} already exists.
@end deffn
@defun define-logical-name varname string
@ -1154,7 +1154,7 @@ This function defines the logical name @var{name} to have the value
@defun set-file-modes filename mode
This function sets mode bits of @var{filename} to @var{mode} (which must
be an integer). Only the 12 low bits of @var{mode} are used.
be an integer). Only the low 12 bits of @var{mode} are used.
@end defun
@c Emacs 19 feature
@ -1164,7 +1164,7 @@ 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.
The argument @var{mode} must be an integer. Only the 9 low bits of
The argument @var{mode} must be an integer. Only the low 9 bits of
@var{mode} are used.
Saving a modified version of an existing file does not count as creating
@ -1200,10 +1200,10 @@ how to manipulate file names.
can operate on file names that do not refer to an existing file or
directory.
On VMS, all these functions understand both VMS file name syntax and
On VMS, all these functions understand both VMS file-name syntax and
Unix syntax. This is so that all the standard Lisp libraries can
specify file names in Unix syntax and work properly on VMS without
change. On MS-DOS, these functions understand MS-DOS file name syntax
change. On MS-DOS, these functions understand MS-DOS file-name syntax
as well as Unix syntax.
@menu
@ -1223,11 +1223,11 @@ as well as Unix syntax.
@cindex version number (in file name)
The operating system groups files into directories. To specify a
file, you must specify the directory, and the file's name in that
directory. Therefore, a file name in Emacs is considered to have two
main parts: the @dfn{directory name} part, and the @dfn{nondirectory}
part (or @dfn{file name within the directory}). Either part may be
empty. Concatenating these two parts reproduces the original file name.
file, you must specify the directory and the file's name within that
directory. Therefore, Emacs considers a file name as having two main
parts: the @dfn{directory name} part, and the @dfn{nondirectory} part
(or @dfn{file name within the directory}). Either part may be empty.
Concatenating these two parts reproduces the original file name.
On Unix, the directory part is everything up to and including the last
slash; the nondirectory part is the rest. The rules in VMS syntax are
@ -1327,9 +1327,9 @@ subtle but crucial. When an Emacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.
These two functions convert between directory names and file names.
They do nothing special with environment variable substitutions such as
@samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
The following two functions convert between directory names and file
names. They do nothing special with environment variable substitutions
such as @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.
@defun file-name-as-directory filename
This function returns a string representing @var{filename} in a form
@ -1510,7 +1510,7 @@ variables; only @code{substitute-in-file-name} does that.
@c Emacs 19 feature
@defun file-relative-name filename directory
This function does the inverse of expansion---it tries to return a
relative name which is equivalent to @var{filename} when interpreted
relative name that is equivalent to @var{filename} when interpreted
relative to @var{directory}. (If such a relative name would be longer
than the absolute name, it returns the absolute name instead.)
@ -1598,8 +1598,8 @@ the same name.
@defun make-temp-name string
This function generates string that can be used as a unique name. The
name starts with the prefix @var{string}, and ends with a number that
is different in each Emacs job.
name starts with @var{string}, and ends with a number that is different
in each Emacs job.
@example
@group
@ -1756,18 +1756,20 @@ This function returns a list of all versions of the file named
@end defun
@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts a directory listing for directory @var{dir},
formatted with @code{ls} according to @var{switches}. It leaves point
after the inserted text.
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to
@var{switches}. It leaves point after the inserted text.
The argument @var{dir} may be either a directory name or a file
The argument @var{file} may be either a directory name or a file
specification including wildcard characters. If @var{wildcard} is
non-@code{nil}, that means treat @var{file} as a file specification with
wildcards.
If @var{full-directory-p} is non-@code{nil}, that means @var{file} is a
directory and switches do not contain @samp{d}, so that a full listing
is expected.
directory and switches do not contain @samp{-d}, so that the listing
should show the full contents of the directory. (The @samp{-d} option
to @code{ls} says to describe a directory itself rather than its
contents.)
This function works by running a directory listing program whose name is
in the variable @code{insert-directory-program}. If @var{wildcard} is
@ -1784,6 +1786,11 @@ for the function @code{insert-directory}.
@section Creating and Deleting Directories
@c Emacs 19 features
Most Emacs Lisp file-manipulation functions get errors when used on
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
This function creates a directory named @var{dirname}.
@end defun
@ -1801,11 +1808,11 @@ must use @code{delete-directory} in that case.
@c Emacs 19 feature
You can implement special handling for certain file names. This is
called making those names @dfn{magic}. You must supply a regular
expression to define the class of names (all those which match the
expression to define the class of names (all those that match the
regular expression), plus a handler that implements all the primitive
Emacs file operations for file names that do match.
The value of @code{file-name-handler-alist} is a list of handlers,
The variable @code{file-name-handler-alist} holds a list of handlers,
together with regular expressions that determine when to apply each
handler. Each element has this form:
@ -1836,7 +1843,7 @@ called like this:
(funcall @var{handler} 'file-exists-p @var{filename})
@end example
Here are the operations that you can handle for a magic file name:
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},
@ -1853,17 +1860,18 @@ Here are the operations that you can handle for a magic file name:
@code{file-name-directory}, @code{file-name-nondirectory},
@code{file-name-sans-versions}, @code{file-newer-than-file-p},
@code{file-readable-p}, @code{file-symlink-p}, @code{file-truename},
@code{file-writable-p},@*
@code{insert-directory},
@code{file-writable-p}, @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{unhandled-file-name-directory},
@code{verify-visited-file-modtime}, @code{write-region}.
The handler function must handle all of the above operations, and
possibly others to be added in the future. Therefore, it should always
reinvoke the ordinary Lisp primitive when it receives an operation it
does not recognize. Here's one way to do this:
possibly others to be added in the future. It need not implement all
these operations itself---when it has nothing special to do for a
certain operation, it can reinvoke the primitive, to handle the
operation ``in the usual way''. It should always reinvoke the primitive
for an operation it does not recognize. Here's one way to do this:
@smallexample
(defun my-file-handler (operation &rest args)
@ -1874,7 +1882,7 @@ does not recognize. Here's one way to do this:
@dots{}
;; @r{Handle any operation we don't know about.}
(t (let ((inhibit-file-name-handlers
(cons 'ange-ftp-file-handler
(cons 'my-file-handler
(and (eq inhibit-file-name-operation operation)
inhibit-file-name-handlers)))
(inhibit-file-name-operation operation))
@ -1909,10 +1917,12 @@ for comparison with @code{inhibit-file-name-operation}.
@end defun
@defun file-local-copy filename
This function copies file @var{filename} to the local site, if it isn't
there already. If @var{filename} specifies a ``magic'' file name which
programs outside Emacs cannot directly read or write, this copies the
contents to an ordinary file and returns that file's name.
This function copies file @var{filename} to an ordinary non-magic file,
if it isn't one already.
If @var{filename} specifies a ``magic'' file name, which programs
outside Emacs cannot directly read or write, this copies the contents to
an ordinary file and returns that file's name.
If @var{filename} is an ordinary file name, not magic, then this function
does nothing and returns @code{nil}.
@ -1936,18 +1946,21 @@ is a good way to come up with one.
@cindex binary files and text files
Emacs on MS-DOS makes a distinction between text files and binary
files. This is necessary because ordinary text files on MS-DOS use two
characters between lines: carriage-return and linefeed. 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 when
the file is saved.
files. This is necessary because ordinary text files on MS-DOS use a
two character sequence between lines: carriage-return and linefeed
(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.
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

2
lispref/modes.texi
View File

@ -1311,10 +1311,10 @@ have very long file names or display the time and load.)
(add-hook 'text-mode-hook
(function (lambda ()
(setq mode-line-format
@end group
'(mode-line-modified
"Emacs: %14b"
" "
@end group
default-directory
" "
global-mode-string

2
lispref/processes.texi
View File

@ -93,7 +93,7 @@ supplied to @var{program} as separate command line arguments. Wildcard
characters and other shell constructs are not allowed in these strings,
since they are passed directly to the specified program.
@strong{Please note:} the argument @var{program} contains only the
@strong{Please note:} The argument @var{program} contains only the
name of the program; it may not contain any command-line arguments. You
must use @var{args} to provide those.

2
lispref/searching.texi
View File

@ -318,7 +318,7 @@ example, the regular expression that matches the @samp{\} character is
@samp{\} is @code{"\\\\"}.@refill
@end table
@strong{Please note:} for historical compatibility, special characters
@strong{Please note:} For historical compatibility, special characters
are treated as ordinary ones if they are in contexts where their special
meanings make no sense. For example, @samp{*foo} treats @samp{*} as
ordinary since there is no preceding expression on which the @samp{*}

43
lispref/text.texi
View File

@ -48,6 +48,7 @@ buffer.
* Case Changes:: Case conversion of parts of the buffer.
* Text Properties:: Assigning Lisp property lists to text characters.
* Substitution:: Replacing a given character wherever it appears.
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Change Hooks:: Supplying functions to be run when text is changed.
@ -520,17 +521,21 @@ In the example below, point is located on the line starting
in the preceding line.
@smallexample
@group
---------- Buffer: foo ----------
When in the course of human
@point{} events, it becomes necessary
---------- Buffer: foo ----------
@end group
(delete-indentation)
@result{} nil
@group
---------- Buffer: foo ----------
When in the course of human@point{} events, it becomes necessary
---------- Buffer: foo ----------
@end group
@end smallexample
After the lines are joined, the function @code{fixup-whitespace} is
@ -2615,6 +2620,25 @@ This function stores the current frame configuration in register
@end deffn
@end ignore
@node Transposition
@section Transposition of Text
This subroutine is used by the transposition commands.
@defun transpose-regions start1 end1 start2 end2 &optional leave-markers
This function exchanges two nonoverlapping portions of the buffer.
Arguments @var{start1} and @var{end1} specify the bounds of one portion
and arguments @var{start2} and @var{end2} specify the bounds of the
other portion.
Normally, @code{transpose-regions} relocates markers with the transposed
text; a marker previously positioned within one of the two transposed
portions moves along with that portion, thus remaining between the same
two characters in their new position. However, if @var{leave-markers}
is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
all markers unrelocated.
@end defun
@node Change Hooks
@section Change Hooks
@cindex change hooks
@ -2665,6 +2689,25 @@ functions. If you do want a hook function to make changes that run
these functions, make it bind these variables back to their usual
values.
One inconvenient result of this protective feature is that you cannot
have a function in @code{after-change-functions} or
@code{before-change-functions} which changes the value of that variable.
But that's not a real limitation. If you want those functions to change
the list of functions to run, simply add one fixed function to the hook,
and code that function to look in another variable for other functions
to call. Here is an example:
@example
(setq my-own-after-change-functions nil)
(defun indirect-after-change-function (beg end len)
(let ((list my-own-after-change-functions))
(while list
(funcall (car list) beg end len)
(setq list (cdr list)))))
(add-hooks 'after-change-functions
'indirect-after-change-function)
@end example
@defvar first-change-hook
This variable is a normal hook that is run whenever a buffer is changed
that was previously in the unmodified state.

8
lispref/variables.texi
View File

@ -492,7 +492,7 @@ of @var{symbol} to the result, provided @var{value} is given. If
@var{symbol} has a buffer-local binding in the current buffer,
@code{defconst} sets the default value, not the local value.
@strong{Please note:} don't use @code{defconst} for user option
@strong{Please note:} Don't use @code{defconst} for user option
variables in libraries that are not standardly preloaded. The user
should be able to specify a value for such a variable in the
@file{.emacs} file, so that it will be in effect if and when the library
@ -536,7 +536,7 @@ then the variable is a user option.
the variable. The property's value is used as if it were the argument
to @code{interactive}.
@strong{Warning:} if the @code{defconst} and @code{defvar} special
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
local binding's value; the global binding is not changed. This is not
what we really want. To prevent it, use these special forms at top
@ -734,7 +734,7 @@ located textually within the function or block that binds the variable.
@cindex CL note---special variables
@quotation
@b{Common Lisp note:} variables declared ``special'' in Common Lisp
@b{Common Lisp note:} Variables declared ``special'' in Common Lisp
are dynamically scoped, like variables in Emacs Lisp.
@end quotation
@ -973,7 +973,7 @@ the (default) global binding untouched. The global value can no longer
be changed with @code{setq}; you need to use @code{setq-default} to do
that.
@strong{Warning:} when a variable has local values in one or more
@strong{Warning:} When a variable has local values in one or more
buffers, you can get Emacs very confused by binding the variable with
@code{let}, changing to a different current buffer in which a different
binding is in effect, and then exiting the @code{let}. This can

2
lispref/windows.texi
View File

@ -321,7 +321,7 @@ among all the siblings.)
This function returns @code{nil} if @var{window} is deleted, and
@code{t} otherwise.
@strong{Warning:} erroneous information or fatal errors may result from
@strong{Warning:} Erroneous information or fatal errors may result from
using a deleted window as if it were live.
@end defun