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

*** empty log message ***

Browse source
This commit is contained in:
Richard M. Stallman 1998-02-28 01:53:53 +00:00
parent cc6d0d2c94
commit f9f59935f3
43 changed files with 4432 additions and 2365 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

38
lispref/abbrevs.texi
View file

@ -82,7 +82,7 @@ This function defines @var{tabname} (a symbol) as an abbrev table name,
i.e., as a variable whose value is an abbrev table. It defines abbrevs
in the table according to @var{definitions}, a list of elements of the
form @code{(@var{abbrevname} @var{expansion} @var{hook}
@var{usecount})}. The value is always @code{nil}.
@var{usecount})}. The return value is always @code{nil}.
@end defun
@defvar abbrev-table-name-list
@ -93,7 +93,7 @@ This is a list of symbols whose values are abbrev tables.
@defun insert-abbrev-table-description name &optional human
This function inserts before point a description of the abbrev table
named @var{name}. The argument @var{name} is a symbol whose value is an
abbrev table. The value is always @code{nil}.
abbrev table. The return value is always @code{nil}.
If @var{human} is non-@code{nil}, the description is human-oriented.
Otherwise the description is a Lisp expression---a call to
@ -124,14 +124,15 @@ existing abbrev.
@end defun
@defun define-abbrev table name expansion hook
This function defines an abbrev in @var{table} named @var{name}, to
expand to @var{expansion}, and call @var{hook}. The return value is an
uninterned symbol that represents the abbrev inside Emacs; its name is
@var{name}.
This function defines an abbrev named @var{name}, in @var{table}, to
expand to @var{expansion} and call @var{hook}. The return value is a
symbol that represents the abbrev inside Emacs; its name is @var{name}.
The argument @var{name} should be a string. The argument
@var{expansion} should be a string, or @code{nil} to undefine the
abbrev.
@var{expansion} is normally the desired expansion (a string), or
@code{nil} to undefine the abbrev. If it is anything but a string or
@code{nil}, then the abbreviation ``expands'' solely by running
@var{hook}.
The argument @var{hook} is a function or @code{nil}. If @var{hook} is
non-@code{nil}, then it is called with no arguments after the abbrev is
@ -198,10 +199,10 @@ define the same abbrevs. This function returns @code{nil}.
@comment node-name, next, previous, up
@section Looking Up and Expanding Abbreviations
Abbrevs are usually expanded by commands for interactive use,
Abbrevs are usually expanded by certain interactive commands,
including @code{self-insert-command}. This section describes the
subroutines used in writing such functions, as well as the variables
they use for communication.
subroutines used in writing such commands, as well as the variables they
use for communication.
@defun abbrev-symbol abbrev &optional table
This function returns the symbol representing the abbrev named
@ -255,22 +256,23 @@ is set by @code{abbrev-prefix-mark}.
@end defvar
@defvar last-abbrev
This is the @code{abbrev-symbol} of the last abbrev expanded. This
This is the @code{abbrev-symbol} of the most recent abbrev expanded. This
information is left by @code{expand-abbrev} for the sake of the
@code{unexpand-abbrev} command.
@code{unexpand-abbrev} command (@pxref{Expanding Abbrevs,, Expanding
Abbrevs, emacs, The GNU Emacs Manual}).
@end defvar
@defvar last-abbrev-location
This is the location of the last abbrev expanded. This contains
This is the location of the most recent abbrev expanded. This contains
information left by @code{expand-abbrev} for the sake of the
@code{unexpand-abbrev} command.
@end defvar
@defvar last-abbrev-text
This is the exact expansion text of the last abbrev expanded, after case
conversion (if any). Its value is @code{nil} if the abbrev has already
been unexpanded. This contains information left by @code{expand-abbrev}
for the sake of the @code{unexpand-abbrev} command.
This is the exact expansion text of the most recent abbrev expanded,
after case conversion (if any). Its value is @code{nil} if the abbrev
has already been unexpanded. This contains information left by
@code{expand-abbrev} for the sake of the @code{unexpand-abbrev} command.
@end defvar
@c Emacs 19 feature

725
lispref/anti.texi
View file

@ -1,619 +1,244 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1993 Free Software Foundation, Inc.
@c Copyright (C) 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Antinews, Index, Standard Hooks, Top
@appendix Emacs 18 Antinews
@appendix Emacs 19 Antinews
For those users who live backwards in time, here is information about
downgrading to Emacs version 18. We hope you will enjoy the greater
simplicity that results from the absence of many Emacs 19 features.
downgrading to Emacs version 19.34. We hope you will enjoy the greater
simplicity that results from the absence of many Emacs 19 features. In
the following section, we carry this information back as far as Emacs
19.29, for which the previous printed edition of this manual was made.
@section Old Features in the Lisp Language
@section Old Lisp Features in Emacs 19
The following functions are missing or different in Emacs version 18.
Here are the most important of the features that you will learn
to do without in Emacs 19:
@itemize @bullet
@item
The functions @code{delete}, @code{member}, @code{indirect-function},
@code{map-y-or-n-p}, and @code{invocation-name} have been removed.
In a great simplification, Emacs 19 supports ASCII characters only.
There are no multibyte characters, character sets, language
environments, coding systems, or input methods; all the functions that
specifically relate to them are gone as well.
Valid character codes for text must be in the range 0 through 255.
Within this range, there are no invalid character codes.
@item
The function @code{read} now skips a terminator character that
terminates a symbol when reading from a buffer. Thus, if you use
@code{read} on a buffer containing @samp{foo(bar)} following point, it
returns @code{foo} and leaves point after the open-parenthesis. This
means there's no way you can properly read the list @samp{(bar)}, but
that's the way the cookie crumbles.
Because of this simplification, it's no longer necessary for an input
stream function to accept an optional argument. In Emacs 18, an input
stream is always called with no arguments, and should always return
the next character of input.
@item
The function @code{documentation} takes just one argument;
@code{documentation-property} takes just two.
@item
@code{random} no longer has the optional argument @var{n}.
@item
You can no longer arrange to run a hook if a particular Lisp library is
loaded. The variable @code{after-load-alist} and the function
@code{eval-after-load} have been removed.
@item
The function @code{autoload} no longer supports autoloading a keymap.
@item
``Magic'' comments of the form @samp{;;;###autoload} are now just
comments. They don't do anything in particular except look pretty.
If you want a function to be autoloaded by default, edit @file{loaddefs.h}
by hand. What do you think editors are for?
@item
We took out the @samp{%S} from the @code{format} function, and the
optional argument @var{noescap} from @code{prin1-to-string}. We removed
the @code{print-level} variable.
The Custom facility has been replaced with a much simpler and more
general method of defining user option variables. Instead of
@code{defcustom}, which requires you to specify each user option's
data type and classify them into groups, all you have to do is write
a @code{defvar} and start the documentation string with @samp{*}.
@end itemize
@section Compilation Features
Here are changes in the Lisp language itself:
@itemize @bullet
@item
Inline functions are nonexistent in Emacs 18. We find they make the
calling function unnecessarily large. (Small size is one of the
features of Emacs 18.)
Symbols whose names start with @samp{:} are no longer special
in any way. They start out void, like most other symbols.
@item
We eliminated the two special forms, @code{eval-when-compile} and
@code{eval-and-compile}, as well as the @code{compile-defun} command.
The macros @code{when} and @code{unless} have been deleted.
@item
When you load a Lisp file or library, you will no longer receive a
warning if the directory contains both a @samp{.elc} file and a new
@samp{.el} file that is newer. So be on your toes.
The functions @code{caar}, @code{cadr}, @code{cdar} and @code{cddr}
no longer exist.
@item
We removed the special data type for byte-code functions. Compiled
functions now work by means of an interpreted function which calls
the function @code{bytecode}. That function runs the byte code
interpreter.
The function @code{functionp} is now gone. If you don't know
by now whether something is a function, Emacs can't tell you.
@end itemize
@section Floating Point Numbers
Emacs 18 doesn't have or need floating point arithmetic built in.
It has a handy Lisp program that allows you to emulate floating point.
You'll have to write programs specially to use it, though.
As a result, certain macros, functions, and predicates no longer handle
specifications for floating point numbers.
Here are changes in handling strings and text.
@itemize @bullet
@item
The function @code{string-to-number}, the predicate @code{floatp}, and
the variable @code{float-output-format} have all been eliminated.
The function @code{substring} works only on strings, not on vectors.
@item
The functions @code{float}, @code{truncate}, @code{floor}, @code{ceil},
@code{round}, and @code{logb} do not exist; neither do the functions
@code{abs}, @code{cos}, @code{sin}, @code{tan}, @code{acos},
@code{asin}, @code{atan}, @code{exp}, @code{expt}, @code{log10},
@code{log}, or @code{sqrt}.
There are no more character categories.
@item
The @code{format} function no longer handles the specifications
@samp{%e}, @samp{%f} and @samp{%g} for printing floating point numbers;
likewise for @code{message}.
When you compare strings with @code{equal}, it now compares
their string properties as well as their text. All must match,
or the strings are not equal.
@item
@code{format-time-string} no longer supports specified field width
or specified padding.
@item
The functions @code{split-string} and @code{concat-chars} no longer exist.
Neither does @code{store-substring} or @code{sref}.
@item
All printing characters have the same width. Therefore, we have deleted
@code{char-width}, @code{string-width} and
@code{truncate-string-to-width}.
@item
We have eliminated the functions @code{next-char-property-change} and
@code{previous-char-property-change} also.
@item
Syntax parsing now determines the syntax of each character from the
syntax table alone---not from text properties. This makes the syntax
codes @samp{|} and @samp{!}, which were meant for use with text
properties, useless; so we have deleted them.
@item
In the function @code{parse-partial-sexp}, passing @code{syntax-table}
as the sixth argument @var{commentstop} no longer has any special meaning.
And the return value has only eight elements.
@end itemize
@section Changes in Basic Editing Functions
Here are changes in other areas of Emacs Lisp:
@itemize @bullet
@item
@code{kill-new} and @code{kill-append}, the primitives for putting text
in the kill ring, have been eliminated.
@c @code{kill-append} seems to exist as a non-documented (no doc string)
@c primitive in emacs 18. but news.texi said it was new for 19.
The macros @code{save-current-buffer}, @code{with-current-buffer},
@code{with-temp-buffer}, @code{with-temp-file}, @code{save-selected-window},
and @code{with-output-to-string} are gone.
@item
The variables @code{interprogram-paste-function} and
@code{interprogram-cut-function} have been removed in Emacs 18.
In addition, there's no need for @code{mark-active} and
@code{deactivate-mark} because there is no Transient Mark mode. We also
removed the hooks @code{activate-mark-hook} and
@code{deactivate-mark-hook}.
The easy-mmode facility for defining minor modes is gone too.
@item
The @code{kill-region} function can no longer be used in read-only
buffers. The @code{compare-buffer-substrings} and @code{current-kill}
functions have been removed.
Process filters and sentinels must explicitly save the match data, with
@code{save-match-data}, or they will clobber the match data and
something horrible will happen.
@item
The variable @code{overwrite-mode-binary} has been removed.
As part of our effort to loosen up, @code{batch-byte-compile-file} no
longer returns a nonzero status code if there is a compilation error.
@item
The function @code{move-to-column} allows just one argument,
@var{column}.
@item
The search functions now just return @code{t} when successful. This
affects the functions @code{search-forward}, @code{search-backward},
@code{word-search-forward}, @code{word-search-backward},
@code{re-search-forward}, and @code{re-search-backward}.
The ``mail user agent'' feature is gone.
@item
When you do regular expression searching or matching, there is a fixed
limit of ten @samp{\(@dots{}\)} pairs that you can get information about
with @code{match-beginning} and @code{match-end}. Moreover,
@code{save-match-data} does not exist; you must use an explicit
@code{unwind-protect} to save the match data.
We have removed the functions @code{add-to-invisibility-spec} and
@code{remove-from-invisibility-spec}, so you should manipulate
the value of @code{buffer-invisibility-spec} by hand.
@item
@code{translate-region} is gone.
The functions @code{face-documentation}, @code{face-bold-p},
@code{face-italic-p}, @code{set-face-bold-p}, @code{set-face-italic-p}
are gone. Instead, use @code{make-face-bold} and friends.
@item
The variables @code{before-change-function},
@code{after-change-function}, and @code{first-change-hook} have been
eliminated.
All the functions that operate on a file now discard an extra redundant
directory name from the beginning of the file name---just like
@code{substitute-in-file-name}.
@item
The second argument to @code{insert-abbrev-table-description} is no
longer optional.
We have got rid of the function @code{access-file}.
@item
Most of the minibuffer input functions, no longer take a default value as
an argument. Also, they do not discard text properties from the result.
This means that if you insert text with text properties into the minibuffer,
the minibuffer value really will contain text properties.
@item
You can still bind @code{x-resource-class} around a call to
@code{x-get-resource}, but it won't do anything special.
@item
Wave goodbye to the hooks @code{before-make-frame-hook},
@code{after-make-frame-functions}, and
@code{window-configuration-change-hook},
@item
The functions and variables that deal with MS Windows NT/95
have been renamed to start with @samp{win32-} instead of @samp{w32-}.
This is because we admire Microsoft more each day as we go back
into the past.
@end itemize
@section Text Properties
@section Onward into the Past!
We eliminated text properties.
@section Features for Files
Many file-related functions have been eliminated or simplified. Here is
a basic listing of these functions.
Here we go even further back, as far as Emacs 19.29, for which the
previous printed edition of the Emacs Lisp manual was made.
@itemize @bullet
@item
The functions @code{file-accessible-directory-p}, @code{file-truename},
@code{make-directory}, @code{delete-directory},
@code{set-visited-file-modtime}, @code{directory-abbrev-alist},
@code{abbreviate-file-name}, @code{write-region},
@code{write-contents-hooks}, @code{after-save-hook},
@code{set-default-file-modes}, @code{default-file-modes}, and
@code{unix-sync} have been eliminated.
There are no char-tables or bool-vectors. Syntax tables, display
tables, and case tables are all vectors now, and the value of
@code{keyboard-translate-table} should be a vector or a string.
@item
We got rid of the ``initial file name'' argument to
@code{read-file-name}.
There is only one kind of marker. When you insert text at the place
where a marker points, the marker always ends up before that text,
unless you use @code{insert-before-markers}, which puts all the markers
after the inserted text.
@item
Additionally, we removed the 12th element from the list returned by
@code{file-attributes}.
There is no function @code{overlays-in}.
@item
@code{directory-files} always sorts the list of files. It's not user
friendly to process the files in any haphazard order.
The variable @code{print-length} applies only to lists, not to
vectors or strings.
@item
We eliminated the variables @code{write-contents-hooks} and
@code{local-write-file-hooks}.
@end itemize
@section Making Certain File Names ``Magic''
There are no more magic filenames. Sorry, but all the mana has been
used up.
@section Frames
There is only one frame in Emacs 18, so all of the frame functions have
been eliminated.
@section X Window System Features
We have simplified the way Emacs and X interact by removing a great deal
of creeping featurism.
@itemize @bullet
@item
The functions @code{mouse-position} and @code{set-mouse-position}, and
the special form @code{track-mouse}, have been eliminated.
@item
Likewise, the functions @code{x-set-selection}, @code{x-set-cut-buffer},
@code{x-close-current-connection}, and @code{x-open-connection} have all
been removed from Emacs Lisp 18.
@item
We removed a series of functions that gave information about the X
server and the screen you were using; after all, the whole point of X is
that all servers are equivalent. The names of the removed functions
are: @code{x-display-screens}, @code{x-server-version},
@code{x-server-vendor}, @code{x-display-pixel-height},
@code{x-display-mm-height}, @code{x-display-pixel-width},
@code{x-display-mm-width}, @code{x-display-backing-store},
@code{x-display-save-under}, @code{x-display-planes},
@code{x-display-visual-class}, @code{x-display-color-p}, and
@code{x-display-color-cells}.
@item
Additionally, we removed the variable @code{x-no-window-manager} and the
functions @code{x-synchronize} and @code{x-get-resource}.
@item
We didn't abolish @code{x-display-color-p}, but we renamed it to
@code{x-color-display-p}. We did abolish @code{x-color-defined-p}.
@item
@code{x-popup-menu} no longer accepts a keymap for its first argument.
@item
We removed both the function @code{x-rebind-key} and the related
function @code{x-rebind-keys}.
@item
We abolished @code{x-parse-geometry}.
@end itemize
@section Window Actions that Were No Longer Useful
Various behaviors of windows in Emacs 19 were obsolete by the time Emacs
18 was due to come out. We have removed them. These changes are listed
below.
@itemize @bullet
@item
We removed the functions @code{window-at}, @code{window-minibuffer-p},
@code{set-window-dedicated-p}, @code{coordinates-in-window-p},
@code{walk-windows}, @code{window-dedicated-p}, and @code{window-end}.
@item
We removed the variables @code{pop-up-frames},
@code{pop-up-frame-function}, @code{display-buffer-function}, and
@code{other-window-scroll-buffer}.
@item
The function @code{minibuffer-window} no longer accepts a frame as
argument, since frames as objects do not exist in Emacs version 18. It
returns the window used for minibuffers.
@item
The functions @code{next-window} and @code{previous-window} no longer
accept the @var{all-frames} argument since there is just one frame.
@item
The functions @code{get-lru-window}, @code{get-largest-window},
@code{get-buffer-window}, and @code{get-buffer-window} also no longer
take the optional argument @var{all-frames} because there is just one
frame to search.
@end itemize
@section Display Features
@itemize @bullet
@item
There are no overlays, and no faces.
@item
We eliminated the mode line spec @samp{%l} that in later versions used
to display the current line number. We removed the variables
@code{line-number-mode} and @code{line-number-display-limit}.
@item
@code{baud-rate} is now a function rather than a variable.
@item
You can no longer call @code{message} with @code{nil} as the only
argument; therefore, you can not reliably make the contents of the
minibuffer visible.
@item
The variable @code{temp-buffer-show-function} has been renamed
@code{temp-buffer-show-hook}.
@item
We removed the function @code{force-mode-line-update}. Use
the following idiom instead:
@example
(set-buffer-modified-p (buffer-modified-p))
@end example
@item
Display tables no longer exist. We know what the @sc{ASCII} characters
should look like, and we made them look that way.
@end itemize
@section Working with Input Events
The big news about input events is that we got rid of function key
and mouse events. Now the only input events are characters.
What's more, these characters now have to be in the range of 0 to 127,
optionally with a meta bit. This makes for big simplifications.
@itemize @bullet
@item
Functions like @code{define-key}, @code{global-set-key},
@code{read-key-sequence}, and @code{local-set-key} used to accept
strings or vectors in Emacs 19; now they only accept strings.
@item
The documentation functions (@code{single-key-description},
@code{key-description}, etc.) also no longer accept vectors, but they do
accept strings.
@item
We removed the @code{read-event}, @code{event-start},
@code{posn-window}, @code{posn-point}, @code{posn-col-row},
@code{posn-timestamp}, @code{scroll-bar-scale}, and @code{event-end}
functions, since they were useful only for non-character events.
@item
We removed the @code{unread-command-events} and @code{last-event-frame}
variables.
@item
The functions @code{this-command-keys} and @code{recent-keys} now always
return a string. Likewise, a keyboard macro's definition can only be a
string, not a vector.
@item
We eliminated @samp{e} as an interactive specification since it
was useful only with non-character events.
@item
In Emacs 18, we represent Meta characters as character objects with the
same encoding used in strings: 128 plus the corresponding non-Meta
@sc{ASCII} character.
@end itemize
@section Menus
@itemize @bullet
@item
You can no longer define menus as keymaps; good system design requires
crafting a special-purpose interface for each facility, so it can
precisely fit the requirements of that facility. We decided that
unifying keymaps and menus was simply too much of a strain.
@item
In Emacs 18, you can activate menus only with the mouse. Using them
with a keyboard was too confusing for too many users.
@item
Emacs 18 has no menu bars. All functions and variables related to the
menu bar have been eliminated.
@end itemize
@section Changes in Minibuffer Features
@itemize @bullet
@item
The minibuffer history feature has been eliminated. Thus, we removed
the optional argument @var{hist} from the minibuffer input functions
@code{read-from-minibuffer} and @code{completing-read}.
@item
The @var{initial} argument to @code{read-from-minibuffer} and other
minibuffer input functions can no longer be a cons cell
@code{(@var{string} . @var{position})}.
@item
In the function @code{read-no-blanks-input}, the @var{initial} argument
is no longer optional.
@end itemize
@section New Features for Defining Commands
@itemize @bullet
@item
The special meaning of @samp{@@} in an interactive specification has
been eliminated.
@item
Emacs 18 does not support use of format-style @samp{%}-sequences in the
prompt strings in interactive specifications.
@item
The property @code{enable-recursive-minibuffers} no longer has any
special meaning.
@end itemize
@section Removed Features for Reading Input
@itemize @bullet
@item
We removed the third argument (@var{meta}) from the function
@code{set-input-mode}. Consequently, we added the variable
@code{meta-flag}; set it to @code{t} to enable use of a Meta key, and
to @code{nil} to disable it. (Those are the only two alternatives.)
@item
We also removed the variable @code{extra-keyboard-modifiers}.
@item
We removed the function @code{keyboard-translate} and the variables
@code{num-input-keys} and @code{function-key-map}.
@end itemize
@section Removed Syntax Table Features
@itemize @bullet
@item
We eliminated the functions @code{skip-syntax-forward},
@code{skip-syntax-backward}, @code{forward-comment}.
@item
We removed the syntax flag for ``prefix syntax'' and the flag for the
alternate comment style. Emacs 18 supports only one style of comment
in any given syntax table.
@item
We abolished the variable @code{words-include-escapes}.
@end itemize
@section The Case Table
@itemize @bullet
@item
Case tables do not exist in Emacs 18. Due to this change, we have
removed the associated functions @code{set-standard-case-table},
@code{standard-case-table}, @code{current-case-table},
@code{set-case-table}, and @code{set-case-syntax-pair}.
@end itemize
@section Features for Dealing with Buffers
@itemize @bullet
@item
We eliminated several functions for dealing with buffers:
@code{buffer-modified-tick} and @code{generate-new-buffer-name}.
@item
We renamed @code{buffer-disable-undo} to @code{buffer-flush-undo}---a
more picturesque name, you will agree.
@item
The function @code{other-buffer} takes just one argument in Emacs 18.
@item
The function @code{rename-buffer} now requires you to specify precisely
the new name you want.
@item
We removed the local variable @code{list-buffers-directory}.
@item
We got rid of the hook @code{kill-buffer-hook}.
@end itemize
@section Local Variables Features
@itemize @bullet
@item
The function @code{kill-all-local-variables} always eliminates all
buffer-local variables of the current buffer. No more exceptions.
@item
Making a variable buffer-local when it is void now sets it to
@code{nil}.
@item
We eliminated the functions @code{default-boundp}, because it is no
longer possible for the default binding of a variable to be void.
@item
The special forms @code{defconst} and @code{defvar} now set the
variable's local value rather than its default value when the variable
is local in the current buffer.
@end itemize
@section Features for Subprocesses
@itemize @bullet
@item
@code{call-process} and @code{call-process-region} no longer indicate
the termination status of the subprocess. We call on users to have faith
that the subprocess executed properly.
@item
The standard asynchronous subprocess features do not work on VMS;
instead, special VMS asynchronous subprocess functions have been added.
Since they are only for VMS, we can't be bothered documenting them;
sorry. Use the source, Luke!
@item
The function @code{signal-process} has been removed.
@item
We eliminated the transaction queue feature, and the associated
functions @code{tq-create}, @code{tq-enqueue}, and @code{tq-close}.
@end itemize
@section Dealing with Times And Time Delays
@itemize @bullet
@item
We removed the functions @code{current-time}, @code{current-time-zone},
@code{run-at-time}, and @code{cancel-timer}.
@item
The function @code{current-time-string} no longer accepts any optional
arguments.
@item
The functions @code{sit-for} and @code{sleep-for} no longer allow an
optional argument to let you specify the time period in milliseconds;
just in seconds. Additionally, we took out the optional third argument
@var{nodisp} from @code{sit-for}.
@item
We removed the optional second and third arguments from the
@code{accept-process-output} function. It accepts just one argument,
the process.
@end itemize
@need 3000
@section Features not Available for Lisp Debuggers
@itemize @bullet
@item
In Emacs 18, you can no longer specify to invoke the Lisp debugger only
upon encountering certain types of errors. Any non-@code{nil} value for
the variable @code{debug-on-error} says to invoke the debugger for any
error whatever.
@item
We removed the variable @code{command-debug-status} and the function
@code{backtrace-frame}.
@end itemize
@section Memory Allocation Changes
@itemize @bullet
@item
We removed the function @code{memory-limit}.
@item
The list returned by @code{garbage-collect} no longer contains an
element to describe floating point numbers, since there aren't any
floating point numbers in Emacs 18.
@end itemize
@section Hook Changes
@itemize @bullet
@item
We removed the hooks @code{pre-abbrev-expand-hook},
@code{pre-command-hook}, @code{post-command-hook}, and
@code{auto-save-hook}.
@item
We removed the variable
@code{revert-buffer-insert-file-contents-function}.
@item
We also removed the new function @code{add-hook}; you will have to set
your hooks by hand. If you want to get really into the swing of things,
set your hook variables the archaic way: store just one function rather
than a list of functions. But that is optional.
@item
The variable @code{lisp-indent-hook} has been renamed to
@code{lisp-indent-function}.
@item
The variable @code{auto-fill-function} has been renamed to
@code{auto-fill-hook}.
@item
The @code{blink-paren-function} has been renamed to
@code{blink-paren-hook}.
@item
The variable @code{temp-buffer-show-function} has been renamed to
@code{temp-buffer-show-hook}.
The function @code{convert-standard-filename} no longer exists, so each
Lisp package must independently figure out which file names to use for
its initialization files on each kind of operating system.
@item
The macro @code{with-timeout} has been eliminated, along with the
function @code{y-or-n-p-with-timeout}. Idle timers don't exist at all;
instead, maybe you can use @code{post-command-idle-hook} to do some of
the same job.
@item
The functions @code{keymap-parent} and @code{set-keymap-parent} are
gone. We expect keymaps to recognize their own parents.
@item
When you delete text and then undo a deletion, markers that were
originally inside the deleted text end up either at the beginning
or the end of it---not back in their original places.
@item
The interactive specification @samp{N} is gone now.
@item
There is no more @code{safe-length}. Don't try to be so safe! Did you
expect to live forever?
@item
We got rid of @code{insert-file-contents-literally}, because
programmers are too literal-minded anyway.
@item
As part of our continuing effort to help Lisp programmers to relax, we
threw out the function @code{error-message-string}. Don't worry so much
about errors! We all make mistakes.
@item
The keymap @code{special-event-map} is gone, because Emacs has no more
special events. If you want to hold a party in Emacs, please let us
know.
@item
You can't do date arithmentic with @code{encode-time} any more.
@item
The functions @code{command-execute} and @code{call-interactively} no
longer accept the optional argument @var{keys}.
@item
@code{get-buffer-window-list} is gone as well.
@item
With the function @code{replace-match}, you can only replace the whole
match, not a subexpression of it.
@item
We eliminated the hooks @code{buffer-access-fontify-functions},
@code{window-scroll-functions}, and @code{redisplay-end-trigger-functions}.
@end itemize

17
lispref/backups.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/backups
@node Backups and Auto-Saving, Buffers, Files, Top
@ -71,10 +71,9 @@ saved for the first time---provided that @code{backup-inhibited}
is @code{nil} (see below).
The following example shows how to change the @code{make-backup-files}
variable only in the @file{RMAIL} buffer and not elsewhere. Setting it
@code{nil} stops Emacs from making backups of the @file{RMAIL} file,
which may save disk space. (You would put this code in your
@file{.emacs} file.)
variable only in the Rmail buffers and not elsewhere. Setting it
@code{nil} stops Emacs from making backups of these files, which may
save disk space. (You would put this code in your @file{.emacs} file.)
@smallexample
@group
@ -135,8 +134,9 @@ in that directory.
@item
Emacs can copy the original file into a backup file, and then overwrite
the original file with new contents. After this procedure, any other
names (i.e., hard links) of the original file still refer to the current
version of the file. The file's owner and group will be unchanged.
names (i.e., hard links) of the original file continue to refer to the
current (updated) version of the file. The file's owner and group will
be unchanged.
@end itemize
The first method, renaming, is the default.
@ -226,7 +226,8 @@ backup version 3 is excess. The function @code{find-backup-file-name}
(@pxref{Backup Names}) is responsible for determining which backup
versions to delete, but does not delete them itself.
@defopt trim-versions-without-asking
@tindex delete-old-versions
@defopt delete-old-versions
If this variable is non-@code{nil}, then saving a file deletes excess
backup versions silently. Otherwise, it asks the user whether to delete
them.

135
lispref/buffers.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/buffers
@node Buffers, Windows, Backups and Auto-Saving, Top
@ -88,9 +88,9 @@ buffer in which most editing takes place, because most of the primitives
for examining or changing text in a buffer operate implicitly on the
current buffer (@pxref{Text}). Normally the buffer that is displayed on
the screen in the selected window is the current buffer, but this is not
always so: a Lisp program can designate any buffer as current
temporarily in order to operate on its contents, without changing what
is displayed on the screen.
always so: a Lisp program can temporarily designate any buffer as
current in order to operate on its contents, without changing what is
displayed on the screen.
The way to designate a current buffer in a Lisp program is by calling
@code{set-buffer}. The specified buffer remains current until a new one
@ -110,10 +110,11 @@ Editing commands written in Emacs Lisp can be called from other programs
as well as from the command loop. It is convenient for the caller if
the subroutine does not change which buffer is current (unless, of
course, that is the subroutine's purpose). Therefore, you should
normally use @code{set-buffer} within a @code{save-excursion} that will
restore the current buffer when your function is done
(@pxref{Excursions}). Here is an example, the code for the command
@code{append-to-buffer} (with the documentation string abridged):
normally use @code{set-buffer} within a @code{save-current-buffer} or
@code{save-excursion} (@pxref{Excursions}) form that will restore the
current buffer when your function is done . Here is an example, the
code for the command @code{append-to-buffer} (with the documentation
string abridged):
@example
@group
@ -122,7 +123,7 @@ restore the current buffer when your function is done
@dots{}"
(interactive "BAppend to buffer: \nr")
(let ((oldbuf (current-buffer)))
(save-excursion
(save-current-buffer
(set-buffer (get-buffer-create buffer))
(insert-buffer-substring oldbuf start end))))
@end group
@ -130,10 +131,10 @@ restore the current buffer when your function is done
@noindent
This function binds a local variable to the current buffer, and then
@code{save-excursion} records the values of point, the mark, and the
original buffer. Next, @code{set-buffer} makes another buffer current.
Finally, @code{insert-buffer-substring} copies the string from the
original current buffer to the new current buffer.
@code{save-current-buffer} records which buffer that was. Next,
@code{set-buffer} makes another buffer current. Finally,
@code{insert-buffer-substring} copies the string from the original
current buffer to the new current buffer.
If the buffer appended to happens to be displayed in some window,
the next redisplay will show how its text has changed. Otherwise, you
@ -147,9 +148,9 @@ same buffer is current at the beginning and at the end of the local
binding's scope. Otherwise you might bind it in one buffer and unbind
it in another! There are two ways to do this. In simple cases, you may
see that nothing ever changes the current buffer within the scope of the
binding. Otherwise, use @code{save-excursion} to make sure that the
buffer current at the beginning is current again whenever the variable
is unbound.
binding. Otherwise, use @code{save-current-buffer} or
@code{save-excursion} to make sure that the buffer current at the
beginning is current again whenever the variable is unbound.
It is not reliable to change the current buffer back with
@code{set-buffer}, because that won't do the job if a quit happens while
@ -166,13 +167,13 @@ the wrong buffer is current. Here is what @emph{not} to do:
@end example
@noindent
Using @code{save-excursion}, as shown below, handles quitting, errors,
and @code{throw}, as well as ordinary evaluation.
Using @code{save-current-buffer}, as shown here, handles quitting,
errors, and @code{throw}, as well as ordinary evaluation.
@example
@group
(let (buffer-read-only)
(save-excursion
(save-current-buffer
(set-buffer @dots{})
@dots{}))
@end group
@ -200,6 +201,47 @@ An error is signaled if @var{buffer-or-name} does not identify an
existing buffer.
@end defun
@tindex save-current-buffer
@defmac save-current-buffer body...
The @code{save-current-buffer} macro saves the identity of the current
buffer, evaluates the @var{body} forms, and finally restores the buffer.
The return value is the value of the last form in @var{body}. The
current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
If the buffer that used to be current has been killed by the time of
exit from @code{save-current-buffer}, then it is not made current again,
of course. Instead, whichever buffer was current just before exit
remains current.
@end defmac
@tindex with-current-buffer
@defmac with-current-buffer buffer body...
The @code{with-current-buffer} macro saves the identity of the current
buffer, makes @var{buffer} current, evaluates the @var{body} forms, and
finally restores the buffer. The return value is the value of the last
form in @var{body}. The current buffer is restored even in case of an
abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac
@tindex with-temp-buffer
@defmac with-temp-buffer body...
The @code{with-temp-buffer} macro evaluates the @var{body} forms
with a temporary buffer as the current buffer. It saves the identity of
the current buffer, creates a temporary buffer and makes it current,
evaluates the @var{body} forms, and finally restores the previous
current buffer while killing the temporary buffer.
The return value is the value of the last form in @var{body}. You can
return the contents of the temporary buffer by using
@code{(buffer-string)} as the last form.
The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac
See also @code{with-temp-file} in @ref{Writing to Files}.
@node Buffer Names
@section Buffer Names
@cindex buffer names
@ -407,9 +449,9 @@ See also @code{clear-visited-file-modtime} and
@end deffn
@defvar list-buffers-directory
This buffer-local variable records a string to display in a buffer
listing in place of the visited file name, for buffers that don't have a
visited file name. Dired buffers use this variable.
This buffer-local variable specifies a string to display in a buffer
listing where the visited file name would go, for buffers that don't
have a visited file name. Dired buffers use this variable.
@end defvar
@node Buffer Modification
@ -567,7 +609,7 @@ narrowing.
@item
A buffer visiting a write-protected file is normally read-only.
Here, the purpose is to show the user that editing the buffer with the
Here, the purpose is to inform the user that editing the buffer with the
aim of saving it in the file may be futile or undesirable. The user who
wants to change the buffer text despite this can do so after clearing
the read-only flag with @kbd{C-x C-q}.
@ -578,7 +620,7 @@ contents with the usual editing commands is probably a mistake.
The special commands of these modes bind @code{buffer-read-only} to
@code{nil} (with @code{let}) or bind @code{inhibit-read-only} to
@code{t} around the places where they change the text.
@code{t} around the places where they themselves change the text.
@end itemize
@defvar buffer-read-only
@ -619,17 +661,28 @@ signal an error if the current buffer is read-only.
@cindex buffer list
The @dfn{buffer list} is a list of all live buffers. Creating a
buffer adds it to this list, and killing a buffer deletes it. The order
buffer adds it to this list, and killing a buffer excises it. The order
of the buffers in the list is based primarily on how recently each
buffer has been displayed in the selected window. Buffers move to the
front of the list when they are selected and to the end when they are
buried. Several functions, notably @code{other-buffer}, use this
ordering. A buffer list displayed for the user also follows this order.
buried (see @code{bury-buffer}, below). Several functions, notably
@code{other-buffer}, use this ordering. A buffer list displayed for the
user also follows this order.
@defun buffer-list
@defun buffer-list &optional frame
This function returns a list of all buffers, including those whose names
begin with a space. The elements are actual buffers, not their names.
If @var{frame} is @code{nil}, all the buffers appear in order of most
recent selection, regardless of which frames they were selected in.
If @var{frame} is a frame, then the buffers that have been selected in
@var{frame} all come at the front of the list, ordered by most recent
selection in @var{frame}. (This order is recorded in @var{frame}'s
@code{buffer-list} frame parameter; see @ref{X Frame Parameters}.) The
buffers that were never selected in @var{frame} come afterward, ordered
according to most recent selection in other frames.
@example
@group
(buffer-list)
@ -651,7 +704,8 @@ begin with a space. The elements are actual buffers, not their names.
The list that @code{buffer-list} returns is constructed specifically
by @code{buffer-list}; it is not an internal Emacs data structure, and
modifying it has no effect on the order of buffers. If you want to
change the order of buffers in the list, here is an easy way:
change the order of buffers in the frame-independent buffer list, here
is an easy way:
@example
(defun reorder-buffer-list (new-list)
@ -664,15 +718,19 @@ change the order of buffers in the list, here is an easy way:
no danger of losing a buffer or adding something that is not a valid
live buffer.
To change the order or value of a frame's buffer list, set the frame's
@code{buffer-list} frame parameter with @code{modify-frame-parameters}
(@pxref{Parameter Access}).
@defun other-buffer &optional buffer visible-ok
This function returns the first buffer in the buffer list other than
@var{buffer}. Usually this is the buffer most recently shown in
the selected window, aside from @var{buffer}. Buffers whose
names start with a space are not considered.
@var{buffer}. Usually this is the buffer selected most recently (in the
currently selected frame), aside from @var{buffer}. Buffers whose names
start with a space are not considered at all.
If @var{buffer} is not supplied (or if it is not a buffer), then
@code{other-buffer} returns the first buffer on the buffer list that is
not visible in any window in a visible frame.
@code{other-buffer} returns the first buffer in the selected frame's
buffer list that is not now visible in any window in a visible frame.
If the selected frame has a non-@code{nil} @code{buffer-predicate}
parameter, then @code{other-buffer} uses that predicate to decide which
@ -691,18 +749,23 @@ If no suitable buffer exists, the buffer @samp{*scratch*} is returned
@end defun
@deffn Command bury-buffer &optional buffer-or-name
This function puts @var{buffer-or-name} at the end of the buffer list
This function puts @var{buffer-or-name} at the end of the buffer list,
without changing the order of any of the other buffers on the list.
This buffer therefore becomes the least desirable candidate for
@code{other-buffer} to return.
@code{bury-buffer} operates on each frame's @code{buffer-list} parameter
as well as the frame-independent Emacs buffer list; therefore, the
buffer that you bury will come last in the value of @code{(buffer-list
@var{frame})} and in the value of @code{(buffer-list nil)}.
If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the
current buffer. In addition, if the buffer is displayed in the selected
window, this switches to some other buffer (obtained using
@code{other-buffer}) in the selected window. But if the buffer is
displayed in some other window, it remains displayed there.
If you wish to replace a buffer in all the windows that display it, use
To replace a buffer in all the windows that display it, use
@code{replace-buffer-in-windows}. @xref{Buffers and Windows}.
@end deffn

6
lispref/calendar.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@node Calendar, Tips, Display, Top
@chapter Customizing the Calendar and Diary
@ -770,7 +770,7 @@ can use
@findex diary-remind
@smallexample
%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ruth & Ed's anniversary
%%(diary-remind '(diary-anniversary 12 22 1968) 7) Ed's anniversary
@end smallexample
@noindent
@ -811,7 +811,7 @@ so on. If @var{n} is negative it counts backward from the end of
@var{month}. The value of @var{month} can be a list of months, a single
month, or @code{t} to specify all months. You can also use an optional
parameter @var{day} to specify the @var{n}th @var{dayname} of
@var{month} on or after/before @var{day}; the value of @{day} defaults
@var{month} on or after/before @var{day}; the value of @var{day} defaults
to 1 if @var{n} is positive and to the last day of @var{month} if
@var{n} is negative. For example,

196
lispref/commands.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/commands
@node Command Loop, Keymaps, Minibuffers, Top
@ -20,6 +20,7 @@ are done, and the subroutines that allow Lisp programs to do them.
* Command Loop Info:: Variables set by the command loop for you to examine.
* 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.
* Waiting:: Waiting for user input or elapsed time.
* Quitting:: How @kbd{C-g} works. How to catch or defer quitting.
* Prefix Command Arguments:: How the commands to set prefix args work.
@ -84,8 +85,8 @@ and also when the command loop is first entered. At that time,
Quitting is suppressed while running @code{pre-command-hook} and
@code{post-command-hook}. If an error happens while executing one of
these hooks, it terminates execution of the hook, but that is all it
does.
these hooks, it terminates execution of the hook, and clears the hook
variable to @code{nil} so as to prevent an infinite loop of errors.
@node Defining Commands
@section Defining Commands
@ -350,6 +351,11 @@ convert an undefined key into a defined one.
@cindex marker argument
The position of the mark, as an integer. No I/O.
@item M
Arbitrary text, read in the minibuffer using the current buffer's input
method, and returned as a string (@pxref{Input Methods,,, emacs, The GNU
Emacs Manual}). Prompt.
@item n
A number read with the minibuffer. If the input is not a number, the
user is asked to try again. The prefix argument, if any, is not used.
@ -459,12 +465,11 @@ Put them into three windows, selecting the last one."
@section Interactive Call
@cindex interactive call
After the command loop has translated a key sequence into a
definition, it invokes that definition using the function
@code{command-execute}. If the definition is a function that is a
command, @code{command-execute} calls @code{call-interactively}, which
reads the arguments and calls the command. You can also call these
functions yourself.
After the command loop has translated a key sequence into a command it
invokes that command using the function @code{command-execute}. If the
command is a function, @code{command-execute} calls
@code{call-interactively}, which reads the arguments and calls the
command. You can also call these functions yourself.
@defun commandp object
Returns @code{t} if @var{object} is suitable for calling interactively;
@ -487,7 +492,7 @@ See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example of using @code{commandp}.
@end defun
@defun call-interactively command &optional record-flag
@defun call-interactively command &optional record-flag keys
This function calls the interactively callable function @var{command},
reading arguments according to its interactive calling specifications.
An error is signaled if @var{command} is not a function or if it cannot
@ -500,13 +505,16 @@ If @var{record-flag} is non-@code{nil}, then this command and its
arguments are unconditionally added to the list @code{command-history}.
Otherwise, the command is added only if it uses the minibuffer to read
an argument. @xref{Command History}.
The argument @var{keys}, if given, specifies the sequence of events to
use if the command inquires which events were used to invoke it.
@end defun
@defun command-execute command &optional record-flag
@defun command-execute command &optional record-flag keys
@cindex keyboard macro execution
This function executes @var{command} as an editing command. The
argument @var{command} must satisfy the @code{commandp} predicate; i.e.,
it must be an interactively callable function or a keyboard macro.
This function executes @var{command}. The argument @var{command} must
satisfy the @code{commandp} predicate; i.e., it must be an interactively
callable function or a keyboard macro.
A string or vector as @var{command} is executed with
@code{execute-kbd-macro}. A function is passed to
@ -517,6 +525,9 @@ symbol with an @code{autoload} definition counts as a command if it was
declared to stand for an interactively callable function. Such a
definition is handled by loading the specified library and then
rechecking the definition of the symbol.
The argument @var{keys}, if given, specifies the sequence of events to
use if the command inquires which events were used to invoke it.
@end defun
@deffn Command execute-extended-command prefix-argument
@ -615,8 +626,8 @@ command loop (the one before the current command). Normally the value
is a symbol with a function definition, but this is not guaranteed.
The value is copied from @code{this-command} when a command returns to
the command loop, except when the command specifies a prefix argument
for the following command.
the command loop, except when the command has specified a prefix
argument for the following command.
This variable is always local to the current terminal and cannot be
buffer-local. @xref{Multiple Displays}.
@ -630,7 +641,7 @@ with a function definition.
The command loop sets this variable just before running a command, and
copies its value into @code{last-command} when the command finishes
(unless the command specifies a prefix argument for the following
(unless the command specified a prefix argument for the following
command).
@cindex kill command repetition
@ -656,6 +667,11 @@ value at the end, like this:
(setq this-command old-this-command)))
@end example
@noindent
We do not bind @code{this-command} with @code{let} because that would
restore the old value in case of error---a feature of @code{let} which
in this case does precisely what we want to avoid.
@defun this-command-keys
This function returns a string or vector containing the key sequence
that invoked the present command, plus any previous commands that
@ -675,8 +691,8 @@ if all those events were characters. @xref{Input Events}.
This variable holds the last input event read as part of a key
sequence, not counting events resulting from mouse menus.
One use of this variable is to figure out a good default location to
pop up another menu.
One use of this variable is for telling @code{x-popup-menu} where to pop
up a menu.
@end defvar
@defvar last-command-event
@ -722,6 +738,7 @@ describes the representation and meaning of input events in detail.
@defun eventp object
This function returns non-@code{nil} if @var{object} is an input event.
A symbol
@end defun
@menu
@ -756,7 +773,7 @@ see @ref{Classifying Events}.
@cindex modifier bits (of input character)
@cindex basic code (of input character)
An input character event consists of a @dfn{basic code} between 0 and
255, plus any or all of these @dfn{modifier bits}:
524287, plus any or all of these @dfn{modifier bits}:
@table @asis
@item meta
@ -808,11 +825,10 @@ $2^{25}$
bit in the character code indicates an @sc{ASCII} control
character typed with the shift key held down.
For letters, the basic code indicates upper versus lower case; for
digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within
the @sc{ASCII} character set whenever possible, Emacs avoids using
the
For letters, the basic code itself indicates upper versus lower case;
for digits and punctuation, the shift key selects an entirely different
character with a different basic code. In order to keep within the
@sc{ASCII} character set whenever possible, Emacs avoids using the
@iftex
$2^{25}$
@end iftex
@ -882,8 +898,8 @@ specify the characters (@pxref{Changing Key Bindings}). The function
@cindex function keys
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
symbols that are not characters. Function keys are represented in Emacs
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
@code{f1} in the input stream.
@ -923,8 +939,8 @@ Keypad keys with digits.
@item @code{kp-f1}, @code{kp-f2}, @code{kp-f3}, @code{kp-f4}
Keypad PF 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{}
Keypad arrow keys. Emacs normally translates these into the
corresponding 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.
@ -1070,11 +1086,13 @@ position and the final position, like this:
@end example
For a drag event, the name of the symbol @var{event-type} contains the
prefix @samp{drag-}. The second and third elements of the event give
the starting and ending position of the drag. Aside from that, the data
have the same meanings as in a click event (@pxref{Click Events}). You
can access the second element of any mouse event in the same way, with
no need to distinguish drag events from others.
prefix @samp{drag-}. For example, dragging the mouse with button 2 held
down generates a @code{drag-mouse-2} event. The second and third
elements of the event give the starting and ending position of the drag.
Aside from that, the data have the same meanings as in a click event
(@pxref{Click Events}). You can access the second element of any mouse
event in the same way, with no need to distinguish drag events from
others.
The @samp{drag-} prefix follows the modifier key prefixes such as
@samp{C-} and @samp{M-}.
@ -1585,8 +1603,8 @@ Other keyboard character events cannot fit in a string. This includes
keyboard events in the range of 128 to 255.
@end itemize
Functions such as @code{read-key-sequence} that can construct strings
of keyboard input characters follow these rules. They construct vectors
Functions such as @code{read-key-sequence} that construct strings of
keyboard input characters follow these rules: they construct vectors
instead of strings, when the events won't fit in a string.
When you use the read syntax @samp{\M-} in a string, it produces a
@ -1643,7 +1661,7 @@ for example, @code{describe-key} uses it to read the key to describe.
@defun read-key-sequence prompt
@cindex key sequence
This function reads a key sequence and returns it as a string or
vector. It keeps reading events until it has accumulated a full key
vector. It keeps reading events until it has accumulated a complete key
sequence; that is, enough to specify a non-prefix command using the
currently active keymaps.
@ -1676,13 +1694,6 @@ and the user types @kbd{C-x C-f}.
@end example
@end defun
@defvar num-input-keys
@c Emacs 19 feature
This variable's value is the number of key sequences processed so far in
this Emacs session. This includes key sequences read from the terminal
and key sequences read from keyboard macros being executed.
@end defvar
@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,
@ -1699,15 +1710,14 @@ with any other events.
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
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},
``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.
@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:
@ -1720,6 +1730,19 @@ mouse on the window's mode line, you get two events, like this:
(40 . 63) 5959987))]
@end example
@defvar num-input-keys
@c Emacs 19 feature
This variable's value is the number of key sequences processed so far in
this Emacs session. This includes key sequences read from the terminal
and key sequences read from keyboard macros being executed.
@end defvar
@tindex num-nonmacro-input-events
@defvar num-nonmacro-input-events
This variable holds the total number of input events received so far
from the terminal---not counting those generated by keyboard macros.
@end defvar
@node Reading One Event
@subsection Reading One Event
@ -1838,7 +1861,7 @@ This variable holds a list of events waiting to be read as command
input. The events are used in the order they appear in the list, and
removed one by one as they are used.
The variable is needed because in some cases a function reads a event
The variable is needed because in some cases a function reads an event
and then decides not to use it. Storing the event in this variable
causes it to be processed normally, by the command loop or by the
functions to read command input.
@ -1854,6 +1877,9 @@ and then execute normally.
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}).
Normally you add events to the front of this list, so that the events
most recently unread will be reread first.
@end defvar
@defvar unread-command-char
@ -1918,6 +1944,31 @@ during the sleep.
@end example
@end defun
@node Special Events
@section Special Events
@cindex special events
Special events are handled at a very low level---as soon as they are
read. The @code{read-event} function processes these events itself, and
never returns them.
Events that are handled in this way do not echo, they are never grouped
into key sequences, and they never appear in the value of
@code{last-command-event} or @code{(this-command-keys)}. They do not
discard a numeric argument, they cannot be unread with
@code{unread-command-events}, they may not appear in a keyboard macro,
and they are not recorded in a keyboard macro while you are defining
one.
These events do, however, appear in @code{last-input-event} immediately
after they are read, and this is the way for the event's definition to
find the actual event.
The events types @code{iconify-frame}, @code{make-frame-visible} and
@code{delete-frame} are normally handled in this way. The keymap which
defines how to handle special events---and which events are special---is
in the variable @code{special-event-map} (@pxref{Active Keymaps}).
@node Waiting
@section Waiting for Elapsed Time or Input
@cindex pausing
@ -2193,13 +2244,13 @@ accessing it is with @code{(interactive "P")}.
@defvar prefix-arg
The value of this variable is the raw prefix argument for the
@emph{next} editing command. Commands that specify prefix arguments for
the following command work by setting this variable.
@emph{next} editing command. Commands such as @code{universal-argument}
that specify prefix arguments for the following command work by setting
this variable.
@end defvar
Do not call @code{universal-argument}, @code{digit-argument}, or
@code{negative-argument} unless you intend to let the user enter the
prefix argument for the @emph{next} command.
The following commands exist to set up prefix arguments for the
following command. Do not call them for any other reason.
@deffn Command universal-argument
This command reads input and specifies a prefix argument for the
@ -2384,8 +2435,8 @@ 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
When the user invokes a disabled command interactively, this normal hook
is run instead of the disabled command. 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. @xref{Hooks}.
@ -2434,8 +2485,7 @@ expressions rather than strings.
previous commands. The commands @code{repeat-complex-command}, and
@code{list-command-history} are described in the user manual
(@pxref{Repetition,,, emacs, The GNU Emacs Manual}). Within the
minibuffer, the history commands used are the same ones available in any
minibuffer.
minibuffer, the usual minibuffer history commands are available.
@node Keyboard Macros
@section Keyboard Macros
@ -2447,36 +2497,38 @@ representation of a keyboard macro is a string or vector containing the
events. Don't confuse keyboard macros with Lisp macros
(@pxref{Macros}).
@defun execute-kbd-macro macro &optional count
This function executes @var{macro} as a sequence of events. If
@var{macro} is a string or vector, then the events in it are executed
@defun execute-kbd-macro kbdmacro &optional count
This function executes @var{kbdmacro} as a sequence of events. If
@var{kbdmacro} is a string or vector, then the events in it are executed
exactly as if they had been input by the user. The sequence is
@emph{not} expected to be a single key sequence; normally a keyboard
macro definition consists of several key sequences concatenated.
If @var{macro} is a symbol, then its function definition is used in
place of @var{macro}. If that is another symbol, this process repeats.
If @var{kbdmacro} is a symbol, then its function definition is used in
place of @var{kbdmacro}. If that is another symbol, this process repeats.
Eventually the result should be a string or vector. If the result is
not a symbol, string, or vector, an error is signaled.
The argument @var{count} is a repeat count; @var{macro} is executed that
many times. If @var{count} is omitted or @code{nil}, @var{macro} is
executed once. If it is 0, @var{macro} is executed over and over until it
The argument @var{count} is a repeat count; @var{kbdmacro} is executed that
many times. If @var{count} is omitted or @code{nil}, @var{kbdmacro} is
executed once. If it is 0, @var{kbdmacro} is executed over and over until it
encounters an error or a failing search.
@xref{Reading One Event}, for an example of using @code{execute-kbd-macro}.
@end defun
@defvar executing-macro
This variable contains the string or vector that defines the keyboard
macro that is currently executing. It is @code{nil} if no macro is
currently executing. A command can test this variable to behave
currently executing. A command can test this variable so as to behave
differently when run from an executing macro. Do not set this variable
yourself.
@end defvar
@defvar defining-kbd-macro
This variable indicates whether a keyboard macro is being defined. A
command can test this variable to behave differently while a macro is
being defined. The commands @code{start-kbd-macro} and
command can test this variable so as to behave differently while a macro
is being defined. The commands @code{start-kbd-macro} and
@code{end-kbd-macro} set this variable---do not set it yourself.
The variable is always local to the current terminal and cannot be

13
lispref/compile.texi
View file

@ -212,8 +212,9 @@ The returned value of this command is unpredictable.
This function runs @code{byte-compile-file} on files specified on the
command line. This function must be used only in a batch execution of
Emacs, as it kills Emacs on completion. An error in one file does not
prevent processing of subsequent files. (The file that gets the error
will not, of course, produce any compiled code.)
prevent processing of subsequent files, but no output file will be
generated for it, and the Emacs process will terminate with a nonzero
status code.
@example
% emacs -batch -f batch-byte-compile *.el
@ -368,11 +369,11 @@ this way.
@end defspec
@defspec eval-when-compile body
This form marks @var{body} to be evaluated at compile time and not when
This form marks @var{body} to be evaluated at compile time but not when
the compiled program is loaded. The result of evaluation by the
compiler becomes a constant which appears in the compiled program. When
the program is interpreted, not compiled at all, @var{body} is evaluated
normally.
compiler becomes a constant which appears in the compiled program. If
you load the source file, rather than compiling it, @var{body} is
evaluated normally.
At top level, this is analogous to the Common Lisp idiom
@code{(eval-when (compile eval) @dots{})}. Elsewhere, the Common Lisp

71
lispref/control.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/control
@node Control Structures, Variables, Evaluation, Top
@ -35,7 +35,7 @@ structure constructs (@pxref{Macros}).
@menu
* Sequencing:: Evaluation in textual order.
* Conditionals:: @code{if}, @code{cond}.
* Conditionals:: @code{if}, @code{cond}, @code{when}, @code{unless}.
* Combining Conditions:: @code{and}, @code{or}, @code{not}.
* Iteration:: @code{while} loops.
* Nonlocal Exits:: Jumping out of a sequence.
@ -172,7 +172,8 @@ never evaluated---it is ignored. Thus, in the example below,
@end example
@end defspec
@defspec when condition then-forms@dots{}
@tindex when
@defmac when condition then-forms@dots{}
This is a variant of @code{if} where there are no @var{else-forms},
and possibly several @var{then-forms}. In particular,
@ -186,9 +187,10 @@ is entirely equivalent to
@example
(if @var{condition} (progn @var{a} @var{b} @var{c}) nil)
@end example
@end defspec
@end defmac
@defspec unless condition forms@dots{}
@tindex condition
@defmac unless condition forms@dots{}
This is a variant of @code{if} where there is no @var{then-form}:
@example
@ -202,7 +204,7 @@ is entirely equivalent to
(if @var{condition} nil
@var{a} @var{b} @var{c})
@end example
@end defspec
@end defmac
@defspec cond clause@dots{}
@code{cond} chooses among an arbitrary number of alternatives. Each
@ -271,7 +273,7 @@ For example,
@noindent
This expression is a @code{cond} which returns @code{foo} if the value
of @code{a} is 1, and returns the string @code{"default"} otherwise.
of @code{a} is @code{hack}, and returns the string @code{"default"} otherwise.
@end defspec
Any conditional construct can be expressed with @code{cond} or with
@ -491,26 +493,32 @@ that @code{catch}. For example:
@example
@group
(catch 'foo
(progn
@dots{}
(throw 'foo t)
@dots{}))
(defun foo-outer ()
(catch 'foo
(foo-inner)))
(defun foo-inner ()
@dots{}
(if x
(throw 'foo t))
@dots{})
@end group
@end example
@noindent
The @code{throw} transfers control straight back to the corresponding
@code{catch}, which returns immediately. The code following the
@code{throw} is not executed. The second argument of @code{throw} is used
as the return value of the @code{catch}.
The @code{throw} form, if executed, transfers control straight back to
the corresponding @code{catch}, which returns immediately. The code
following the @code{throw} is not executed. The second argument of
@code{throw} is used as the return value of the @code{catch}.
The @code{throw} and the @code{catch} are matched through the first
argument: @code{throw} searches for a @code{catch} whose first argument
is @code{eq} to the one specified. Thus, in the above example, the
@code{throw} specifies @code{foo}, and the @code{catch} specifies the
same symbol, so that @code{catch} is applicable. If there is more than
one applicable @code{catch}, the innermost one takes precedence.
The function @code{throw} finds the matching @code{catch} based on the
first argument: it searches for a @code{catch} whose first argument is
@code{eq} to the one specified in the @code{throw}. If there is more
than one applicable @code{catch}, the innermost one takes precedence.
Thus, in the above example, the @code{throw} specifies @code{foo}, and
the @code{catch} in @code{foo-outer} specifies the same symbol, so that
@code{catch} is the applicable one (assuming there is no other matching
@code{catch} in between).
Executing @code{throw} exits all Lisp constructs up to the matching
@code{catch}, including function calls. When binding constructs such as
@ -726,10 +734,10 @@ These examples show typical uses of @code{error}:
error symbol @code{error}, and a list containing the string returned by
@code{format}.
If you want to use your own string as an error message verbatim, don't
just write @code{(error @var{string})}. If @var{string} contains
@samp{%}, it will be interpreted as a format specifier, with undesirable
results. Instead, use @code{(error "%s" @var{string})}.
@strong{Warning:} If you want to use your own string as an error message
verbatim, don't just write @code{(error @var{string})}. If @var{string}
contains @samp{%}, it will be interpreted as a format specifier, with
undesirable results. Instead, use @code{(error "%s" @var{string})}.
@end defun
@defun signal error-symbol data
@ -848,6 +856,13 @@ starting with the most recently established one. Thus, if two nested
@code{condition-case} forms offer to handle the same error, the inner of
the two will actually handle it.
If an error is handled by some @code{condition-case} form, this
ordinarily prevents the debugger from being run, even if
@code{debug-on-error} says this error should invoke the debugger.
@xref{Error Debugging}. If you want to be able to debug errors that are
caught by a @code{condition-case}, set the variable
@code{debug-on-signal} to a non-@code{nil} value.
When an error is handled, control returns to the handler. Before this
happens, Emacs unbinds all variable bindings made by binding constructs
that are being exited and executes the cleanups of all
@ -964,7 +979,7 @@ The handler specifies condition name @code{arith-error} so that it will handle o
@smallexample
@group
(safe-divide nil 3)
@error{} Wrong type argument: integer-or-marker-p, nil
@error{} Wrong type argument: number-or-marker-p, nil
@end group
@end smallexample
@ -1094,7 +1109,7 @@ and their conditions.
The @code{unwind-protect} construct is essential whenever you
temporarily put a data structure in an inconsistent state; it permits
you to ensure the data are consistent in the event of an error or throw.
you to make the data consistent again in the event of an error or throw.
@defspec unwind-protect body cleanup-forms@dots{}
@cindex cleanup forms

29
lispref/debugging.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/debugging
@node Debugging, Read and Print, Byte Compilation, Top
@ -105,6 +105,28 @@ that error does not enter the debugger, regardless of the value of
The normal value of this variable lists several errors that happen often
during editing but rarely result from bugs in Lisp programs.
@end defopt
@defopt debug-on-signal
Normally, errors that are caught by @code{condition-case} never run the
debugger, even if @code{debug-on-error} is non-@code{nil}. In other
words, @code{condition-case} gets a chance to catch the error before the
debugger gets a chance.
If you set @code{debug-on-signal} non-@code{nil}, then the debugger gets
first chance at every error; an error will invoke the debugger
regardless of any @code{condition-case}, if the fits the criterion
specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medecine! Various parts of
Emacs handle errors in the normal course of affairs, and you may not
even realize that errors happen there. If you set
@code{debug-on-signal} to a non-@code{nil} value, those errors will
enter the debugger.
@strong{Warning:} @code{debug-on-signal} has no effect when
@code{debug-on-error} is @code{nil}.
@end defopt
To debug an error that happens during loading of the @file{.emacs}
@ -580,7 +602,8 @@ This function is used only by the debugger.
This variable records the debugging status of the current interactive
command. Each time a command is called interactively, this variable is
bound to @code{nil}. The debugger can set this variable to leave
information for future debugger invocations during the same command.
information for future debugger invocations during the same command
invocation.
The advantage, for the debugger, of using this variable rather than
another global variable is that the data will never carry over to a
@ -645,7 +668,7 @@ C-@key{SPC}} to set the mark there, undo the insertion of the
close parenthesis, and finally return to the mark.)
The next step is to determine precisely what is wrong. There is no
way to be sure of this except to study the program, but often the
way to be sure of this except by studying the program, but often the
existing indentation is a clue to where the parentheses should have
been. The easiest way to use this clue is to reindent with @kbd{C-M-q}
and see what moves.

368
lispref/display.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/display
@node Display, Calendar, System Interface, Top
@ -19,6 +19,7 @@ that Emacs presents to the user.
* Overlay Arrow:: Display of an arrow to indicate position.
* Temporary Displays:: Displays that go away automatically.
* Overlays:: Use overlays to highlight parts of the buffer.
* Width:: How wide is a character or string.
* Faces:: A face defines a graphics appearance: font, color, etc.
* Blinking:: How Emacs shows the matching open parenthesis.
* Inverse Video:: Specifying how the screen looks.
@ -60,8 +61,8 @@ resumption.
@cindex suspend (cf. @code{no-redraw-on-reenter})
@cindex resume (cf. @code{no-redraw-on-reenter})
This variable controls whether Emacs redraws the entire screen after it
has been suspended and resumed. Non-@code{nil} means yes, @code{nil}
means no.
has been suspended and resumed. Non-@code{nil} means there is no need
to redraw, @code{nil} means redrawing is needed.
@end defvar
@node Screen Size
@ -166,8 +167,8 @@ If it is non-@code{nil}, these lines are truncated; otherwise,
@code{truncate-lines} says what to do with them.
@end defopt
You can override the images that indicate continuation or truncation
with the display table; see @ref{Display Tables}.
You can override the glyphs that indicate continuation or truncation
using the display table; see @ref{Display Tables}.
If your buffer contains @strong{very} long lines, and you use
continuation to display them, just thinking about them can make Emacs
@ -235,6 +236,18 @@ Minibuffer depth is 0.
@end example
@end defun
@tindex current-message
@defun current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
@tindex echo-area-clear-hook
@defvar echo-area-clear-hook
This normal hook is run whenever the echo area is cleared---either by
@code{(message nil)} or for any other reason.
@end defvar
Almost all the messages displayed in the echo area are also recorded
in the @samp{*Messages*} buffer.
@ -327,6 +340,40 @@ by a visible newline, it displays an ellipsis.
@end table
@end defvar
Two functions are specifically provided for adding elements to
@code{buffer-invisibility-spec} and removing elements from it.
@tindex add-to-invisibility-spec
@defun add-to-invisibility-spec element
Add the element @var{element} to @code{buffer-invisibility-spec}
(if it is not already present in that list).
@end defun
@tindex remove-from-invisibility-spec
@defun remove-from-invisibility-spec element
Remove the element @var{element} from @code{buffer-invisibility-spec}.
@end defun
One convention about the use of @code{buffer-invisibility-spec} is
that a major mode should use the mode's own name as an element of
@code{buffer-invisibility-spec} and as the value of the @code{invisible}
property:
@example
;; If we want to display an ellipsis:
(add-to-invisibility-spec '(my-symbol . t))
;; If you don't want ellipsis:
(add-to-invisibility-spec 'my-symbol)
(overlay-put (make-overlay beginning end)
'invisible 'my-symbol)
;; When done with the overlays:
(remove-from-invisibility-spec '(my-symbol . t))
;; Or respectively:
(remove-from-invisibility-spec 'my-symbol)
@end example
@vindex line-move-ignore-invisible
Ordinarily, commands that operate on text or move point do not care
whether the text is invisible. The user-level line motion commands
@ -334,6 +381,22 @@ explicitly ignore invisible newlines if
@code{line-move-ignore-invisible} is non-@code{nil}, but only because
they are explicitly programmed to do so.
Incremental search can make invisible overlays visible temporarily
and/or permanently when a match includes invisible text. To enable
this, the overlay should have a non-@code{nil}
@code{isearch-open-invisible} property. The property value should be a
function to be called with the overlay as an argument. This function
should make the overlay visible permanently; it is used when the match
overlaps the overlay on exit from the search.
During the search, such overlays are made temporarily visible by
temporarily modifying their invisible and intangible properties. If you
want this to be done differently for a certain overlays, give it a
@code{isearch-open-invisible-temporary} property which is a function.
The function is called with two arguments: the first is the overlay, and
the second is @code{nil} to make the overlay visible or @code{t} to make
it invisible again.
@node Selective Display
@section Selective Display
@cindex selective display
@ -652,16 +715,20 @@ of the symbol serve as defaults for the properties of the overlay.
@item face
@kindex face @r{(overlay property)}
This property controls the font and color of text. Its value is a face
name or a list of face names. @xref{Faces}, for more information. This
feature may be temporary; in the future, we may replace it with other
ways of specifying how to display text.
This property controls the way text is displayed---for example, which
font and which colors. Its value is a face name or a list of face
names. @xref{Faces}, for more information.
If the property value is a list, elements may also have the form
@code{(foreground-color . @var{color-name})} or @code{(background-color
. @var{color-name})}. These elements specify just the foreground color
or just the background color; therefore, there is no need to create a
face for each color that you want to use.
@item mouse-face
@kindex mouse-face @r{(overlay property)}
This property is used instead of @code{face} when the mouse is within
the range of the overlay. This feature may be temporary, like
@code{face}.
the range of the overlay.
@item modification-hooks
@kindex modification-hooks @r{(overlay property)}
@ -703,12 +770,16 @@ The @code{invisible} property can make the text in the overlay
invisible, which means that it does not appear on the screen.
@xref{Invisible Text}, for details.
@ignore This isn't implemented yet
@item intangible
@kindex intangible @r{(overlay property)}
The @code{intangible} property on an overlay works just like the
@code{intangible} text property. @xref{Special Properties}, for details.
@end ignore
@item isearch-open-invisible
@itemx isearch-open-invisible-temporary
These properties control how incremental search should make invisible an
overlay visible, either permanently or temporarily. @xref{Invisible
Text}.
@item before-string
@kindex before-string @r{(overlay property)}
@ -765,20 +836,26 @@ overlay properties and text properties for a given character.
This section describes the functions to create, delete and move
overlays, and to examine their contents.
@defun make-overlay start end &optional buffer
@defun make-overlay start end &optional buffer front-advance rear-advance
This function creates and returns an overlay that belongs to
@var{buffer} and ranges from @var{start} to @var{end}. Both @var{start}
and @var{end} must specify buffer positions; they may be integers or
markers. If @var{buffer} is omitted, the overlay is created in the
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}.
@end defun
@defun overlay-start overlay
This function returns the position at which @var{overlay} starts.
This function returns the position at which @var{overlay} starts,
as an integer.
@end defun
@defun overlay-end overlay
This function returns the position at which @var{overlay} ends.
This function returns the position at which @var{overlay} ends,
as an integer.
@end defun
@defun overlay-buffer overlay
@ -812,6 +889,15 @@ An overlay contains position @var{pos} if it begins at or before
@var{pos}, and ends after @var{pos}.
@end defun
@tindex overlays-in
@defun overlays-in beg end
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}.
@end defun
@defun next-overlay-change pos
This function returns the buffer position of the next beginning or end
of an overlay, after @var{pos}.
@ -822,12 +908,65 @@ This function returns the buffer position of the previous beginning or
end of an overlay, before @var{pos}.
@end defun
@node Width
@section Width
Since not all characters have the same width, these functions let you
check the width of a character. @ref{Primitive Indent}
@xref{Screen Lines}, for related
functions.
@tindex char-width
@defun char-width char
This function returns the width in columns of the character @var{char},
if it were displayed in the current buffer and the selected window.
@end defun
@tindex string-width
@defun string-width string
This function returns the width in columns of the string @var{string},
if it were displayed in the current buffer and the selected window.
@end defun
@tindex truncate-string-to-width
@defun truncate-string-to-width string width &optional start-column padding
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
If @var{string} does not reach @var{width}, then the result ends where
@var{string} ends. If one multi-column character in @var{string}
extends across the column @var{width}, that character is not included in
the result. Thus, the result can fall short of @var{width} but cannot
go beyond it.
The optional argument @var{start-column} specifies the starting column.
If this is non-@code{nil}, then the first @var{start-column} columns of
the string are omitted from the value. If one multi-column character in
@var{string} extends across the column @var{start-column}, that
character is not included.
The optional argument @var{padding}, if non-@code{nil}, is a padding
character added at the beginning and end of the result string, to extend
it to exactly @var{width} columns. The padding character is used at the
end of the result if it falls short of @var{width}. It is also used at
the beginning of the result if one multi-column character in
@var{string} extends across the column @var{start-column}.
@example
(truncate-string-to-width "\tab\t" 12 4)
@result{} "ab"
(truncate-string-to-width "\tab\t" 12 4 ?\ )
@result{} " ab "
@end example
@end defun
@node Faces
@section Faces
@cindex face
A @dfn{face} is a named collection of graphical attributes: font,
foreground color, background color and optional underlining. Faces
foreground color, background color, and optional underlining. Faces
control the display of text on the screen.
@cindex face id
@ -1003,39 +1142,9 @@ they are used automatically to handle certain shades of gray.
@defun set-face-font face font &optional frame
This function sets the font of face @var{face}. The argument @var{font}
should be a string.
@end defun
@defun make-face-bold face &optional frame noerror
Make face @var{face} bold, by setting its font to the bold variant of
the font it is now using. If @var{noerror} is non-@code{nil}, return
@code{nil} on failure; otherwise, that signals an error.
@end defun
@defun make-face-italic face &optional frame noerror
Make face @var{face} italic, by setting its font to the italic variant of
the font it is now using. If @var{noerror} is non-@code{nil}, return
@code{nil} on failure; otherwise, that signals an error.
@end defun
@defun make-face-bold-italic face &optional frame noerror
Make face @var{face} bold and italic, by setting its font to the bold
italic variant of the font it is now using. If @var{noerror} is
non-@code{nil}, return @code{nil} on failure; otherwise, that signals an
error.
@end defun
@defun make-face-unbold face &optional frame noerror
Make face @var{face} not bold, by setting its font to the medium variant
of the font it is now using. If @var{noerror} is non-@code{nil}, return
@code{nil} on failure; otherwise, that signals an error.
@end defun
@defun make-face-unitalic face &optional frame noerror
Make face @var{face} italic, by setting its font to the non-slanted
variant of the font it is now using. If @var{noerror} is
non-@code{nil}, return @code{nil} on failure; otherwise, that signals an
error.
should be a string. Note that if you set the font explicitly, the bold
and italic attributes cease to have any effect, because the precise font
that you specified is always used.
@end defun
@defun set-face-underline-p face underline-p &optional frame
@ -1043,6 +1152,18 @@ This function sets the underline attribute of face @var{face}.
Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
@tindex set-face-bold-p
@defun set-face-bold-p face bold-p &optional frame
This function sets the bold attribute of face @var{face}.
Non-@code{nil} means bold; @code{nil} means non-bold.
@end defun
@tindex set-face-italic-p
@defun set-face-italic-p face italic-p &optional frame
This function sets the italic attribute of face @var{face}.
Non-@code{nil} means italic; @code{nil} means non-italic.
@end defun
@defun invert-face face &optional frame
Swap the foreground and background colors of face @var{face}. If the
face doesn't specify both foreground and background, then its foreground
@ -1072,10 +1193,26 @@ This function returns the name of the font of face @var{face}.
This function returns the underline attribute of face @var{face}.
@end defun
@tindex face-bold-p
@defun face-bold-p face &optional frame
This function returns the bold attribute of face @var{face}.
@end defun
@tindex face-italic-p
@defun face-italic-p face &optional frame
This function returns the italic attribute of face @var{face}.
@end defun
@defun face-id face
This function returns the face id number of face @var{face}.
@end defun
@tindex face-documentation
@defun face-documentation face
This function returns the documentation string of face @var{face}, or
@code{nil} if none was specified for it.
@end defun
@defun face-equal face1 face2 &optional frame
This returns @code{t} if the faces @var{face1} and @var{face2} have the
same attributes for display.
@ -1230,7 +1367,10 @@ specify the characters for which you want unusual behavior.
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.
they also affect the indentation functions. These variables also affect
how the mode line is displayed; if you want to force redisplay of the
mode line using the new values, call the function
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@defopt ctl-arrow
@cindex control characters in display
@ -1249,7 +1389,7 @@ buffers that do not override it. @xref{Default Value}.
@defopt tab-width
The value of this variable is the spacing between tab stops used for
displaying tab characters in Emacs buffers. The default is 8. Note
that this feature is completely independent from the user-settable tab
that this feature is completely independent of the user-settable tab
stops used by the command @code{tab-to-tab-stop}. @xref{Indent Tabs}.
@end defopt
@ -1267,51 +1407,55 @@ The display table maps each character code into a sequence of
position on the screen. You can also define how to display each glyph
on your terminal, using the @dfn{glyph table}.
Display tables affect how the mode line is displayed; if you want to
force redisplay of the mode line using a new display table, call
@code{force-mode-line-update} (@pxref{Mode Line Format}).
@menu
* Display Table Format:: What a display table consists of.
* Active Display Table:: How Emacs selects a display table to use.
* Glyphs:: How to define a glyph, and what glyphs mean.
* ISO Latin 1:: How to use display tables
to support the ISO Latin 1 character set.
@end menu
@node Display Table Format
@subsection Display Table Format
A display table is actually an array of 262 elements.
A display table is actually char-table with subtype @code{display-table}.
@defun make-display-table
This creates and returns a display table. The table initially has
@code{nil} in all elements.
@end defun
The first 256 elements correspond to character codes; the @var{n}th
element says how to display the character code @var{n}. The value
should be @code{nil} or a vector of glyph values (@pxref{Glyphs}). If
an element is @code{nil}, it says to display that character according to
the usual display conventions (@pxref{Usual Display}).
The ordinary elements of the display table are indexed by character
codes; the element at index @var{c} says how to display the character
code @var{c}. The value should be @code{nil} or a vector of glyph
values (@pxref{Glyphs}). If an element is @code{nil}, it says to
display that character according to the usual display conventions
(@pxref{Usual Display}).
If you use the display table to change the display of newline
characters, the whole buffer will be displayed as one long ``line.''
The remaining six elements of a display table serve special purposes,
and @code{nil} means use the default stated below.
The display table also has six ``extra slots'' which serve special
purposes. Here is a table of their meanings; @code{nil} means to use
the default stated below.
@table @asis
@item 256
@item 0
The glyph for the end of a truncated screen line (the default for this
is @samp{$}). @xref{Glyphs}.
@item 257
@item 1
The glyph for the end of a continued line (the default is @samp{\}).
@item 258
@item 2
The glyph for indicating a character displayed as an octal character
code (the default is @samp{\}).
@item 259
@item 3
The glyph for indicating a control character (the default is @samp{^}).
@item 260
@item 4
A vector of glyphs for indicating the presence of invisible lines (the
default is @samp{...}). @xref{Selective Display}.
@item 261
@item 5
The glyph used to draw the border between side-by-side windows (the
default is @samp{|}). @xref{Splitting Windows}.
@end table
@ -1329,6 +1473,24 @@ effect of setting @code{ctl-arrow} to a non-@code{nil} value:
(aset disptab 127 (vector ?^ ??)))
@end example
@tindex display-table-slot
@defun display-table-slot display-table slot
This function returns the value of the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
@code{truncation}, @code{wrap}, @code{escape}, @code{control},
@code{selective-display}, and @code{vertical-border}.
@end defun
@tindex set-display-table-slot
@defun set-display-table-slot display-table slot value
This function stores @var{value} in the extra slot @var{slot} of
@var{display-table}. The argument @var{slot} may be a number from 0 to
5 inclusive, or a slot name (symbol). Valid symbols are
@code{truncation}, @code{wrap}, @code{escape}, @code{control},
@code{selective-display}, and @code{vertical-border}.
@end defun
@node Active Display Table
@subsection Active Display Table
@cindex active display table
@ -1364,8 +1526,8 @@ that window. This variable is @code{nil} by default.
@end defvar
If there is no display table to use for a particular window---that is,
if the window has none, its buffer has none, and
@code{standard-display-table} has none---then Emacs uses the usual
if the window specifies none, its buffer specifies none, and
@code{standard-display-table} is @code{nil}---then Emacs uses the usual
display conventions for all character codes in that window. @xref{Usual
Display}.
@ -1401,53 +1563,32 @@ Define this glyph code as an alias for code @var{integer}. You can use
an alias to specify a face code for the glyph; see below.
@item @code{nil}
This glyph is simple. On an ordinary terminal, the glyph code mod 256
is the character to output. With X, the glyph code mod 256 is the
character to output, and the glyph code divided by 256 specifies the
@dfn{face id number} to use while outputting it. @xref{Faces}.
This glyph is simple. On an ordinary terminal, the glyph code mod 524288
is the character to output. With X, the glyph code mod 524288 is the
character to output, and the glyph code divided by 524288 specifies the
@dfn{face id number} to use while outputting it. (524288 is
@ifinfo
2**19.
@end ifinfo
@tex
$2^{19}$.
@end tex
@xref{Faces}.
@end table
If a glyph code is greater than or equal to the length of the glyph
table, that code is automatically simple.
@node ISO Latin 1
@subsection ISO Latin 1
If you have a terminal that can handle the entire ISO Latin 1 character
set, you can arrange to use that character set as follows:
@example
(require 'disp-table)
;; @r{Set char codes 160--255 to display as themselves.}
;; @r{(Codes 128--159 are the additional control characters.)}
(standard-display-8bit 160 255)
@end example
If you are editing buffers written in the ISO Latin 1 character set and
your terminal doesn't handle anything but @sc{ASCII}, you can load the
file @file{iso-ascii} to set up a display table that displays the other
ISO characters as explanatory sequences of @sc{ASCII} characters. For
example, the character ``o with umlaut'' displays as @samp{@{"o@}}.
Some European countries have terminals that don't support ISO Latin 1
but do support the special characters for that country's language. You
can define a display table to work one language using such terminals.
For an example, see @file{lisp/iso-swed.el}, which handles certain
Swedish terminals.
You can load the appropriate display table for your terminal
automatically by writing a terminal-specific Lisp file for the terminal
type.
@node Beeping
@section Beeping
@cindex beeping
@cindex bell
You can make Emacs ring a bell (or blink the screen) to attract the
user's attention. Be conservative about how often you do this; frequent
bells can become irritating. Also be careful not to use beeping alone
when signaling an error is appropriate. (@xref{Errors}.)
This section describes how to make Emacs ring the bell (or blink the
screen) to attract the user's attention. Be conservative about how
often you do this; frequent bells can become irritating. Also be
careful not to use just beeping when signaling an error is more
appropriate. (@xref{Errors}.)
@defun ding &optional dont-terminate
@cindex keyboard macro termination
@ -1468,6 +1609,12 @@ the terminal's Termcap entry defines the visible bell capability
(@samp{vb}).
@end defvar
@tindex ring-bell-function
@defvar ring-bell-function
If this is non-@code{nil}, it specifies how Emacs should ``ring the
bell.'' Its value should bea function of no arguments.
@end defvar
@node Window Systems
@section Window Systems
@ -1485,9 +1632,10 @@ terminal).
@end defvar
@defvar window-setup-hook
This variable is a normal hook which Emacs runs after loading your
@file{.emacs} file and the default initialization file (if any), after
loading terminal-specific Lisp code, and after running the hook
This variable is a normal hook which Emacs runs after handling the
initialization files. Emacs runs this hook after it has completed
loading your @file{.emacs} file, the default initialization file (if
any), and the terminal-specific Lisp code, and runring the hook
@code{term-setup-hook}.
This hook is used for internal purposes: setting up communication with

4
lispref/edebug.texi
View file

@ -180,8 +180,8 @@ edebug-all-forms} toggles this option.
@findex edebug-eval-top-level-form
Another command, @kbd{M-x edebug-eval-top-level-form}, is available to
instrument any top-level form regardless of the value of
@code{edebug-all-defs} or @code{edebug-all-forms}.
instrument any top-level form regardless of the values of
@code{edebug-all-defs} and @code{edebug-all-forms}.
When Edebug is about to instrument code for the first time in a session,
it runs the hook @code{edebug-setup-hook}, then sets it to @code{nil}.

54
lispref/elisp.texi
View file

@ -5,8 +5,8 @@
@c %**end of header
@ifinfo
This version is the edition 2.4.2 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 19.34.
This version is the edition 2.5 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 20.3
@c Please REMEMBER to update edition number in *four* places in this file
@c and also in *one* place in intro.texi
@ -14,7 +14,7 @@ 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 Free Software Foundation, Inc.
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 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
@ -56,29 +56,30 @@ instead of in the original English.
@syncodeindex vr fn
@syncodeindex ky fn
@syncodeindex pg fn
@syncodeindex tp fn
@c We use the "type index" to index new functions and variables.
@c @syncodeindex tp fn
@setchapternewpage odd
@finalout
@titlepage
@title GNU Emacs Lisp Reference Manual
@subtitle GNU Emacs Version 19
@subtitle GNU Emacs Version 20
@subtitle for Unix Users
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
@subtitle Revision 2.4.2, December 1996
@subtitle Revision 2.5, February 1998
@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 Free Software Foundation, Inc.
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc.
@sp 2
Edition 2.4.2 @*
Revised for Emacs Version 19.34,@*
July 1996.@*
Edition 2.5 @*
Revised for Emacs Version 20.3,@*
February 1998.@*
@sp 2
ISBN 1-882114-71-X
@ -111,8 +112,8 @@ Cover art by Etienne Suvasa.
@node Top, Copying, (dir), (dir)
@ifinfo
This Info file contains edition 2.4.2 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 19.34.
This Info file contains edition 2.5 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 20.3.
@end ifinfo
@menu
@ -135,6 +136,7 @@ Reference Manual, corresponding to GNU Emacs version 19.34.
* Functions:: A function is a Lisp program
that can be invoked from other functions.
* Macros:: Macros are a way to extend the Lisp language.
* Customization:: Writing customization declarations.
* Loading:: Reading files of Lisp code into Lisp.
* Byte Compilation:: Compilation makes programs run faster.
@ -159,6 +161,7 @@ Reference Manual, corresponding to GNU Emacs version 19.34.
automatically when the text is changed.
* Text:: Examining and changing text in buffers.
* Non-ASCII Characters:: Non-ASCII text in buffers and strings.
* Searching and Matching:: Searching buffers for strings or regexps.
* Syntax Tables:: The syntax table controls word and list parsing.
* Abbrevs:: How Abbrev mode works, and its data structures.
@ -183,6 +186,8 @@ Appendices
* Index:: Index including concepts, functions, variables,
and other terms.
* New Symbols:: New functions and variables in Emacs 20.
--- The Detailed Node Listing ---
Here are other nodes that are inferiors of those already listed,
@ -578,8 +583,8 @@ Files
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
* Contents of Directories:: Getting a list of the files in a directory.
* Changing File Attributes:: Renaming files, changing protection, etc.
* File Names:: Decomposing and expanding file names.
* Changing Files:: Renaming files, changing protection, etc.
* File Names:: Decomposing and expanding file names.
Visiting Files
@ -651,7 +656,6 @@ Windows
* Window Start:: The display-start position controls which text
is on-screen in the window.
* Vertical Scrolling:: Moving text up and down in the window.
* Scrolling Hooks:: Hooks that run when you scroll a window.
* Horizontal Scrolling:: Moving text sideways on the window.
* Size of Window:: Accessing the size of a window.
* Resizing Windows:: Changing the size of a window.
@ -707,7 +711,7 @@ Markers
* Creating Markers:: Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character
position.
* Changing Markers:: Moving the marker to a new buffer or position.
* Moving Markers:: Moving the marker to a new buffer or position.
* The Mark:: How ``the mark'' is implemented with a marker.
* The Region:: How to access ``the region''.
@ -895,33 +899,36 @@ Object Internals
@include functions.texi
@include macros.texi
@include customize.texi
@include loading.texi
@include compile.texi
@include debugging.texi
@include streams.texi
@include streams.texi
@include minibuf.texi
@include commands.texi
@include keymaps.texi
@include modes.texi
@include modes.texi
@include help.texi
@include files.texi
@include backups.texi
@include buffers.texi
@include buffers.texi
@include windows.texi
@include frames.texi
@include positions.texi
@include markers.texi
@include text.texi
@include nonascii.texi
@include searching.texi
@include syntax.texi
@include abbrevs.texi
@include processes.texi
@include os.texi
@include display.texi
@include calendar.texi
@ -940,6 +947,11 @@ Object Internals
@include index.texi
@node New Symbols, , Index, Top
@chapter New Symbols Since the Previous Edition
@include elisp.tps
@c Print the tables of contents
@summarycontents
@contents

9
lispref/errors.texi
View file

@ -16,7 +16,9 @@ list of symbols. Normally this list includes the error symbol itself
and the symbol @code{error}. Occasionally it includes additional
symbols, which are intermediate classifications, narrower than
@code{error} but broader than a single error symbol. For example, all
the errors in accessing files have the condition @code{file-error}.
the errors in accessing files have the condition @code{file-error}. If
we do not say here that a certain error symbol has additional error
conditions, that means it has none.
As a special exception, the error symbol @code{quit} does not have the
condition @code{error}, because quitting is not considered an error.
@ -66,6 +68,11 @@ loop"}@*
This is not a @code{file-error}.@*
@xref{Input Functions}.
@item file-date-error
This is a subcategory of @code{file-error}. It occurs when
@code{copy-file} tries and fails to set the last-modification time of
the output file. @xref{Changing Files}.
@item file-error
This error and its subcategories do not have error-strings, because the
error message is constructed from the data items alone when the error

298
lispref/eval.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/eval
@node Evaluation, Control Structures, Symbols, Top
@ -21,9 +21,9 @@ function @code{eval}.
@ifinfo
@menu
* Intro Eval:: Evaluation in the scheme of things.
* Eval:: How to invoke the Lisp interpreter explicitly.
* Forms:: How various sorts of objects are evaluated.
* Quoting:: Avoiding evaluation (to put constants in the program).
* Eval:: How to invoke the Lisp interpreter explicitly.
@end menu
@node Intro Eval
@ -84,9 +84,9 @@ primitive implemented in C, or it may be a byte-compiled function
@dfn{environment}, which consists of the current values and bindings of
all Lisp variables.@footnote{This definition of ``environment'' is
specifically not intended to include all the data that can affect the
result of a program.} Whenever the form refers to a variable without
creating a new binding for it, the value of the binding in the current
environment is used. @xref{Variables}.
result of a program.} Whenever a form refers to a variable without
creating a new binding for it, the value of the variable's binding in
the current environment is used. @xref{Variables}.
@cindex side effect
Evaluation of a form may create new environments for recursive
@ -99,150 +99,15 @@ effects is @code{(setq foo 1)}.
The details of what evaluation means for each kind of form are
described below (@pxref{Forms}).
@node Eval
@section Eval
@c ??? Perhaps this should be the last section in the chapter.
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list. On these occasions, use the @code{eval} function.
@strong{Note:} it is generally cleaner and more flexible to call
functions that are stored in data structures, rather than to evaluate
expressions stored in data structures. Using functions provides the
ability to pass information to them as arguments.
The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
values. Loading a file also does evaluation (@pxref{Loading}).
@defun eval form
This is the basic function for performing evaluation. It evaluates
@var{form} in the current environment and returns the result. How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).
Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before
@code{eval} is called, and again by the @code{eval} function itself.
Here is an example:
@example
@group
(setq foo 'bar)
@result{} bar
@end group
@group
(setq bar 'baz)
@result{} baz
;; @r{@code{eval} receives argument @code{bar}, which is the value of @code{foo}}
(eval foo)
@result{} baz
(eval 'foo)
@result{} bar
@end group
@end example
The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth} (see below).
@end defun
@deffn Command eval-region start end &optional stream
This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}. It reads forms from
the region and calls @code{eval} on them until the end of the region is
reached, or until an error is signaled and not handled.
If @var{stream} is supplied, @code{standard-output} is bound to it
during the evaluation.
You can use the variable @code{load-read-function} to specify a function
for @code{eval-region} to use instead of @code{read} for reading
expressions. @xref{How Programs Do Loading}.
@code{eval-region} always returns @code{nil}.
@end deffn
@cindex evaluation of buffer contents
@deffn Command eval-current-buffer &optional stream
This is like @code{eval-region} except that it operates on the whole
buffer.
@end deffn
@defvar max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts
internal uses of those functions, such as for calling the functions
mentioned in Lisp expressions, and recursive evaluation of function call
arguments and function body forms.
This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
@cindex Lisp nesting error
The default value of this variable is 200. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
@code{max-specpdl-size} provides another limit on nesting.
@xref{Local Variables}.
@end defvar
@defvar values
The value of this variable is a list of the values returned by all the
expressions that were read from buffers (including the minibuffer),
evaluated, and printed. The elements are ordered most recent first.
@example
@group
(setq x 1)
@result{} 1
@end group
@group
(list 'A (1+ 2) auto-save-default)
@result{} (A 3 t)
@end group
@group
values
@result{} ((A 3 t) 1 @dots{})
@end group
@end example
This variable is useful for referring back to values of forms recently
evaluated. It is generally a bad idea to print the value of
@code{values} itself, since this may be very long. Instead, examine
particular elements, like this:
@example
@group
;; @r{Refer to the most recent evaluation result.}
(nth 0 values)
@result{} (A 3 t)
@end group
@group
;; @r{That put a new element on,}
;; @r{so all elements move back one.}
(nth 1 values)
@result{} (A 3 t)
@end group
@group
;; @r{This gets the element that was next-to-most-recent}
;; @r{before this example.}
(nth 3 values)
@result{} 1
@end group
@end example
@end defvar
@node Forms
@section Kinds of Forms
A Lisp object that is intended to be evaluated is called a @dfn{form}.
How Emacs evaluates a form depends on its data type. Emacs has three
different kinds of form that are evaluated differently: symbols, lists,
and ``all other types''. This section describes all three kinds,
starting with ``all other types'' which are self-evaluating forms.
and ``all other types''. This section describes all three kinds, one by
one, starting with the ``all other types'' which are self-evaluating
forms.
@menu
* Self-Evaluating Forms:: Forms that evaluate to themselves.
@ -301,12 +166,12 @@ program. Here is an example:
@example
@group
;; @r{Build an expression containing a buffer object.}
(setq buffer (list 'print (current-buffer)))
(setq print-exp (list 'print (current-buffer)))
@result{} (print #<buffer eval.texi>)
@end group
@group
;; @r{Evaluate it.}
(eval buffer)
(eval print-exp)
@print{} #<buffer eval.texi>
@result{} #<buffer eval.texi>
@end group
@ -344,7 +209,8 @@ a
value of @code{nil} is always @code{nil}, and the value of @code{t} is
always @code{t}; you cannot set or bind them to any other values. Thus,
these two symbols act like self-evaluating forms, even though
@code{eval} treats them like any other symbol.
@code{eval} treats them like any other symbol. A symbol whose name
starts with @samp{:} also self-evaluates in the same way.
@node Classifying Lists
@subsection Classification of List Forms
@ -507,7 +373,7 @@ and they may or may not evaluate the expansions.
Normally, the argument expressions are not evaluated as part of
computing the macro expansion, but instead appear as part of the
expansion, so they are computed when the expansion is computed.
expansion, so they are computed when the expansion is evaluated.
For example, given a macro defined as follows:
@ -704,3 +570,141 @@ Here are some examples of expressions that use @code{quote}:
Functions}), which causes an anonymous lambda expression written in Lisp
to be compiled, and @samp{`} (@pxref{Backquote}), which is used to quote
only part of a list, while computing and substituting other parts.
@node Eval
@section Eval
Most often, forms are evaluated automatically, by virtue of their
occurrence in a program being run. On rare occasions, you may need to
write code that evaluates a form that is computed at run time, such as
after reading a form from text being edited or getting one from a
property list. On these occasions, use the @code{eval} function.
The functions and variables described in this section evaluate forms,
specify limits to the evaluation process, or record recently returned
values. Loading a file also does evaluation (@pxref{Loading}).
@strong{Note:} it is generally cleaner and more flexible to store a
function in a data structure, and call it with @code{funcall} or
@code{apply}, than to store an expression in the data structure and
evaluate it. Using functions provides the ability to pass information
to them as arguments.
@defun eval form
This is the basic function evaluating an expression. It evaluates
@var{form} in the current environment and returns the result. How the
evaluation proceeds depends on the type of the object (@pxref{Forms}).
Since @code{eval} is a function, the argument expression that appears
in a call to @code{eval} is evaluated twice: once as preparation before
@code{eval} is called, and again by the @code{eval} function itself.
Here is an example:
@example
@group
(setq foo 'bar)
@result{} bar
@end group
@group
(setq bar 'baz)
@result{} baz
;; @r{Here @code{eval} receives argument @code{foo}}
(eval 'foo)
@result{} bar
;; @r{Here @code{eval} receives argument @code{bar}, which is the value of @code{foo}}
(eval foo)
@result{} baz
@end group
@end example
The number of currently active calls to @code{eval} is limited to
@code{max-lisp-eval-depth} (see below).
@end defun
@deffn Command eval-region start end &optional stream
This function evaluates the forms in the current buffer in the region
defined by the positions @var{start} and @var{end}. It reads forms from
the region and calls @code{eval} on them until the end of the region is
reached, or until an error is signaled and not handled.
If @var{stream} is supplied, @code{standard-output} is bound to it
during the evaluation.
You can use the variable @code{load-read-function} to specify a function
for @code{eval-region} to use instead of @code{read} for reading
expressions. @xref{How Programs Do Loading}.
@code{eval-region} always returns @code{nil}.
@end deffn
@cindex evaluation of buffer contents
@deffn Command eval-current-buffer &optional stream
This is like @code{eval-region} except that it operates on the whole
buffer.
@end deffn
@defvar max-lisp-eval-depth
This variable defines the maximum depth allowed in calls to @code{eval},
@code{apply}, and @code{funcall} before an error is signaled (with error
message @code{"Lisp nesting exceeds max-lisp-eval-depth"}). This counts
internal uses of those functions, such as for calling the functions
mentioned in Lisp expressions, and recursive evaluation of function call
arguments and function body forms.
This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
@cindex Lisp nesting error
The default value of this variable is 200. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
@code{max-specpdl-size} provides another limit on nesting.
@xref{Local Variables}.
@end defvar
@defvar values
The value of this variable is a list of the values returned by all the
expressions that were read, evaluated, and printed from buffers
(including the minibuffer) by the standard Emacs commands which do this.
The elements are ordered most recent first.
@example
@group
(setq x 1)
@result{} 1
@end group
@group
(list 'A (1+ 2) auto-save-default)
@result{} (A 3 t)
@end group
@group
values
@result{} ((A 3 t) 1 @dots{})
@end group
@end example
This variable is useful for referring back to values of forms recently
evaluated. It is generally a bad idea to print the value of
@code{values} itself, since this may be very long. Instead, examine
particular elements, like this:
@example
@group
;; @r{Refer to the most recent evaluation result.}
(nth 0 values)
@result{} (A 3 t)
@end group
@group
;; @r{That put a new element on,}
;; @r{so all elements move back one.}
(nth 1 values)
@result{} (A 3 t)
@end group
@group
;; @r{This gets the element that was next-to-most-recent}
;; @r{before this example.}
(nth 3 values)
@result{} 1
@end group
@end example
@end defvar

259
lispref/files.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
@ -28,7 +28,7 @@ substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
* File Locks:: Locking and unlocking files, to prevent
simultaneous editing by two people.
* Information about Files:: Testing existence, accessibility, size of files.
* Changing File Attributes:: Renaming files, changing protection, etc.
* Changing Files:: Renaming files, changing protection, etc.
* File Names:: Decomposing and expanding file names.
* Contents of Directories:: Getting a list of the files in a directory.
* Create/Delete Dirs:: Creating and Deleting Directories.
@ -103,7 +103,7 @@ When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn
@defun find-file-noselect filename
@defun find-file-noselect filename &optional nowarn rawfile
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
@ -120,11 +120,22 @@ If @code{find-file-noselect} needs to create a buffer, and there is no
file named @var{filename}, it displays the message @samp{New file} in
the echo area, and leaves the buffer empty.
The @code{find-file-noselect} function calls @code{after-find-file}
after reading the file (@pxref{Subroutines of Visiting}). That function
sets the buffer major mode, parses local variables, warns the user if
there exists an auto-save file more recent than the file just visited,
and finishes by running the functions in @code{find-file-hooks}.
This function displays warning or advisory messages in various peculiar
cases, unless the optional argument @var{nowarn} is non-@code{nil}.
The @code{find-file-noselect} function normally calls
@code{after-find-file} after reading the file (@pxref{Subroutines of
Visiting}). That function sets the buffer major mode, parses local
variables, warns the user if there exists an auto-save file more recent
than the file just visited, and finishes by running the functions in
@code{find-file-hooks}.
If the optional argument @var{rawfile} is non-@code{nil}, then
@code{after-find-file} is not called, and the
@code{find-file-not-found-hooks} are not run in case of failure. What's
more, a non-@code{nil} @var{rawfile} value suppresses coding system
conversion (@pxref{Coding Systems}) and format conversion (@pxref{Format
Conversion}).
The @code{find-file-noselect} function returns the buffer that is
visiting the file @var{filename}.
@ -185,7 +196,7 @@ until one of them returns non-@code{nil}. @code{buffer-file-name} is
already set up.
This is not a normal hook because the values of the functions are
used and they may not all be called.
used, and in many cases only some of the functions are called.
@end defvar
@node Subroutines of Visiting
@ -331,15 +342,18 @@ You might wish to save the file modes value returned by
@code{backup-buffer} and use that to set the mode bits of the file that
you write. This is what @code{save-buffer} normally does.
Do not make this variable buffer-local. To set up buffer-specific hook
functions, use @code{write-contents-hooks} instead.
Even though this is not a normal hook, you can use @code{add-hook} and
@code{remove-hook} to manipulate the list. @xref{Hooks}.
@end defvar
@c Emacs 19 feature
@defvar local-write-file-hooks
This works just like @code{write-file-hooks}, but it is intended
to be made local to particular buffers. It's not a good idea to make
@code{write-file-hooks} local to a buffer---use this variable instead.
This works just like @code{write-file-hooks}, but it is intended to be
made local to particular buffers, and used for hooks that pertain to the
file name or the way the buffer contents were obtained.
The variable is marked as a permanent local, so that changing the major
mode does not alter a buffer-local value. This is convenient for
@ -449,6 +463,18 @@ contents of the buffer (actually, just the accessible portion) with the
contents of the file. This is better than simply deleting the buffer
contents and inserting the whole file, because (1) it preserves some
marker positions and (2) it puts less data in the undo list.
It works to read a special file with @code{insert-file-contents}
as long as @var{replace} and @var{visit} are @code{nil}.
@end defun
@tindex insert-file-contents-literally
@defun insert-file-contents-literally filename &optional visit beg end replace
This function works like @code{insert-file-contents} except that it does
not do format decoding (@pxref{Format Conversion}), does not do
character code conversion (@pxref{Coding Systems}), does not run
@code{find-file-hooks}, does not perform automatic uncompression, and so
on.
@end defun
If you want to pass a file name to another process so that another
@ -514,6 +540,24 @@ feature is useful for programs that use files for internal purposes,
files that the user does not need to know about.
@end deffn
@tindex with-temp-file
@defmac with-temp-file file body...
The @code{with-temp-file} macro evaluates the @var{body} forms
with a temporary buffer as the current buffer; then, at the end, it
writes the buffer contents into file @var{file}. It kills the temporary
buffer when finished, restoring the buffer that was current before the
@code{with-temp-file} form.
The return value is the value of the last form in @var{body}. You can
return the contents of the temporary buffer by using
@code{(buffer-string)} as the last form.
The current buffer is restored even in case of an abnormal exit via
@code{throw} or error (@pxref{Nonlocal Exits}).
See also @code{with-temp-buffer} in @ref{Current Buffer}.
@end defmac
@node File Locks
@section File Locks
@cindex file locks
@ -562,8 +606,9 @@ 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 named @var{other-user}. The value it returns
determines what happens next:
is locked by another user named @var{other-user}. The default
definition of this function asks the user to say what to do. The value
this function returns determines what Emacs does next:
@itemize @bullet
@item
@ -590,9 +635,8 @@ where @code{file} is the name of the file and @var{other-user} is the
name of the user who has locked the file.
@end itemize
The default definition of this function asks the user to choose what
to do. If you wish, you can replace the @code{ask-user-about-lock}
function with your own version that decides in another way. The code
If you wish, you can replace the @code{ask-user-about-lock} function
with your own version that makes the decision in another way. The code
for its usual definition is in @file{userlock.el}.
@end defun
@ -694,7 +738,7 @@ This function returns @code{t} if you have permission to open existing
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.
file which is a directory.
Example: after the following,
@ -708,6 +752,13 @@ we can deduce that any attempt to read a file in @file{/foo/} will
give an error.
@end defun
@tindex access-file
@defun access-file filename string
This function opens file @var{filename} for reading, then closes it and
returns @code{nil}. However, if the open fails, it signals an error
using @var{string} as the error message text.
@end defun
@defun file-ownership-preserved-p filename
This function returns @code{t} if deleting the file @var{filename} and
then creating it anew would keep the file's owner unchanged.
@ -932,7 +983,7 @@ linked to), or @code{nil} for a text file.
@item
The number of names the file has. Alternate names, also known as hard
links, can be created by using the @code{add-name-to-file} function
(@pxref{Changing File Attributes}).
(@pxref{Changing Files}).
@item
The file's @sc{uid}.
@ -1038,7 +1089,7 @@ is on file system number -32252.
@end table
@end defun
@node Changing File Attributes
@node Changing Files
@section Changing File Names and Attributes
@cindex renaming files
@cindex copying files
@ -1090,7 +1141,7 @@ the files again. This shows two names for one file, @file{foo} and
@example
@group
(add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
(add-name-to-file "~/lewis/foo" "~/lewis/foo2")
@result{} nil
@end group
@ -1151,9 +1202,10 @@ In an interactive call, this function prompts for @var{filename} and
This command copies the file @var{oldname} to @var{newname}. An
error is signaled if @var{oldname} does not exist.
If @var{time} is non-@code{nil}, then this functions gives the new
file the same last-modified time that the old one has. (This works on
only some operating systems.)
If @var{time} is non-@code{nil}, then this functions gives the new file
the same last-modified time that the old one has. (This works on only
some operating systems.) If setting the time gets an error,
@code{copy-file} signals a @code{file-date-error} error.
In an interactive call, this function prompts for @var{filename} and
@var{newname} in the minibuffer; also, it requests confirmation if
@ -1202,8 +1254,8 @@ 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 low 9 bits of
@var{mode} are used.
The argument @var{mode} must be an integer. On most systems, only the
low 9 bits of @var{mode} are meaningful.
Saving a modified version of an existing file does not count as creating
the file; it does not change the file's mode, and does not use the
@ -1230,7 +1282,7 @@ File names in Emacs are represented as strings. The functions that
operate on a file all expect a file name argument.
In addition to operating on files themselves, Emacs Lisp programs
often need to operate on the names; i.e., to take them apart and to use
often need to operate on file names; i.e., to take them apart and to use
part of a name to construct related file names. This section describes
how to manipulate file names.
@ -1241,8 +1293,8 @@ directory.
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
as well as Unix syntax.
change. On MS-DOS and MS-Windows, these functions understand MS-DOS or
MS-Windows file-name syntax as well as Unix syntax.
@menu
* File Name Components:: The directory part of a file name, and the rest.
@ -1275,13 +1327,13 @@ complicated.
For some purposes, the nondirectory part is further subdivided into
the name proper and the @dfn{version number}. On Unix, only backup
files have version numbers in their names; on VMS, every file has a
files have version numbers in their names. On VMS, every file has a
version number, but most of the time the file name actually used in
Emacs omits the version number. Version numbers are found mostly in
directory lists.
Emacs omits the version number, so that version numbers in Emacs are
found mostly in directory lists.
@defun file-name-directory filename
This function returns the directory part of @var{filename} (or
This function returns the directory part of @var{filename} (or
@code{nil} if @var{filename} does not include a directory part). On
Unix, the function returns a string ending in a slash. On VMS, it
returns a string ending in one of the three characters @samp{:},
@ -1304,7 +1356,7 @@ returns a string ending in one of the three characters @samp{:},
@end defun
@defun file-name-nondirectory filename
This function returns the nondirectory part of @var{filename}.
This function returns the nondirectory part of @var{filename}.
@example
@group
@ -1324,8 +1376,8 @@ returns a string ending in one of the three characters @samp{:},
@end defun
@defun file-name-sans-versions filename
This function returns @var{filename} without any file version numbers,
backup version numbers, or trailing tildes.
This function returns @var{filename} with any file version numbers,
backup version numbers, or trailing tildes deleted.
@example
@group
@ -1387,9 +1439,9 @@ 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
that the operating system will interpret as the name of a directory. In
Unix, this means appending a slash to the string. On VMS, the function
converts a string of the form @file{[X]Y.DIR.1} to the form
@file{[X.Y]}.
Unix, this means appending a slash to the string (if it does not already
end in one). On VMS, the function converts a string of the form
@file{[X]Y.DIR.1} to the form @file{[X.Y]}.
@example
@group
@ -1400,9 +1452,9 @@ converts a string of the form @file{[X]Y.DIR.1} to the form
@end defun
@defun directory-file-name dirname
This function returns a string representing @var{dirname} in a form
that the operating system will interpret as the name of a file. On
Unix, this means removing a final slash from the string. On VMS, the
This function returns a string representing @var{dirname} in a form that
the operating system will interpret as the name of a file. On Unix,
this means removing the final slash from the string. On VMS, the
function converts a string of the form @file{[X.Y]} to
@file{[X]Y.DIR.1}.
@ -1500,9 +1552,9 @@ redundancies such as @file{./} and @file{@var{name}/../}.
@defun expand-file-name filename &optional directory
This function converts @var{filename} to an absolute file name. If
@var{directory} is supplied, it is the directory to start with if
@var{filename} is relative. (The value of @var{directory} should itself
be an absolute directory name; it may start with @samp{~}.)
@var{directory} is supplied, it is the default directory to start with
if @var{filename} is relative. (The value of @var{directory} should
itself be an absolute directory name; it may start with @samp{~}.)
Otherwise, the current buffer's value of @code{default-directory} is
used. For example:
@ -1535,27 +1587,6 @@ canonical form:
@end group
@end example
@samp{~/} is expanded into the user's home directory. A @samp{/} or
@samp{~} following a @samp{/} is taken to be the start of an absolute
file name that overrides what precedes it, so everything before that
@samp{/} or @samp{~} is deleted. For example:
@example
@group
(expand-file-name
"/a1/gnu//usr/local/lib/emacs/etc/MACHINES")
@result{} "/usr/local/lib/emacs/etc/MACHINES"
@end group
@group
(expand-file-name "/a1/gnu/~/foo")
@result{} "/xcssun/users/rms/foo"
@end group
@end example
@noindent
In both cases, @file{/a1/gnu/} is discarded because an absolute file
name follows it.
Note that @code{expand-file-name} does @emph{not} expand environment
variables; only @code{substitute-in-file-name} does that.
@end defun
@ -1631,6 +1662,7 @@ substitution, everything before the following @samp{/} is discarded:
@group
(substitute-in-file-name "/usr/local/$HOME/foo")
@result{} "/xcssun/users/rms/foo"
;; @r{@file{/usr/local/} has been discarded.}
@end group
@end example
@ -1645,14 +1677,21 @@ on VMS except discard superfluous initial components as shown above.
construct a name for such a file:
@example
(make-temp-name (concat "/tmp/" @var{name-of-application}))
(make-temp-name
(expand-file-name @var{name-of-application}
(or (getenv "TMPDIR")
"/tmp/")))
@end example
@cindex @code{TMPDIR} environment variable.
@noindent
Here we use the directory @file{/tmp/} because that is the standard
place on Unix for temporary files. The job of @code{make-temp-name} is
to prevent two different users or two different jobs from trying to use
the same name.
The job of @code{make-temp-name} is to prevent two different users or
two different jobs from trying to use the same name.
This example uses the environment variable @code{TMPDIR} to specify the
directory, and if that is not specified, we use the directory
@file{/tmp/}. This is the standard way to choose the directory, and all
Emacs Lisp programs should use it.
@defun make-temp-name string
This function generates string that can be used as a unique name. The
@ -1870,11 +1909,11 @@ 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 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.)
If @var{full-directory-p} is non-@code{nil}, that the directory listing
is expected to show a complete directory. You should specify @code{t}
when @var{file} is a directory and switches do not contain @samp{-d}.
(The @samp{-d} option to @code{ls} says to describe a directory itself
as a file, rather than showing 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
@ -1912,13 +1951,17 @@ any files, @code{delete-directory} signals an error.
@cindex magic file names
@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
You can implement special handling for certain file names. This is
called making those names @dfn{magic}. The principal use for this
feature is in implementing remote file names (@pxref{Remote Files,,
Remote Files, emacs, The GNU Emacs Manual}).
To define a kind of magic file name, you must supply a regular
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 variable @code{file-name-handler-alist} holds 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:
@ -2003,10 +2046,10 @@ for an operation it 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 'my-file-handler
(and (eq inhibit-file-name-operation operation)
inhibit-file-name-handlers)))
(inhibit-file-name-operation operation))
(cons 'my-file-handler
(and (eq inhibit-file-name-operation operation)
inhibit-file-name-handlers)))
(inhibit-file-name-operation operation))
(apply operation args)))))
@end smallexample
@ -2050,9 +2093,10 @@ does nothing and returns @code{nil}.
@end defun
@defun unhandled-file-name-directory filename
This function returns the name of a directory that is not magic.
It uses the directory part of @var{filename} if that is not magic.
Otherwise, it asks the handler what to do.
This function returns the name of a directory that is not magic. It
uses the directory part of @var{filename} if that is not magic. For a
magic file name, it invokes the file name handler, which therefore
decides what value to return.
This is useful for running a subprocess; every subprocess must have a
non-magic directory to serve as its current directory, and this function
@ -2096,25 +2140,32 @@ A regular expression which is used to recognize files represented in
this format.
@item from-fn
A function to call to decode data in this format (to convert file data into
the usual Emacs data representation).
A function or shell command to decode data in this format (to convert
file data into the usual Emacs data representation).
The @var{from-fn} is called with two args, @var{begin} and @var{end},
which specify the part of the buffer it should convert. It should convert
the text by editing it in place. Since this can change the length of the
text, @var{from-fn} should return the modified end position.
If @var{from-fn} is a function, it is called with two args, @var{begin}
and @var{end}, which specify the part of the buffer it should convert.
It should convert the text by editing it in place. Since this can
change the length of the text, @var{from-fn} should return the modified
end position.
One responsibility of @var{from-fn} is to make sure that the beginning
of the file no longer matches @var{regexp}. Otherwise it is likely to
get called again.
If @var{from-fn} is a string, it is a shell command; Emacs runs the
command as a filter to perform the conversion.
@item to-fn
A function to call to encode data in this format (to convert
A function or shell command to encode data in this format (to convert
the usual Emacs data representation into this format).
The @var{to-fn} is called with two args, @var{begin} and @var{end},
which specify the part of the buffer it should convert. There are
two ways it can do the conversion:
If @var{to-fn} is a string, it is a shell command; Emacs runs the
command as a filter to perform the conversion.
If @var{to-fn} is a function, it is called with two args, @var{begin}
and @var{end}, which specify the part of the buffer it should convert.
There are two ways it can do the conversion:
@itemize @bullet
@item
@ -2166,14 +2217,14 @@ When @code{write-region} writes data into a file, it first calls the
encoding functions for the formats listed in @code{buffer-file-format},
in the order of appearance in the list.
@defun format-write-file file format
@deffn Command format-write-file file format
This command writes the current buffer contents into the file @var{file}
in format @var{format}, and makes that format the default for future
saves of the buffer. The argument @var{format} is a list of format
names.
@end defun
@end deffn
@defun format-find-file file format
@deffn Command format-find-file file format
This command finds the file @var{file}, converting it according to
format @var{format}. It also makes @var{format} the default if the
buffer is saved later.
@ -2181,9 +2232,9 @@ buffer is saved later.
The argument @var{format} is a list of format names. If @var{format} is
@code{nil}, no conversion takes place. Interactively, typing just
@key{RET} for @var{format} specifies @code{nil}.
@end defun
@end deffn
@defun format-insert-file file format %optional beg end
@deffn format-insert-file file format %optional beg end
This command inserts the contents of file @var{file}, converting it
according to format @var{format}. If @var{beg} and @var{end} are
non-@code{nil}, they specify which part of the file to read, as in
@ -2196,7 +2247,7 @@ list of the absolute file name and the length of the data inserted
The argument @var{format} is a list of format names. If @var{format} is
@code{nil}, no conversion takes place. Interactively, typing just
@key{RET} for @var{format} specifies @code{nil}.
@end defun
@end deffn
@defvar auto-save-file-format
This variable specifies the format to use for auto-saving. Its value is
@ -2214,6 +2265,8 @@ is always local in all buffers.
@cindex binary files and text files
@cindex Windows file types
@c ??? This needs to be updated.
Emacs on MS-DOS and on Windows NT or 95 makes a distinction between
text files and binary files. This is necessary because ordinary text
files on MS-DOS use a two character sequence between lines:
@ -2240,7 +2293,7 @@ or a binary file. It returns @code{nil} for text, @code{t} for binary.
@defopt file-name-buffer-file-type-alist
This variable holds an alist for distinguishing text files from binary
files. Each element has the form (@var{regexp} . @var{type}), where
@var{regexp} is matched against the file name, and @var{type} may be is
@var{regexp} is matched against the file name, and @var{type} may be
@code{nil} for text, @code{t} for binary, or a function to call to
compute which. If it is a function, then it is called with a single
argument (the file name) and should return @code{t} or @code{nil}.

96
lispref/frames.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
@node Frames, Positions, Windows, Top
@ -49,6 +49,7 @@ This predicate returns @code{t} if @var{object} is a frame, and
* Dialog Boxes:: Displaying a box to ask yes or no.
* Pointer Shapes:: Specifying the shape of the mouse pointer.
* X Selections:: Transferring text to and from other X clients.
* Font Names:: Looking up font names.
* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@ -75,13 +76,17 @@ window system Emacs uses to display its frames. @xref{X Frame
Parameters}, for documentation of individual parameters you can specify.
@end defun
@tindex before-make-frame-hook
@defvar before-make-frame-hook
A normal hook run by @code{make-frame} before it actually creates the
frame.
@end defvar
@tindex after-make-frame-hook
@defvar after-make-frame-hook
A normal hook run by @code{make-frame} after it creates the frame.
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-hook} receives one argument, the
frame just created.
@end defvar
@node Multiple Displays
@ -129,7 +134,7 @@ This function opens a connection to the X display @var{display}. It
does not create a frame on that display, but it permits you to check
that communication can be established with that display.
The optional argument @var{resource-string}, if not @code{nil}, is a
The optional argument @var{xrm-string}, if not @code{nil}, is a
string of resource names and values, in the same format used in the
@file{.Xresources} file. The values you specify override the resource
values recorded in the X server itself; they apply to all Emacs frames
@ -265,6 +270,9 @@ If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
Since a non-window terminal can display only one frame at a time, the
frame name appears in the mode line.
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
@ -356,6 +364,9 @@ decide which buffers it should consider, if the predicate is not
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
@item buffer-list
A list of buffers recently selected in this frame.
@item font
The name of the font for displaying text in the frame. This is a
string.
@ -367,8 +378,9 @@ Whether selecting the frame raises it (non-@code{nil} means yes).
Whether deselecting the frame lowers it (non-@code{nil} means yes).
@item vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling
(non-@code{nil} means yes).
Whether the frame has scroll bars for vertical scrolling, and which side
of the frame they should be on. The possible values are @code{left},
@code{right}, and @code{nil} for no scroll bars.
@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
@ -666,7 +678,7 @@ This function returns the frame that @var{window} is on.
order. The order runs from the frame's top window, which is at the
upper left corner, down and to the right, until it reaches the window at
the lower right corner (always the minibuffer window, if the frame has
one), and then it moves back to the top.
one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
@defun frame-top-window frame
This returns the topmost, leftmost window of frame @var{frame}.
@ -765,8 +777,8 @@ Don't call it for any other reason.
@defun redirect-frame-focus frame focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes
intended for @var{frame}. After such an event, the value of
This means that @var{focus-frame} will receive subsequent keystrokes and
events intended for @var{frame}. After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.
@ -843,21 +855,21 @@ changes. @xref{Misc Events}.
@node Raising and Lowering
@section Raising and Lowering Frames
The X Window System uses a desktop metaphor. Part of this metaphor is
The X Window System uses a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
to ``lowest''. Where two windows overlap, the one higher up covers the
one underneath. Even a window at the bottom of the stack can be seen if
no other window overlaps it.
to ``lowest''. Where two X windows overlap, the one higher up covers
the one underneath. Even an X window at the bottom of the stack can be
seen if no other X window overlaps it.
@cindex raising a frame
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend to
change the order frequently. @dfn{Raising} a window means moving it
``up'', to the top of the stack. @dfn{Lowering} a window means moving
it to the bottom of the stack. This motion is in the notional third
dimension only, and does not change the position of the window on the
screen.
An X window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. @dfn{Raising} an X window means moving
it ``up'', to the top of the stack. @dfn{Lowering} an X window means
moving it to the bottom of the stack. This motion is in the notional
third dimension only, and does not change the position of the X window
on the screen.
You can raise and lower Emacs's X windows with these functions:
@ -1046,13 +1058,13 @@ Each @var{line} should be a string, and each @var{item} should be the
value to return if that @var{line} is chosen.
@end defun
@strong{Usage note:} Don't use @code{x-popup-menu} to display a menu if
a prefix key with a menu keymap would do the job. If you use a menu
keymap to implement a menu, @kbd{C-h c} and @kbd{C-h a} can see the
individual items in that menu and provide help for them. If instead you
implement the menu by defining a command that calls @code{x-popup-menu},
the help facilities cannot know what happens inside that command, so
they cannot give any help for the menu's items.
@strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
if you could do the job with a prefix key defined with a menu keymap.
If you use a menu keymap to implement a menu, @kbd{C-h c} and @kbd{C-h
a} can see the individual items in that menu and provide help for them.
If instead you implement the menu by defining a command that calls
@code{x-popup-menu}, the help facilities cannot know what happens inside
that command, so they cannot give any help for the menu's items.
The menu bar mechanism, which lets you switch between submenus by
moving the mouse, cannot look within the definition of a command to see
@ -1162,7 +1174,8 @@ selection. Otherwise, @var{data} may be a string, a symbol, an integer
cons of two markers pointing to the same buffer. An overlay or a pair
of markers stands for text in the overlay or between the markers.
The data may also be a vector of valid non-vector selection values.
The argument @var{data} may also be a vector of valid non-vector
selection values.
Each possible @var{type} has its own selection value, which changes
independently. The usual values of @var{type} are @code{PRIMARY} and
@ -1203,6 +1216,30 @@ This function stores @var{string} into the first cut buffer (cut buffer
like the way successive kills in Emacs move down the kill ring.
@end defun
@node Font Names
@section Looking up Font Names
@defun x-list-font pattern &optional face frame maximum
This function returns a list of available font names that match
@var{pattern}. If the optional arguments FACE and FRAME are specified,
then the list is limited to fonts that are the same size as @var{face}
currently is on @var{frame}.
The argument @var{pattern} should be a string, perhaps with wildcard
characters: the @samp{*} character matches any substring, and the
@samp{?} character matches any single character. Pattern matching
of font names ignores case.
If you specify @var{face} and @var{frame}, @var{face} should be a face name
(a symbol) and @var{frame} should be a frame.
The optional argument @var{maximum} sets a limit on how many fonts to
return. If this is non-@code{nil}, then the return value is truncated
after the first @var{maximum} matching fonts. Specifying a small value
for @var{maximum} can make this function much faster, in cases where
many fonts match the pattern.
@end defun
@node Color Names
@section Color Names
@ -1274,6 +1311,13 @@ If you specify them, the key is
@samp{Emacs.@var{class}.@var{subclass}}.
@end defun
@defvar x-resource-class
This variable specifies the application name that @code{x-get-resource}
should look up. The default value is @code{"Emacs"}. You can examine X
resources for application names other than ``Emacs'' by binding this
variable to some other string, around a call to @code{x-get-resource}.
@end defvar
@xref{Resources X,, X Resources, emacs, The GNU Emacs Manual}.
@node Server Data

166
lispref/functions.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/functions
@node Functions, Macros, Variables, Top
@ -54,8 +54,8 @@ such as @code{car} or @code{append}. These functions are also called
@dfn{built-in} functions or @dfn{subrs}. (Special forms are also
considered primitives.)
Usually the reason that a function is a primitives is because it is
fundamental, because it provides a low-level interface to operating
Usually the reason we implement a function as a primitive is because it
is fundamental, because it provides a low-level interface to operating
system services, or because it needs to run fast. Primitives can be
modified or added only by changing the C sources and recompiling the
editor. See @ref{Writing Emacs Primitives}.
@ -110,6 +110,12 @@ A @dfn{byte-code function} is a function that has been compiled by the
byte compiler. @xref{Byte-Code Type}.
@end table
@tindex functionp
@defun functionp object
This function returns @code{t} if @var{object} is any kind of function;
that is, anything that could be called as a function.
@end defun
@defun subrp object
This function returns @code{t} if @var{object} is a built-in function
(i.e., a Lisp primitive).
@ -188,7 +194,7 @@ reason functions are defined to start with @code{lambda} is so that
other lists, intended for other uses, will not accidentally be valid as
functions.
The second element is a list of symbols--the argument variable names.
The second element is a list of symbols---the argument variable names.
This is called the @dfn{lambda list}. When a Lisp function is called,
the argument values are matched up against the variables in the lambda
list, which are given local bindings with the values provided.
@ -267,7 +273,7 @@ that time, they were the only way to bind and initialize local
variables.
@node Argument List
@subsection Advanced Features of Argument Lists
@subsection Other Features of Argument Lists
@kindex wrong-number-of-arguments
@cindex argument binding
@cindex binding arguments
@ -326,7 +332,8 @@ This is what @code{substring} does; @code{nil} as the third argument to
@quotation
@b{Common Lisp note:} Common Lisp allows the function to specify what
default value to use when an optional argument is omitted; Emacs Lisp
always uses @code{nil}.
always uses @code{nil}. Emacs Lisp does not support ``supplied-p''
variables that tell you whether an argument was explicitly passed.
@end quotation
For example, an argument list that looks like this:
@ -453,6 +460,9 @@ equally well a name for the same function.
A symbol used as a function name may also be used as a variable;
these two uses of a symbol are independent and do not conflict.
(Some Lisp dialects, such as Scheme, do not distinguish between a
symbol's value and its function definition; a symbol's value as a variable
is also its function definition.)
@node Defining Functions
@section Defining Functions
@ -476,8 +486,8 @@ value.
As described previously (@pxref{Lambda Expressions}),
@var{argument-list} is a list of argument names and may include the
keywords @code{&optional} and @code{&rest}. Also, the first two forms
in @var{body-forms} may be a documentation string and an interactive
keywords @code{&optional} and @code{&rest}. Also, the first two of the
@var{body-forms} may be a documentation string and an interactive
declaration.
There is no conflict if the same symbol @var{name} is also used as a
@ -566,11 +576,11 @@ function @code{concat} with arguments @code{"a"} and @code{"b"}.
@xref{Evaluation}, for a description of evaluation.
When you write a list as an expression in your program, the function
name is part of the program. This means that you choose which function
to call, and how many arguments to give it, when you write the program.
Usually that's just what you want. Occasionally you need to decide at
run time which function to call. To do that, use the functions
@code{funcall} and @code{apply}.
name it calls is written in your program. This means that you choose
which function to call, and how many arguments to give it, when you
write the program. Usually that's just what you want. Occasionally you
need to compute at run time which function to call. To do that, use the
functions @code{funcall} and @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
@ -616,9 +626,10 @@ Compare these example with the examples of @code{apply}.
@defun apply function &rest arguments
@code{apply} calls @var{function} with @var{arguments}, just like
@code{funcall} but with one difference: the last of @var{arguments} is a
list of arguments to give to @var{function}, rather than a single
argument. We also say that @code{apply} @dfn{spreads} this list so that
each individual element becomes an argument.
list of objects, which are passed to @var{function} as separate
arguments, rather than a single list. We say that @code{apply}
@dfn{spreads} this list so that each individual element becomes an
argument.
@code{apply} returns the result of calling @var{function}. As with
@code{funcall}, @var{function} must either be a Lisp function or a
@ -676,10 +687,12 @@ This function ignores any arguments and returns @code{nil}.
@cindex mapping functions
A @dfn{mapping function} applies a given function to each element of a
list or other collection. Emacs Lisp has three such functions;
list or other collection. Emacs Lisp has several such functions;
@code{mapcar} and @code{mapconcat}, which scan a list, are described
here. For the third mapping function, @code{mapatoms}, see
@ref{Creating Symbols}.
here. @xref{Creating Symbols}, for the function @code{mapatoms} which
maps over the symbols in an obarray. @xref{Char-Tables}, for the
function @code{map-char-table}, which maps over the elements in a
char-table.
@defun mapcar function sequence
@code{mapcar} applies @var{function} to each element of @var{sequence}
@ -793,26 +806,68 @@ is not the @emph{function definition} of @code{silly}. We have not given
@code{silly} any function definition, just a value as a variable.)
Most of the time, anonymous functions are constants that appear in
your program. For example, you might want to pass one as an argument
to the function @code{mapcar}, which applies any given function to each
element of a list. Here we pass an anonymous function that multiplies
a number by two:
your program. For example, you might want to pass one as an argument to
the function @code{mapcar}, which applies any given function to each
element of a list.
Here we define a function @code{change-property} which
uses a function as its third argument:
@example
@group
(defun double-each (list)
(mapcar '(lambda (x) (* 2 x)) list))
@result{} double-each
(defun change-property (symbol prop function)
(let ((value (get symbol prop)))
(put symbol prop (funcall function value))))
@end group
@end example
@noindent
Here we define a function that uses @code{change-property},
passing a function that doubles its argument:
@example
@group
(double-each '(2 11))
@result{} (4 22)
(defun double-property (symbol prop)
(change-property symbol prop '(lambda (x) (* 2 x))))
@end group
@end example
@noindent
In such cases, we usually use the special form @code{function} instead
of simple quotation to quote the anonymous function.
of simple quotation to quote the anonymous function, like this:
@example
@group
(defun double-property (symbol prop)
(change-property symbol prop (function (lambda (x) (* 2 x)))))
@end group
@end example
Using @code{function} instead of @code{quote} makes a difference if you
compile the function @code{double-property}. For example, if you
compile the second definition of @code{double-property}, the anonymous
function is compiled as well. By contrast, if you compile the first
definition which uses ordinary @code{quote}, the argument passed to
@code{change-property} is the precise list shown:
@example
(lambda (x) (* x 2))
@end example
@noindent
The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what @code{change-property} will
do with the list. Perhaps will check whether the @sc{car} of the third
element is the symbol @code{*}! Using @code{function} tells the
compiler it is safe to go ahead and compile the constant function.
We sometimes write @code{function} instead of @code{quote} when
quoting the name of a function, but this usage is just a sort of
comment:
@example
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
@end example
@defspec function function-object
@cindex function quoting
@ -823,47 +878,6 @@ to be used only as a function, and therefore can safely be compiled.
Contrast this with @code{quote}, in @ref{Quoting}.
@end defspec
Using @code{function} instead of @code{quote} makes a difference
inside a function or macro that you are going to compile. For example:
@example
@group
(defun double-each (list)
(mapcar (function (lambda (x) (* 2 x))) list))
@result{} double-each
@end group
@group
(double-each '(2 11))
@result{} (4 22)
@end group
@end example
@noindent
If this definition of @code{double-each} is compiled, the anonymous
function is compiled as well. By contrast, in the previous definition
where ordinary @code{quote} is used, the argument passed to
@code{mapcar} is the precise list shown:
@example
(lambda (x) (* x 2))
@end example
@noindent
The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what @code{mapcar} does with the
list. Perhaps @code{mapcar} will check that the @sc{car} of the third
element is the symbol @code{*}! The advantage of @code{function} is
that it tells the compiler to go ahead and compile the constant
function.
We sometimes write @code{function} instead of @code{quote} when
quoting the name of a function, but this usage is just a sort of
comment.
@example
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
@end example
See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example using @code{function} and an anonymous function.
@ -936,7 +950,7 @@ error. (See also @code{makunbound}, in @ref{Local Variables}.)
@example
@group
(defun foo (x) x)
@result{} x
@result{} foo
@end group
@group
(foo 1)
@ -944,7 +958,7 @@ error. (See also @code{makunbound}, in @ref{Local Variables}.)
@end group
@group
(fmakunbound 'foo)
@result{} x
@result{} foo
@end group
@group
(foo 1)
@ -954,9 +968,11 @@ error. (See also @code{makunbound}, in @ref{Local Variables}.)
@end defun
@defun fset symbol definition
This function stores @var{definition} in the function cell of @var{symbol}.
The result is @var{definition}. Normally @var{definition} should be a function
or the name of a function, but this is not checked.
This function stores @var{definition} in the function cell of
@var{symbol}. The result is @var{definition}. Normally
@var{definition} should be a function or the name of a function, but
this is not checked. The argument @var{symbol} is an ordinary evaluated
argument.
There are three normal uses of this function:

77
lispref/help.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/help
@node Documentation, Files, Modes, Top
@ -60,20 +60,20 @@ documentation is displayed. This allows documentation strings to refer
to the keys for related commands and be accurate even when a user
rearranges the key bindings. (@xref{Accessing Documentation}.)
Within the Lisp world, a documentation string accessible through the
In Emacs Lisp, a documentation string is accessible through the
function or variable that it describes:
@itemize @bullet
@item
The documentation for a function is stored in the function definition
itself (@pxref{Lambda Expressions}). The function
@code{documentation} knows how to extract it.
itself (@pxref{Lambda Expressions}). The function @code{documentation}
knows how to extract it.
@item
@kindex variable-documentation
The documentation for a variable is stored in the variable's property
list under the property name @code{variable-documentation}. The
function @code{documentation-property} knows how to extract it.
function @code{documentation-property} knows how to retrieve it.
@end itemize
@cindex @file{DOC} (documentation) file
@ -81,17 +81,17 @@ function @code{documentation-property} knows how to extract it.
@cindex @file{etc/DOC-@var{version}}
To save space, the documentation for preloaded functions and variables
(including primitive functions and autoloaded functions) is stored in
the file @file{emacs/etc/DOC-@var{version}}. The documentation for
functions and variables loaded during the Emacs session from
byte-compiled files is stored in those files (@pxref{Docs and
Compilation}).
the file @file{emacs/etc/DOC-@var{version}}---not inside Emacs. The
documentation strings for functions and variables loaded during the
Emacs session from byte-compiled files are stored in those files
(@pxref{Docs and Compilation}).
The data structure inside Emacs has an integer offset into the file, or
a list containing a string and an integer, in place of the documentation
string. The functions @code{documentation} and
@code{documentation-property} use that information to read the
documentation from the appropriate file; this is transparent to the
user.
a list containing a file name and an integer, in place of the
documentation string. The functions @code{documentation} and
@code{documentation-property} use that information to fetch the
documentation string from the appropriate file; this is transparent to
the user.
For information on the uses of documentation strings, see @ref{Help, ,
Help, emacs, The GNU Emacs Manual}.
@ -110,8 +110,7 @@ This function returns the documentation string that is recorded
@var{symbol}'s property list under property @var{property}. It
retrieves the text from a file if necessary, and runs
@code{substitute-command-keys} to substitute actual key bindings. (This
substitution is not done if @var{verbatim} is non-@code{nil}; the
@var{verbatim} argument exists only as of Emacs 19.)
substitution is not done if @var{verbatim} is non-@code{nil}.)
@smallexample
@group
@ -242,15 +241,15 @@ When the `track-eol' feature is doing its job, the value is 9999.
@end smallexample
@defun Snarf-documentation filename
This function is used only during Emacs initialization, just before
This function is used only during Emacs initialization, just before
the runnable Emacs is dumped. It finds the file offsets of the
documentation strings stored in the file @var{filename}, and records
them in the in-core function definitions and variable property lists in
place of the actual strings. @xref{Building Emacs}.
Emacs finds the file @var{filename} in the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file is found in the
directory @code{doc-directory}. Usually @var{filename} is
Emacs reads the file @var{filename} from the @file{emacs/etc} directory.
When the dumped Emacs is later executed, the same file will be looked
for in the directory @code{doc-directory}. Usually @var{filename} is
@code{"DOC-@var{version}"}.
@end defun
@ -289,13 +288,13 @@ stands for a key sequence that will invoke @var{command}, or @samp{M-x
@var{command}} if @var{command} has no key bindings.
@item \@{@var{mapvar}@}
stands for a summary of the value of @var{mapvar}, which should be a
keymap. The summary is made by @code{describe-bindings}.
stands for a summary of the value of @var{mapvar}. The value should be
a keymap. The summary is made by @code{describe-bindings}.
@item \<@var{mapvar}>
stands for no text itself. It is used for a side effect: it specifies
@var{mapvar} as the keymap for any following @samp{\[@var{command}]}
sequences in this documentation string.
stands for no text itself. It is used only for a side effect: it
specifies @var{mapvar} as the keymap for any following
@samp{\[@var{command}]} sequences in this documentation string.
@item \=
quotes the following character and is discarded; thus, @samp{\=\[} puts
@ -348,10 +347,10 @@ C-g abort-recursive-edit
@node Describing Characters
@section Describing Characters for Help Messages
These functions convert events, key sequences or characters to textual
descriptions. These descriptions are useful for including arbitrary
text characters or key sequences in messages, because they convert
non-printing and whitespace characters to sequences of printing
These functions convert events, key sequences, or characters to
textual descriptions. These descriptions are useful for including
arbitrary text characters or key sequences in messages, because they
convert non-printing and whitespace characters to sequences of printing
characters. The description of a non-whitespace printing character is
the character itself.
@ -428,7 +427,8 @@ we describe some program-level interfaces to the same information.
This function finds all symbols whose names contain a match for the
regular expression @var{regexp}, and returns a list of them
(@pxref{Regular Expressions}). It also displays the symbols in a buffer
named @samp{*Help*}, each with a one-line description.
named @samp{*Help*}, each with a one-line description taken from the
beginning of its documentation string.
@c Emacs 19 feature
If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
@ -441,8 +441,8 @@ displayed.
In the first of the following examples, @code{apropos} finds all the
symbols with names containing @samp{exec}. In the second example, it
finds and returns only those symbols that are also commands.
(We don't show the output that results in the @samp{*Help*} buffer.)
finds and returns only those symbols that are also commands. (We don't
show here the output that results in the @samp{*Help*} buffer.)
@smallexample
@group
@ -471,8 +471,8 @@ execute-extended-command ESC x
@end smallexample
The command @kbd{C-h a} (@code{command-apropos}) calls @code{apropos},
but specifies a @var{predicate} to restrict the output to symbols that
are commands. The call to @code{apropos} looks like this:
but specifies a @var{predicate} that restricts the output to symbols
that are commands. The call to @code{apropos} looks like this:
@smallexample
(apropos string t 'commandp)
@ -483,8 +483,8 @@ are commands. The call to @code{apropos} looks like this:
@deffn Command super-apropos regexp &optional do-all
This function differs from @code{apropos} in that it searches
documentation strings as well as symbol names for matches for
@var{regexp}. By default, it searches the documentation strings only
for preloaded functions and variables. If @var{do-all} is
@var{regexp}. By default, it searches the documentation strings for
preloaded functions and variables only. If @var{do-all} is
non-@code{nil}, it scans the names and documentation strings of all
functions and variables.
@end deffn
@ -495,7 +495,7 @@ Help key, @kbd{C-h}.
@end defvar
@deffn {Prefix Command} help-command
This symbol is not a function; its function definition is actually the
This symbol is not a function; its function definition cell holds the
keymap known as @code{help-map}. It is defined in @file{help.el} as
follows:
@ -617,6 +617,9 @@ The argument @var{help-line} should be a single-line summary of the
alternatives in @var{help-map}. In the current version of Emacs, this
argument is used only if you set the option @code{three-step-help} to
@code{t}.
This macro is used in the command @code{help-for-help} which is the
binding of @kbd{C-h C-h}.
@end defmac
@defopt three-step-help

21
lispref/hooks.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/hooks
@node Standard Hooks, Index, Standard Keymaps, Top
@ -39,22 +39,29 @@ however, we have renamed all of those.)
@item after-init-hook
@item after-insert-file-functions
@item after-make-frame-hook
@item after-revert-hook
@item after-save-hook
@item auto-fill-function
@item auto-save-hook
@item before-change-function
@item before-change-functions
@item before-init-hook
@item before-make-frame-hook
@item before-revert-hook
@item blink-paren-function
@item buffer-access-fontify-functions
@item c-mode-hook
@item calendar-load-hook
@item change-major-mode-hook
@item command-history-hook
@item command-line-functions
@item comment-indent-function
@item deactivate-mark-hook
@item diary-display-hook
@item diary-hook
@item dired-mode-hook
@item disabled-command-hook
@item echo-area-clear-hook
@item edit-picture-hook
@item electric-buffer-menu-mode-hook
@item electric-command-history-hook
@ -69,7 +76,9 @@ however, we have renamed all of those.)
@item ftp-write-file-hook
@item indent-mim-hook
@item initial-calendar-window-hook
@item kill-buffer-hook
@item kill-buffer-query-functions
@item kill-emacs-hook
@item kill-emacs-query-functions
@item LaTeX-mode-hook
@item ledit-mode-hook
@ -77,15 +86,13 @@ however, we have renamed all of those.)
@item lisp-interaction-mode-hook
@item lisp-mode-hook
@item list-diary-entries-hook
@item local-write-file-hooks
@item m2-mode-hook
@item mail-mode-hook
@item mail-setup-hook
@item mark-diary-entries-hook
@item medit-mode-hook
@item mh-compose-letter-hook
@item mh-folder-mode-hook
@item mh-letter-mode-hook
@item mim-mode-hook
@item menu-bar-update-hook
@item minibuffer-setup-hook
@item minibuffer-exit-hook
@item news-mode-hook
@ -102,6 +109,7 @@ however, we have renamed all of those.)
@item print-diary-entries-hook
@item prolog-mode-hook
@item protect-innocence-hook
@item redisplay-end-trigger-functions
@item rmail-edit-mode-hook
@item rmail-mode-hook
@item rmail-summary-mode-hook
@ -122,7 +130,10 @@ however, we have renamed all of those.)
@item today-invisible-calendar-hook
@item vi-mode-hook
@item view-hook
@item window-configuration-change-hook
@item window-scroll-functions
@item window-setup-hook
@item window-size-change-functions
@item write-contents-hooks
@item write-file-hooks
@item write-region-annotate-functions

39
lispref/internals.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/internals
@node GNU Emacs Internals, Standard Errors, Tips, Top
@ -125,8 +125,8 @@ running. It is useful to include this string in bug reports.
@example
@group
(emacs-version)
@result{} "GNU Emacs 19.29.1 (i386-debian-linux) \
of Tue Jun 6 1995 on balloon"
@result{} "GNU Emacs 20.2.5 (i486-pc-linux-gnulibc1, X toolkit)
of Sat Feb 14 1998 on psilocin.gnu.org"
@end group
@end example
@ -148,21 +148,21 @@ emacs-build-time
@defvar emacs-version
The value of this variable is the version of Emacs being run. It is a
string such as @code{"19.29.1"}.
string such as @code{"20.3.1"}. The last number in this string is not
really part of the Emacs release version number; it is incremented each
time you build Emacs in any given directory.
@end defvar
The following two variables did not exist before Emacs version 19.23,
which reduces their usefulness at present, but we hope they will be
convenient in the future.
The following two variables have existed since Emacs version 19.23,
@defvar emacs-major-version
The major version number of Emacs, as an integer. For Emacs version
19.29, the value is 19.
20.2, the value is 20.
@end defvar
@defvar emacs-minor-version
The minor version number of Emacs, as an integer. For Emacs version
19.29, the value is 29.
20.2, the value is 2.
@end defvar
@node Pure Storage, Garbage Collection, Building Emacs, GNU Emacs Internals
@ -294,12 +294,13 @@ information:
(@var{used-markers} . @var{free-markers})
@var{used-string-chars}
@var{used-vector-slots}
(@var{used-floats} . @var{free-floats}))
(@var{used-floats} . @var{free-floats})
(@var{used-intervals} . @var{free-intervals}))
@group
(garbage-collect)
@result{} ((3435 . 2332) (1688 . 0)
(57 . 417) 24510 3839 (4 . 1))
@result{} ((106886 . 13184) (9769 . 0)
(7731 . 4651) 347543 121628
(31 . 94) (1273 . 168))
@end group
@end example
@ -360,7 +361,7 @@ that the subsequent garbage collection does not happen immediately when
the threshold is exhausted, but only the next time the Lisp evaluator is
called.
The initial threshold value is 300,000. If you specify a larger
The initial threshold value is 400,000. If you specify a larger
value, garbage collection will happen less often. This reduces the
amount of time spent garbage collecting, but increases total memory use.
You may want to do this when running a program that creates lots of
@ -609,6 +610,8 @@ DEFUN ("coordinates-in-window-p", Fcoordinates_in_window_p,
|| (XINT (xcoord) >= (XINT (XWINDOW (window)->left)
+ XINT (XWINDOW (window)->width))))
return Qnil;
/* @r{Subtracting from XFASTINT (xcoord) is safe}
@r{as long as we know the result is not negative.} */
XFASTINT (xcoord) -= XFASTINT (XWINDOW (window)->left);
@end group
@group
@ -652,11 +655,11 @@ functions.
@cindex object internals
GNU Emacs Lisp manipulates many different types of data. The actual
data are stored in a heap and the only access that programs have to it is
through pointers. Pointers are thirty-two bits wide in most
data are stored in a heap and the only access that programs have to it
is through pointers. Pointers are thirty-two bits wide in most
implementations. Depending on the operating system and type of machine
for which you compile Emacs, twenty-four to twenty-six bits are used to
address the object, and the remaining six to eight bits are used for a
for which you compile Emacs, twenty-eight bits are used to address the
object, and the remaining four bits are used for a GC mark bit and the
tag that identifies the object's type.
Because Lisp objects are represented as tagged pointers, it is always

4
lispref/intro.texi
View file

@ -425,7 +425,7 @@ describe features of Emacs Lisp that have counterparts in many
programming languages, and later chapters describe features that are
peculiar to Emacs Lisp or relate specifically to editing.
This is edition 2.4.
This is edition 2.5.
@menu
* Caveats:: Flaws and a request for help.
@ -662,7 +662,7 @@ the echo area.
@example
(+ 23 'x)
@error{} Wrong type argument: integer-or-marker-p, x
@error{} Wrong type argument: number-or-marker-p, x
@end example
@node Buffer Text Notation

345
lispref/keymaps.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/keymaps
@node Keymaps, Modes, Command Loop, Top
@ -9,10 +9,10 @@
The bindings between input events and commands are recorded in data
structures called @dfn{keymaps}. Each binding in a keymap associates
(or @dfn{binds}) an individual event type either with another keymap or
with a command. When an event is bound to a keymap, that keymap is
used to look up the next input event; this continues until a command
is found. The whole process is called @dfn{key lookup}.
(or @dfn{binds}) an individual event type either to another keymap or to
a command. When an event type is bound to a keymap, that keymap is used
to look up the next input event; this continues until a command is
found. The whole process is called @dfn{key lookup}.
@menu
* Keymap Terminology:: Definitions of terms pertaining to keymaps.
@ -29,7 +29,7 @@ is found. The whole process is called @dfn{key lookup}.
* Changing Key Bindings:: Redefining a key in a keymap.
* Key Binding Commands:: Interactive interfaces for redefining keys.
* Scanning Keymaps:: Looking through all keymaps, for printing help.
* Menu Keymaps:: A keymap can define a menu.
* Menu Keymaps:: Defining a menu as a keymap.
@end menu
@node Keymap Terminology
@ -72,16 +72,17 @@ details.
The rule for finding the binding of a key sequence assumes that the
intermediate bindings (found for the events before the last) are all
keymaps; if this is not so, the sequence of events does not form a
unit---it is not really a key sequence. In other words, removing one or
more events from the end of any valid key must always yield a prefix
key. For example, @kbd{C-f C-n} is not a key; @kbd{C-f} is not a prefix
key, so a longer sequence starting with @kbd{C-f} cannot be a key.
unit---it is not really one key sequence. In other words, removing one
or more events from the end of any valid key sequence must always yield
a prefix key. For example, @kbd{C-f C-n} is not a key sequence;
@kbd{C-f} is not a prefix key, so a longer sequence starting with
@kbd{C-f} cannot be a key sequence.
Note that the set of possible multi-event key sequences depends on the
bindings for prefix keys; therefore, it can be different for different
keymaps, and can change when bindings are changed. However, a one-event
sequence is always a key sequence, because it does not depend on any
prefix keys for its well-formedness.
The set of possible multi-event key sequences depends on the bindings
for prefix keys; therefore, it can be different for different keymaps,
and can change when bindings are changed. However, a one-event sequence
is always a key sequence, because it does not depend on any prefix keys
for its well-formedness.
At any time, several primary keymaps are @dfn{active}---that is, in
use for finding key bindings. These are the @dfn{global map}, which is
@ -105,47 +106,51 @@ remaining elements of the list define the key bindings of the keymap.
Use the function @code{keymapp} (see below) to test whether an object is
a keymap.
Each ordinary binding applies to events of a particular @dfn{event
type}, which is always a character or a symbol. @xref{Classifying
Events}.
Several kinds of elements may appear in a keymap, after the symbol
@code{keymap} that begins it:
An ordinary element of a keymap is a cons cell of the form
@code{(@var{type} .@: @var{binding})}. This specifies one binding, for
events of type @var{type}.
@table @code
@item (@var{type} .@: @var{binding})
This specifies one binding, for events of type @var{type}. Each
ordinary binding applies to events of a particular @dfn{event type},
which is always a character or a symbol. @xref{Classifying Events}.
@item (t .@: @var{binding})
@cindex default key binding
@c Emacs 19 feature
A cons cell whose @sc{car} is @code{t} is a @dfn{default key binding};
any event not bound by other elements of the keymap is given
@var{binding} as its binding. Default bindings allow a keymap to bind
all possible event types without having to enumerate all of them. A
keymap that has a default binding completely masks any lower-precedence
keymap.
This specifies a @dfn{default key binding}; any event not bound by other
elements of the keymap is given @var{binding} as its binding. Default
bindings allow a keymap to bind all possible event types without having
to enumerate all of them. A keymap that has a default binding
completely masks any lower-precedence keymap.
If an element of a keymap is a vector, the vector counts as bindings
for all the @sc{ASCII} characters; vector element @var{n} is the binding
for the character with code @var{n}. This is a compact way to
record lots of bindings. A keymap with such a vector is called a
@dfn{full keymap}. Other keymaps are called @dfn{sparse keymaps}.
@item @var{vector}
If an element of a keymap is a vector, the vector counts as bindings for
all the @sc{ASCII} characters; vector element @var{n} is the binding for
the character with code @var{n}. This is a compact way to record lots
of bindings. A keymap with such a vector is called a @dfn{full keymap}.
Other keymaps are called @dfn{sparse keymaps}.
When a keymap contains a vector, it always defines a binding for every
@sc{ASCII} character even if the vector element is @code{nil}. Such a
binding of @code{nil} overrides any default binding in the keymap.
However, default bindings are still meaningful for events that are not
@sc{ASCII} characters. A binding of @code{nil} does @emph{not}
override lower-precedence keymaps; thus, if the local map gives a
binding of @code{nil}, Emacs uses the binding from the global map.
When a keymap contains a vector, it always defines a binding for each
@sc{ASCII} character, even if the vector contains @code{nil} for that
character. Such a binding of @code{nil} overrides any default binding
in the keymap. However, default bindings are still meaningful for
events that are not @sc{ASCII} characters. A binding of @code{nil} does
@emph{not} override lower-precedence keymaps; thus, if the local map
gives a binding of @code{nil}, Emacs uses the binding from the global
map.
@item @var{string}
@cindex keymap prompt string
@cindex overall prompt string
@cindex prompt string of keymap
Aside from bindings, a keymap can also have a string as an element.
Aside from bindings, a keymap can also have a string as an element.
This is called the @dfn{overall prompt string} and makes it possible to
use the keymap as a menu. @xref{Menu Keymaps}.
@end table
@cindex meta characters lookup
Keymaps do not directly record bindings for the meta characters, whose
codes are from 128 to 255. Instead, meta characters are regarded for
Keymaps do not directly record bindings for the meta characters.
Instead, meta characters are regarded for
purposes of key lookup as sequences of two characters, the first of
which is @key{ESC} (or whatever is currently the value of
@code{meta-prefix-char}). Thus, the key @kbd{M-a} is really represented
@ -207,7 +212,7 @@ otherwise. More precisely, this function tests for a list whose
Here we describe the functions for creating keymaps.
@c ??? This should come after makr-sparse-keymap
@c ??? This should come after make-sparse-keymap
@defun make-keymap &optional prompt
This function creates and returns a new full keymap (i.e., one
containing a vector of length 128 for defining all the @sc{ASCII}
@ -327,49 +332,55 @@ from @code{text-mode-map}:
@section Prefix Keys
@cindex prefix key
A @dfn{prefix key} has an associated keymap that defines what to do
with key sequences that start with the prefix key. For example,
@kbd{C-x} is a prefix key, and it uses a keymap that is also stored in
the variable @code{ctl-x-map}. Here is a list of the standard prefix
keys of Emacs and their keymaps:
A @dfn{prefix key} is a key sequence whose binding is a keymap. The
keyamp defines what to do with key sequences that extend the prefix key.
For example, @kbd{C-x} is a prefix key, and it uses a keymap that is
also stored in the variable @code{ctl-x-map}. This keymap defines
bindings for key sequences starting with @kbd{C-x}.
Here is a list of the standard prefix keys of Emacs and their keymaps:
@itemize @bullet
@item
@vindex esc-map
@findex ESC-prefix
@code{esc-map} is used for events that follow @key{ESC}. Thus, the
global definitions of all meta characters are actually found here. This
map is also the function definition of @code{ESC-prefix}.
@code{esc-map} is the global keymap for the @key{ESC} prefix key. Thus,
the global definitions of all meta characters are actually found here.
This map is also the function definition of @code{ESC-prefix}.
@item
@cindex @kbd{C-h}
@code{help-map} is used for events that follow @kbd{C-h}.
@code{help-map} is the global definitions for the @kbd{C-h} prefix key.
@item
@cindex @kbd{C-c}
@vindex mode-specific-map
@code{mode-specific-map} is for events that follow @kbd{C-c}. This
map is not actually mode specific; its name was chosen to be informative
for the user in @kbd{C-h b} (@code{display-bindings}), where it
describes the main use of the @kbd{C-c} prefix key.
@code{mode-specific-map} is the global keymap for the prefix key
@kbd{C-c}. This map is actually global, not mode-specific, but its name
provides useful information about @kbd{C-c} in the output of @kbd{C-h b}
(@code{display-bindings}), since the main use of this prefix key is for
mode-specific bindings.
@item
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex Control-X-prefix
@code{ctl-x-map} is the map used for events that follow @kbd{C-x}. This
map is also the function definition of @code{Control-X-prefix}.
@code{ctl-x-map} is the global key map used for the @kbd{C-x} prefix
key. This map is found via the function definition of the symbol
@code{Control-X-prefix}.
@item
@cindex @kbd{C-x 4}
@vindex ctl-x-4-map
@code{ctl-x-4-map} is used for events that follow @kbd{C-x 4}.
@code{ctl-x-4-map} is the global keymap used for the @kbd{C-x 4} prefix
key.
@c Emacs 19 feature
@item
@cindex @kbd{C-x 5}
@vindex ctl-x-5-map
@code{ctl-x-5-map} is used for events that follow @kbd{C-x 5}.
@code{ctl-x-5-map} is the global keymap used for the @kbd{C-x 5} prefix
key.
@c Emacs 19 feature
@item
@ -377,15 +388,15 @@ map is also the function definition of @code{Control-X-prefix}.
@cindex @kbd{C-x r}
@cindex @kbd{C-x a}
The prefix keys @kbd{C-x n}, @kbd{C-x r} and @kbd{C-x a} use keymaps
that have no special name.
that have no special names.
@end itemize
The binding of a prefix key is the keymap to use for looking up the
events that follow the prefix key. (It may instead be a symbol whose
function definition is a keymap. The effect is the same, but the symbol
serves as a name for the prefix key.) Thus, the binding of @kbd{C-x} is
the symbol @code{Control-X-prefix}, whose function definition is the
keymap for @kbd{C-x} commands. (The same keymap is also the value of
The keymap binding of a prefix key is used for looking up the event
that follows the prefix key. (It may instead be a symbol whose function
definition is a keymap. The effect is the same, but the symbol serves
as a name for the prefix key.) Thus, the binding of @kbd{C-x} is the
symbol @code{Control-X-prefix}, whose function definition is the keymap
for @kbd{C-x} commands. (The same keymap is also the value of
@code{ctl-x-map}.)
Prefix key definitions can appear in any active keymap. The
@ -428,14 +439,16 @@ active keymap.
@defun define-prefix-command symbol
@cindex prefix command
This function defines @var{symbol} as a prefix command: it creates a
full keymap and stores it as @var{symbol}'s function definition.
Storing the symbol as the binding of a key makes the key a prefix key
that has a name. The function also sets @var{symbol} as a variable, to
have the keymap as its value. It returns @var{symbol}.
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.
In Emacs version 18, only the function definition of @var{symbol} was
set, not the value as a variable.
This function also sets @var{symbol} as a variable, with the keymap as
its value. It returns @var{symbol}.
@c In Emacs version 18, only the function definition of @var{symbol} was
@c set, not the value as a variable.
@end defun
@node Active Keymaps
@ -474,8 +487,7 @@ order of decreasing precedence, until it finds a binding in one of the maps.
maps (one map at a time); if they do not supply a binding for the key,
Emacs searches the local map; if that too has no binding, Emacs then
searches the global map. However, if @code{overriding-local-map} is
non-@code{nil}, Emacs searches that map first, followed by the global
map.
non-@code{nil}, Emacs searches that map first, before the global map.
The procedure for searching a single keymap is called
@dfn{key lookup}; see @ref{Key Lookup}.
@ -580,8 +592,8 @@ enables or disables a minor mode. @xref{Keymaps and Minor Modes}.
Note that elements of @code{minor-mode-map-alist} do not have the same
structure as elements of @code{minor-mode-alist}. The map must be the
@sc{cdr} of the element; a list with the map as the second element will
not do.
@sc{cdr} of the element; a list with the map as the @sc{cadr} will not
do.
What's more, the keymap itself must appear in the @sc{cdr}. It does not
work to store a variable in the @sc{cdr} and make the map the value of
@ -592,8 +604,22 @@ is the order of @code{minor-mode-map-alist}. But you should design
minor modes so that they don't interfere with each other. If you do
this properly, the order will not matter.
See also @code{minor-mode-key-binding}, above. See @ref{Keymaps and
Minor Modes}, for more information about minor modes.
See @ref{Keymaps and Minor Modes}, for more information about minor
modes. See also @code{minor-mode-key-binding} (@pxref{Functions for Key
Lookup}).
@end defvar
@tindex minor-mode-overriding-map-alist
@defvar minor-mode-overriding-map-alist
This variable allows major modes to override the key bindings for
particular minor modes. The elements of this alist look like the
elements of @code{minor-mode-map-alist}: @code{(@var{variable}
. @var{keymap})}. If a variable has an element
@code{minor-mode-overriding-map-alist}. that map overrides the one in
@code{minor-mode-map-alist}.
@code{minor-mode-overriding-map-alist} is automatically local in all
buffers.
@end defvar
@defvar overriding-local-map
@ -628,6 +654,12 @@ they respond to events that they do not handle by ``unreading'' them and
exiting.
@end defvar
@defvar special-event-map
This variable holds a keymap for special events. If an event type has a
binding in this keymap, then it is special, and the binding for the
event is run directly by @code{read-event}. @xref{Special Events}.
@end defvar
@node Key Lookup
@section Key Lookup
@cindex key lookup
@ -637,13 +669,12 @@ exiting.
sequence from a given keymap. Actual execution of the binding is not
part of key lookup.
Key lookup uses just the event type of each event in the key
sequence; the rest of the event is ignored. In fact, a key sequence
used for key lookup may designate mouse events with just their types
(symbols) instead of with entire mouse events (lists). @xref{Input
Events}. Such a pseudo-key-sequence is insufficient for
@code{command-execute}, but it is sufficient for looking up or rebinding
a key.
Key lookup uses just the event type of each event in the key sequence;
the rest of the event is ignored. In fact, a key sequence used for key
lookup may designate mouse events with just their types (symbols)
instead of with entire mouse events (lists). @xref{Input Events}. Such
a ``key-sequence'' is insufficient for @code{command-execute} to run,
but it is sufficient for looking up or rebinding a key.
When the key sequence consists of multiple events, key lookup
processes the events sequentially: the binding of the first event is
@ -724,7 +755,7 @@ binding of @kbd{Meta-@key{SPC}}, whatever that may be.''
The function definition of @var{symbol} is used in place of
@var{symbol}. If that too is a symbol, then this process is repeated,
any number of times. Ultimately this should lead to an object that is
a keymap, a command or a keyboard macro. A list is allowed if it is a
a keymap, a command, or a keyboard macro. A list is allowed if it is a
keymap or a command, but indirect entries are not understood when found
via symbols.
@ -778,9 +809,10 @@ of @code{emacs-lisp-mode-map}. Note that 9 is the code for @key{TAB},
@defun lookup-key keymap key &optional accept-defaults
This function returns the definition of @var{key} in @var{keymap}. If
the string or vector @var{key} is not a valid key sequence according to
the prefix keys specified in @var{keymap} (which means it is ``too
long'' and has extra events at the end), then the value is a number, the
number of events at the front of @var{key} that compose a complete key.
the prefix keys specified in @var{keymap}, it must be ``too long'' and
have extra events at the end that do not fit into a single key sequence.
Then the value is a number, the number of events at the front of
@var{key} that compose a complete key.
@c Emacs 19 feature
If @var{accept-defaults} is non-@code{nil}, then @code{lookup-key}
@ -878,10 +910,10 @@ variable that enables the minor mode, and @var{binding} is @var{key}'s
binding in that mode. If @var{key} has no minor-mode bindings, the
value is @code{nil}.
If the first binding is not a prefix command, all subsequent bindings
from other minor modes are omitted, since they would be completely
shadowed. Similarly, the list omits non-prefix bindings that follow
prefix bindings.
If the first binding found is not a prefix definition (a keymap or a
symbol defined as a keymap), all subsequent bindings from other minor
modes are omitted, since they would be completely shadowed. Similarly,
the list omits non-prefix bindings that follow prefix bindings.
The argument @var{accept-defaults} controls checking for default
bindings, as in @code{lookup-key} (above).
@ -990,6 +1022,11 @@ keymap) or undefined; otherwise an error is signaled.
If some prefix of @var{key} is undefined, then @code{define-key} defines
it as a prefix key so that the rest of @var{key} may be defined as
specified.
If there was previously no binding for @var{key} in @var{keymap}, the
new binding is added at the beginning of @var{keymap}. The order of
bindings in a keymap makes no difference in most cases, but it does
matter for menu keymaps (@pxref{Menu Keymaps}).
@end defun
Here is an example that creates a sparse keymap and makes a number of
@ -1274,11 +1311,11 @@ local map.
for the sake of printing help information.
@defun accessible-keymaps keymap &optional prefix
This function returns a list of all the keymaps that can be accessed
(via prefix keys) from @var{keymap}. The value is an association list
with elements of the form @code{(@var{key} .@: @var{map})}, where
@var{key} is a prefix key whose definition in @var{keymap} is
@var{map}.
This function returns a list of all the keymaps that can be reached (via
zero or more prefix keys) from @var{keymap}. The value is an
association list with elements of the form @code{(@var{key} .@:
@var{map})}, where @var{key} is a prefix key whose definition in
@var{keymap} is @var{map}.
The elements of the alist are ordered so that the @var{key} increases
in length. The first element is always @code{("" .@: @var{keymap})},
@ -1350,8 +1387,10 @@ These are not all the keymaps you would see in an actual case.
@end defun
@defun where-is-internal command &optional keymap firstonly noindirect
This function returns a list of key sequences (of any length) that are
bound to @var{command} in a set of keymaps.
This function is a subroutine used by the @code{where-is} command
(@pxref{Help, , Help, emacs,The GNU Emacs Manual}). It returns a list
of key sequences (of any length) that are bound to @var{command} in a
set of keymaps.
The argument @var{command} can be any object; it is compared with all
keymap entries using @code{eq}.
@ -1377,9 +1416,6 @@ If @var{noindirect} is non-@code{nil}, @code{where-is-internal} doesn't
follow indirect keymap bindings. This makes it possible to search for
an indirect definition itself.
This function is used by @code{where-is} (@pxref{Help, , Help, emacs,
The GNU Emacs Manual}).
@smallexample
@group
(where-is-internal 'describe-function)
@ -1615,37 +1651,74 @@ for @key{SPC}.
@node Menu Example
@subsection Menu Example
@cindex menu definition example
Here is a simple example of how to set up a menu for mouse use.
Here is a complete example of defining a menu keymap. It is the
definition of the @samp{Print} submenu in the @samp{Tools} menu in the
menu bar. First we create the keymap, and give it a name:
@example
(defvar my-menu-map
(make-sparse-keymap "Key Commands <==> Functions"))
(fset 'help-for-keys my-menu-map)
(define-key my-menu-map [bindings]
'("List all keystroke commands" . describe-bindings))
(define-key my-menu-map [key]
'("Describe key briefly" . describe-key-briefly))
(define-key my-menu-map [key-verbose]
'("Describe key verbose" . describe-key))
(define-key my-menu-map [function]
'("Describe Lisp function" . describe-function))
(define-key my-menu-map [where-is]
'("Where is this command" . where-is))
(define-key global-map [C-S-down-mouse-1] 'help-for-keys)
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
@end example
The symbols used in the key sequences bound in the menu are fictitious
``function keys''; they don't appear on the keyboard, but that doesn't
stop you from using them in the menu. Their names were chosen to be
mnemonic, because they show up in the output of @code{where-is} and
@code{apropos} to identify the corresponding menu items.
Next we define the menu items:
However, if you want the menu to be usable from the keyboard as well,
you must bind real @sc{ASCII} characters as well as fictitious function
keys.
@example
(define-key menu-bar-print-menu [ps-print-region]
'("Postscript Print Region" . ps-print-region-with-faces))
(define-key menu-bar-print-menu [ps-print-buffer]
'("Postscript Print Buffer" . ps-print-buffer-with-faces))
(define-key menu-bar-print-menu [separator-ps-print]
'("--"))
(define-key menu-bar-print-menu [print-region]
'("Print Region" . print-region))
(define-key menu-bar-print-menu [print-buffer]
'("Print Buffer" . print-buffer))
@end example
@noindent
Note the symbols which the bindings are ``made for''; these appear
inside square brackets, in the key sequence being defined. In some
cases, this symbol is the same as the command name; sometimes it is
different. These symbols are treated as ``function keys'', but they are
not real function keys on the keyboard. They do not affect the
functioning of the menu itself, but they are ``echoed'' in the echo area
when the user selects from the menu, and they appear in the output of
@code{where-is} and @code{apropos}.
The binding whose definition is @code{("--")} is a separator line.
Like a real menu item, the separator has a key symbol, in this case
@code{separator-ps-print}. If one menu has two separators, they must
have two different key symbols.
Here is code to define enable conditions for two of the commands in
the menu:
@example
(put 'print-region 'menu-enable 'mark-active)
(put 'ps-print-region-with-faces 'menu-enable 'mark-active)
@end example
Here is how we make this menu appear as an item in the parent menu:
@example
(define-key menu-bar-tools-menu [print]
(cons "Print" menu-bar-print-menu))
@end example
@noindent
Note that this incorporates the submenu keymap, which is the value of
the variable @code{menu-bar-print-menu}, rather than the symbol
@code{menu-bar-print-menu} itself. Using that symbol in the parent menu
item would be meaningless because @code{menu-bar-print-menu} is not a
command.
If you wanted to attach the same print menu to a mouse click, you
might do it this way:
@example
(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
@end example
@node Menu Bar
@subsection The Menu Bar
@ -1743,13 +1816,14 @@ should vary.
When you insert a new item in an existing menu, you probably want to
put it in a particular place among the menu's existing items. If you
use @code{define-key} to add the item, it normally goes at the front of
the menu. To put it elsewhere, use @code{define-key-after}:
the menu. To put it elsewhere in the menu, use @code{define-key-after}:
@defun define-key-after map key binding after
Define a binding in @var{map} for @var{key}, with value @var{binding},
just like @code{define-key}, but position the binding in @var{map} after
the binding for the event @var{after}. The argument @var{key} should
be of length one---a vector or string with just one element.
the binding for the event @var{after}. The argument @var{key} should be
of length one---a vector or string with just one element. But
@var{after} should be an event type---a symbol or a character.
For example,
@ -1762,6 +1836,9 @@ For example,
makes a binding for the fake function key @key{drink} and puts it
right after the binding for @key{eat}.
If @var{after} is @code{t}, then the new binding goes last---at the end
of the keymap.
Here is how to insert an item called @samp{Work} in the @samp{Signals}
menu of Shell mode, after the item @code{break}:

57
lispref/lists.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/lists
@node Lists, Sequences Arrays Vectors, Strings and Characters, Top
@ -327,7 +327,7 @@ If @var{n} is negative, @code{nth} returns the first element of
@defun nthcdr n list
This function returns the @var{n}th @sc{cdr} of @var{list}. In other
words, it removes the first @var{n} links of @var{list} and returns
words, it skips past the first @var{n} links of @var{list} and returns
what follows.
If @var{n} is zero or negative, @code{nthcdr} returns all of
@ -350,6 +350,38 @@ If @var{n} is zero or negative, @code{nthcdr} returns all of
@end example
@end defun
@tindex safe-length
@defun safe-length sequence
This function returns the length of @var{list}, with no risk
of either an error or an infinite loop.
If @var{list} is not really a list, @code{safe-length} returns 0. If
@var{list} is circular, it returns a finite value which is at least the
number of distinct elements.
@end defun
@tindex caar
@defun caar list
This is the same as @code{(car (car @var{list}))}.
@end defun
@tindex cadr
@defun cadr list
This is the same as @code{(car (cdr @var{list}))}
or @code{(nth 1 @var{list})}.
@end defun
@tindex cdar
@defun cdar list
This is the same as @code{(cdr (car @var{list}))}.
@end defun
@tindex cddr
@defun cddr list
This is the same as @code{(cdr (cdr @var{list}))}
or @code{(nthcdr 2 @var{list})}.
@end defun
@node Building Lists
@comment node-name, next, previous, up
@section Building Cons Cells and Lists
@ -439,8 +471,8 @@ elements have the identical value @var{object}. Compare
@cindex copying lists
This function returns a list containing all the elements of
@var{sequences}. The @var{sequences} may be lists, vectors, or strings,
but the last one should be a list. All arguments except the last one
are copied, so none of them are altered.
but the last one should usually be a list. All arguments except the
last one are copied, so none of the arguments is altered.
More generally, the final argument to @code{append} may be any Lisp
object. The final argument is not copied or converted; it becomes the
@ -1002,12 +1034,12 @@ nums
@end example
@noindent
Note that the list in @code{nums} no longer contains 0; this is the same
cons cell that it was before, but it is no longer the first one in the
list. Don't assume a variable that formerly held the argument now holds
the entire sorted list! Instead, save the result of @code{sort} and use
that. Most often we store the result back into the variable that held
the original list:
@strong{Warning}: Note that the list in @code{nums} no longer contains
0; this is the same cons cell that it was before, but it is no longer
the first one in the list. Don't assume a variable that formerly held
the argument now holds the entire sorted list! Instead, save the result
of @code{sort} and use that. Most often we store the result back into
the variable that held the original list:
@example
(setq nums (sort nums '<))
@ -1125,8 +1157,7 @@ and the @code{(4)} in the @code{sample-list} are not @code{eq}:
@end example
The following two functions are like @code{memq} and @code{delq} but use
@code{equal} rather than @code{eq} to compare elements. They are new in
Emacs 19.
@code{equal} rather than @code{eq} to compare elements.
@defun member object list
The function @code{member} tests to see whether @var{object} is a member
@ -1222,7 +1253,7 @@ example:
@noindent
Here we regard @code{red} as the value associated with @code{rose}. One
advantage of this method is that you can store other related
advantage of this kind of alist is that you can store other related
information---even a list of other items---in the @sc{cdr} of the
@sc{cdr}. One disadvantage is that you cannot use @code{rassq} (see
below) to find the element containing a given value. When neither of

95
lispref/loading.texi
View file

@ -1,9 +1,9 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/loading
@node Loading, Byte Compilation, Macros, Top
@node Loading, Byte Compilation, Customization, Top
@chapter Loading
@cindex loading
@cindex library
@ -47,11 +47,11 @@ containing Lisp code.
@section How Programs Do Loading
Emacs Lisp has several interfaces for loading. For example,
@code{autoload} creates a placeholder object for a function in a file;
trying to call the autoloading function loads the file to get the
@code{autoload} creates a placeholder object for a function defined in a
file; trying to call the autoloading function loads the file to get the
function's real definition (@pxref{Autoload}). @code{require} loads a
file if it isn't already loaded (@pxref{Named Features}). Ultimately, all
these facilities call the @code{load} function to do the work.
file if it isn't already loaded (@pxref{Named Features}). Ultimately,
all these facilities call the @code{load} function to do the work.
@defun load filename &optional missing-ok nomessage nosuffix
This function finds and opens a file of Lisp code, evaluates all the
@ -70,7 +70,9 @@ evaluation of @code{(load "foo.el")} will indeed find it.)
If the optional argument @var{nosuffix} is non-@code{nil}, then the
suffixes @samp{.elc} and @samp{.el} are not tried. In this case, you
must specify the precise file name you want.
must specify the precise file name you want. By specifying the precise
file name and using @code{t} for @var{nosuffix}, you can prevent
perverse file names such as @file{foo.el.el} from being tried.
If @var{filename} is a relative file name, such as @file{foo} or
@file{baz/foo.bar}, @code{load} searches for the file using the variable
@ -108,22 +110,17 @@ See below.
@code{load} returns @code{t} if the file loads successfully.
@end defun
@ignore
@deffn Command load-file filename
This function loads the file @var{filename}. If @var{filename} is an
absolute file name, then it is loaded. If it is relative, then the
current default directory is assumed. @code{load-path} is not used, and
suffixes are not appended. Use this function if you wish to specify
the file to be loaded exactly.
This command loads the file @var{filename}. If @var{filename} is a
relative file name, then the current default directory is assumed.
@code{load-path} is not used, and suffixes are not appended. Use this
command if you wish to specify the file to be loaded exactly.
@end deffn
@deffn Command load-library library
This function loads the library named @var{library}. A library is
nothing more than a file that may be loaded as described earlier. This
function is identical to @code{load}, save that it reads a file name
interactively with completion.
This command loads the library named @var{library}. It is equivalent to
@code{load}, except in how it reads its argument interactively.
@end deffn
@end ignore
@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
@ -238,6 +235,22 @@ functions should use @code{read}.
To learn how @code{load} is used to build Emacs, see @ref{Building Emacs}.
@deffn Command locate-library library &optional nosuffix path interactive-call
This command finds the precise file name for library @var{library}. It
searches for the library in the same way @code{load} does, and the
argument @var{nosuffix} has the same meaning as in @code{load}: don't
add suffixes @samp{.elc} or @samp{.el} to the specified name
@var{library}.
If the @var{path} is non-@code{nil}, that list of directories is used
instead of @code{load-path}.
When @code{locate-library} is called from a program, it returns the file
name as a string. When the user runs @code{locate-library}
interactively, the argument @var{interactive-call} is @code{t}, and this
tells @code{locate-library} to display the file name in the echo area.
@end deffn
@node Autoload
@section Autoload
@cindex autoload
@ -263,8 +276,13 @@ This function defines the function (or macro) named @var{function} so as
to load automatically from @var{filename}. The string @var{filename}
specifies the file to load to get the real definition of @var{function}.
If @var{filename} does not contain either a directory name, or the
suffix @code{.el} or @code{.elc}, then @code{autoload} insists on adding
one of these suffixes, and it will not load from a file whose name is
just @var{filename} with no added suffix.
The argument @var{docstring} is the documentation string for the
function. Normally, this is the identical to the documentation string
function. Normally, this should be identical to the documentation string
in the function definition itself. Specifying the documentation string
in the call to @code{autoload} makes it possible to look at the
documentation without loading the function's real definition.
@ -272,7 +290,7 @@ documentation without loading the function's real definition.
If @var{interactive} is non-@code{nil}, then the function can be called
interactively. This lets completion in @kbd{M-x} work without loading
the function's real definition. The complete interactive specification
need not be given here; it's not needed unless the user actually calls
is not given here; it's not needed unless the user actually calls
@var{function}, and when that happens, it's time to load the real
definition.
@ -310,9 +328,10 @@ For example,
@noindent
In this case, @code{"prolog"} is the name of the file to load, 169681
refers to the documentation string in the @file{emacs/etc/DOC} file
(@pxref{Documentation Basics}), @code{t} means the function is
interactive, and @code{nil} that it is not a macro or a keymap.
refers to the documentation string in the
@file{emacs/etc/DOC-@var{version}} file (@pxref{Documentation Basics}),
@code{t} means the function is interactive, and @code{nil} that it is
not a macro or a keymap.
@end defun
@cindex autoload errors
@ -389,16 +408,17 @@ version; you can do this by reloading the file it came from.
When you load or reload files, bear in mind that the @code{load} and
@code{load-library} functions automatically load a byte-compiled file
rather than a non-compiled file of similar name. If you rewrite a file
that you intend to save and reinstall, remember to byte-compile it if
necessary; otherwise you may find yourself inadvertently reloading the
older, byte-compiled file instead of your newer, non-compiled file!
that you intend to save and reinstall, you need to byte-compile the new
version; otherwise Emacs will load the older, byte-compiled file instead
of your newer, non-compiled file! If that happens, the message
displayed when loading the file says, ``(compiled; source is newer'', to
remind you to recompile.
When writing the forms in a Lisp library file, keep in mind that the
file might be loaded more than once. For example, the choice of
@code{defvar} vs.@: @code{defconst} for defining a variable depends on
whether it is desirable to reinitialize the variable if the library is
reloaded: @code{defconst} does so, and @code{defvar} does not.
(@xref{Defining Variables}.)
file might be loaded more than once. For example, think about whether
each variable should be reinitialized when you reload the library;
@code{defvar} does not change the value if the variable is already
initialized. (@xref{Defining Variables}.)
The simplest way to add an element to an alist is like this:
@ -552,10 +572,15 @@ error in the evaluating its contents, any function definitions or
@defun require feature &optional filename
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below). If it
is not, then @code{require} loads @var{filename} with @code{load}. If
@var{filename} is not supplied, then the name of the symbol
@var{feature} is used as the file name to load.
Emacs session (using @code{(featurep @var{feature})}; see below). The
argument @var{feature} must be a symbol.
If the feature is not present, then @code{require} loads @var{filename}
with @code{load}. If @var{filename} is not supplied, then the name of
the symbol @var{feature} is used as the base file name to load.
However, in this case, @code{require} insists on finding @var{feature}
with an added suffix; a file whose name is just @var{feature} won't be
used.
If loading the file fails to provide @var{feature}, @code{require}
signals an error, @samp{Required feature @var{feature} was not

50
lispref/macros.texi
View file

@ -1,9 +1,9 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/macros
@node Macros, Loading, Functions, Top
@node Macros, Customization, Functions, Top
@chapter Macros
@cindex macros
@ -153,12 +153,13 @@ intended for the macro, but executes at full compiled speed. This would
not work if the macro body computed the value and side effects
itself---they would be computed at compile time, which is not useful.
In order for compilation of macro calls to work, the macros must be
defined in Lisp when the calls to them are compiled. The compiler has a
special feature to help you do this: if a file being compiled contains a
@code{defmacro} form, the macro is defined temporarily for the rest of
the compilation of that file. To use this feature, you must define the
macro in the same file where it is used and before its first use.
In order for compilation of macro calls to work, the macros must
already be defined in Lisp when the calls to them are compiled. The
compiler has a special feature to help you do this: if a file being
compiled contains a @code{defmacro} form, the macro is defined
temporarily for the rest of the compilation of that file. To make this
feature work, you must put the @code{defmacro} in the same file where it
is used, and before its first use.
Byte-compiling a file executes any @code{require} calls at top-level
in the file. This is in case the file needs the required packages for
@ -242,11 +243,27 @@ argument of @samp{,} and puts the value in the list structure:
`(a list of ,(+ 2 3) elements)
@result{} (a list of 5 elements)
@end group
@end example
Substitution with @samp{,} is allowed at deeper levels of the list
structure also. For example:
@example
@group
(defmacro t-becomes-nil (variable)
`(if (eq ,variable t)
(setq ,variable nil)))
@end group
@group
(t-becomes-nil foo)
@equiv{} (if (eq foo t) (setq foo nil))
@end group
@end example
@findex ,@@ @r{(with Backquote)}
@cindex splicing (with backquote)
You can also @dfn{splice} an evaluated value into the resulting list,
You can also @dfn{splice} an evaluated value into the resulting list,
using the special marker @samp{,@@}. The elements of the spliced list
become elements at the same level as the other elements of the resulting
list. The equivalent code without using @samp{`} is often unreadable.
@ -291,8 +308,8 @@ and the following expression. The old syntax required whitespace
between the @samp{`}, @samp{,} or @samp{,@@} and the following
expression.
This syntax is still accepted, but no longer recommended except for
compatibility with old Emacs versions.
This syntax is still accepted, for compatibility with old Emacs
versions, but we recommend not using it in new programs.
@end quotation
@node Problems with Macros
@ -488,14 +505,14 @@ in expressions ordinarily.
@node Eval During Expansion
@subsection Evaluating Macro Arguments in Expansion
Another problem can happen if you evaluate any of the macro argument
expressions during the computation of the expansion, such as by calling
Another problem can happen if you the macro definition itself
evaluates any of the macro argument expressions, such as by calling
@code{eval} (@pxref{Eval}). If the argument is supposed to refer to the
user's variables, you may have trouble if the user happens to use a
variable with the same name as one of the macro arguments. Inside the
macro body, the macro argument binding is the most local binding of this
variable, so any references inside the form being evaluated do refer
to it. Here is an example:
variable, so any references inside the form being evaluated do refer to
it. Here is an example:
@example
@group
@ -528,7 +545,8 @@ exist.
The safe way to work with the run-time value of an expression is to
put the expression into the macro expansion, so that its value is
computed as part of executing the expansion.
computed as part of executing the expansion. This is what the other
examples in this chapter do.
@node Repeated Expansion
@subsection How Many Times is the Macro Expanded?

43
lispref/markers.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/markers
@node Markers, Text, Positions, Top
@ -17,7 +17,9 @@ deleted, so that it stays with the two characters on either side of it.
* Predicates on Markers:: Testing whether an object is a marker.
* Creating Markers:: Making empty markers or markers at certain places.
* Information from Markers:: Finding the marker's buffer or character position.
* Changing Markers:: Moving the marker to a new buffer or position.
* Marker Insertion Types:: Two ways a marker can relocate when you
insert where it points.
* Moving Markers:: Moving the marker to a new buffer or position.
* The Mark:: How ``the mark'' is implemented with a marker.
* The Region:: How to access ``the region''.
@end menu
@ -197,13 +199,16 @@ chapter.
@end example
@end defun
@defun copy-marker marker-or-integer
@defun copy-marker marker-or-integer insertion-type
If passed a marker as its argument, @code{copy-marker} returns a
new marker that points to the same place and the same buffer as does
@var{marker-or-integer}. If passed an integer as its argument,
@code{copy-marker} returns a new marker that points to position
@var{marker-or-integer} in the current buffer.
The new marker's insertion type is specified by the argument
@var{insertion-type}. @xref{Marker Insertion Types}.
If passed an integer argument less than 1, @code{copy-marker} returns a
new marker that points to the beginning of the current buffer. If
passed an integer argument greater than the length of the buffer,
@ -294,8 +299,30 @@ This function returns the buffer that @var{marker} points into, or
@code{eq}) to each other if they have the same position and buffer, or
if they both point nowhere.
@node Changing Markers
@section Changing Marker Positions
@node Marker Insertion Types
@section Marker Insertion Types
@cindex insertion type of a marker
When you insert text directly at the place where a marker points,
there are two possible ways to relocate that marker: it can point before
the inserted text, or point after it. You can specify which one a given
marker should do by setting its @dfn{insertion type}.
@tindex set-marker-insertion-type
@defun set-marker-insertion-type marker type
This function sets the insertion type of marker @var{marker} to
@var{type}. If @var{type} is @code{t}, @var{marker} will advances when
text is inserted at it. If @var{type} is @code{nil}, @var{marker} does
not advance when text is inserted there.
@end defun
@tindex marker-insertion-type
@defun marker-insertion-type marker
This function reports the current insertion type of @var{marker}.
@end defun
@node Moving Markers
@section Moving Marker Positions
This section describes how to change the position of an existing
marker. When you do this, be sure you know whether the marker is used
@ -521,9 +548,9 @@ is always local in each buffer.
@defvar activate-mark-hook
@defvarx deactivate-mark-hook
These normal hooks are run, respectively, when the mark becomes active
and when it becomes inactive. The hook @code{activate-mark-hook} is also
run at the end of a command if the mark is active and the region may
have changed.
and when it becomes inactive. The hook @code{activate-mark-hook} is
also run at the end of a command if the mark is active and it is
possible that the region may have changed.
@end defvar
@defvar mark-ring

152
lispref/minibuf.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/minibuf
@node Minibuffers, Command Loop, Read and Print, Top
@ -25,6 +25,7 @@ use for reading an argument.
* Completion:: How to invoke and customize completion.
* Yes-or-No Queries:: Asking a question with a simple answer.
* Multiple Queries:: Asking a series of similar questions.
* Reading a Password:: Function for reading a password.
* Minibuffer Misc:: Various customization hooks and variables.
@end menu
@ -92,7 +93,7 @@ middle of a Lisp function. Instead, do all minibuffer input as part of
reading the arguments for a command, in the @code{interactive} spec.
@xref{Defining Commands}.
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist
@defun read-from-minibuffer prompt-string &optional initial-contents keymap read hist default inherit-input-method
This function is the most general way to get input through the
minibuffer. By default, it accepts arbitrary text and returns it as a
string; however, if @var{read} is non-@code{nil}, then it uses
@ -107,6 +108,13 @@ Then, if @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end. The
minibuffer appears with this text as its contents.
@strong{Usage note:} The @var{initial-contents} argument and the
@var{default} argument are two alternative features for the same job.
It usually does not make sense to use both at once. In most cases, you
should use @var{default}, since this permits the user to insert the
default value but does not burden the user with deleting it from the
minibuffer.
@c Emacs 19 feature
The value of @var{initial-contents} may also be a cons cell of the form
@code{(@var{string} . @var{position})}. This means to insert
@ -130,26 +138,58 @@ text. However, if @var{read} is non-@code{nil},
@code{read-from-minibuffer} reads the text and returns the resulting
Lisp object, unevaluated. (@xref{Input Functions}, for information
about reading.)
If the variable @code{minibuffer-allow-text-properties} is
non-@code{nil}, then the string which is returned includes whatever text
properties were present in the minibuffer. Otherwise all the text
properties are stripped when the value is returned.
The argument @var{default} specifies a default value to make available
through the history list. It should be a string, or @code{nil}. If
@var{read} is non-@code{nil}, then @var{default} is passed through
@code{read}, just as ordinary user input would be. Unlike many other
minibuffer functions, this function does @emph{not} return @var{default}
if the user enters empty input. It returns @code{""} in that case.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer.
@end defun
@defun read-string prompt &optional initial
@defun read-string prompt &optional initial history default inherit-input-method
This function reads a string from the minibuffer and returns it. The
arguments @var{prompt} and @var{initial} are used as in
@code{read-from-minibuffer}. The keymap used is
@code{minibuffer-local-map}.
This is a simplified interface to the
The optional argument @var{history}, if non-nil, specifies a history
list and optionally the initial position in the list. The optional
argument @var{default} specifies a default value to return if the user
enters null input; it should be a string. The optional argument
@var{inherit-input-method} specifies whether to inherit the current
buffer's input method.
This function is a simplified interface to the
@code{read-from-minibuffer} function:
@smallexample
@group
(read-string @var{prompt} @var{initial})
(read-string @var{prompt} @var{initial} @var{history} @var{default} @var{inherit})
@equiv{}
(read-from-minibuffer @var{prompt} @var{initial} nil nil nil)
(read-from-minibuffer @var{prompt} @var{initial} nil nil
@var{history} @var{default} @var{inherit})
@end group
@end smallexample
@end defun
@defvar minibuffer-allow-text-properties
If this variable is non-@code{nil}, then @code{read-from-minibuffer}
strips all text properties from the string before returning the string.
Since all minibuffer input uses @code{read-from-minibuffer}, this
variable applies to all minibuffer input.
@end defvar
@defvar minibuffer-local-map
This is the default local keymap for reading from the minibuffer. By
default, it makes the following bindings:
@ -180,11 +220,11 @@ default, it makes the following bindings:
@c In version 18, initial is required
@c Emacs 19 feature
@defun read-no-blanks-input prompt &optional initial
@defun read-no-blanks-input prompt &optional initial inherit-input-method
This function reads a string from the minibuffer, but does not allow
whitespace characters as part of the input: instead, those characters
terminate the input. The arguments @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}.
terminate the input. The arguments @var{prompt}, @var{initial}, and
@var{inherit-input-method} are used as in @code{read-from-minibuffer}.
This is a simplified interface to the @code{read-from-minibuffer}
function, and passes the value of the @code{minibuffer-local-ns-map}
@ -228,7 +268,7 @@ following bindings, in addition to those of @code{minibuffer-local-map}:
minibuffer.
@defun read-minibuffer prompt &optional initial
This function reads a Lisp object in the minibuffer and returns it,
This function reads a Lisp object using the minibuffer, and returns it
without evaluating it. The arguments @var{prompt} and @var{initial} are
used as in @code{read-from-minibuffer}.
@ -267,9 +307,9 @@ default, or can edit the input.
@end defun
@defun eval-minibuffer prompt &optional initial
This function reads a Lisp expression in the minibuffer, evaluates it,
then returns the result. The arguments @var{prompt} and @var{initial}
are used as in @code{read-from-minibuffer}.
This function reads a Lisp expression using the minibuffer, evaluates
it, then returns the result. The arguments @var{prompt} and
@var{initial} are used as in @code{read-from-minibuffer}.
This function simply evaluates the result of a call to
@code{read-minibuffer}:
@ -294,7 +334,7 @@ appear in the initial text. @xref{Output Functions}.
The first thing @code{edit-and-eval-command} does is to activate the
minibuffer with @var{prompt} as the prompt. Then it inserts the printed
representation of @var{form} in the minibuffer, and lets the user edit.
representation of @var{form} in the minibuffer, and lets the user edit it.
When the user exits the minibuffer, the edited text is read with
@code{read} and then evaluated. The resulting value becomes the value
of @code{edit-and-eval-command}.
@ -581,7 +621,7 @@ non-@code{nil}, Emacs does not consider case significant in completion.
This section describes the basic interface for reading from the
minibuffer with completion.
@defun completing-read prompt collection &optional predicate require-match initial hist
@defun completing-read prompt collection &optional predicate require-match initial hist default inherit-input-method
This function reads a string in the minibuffer, assisting the user by
providing completion. It activates the minibuffer with prompt
@var{prompt}, which must be a string. If @var{initial} is
@ -593,12 +633,16 @@ The actual completion is done by passing @var{collection} and
@var{predicate} to the function @code{try-completion}. This happens in
certain commands bound in the local keymaps used for completion.
If @var{require-match} is @code{t}, the usual minibuffer exit commands
won't exit unless the input completes to an element of @var{collection}.
If @var{require-match} is neither @code{nil} nor @code{t}, then the exit
commands won't exit unless the input typed is itself an element of
@var{collection}. If @var{require-match} is @code{nil}, the exit
commands work regardless of the input in the minibuffer.
If @var{require-match} is @code{nil}, the exit commands work regardless
of the input in the minibuffer. If @var{require-match} is @code{t}, the
usual minibuffer exit commands won't exit unless the input completes to
an element of @var{collection}. If @var{require-match} is neither
@code{nil} nor @code{t}, then the exit commands won't exit unless the
input already in the buffer matches an element of @var{collection}.
However, empty input is always permitted, regardless of the value of
@var{require-match}; in that case, @code{completing-read} returns
@var{default}.
The user can exit with null input by typing @key{RET} with an empty
minibuffer. Then @code{completing-read} returns @code{""}. This is how
@ -617,6 +661,15 @@ The argument @var{hist} specifies which history list variable to use for
saving the input and for minibuffer history commands. It defaults to
@code{minibuffer-history}. @xref{Minibuffer History}.
The optional argument @var{default} specifies a default value to return
if the user enters null input; it should be a string.
If the argument @var{inherit-input-method} is non-@code{nil}, then the
minibuffer inherits the current input method and the setting of
@code{enable-multibyte-characters} from whichever buffer was current
before entering the minibuffer. @xref{Input Methods,,, emacs, The GNU
Emacs Manual}.
Completion ignores case when comparing the input against the possible
matches, if the built-in variable @code{completion-ignore-case} is
non-@code{nil}. @xref{Basic Completion}.
@ -835,13 +888,26 @@ Buffer name? (default foo) @point{}
@end example
@end defun
@defun read-command prompt
@defvar read-buffer-function
This variable specifies how to read buffer names. For example, if you
set this variable to @code{iswitchb-read-buffer}, all Emacs commands
that call @code{read-buffer} to read a buffer name will actually use the
@code{iswitchb} package to read it.
@end defvar
@defun read-command prompt &optional default
This function reads the name of a command and returns it as a Lisp
symbol. The argument @var{prompt} is used as in
@code{read-from-minibuffer}. Recall that a command is anything for
which @code{commandp} returns @code{t}, and a command name is a symbol
for which @code{commandp} returns @code{t}. @xref{Interactive Call}.
The argument @var{default} specifies what to return if the user enters
null input. It can be a symbol or a string, but the value returned by
@code{read-command} is always a symbol. If @var{default} is @code{nil},
that means no default has been specified; then if the user enters null
input, the return value is @code{nil}.
@example
(read-command "Command name? ")
@ -877,10 +943,16 @@ complete in the set of extant Lisp symbols, and it uses the
@end example
@end defun
@defun read-variable prompt
@defun read-variable prompt &optional default
This function reads the name of a user variable and returns it as a
symbol.
The argument @var{default} specifies what to return if the user enters
null input. It can be a symbol or a string, but the value returned by
@code{read-variable} is always a symbol. If @var{default} is
@code{nil}, that means no default has been specified; then if the user
enters null input, the return value is @code{nil}.
@example
@group
(read-variable "Variable name? ")
@ -916,6 +988,22 @@ predicate @code{user-variable-p} instead of @code{commandp}:
@end example
@end defun
@tindex read-coding-system
@defun read-coding-system prompt default
This function reads a coding system using the minibuffer, prompting with
string @var{prompt}, and returns the coding system name as a symbol. If
the user tries to enter null input, it asks the user to try again.
@xref{Coding Systems}.
@end defun
@tindex read-non-nil-coding-system
@defun read-non-nil-coding-system prompt
This function reads a coding system using the minibuffer, prompting with
string @var{prompt},and returns the coding system name as a symbol. If
the user enters null input, it returns @var{default-coding-system}.
which should be a symbol or a string. @xref{Coding Systems}.
@end defun
@node Reading File Names
@subsection Reading File Names
@ -1244,8 +1332,8 @@ convenient facilities such as the ability to answer the whole series at
once.
@defun map-y-or-n-p prompter actor list &optional help action-alist
This function, new in Emacs 19, asks the user a series of questions,
reading a single-character answer in the echo area for each one.
This function asks the user a series of questions, reading a
single-character answer in the echo area for each one.
The value of @var{list} specifies the objects to ask questions about.
It should be either a list of objects or a generator function. If it is
@ -1323,8 +1411,20 @@ value around the call.
The return value of @code{map-y-or-n-p} is the number of objects acted on.
@end defun
@node Reading a Password
@section Reading a Password
This function is useful for reading passwords.
@tindex read-password
@defun read-password prompt default
This function reads a password, echoing @samp{.} in the echo area
for each character entered, and returns it as a string. It prompts
with @var{prompt}, and returns @var{default} if the user enters the
null string.
@end defun
@node Minibuffer Misc
@comment node-name, next, previous, up
@section Minibuffer Miscellany
This section describes some basic functions and variables related to

743
lispref/modes.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/modes
@node Modes, Documentation, Keymaps, Top
@ -22,6 +22,9 @@ user. For related topics such as keymaps and syntax tables, see
* Major Modes:: Defining major modes.
* Minor Modes:: Defining minor modes.
* Mode Line Format:: Customizing the text that appears in the mode line.
* Imenu:: How a mode can provide a menu
of definitions in the buffer.
* Font Lock Mode:: How modes can highlight text according to syntax.
* Hooks:: How to use hooks; how to write code that provides hooks.
@end menu
@ -68,9 +71,9 @@ Using alternative major modes avoids this limitation. @xref{Recursive
Editing}.
The standard GNU Emacs Lisp library directory contains the code for
several major modes, in files including @file{text-mode.el},
several major modes, in files such as @file{text-mode.el},
@file{texinfo.el}, @file{lisp-mode.el}, @file{c-mode.el}, and
@file{rmail.el}. You can look at these libraries to see how modes are
@file{rmail.el}. You can study these libraries to see how modes are
written. Text mode is perhaps the simplest major mode aside from
Fundamental mode. Rmail mode is a complicated and specialized mode.
@ -230,8 +233,8 @@ or it may run them earlier.
@item
If something special should be done if the user switches a buffer from
this mode to any other major mode, the mode can set a local value for
@code{change-major-mode-hook}.
this mode to any other major mode, this mode can set up a buffer-local
value for @code{change-major-mode-hook} (see below).
@item
If this mode is appropriate only for specially-prepared text, then the
@ -271,11 +274,11 @@ Even if you never load the file more than once, someone else will.
@end itemize
@defvar change-major-mode-hook
This normal hook is run by @code{kill-all-local-variables} before it
does anything else. This gives major modes a way to arrange for
something special to be done if the user switches to a different major
mode. For best results, make this variable buffer-local, so that it
will disappear after doing its job and will not interfere with the
The function @code{kill-all-local-variables} runs this normal hook
before it does anything else. This gives major modes a way to arrange
for something special to be done if the user switches to a different
major mode. For best results, make this variable buffer-local, so that
it will disappear after doing its job and will not interfere with the
subsequent major mode. @xref{Hooks}.
@end defvar
@ -447,7 +450,7 @@ rest of @code{lisp-mode-variables}.
@end smallexample
Each of the different Lisp modes has a slightly different keymap. For
example, Lisp mode binds @kbd{C-c C-l} to @code{run-lisp}, but the other
example, Lisp mode binds @kbd{C-c C-z} to @code{run-lisp}, but the other
Lisp modes do not. However, all Lisp modes have some commands in
common. The following function adds these common commands to a given
keymap.
@ -592,7 +595,7 @@ standard value is @code{fundamental-mode}.
If the value of @code{default-major-mode} is @code{nil}, Emacs uses
the (previously) current buffer's major mode for the major mode of a new
buffer. However, if the major mode symbol has a @code{mode-class}
buffer. However, if that major mode symbol has a @code{mode-class}
property with value @code{special}, then it is not used for new buffers;
Fundamental mode is used instead. The modes that have this property are
those such as Dired and Rmail that are useful only with text that has
@ -613,15 +616,15 @@ but medium-level commands such as @code{switch-to-buffer} and
@cindex @samp{*scratch*}
The value of this variable determines the major mode of the initial
@samp{*scratch*} buffer. The value should be a symbol that is a major
mode command name. The default value is @code{lisp-interaction-mode}.
mode command. The default value is @code{lisp-interaction-mode}.
@end defvar
@defvar auto-mode-alist
This variable contains an association list of file name patterns
(regular expressions; @pxref{Regular Expressions}) and corresponding
major mode functions. Usually, the file name patterns test for
suffixes, such as @samp{.el} and @samp{.c}, but this need not be the
case. An ordinary element of the alist looks like @code{(@var{regexp} .
major mode commands. Usually, the file name patterns test for suffixes,
such as @samp{.el} and @samp{.c}, but this need not be the case. An
ordinary element of the alist looks like @code{(@var{regexp} .
@var{mode-function})}.
For example,
@ -651,7 +654,7 @@ If an element of @code{auto-mode-alist} has the form @code{(@var{regexp}
name that did not match before.
This match-again feature is useful for uncompression packages: an entry
of the form @code{("\\.gz\\'" . @var{function})} can uncompress the file
of the form @code{("\\.gz\\'" @var{function} t)} can uncompress the file
and then put the uncompressed file in the proper mode according to the
name sans @samp{.gz}.
@ -663,7 +666,7 @@ Here is an example of how to prepend several pattern pairs to
@group
(setq auto-mode-alist
(append
;; @r{File name starts with a dot.}
;; @r{File name (within directory) starts with a dot.}
'(("/\\.[^/]*\\'" . fundamental-mode)
;; @r{File name has no dot.}
("[^\\./]*\\'" . fundamental-mode)
@ -675,12 +678,13 @@ Here is an example of how to prepend several pattern pairs to
@end defvar
@defvar interpreter-mode-alist
This variable specifes major modes to use for scripts that specify a
This variable specifies major modes to use for scripts that specify a
command interpreter in an @samp{#!} line. Its value is a list of
elements of the form @code{(@var{interpreter} . @var{mode})}; for
example, @code{("perl" . perl-mode)} is one element present by default.
The element says to use mode @var{mode} if the file specifies
@var{interpreter}.
an interpreter which matches @var{interpreter}. The value of
@var{interpreter} is actually a regular expression.
This variable is applicable only when the @code{auto-mode-alist} does
not indicate which major mode to use.
@ -814,6 +818,7 @@ keymaps make this easier than it used to be.
@menu
* Minor Mode Conventions:: Tips for writing a minor mode.
* Keymaps and Minor Modes:: How a minor mode can have its own keymap.
* Easy-Mmode:: A convenient facility for defining minor modes.
@end menu
@node Minor Mode Conventions
@ -904,7 +909,7 @@ is enabled. To set up a keymap for a minor mode, add an element to the
alist @code{minor-mode-map-alist}. @xref{Active Keymaps}.
@cindex @code{self-insert-command}, minor modes
One use of minor mode keymaps is to modify the behavior of certain
One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert. In general, this is the only way to do that, since the
facilities for customizing @code{self-insert-command} are limited to
@ -917,6 +922,75 @@ followed by a punctuation character @emph{other than} @kbd{@{},
@kbd{@}}, @kbd{<}, @kbd{>}, @kbd{:} or @kbd{;}. (Those few punctuation
characters are reserved for major modes.)
@node Easy-Mmode
@subsection Easy-Mmode
The easy-mmode package provides a convenient way of implementing a
minor mode; with it, you can specify all about a simple minor mode in
one self-contained definition.
@tindex easy-mmode-define-minor-mode
@defmac easy-mmode-define-minor-mode mode doc &optional init-value mode-indicator keymap
This macro defines a new minor mode whose name is @var{mode} (a symbol).
This macro defines a command named @var{mode} which toggles the minor
mode, and has @var{doc} as its documentation string.
It also defines a variable named @var{mode}, which is set to @code{t} or
@code{nil} by enabling or disabling the mode. The variable is
initialized to @var{init-value}.
The string @var{mode-indicator} says what to display in the mode line
when the mode is enabled; if it is @code{nil}, the mode is not displayed
in the mode line.
The optional argument @var{keymap} specifies the keymap for the minor mode.
It can be a variable name, whose value is the keymap, or it can be an alist
specifying bindings in this form:
@example
(@var{key-sequence} . @var{definition})
@end example
@end defmac
Here is an example of using @code{easy-mmode-define-minor-mode}:
@smallexample
(easy-mmode-define-minor-mode
hungry-mode
"Toggle Hungry mode.
With no argument, this command toggles the mode.
Non-null prefix argument turns on the mode.
Null prefix argument turns off the mode.
When Hungry mode is enabled, the control delete key
gobbles all preceding whitespace except the last.
See the command \\[hungry-electric-delete]."
;; The initial value.
nil
;; The indicator for the mode line.
" Hungry"
;; The minor mode bindings.
'(("\C-\^?" . hungry-electric-delete)
("\C-\M-\^?"
. (lambda ()
(interactive)
(hungry-electric-delete t)))))
@end smallexample
@noindent
This defines a minor mode named ``Hungry mode'', a command named
@code{hungry-mode} to toggle it, a variable named @code{hungry-mode}
which indicates whether the mode is enabled, and a variable named
@code{hungry-mode-map} which holds the keymap that is active when the
mode is enabled. It initializes the keymap with key bindings for
@kbd{C-@key{DEL}} and @kbd{C-M-@key{DEL}}.
The command @code{hungry-mode} also runs three hooks:
@code{hungry-mode-on-hook} when enabling Hungry mode,
@code{hungry-mode-off-hook} when disabling the mode, and
@code{hungry-mode-hook} in both of those cases.
@node Mode Line Format
@section Mode Line Format
@cindex mode line
@ -928,7 +1002,7 @@ name, associated file, depth of recursive editing, and the major and
minor modes.
This section describes how the contents of the mode line are
controlled. It is in the chapter on modes because much of the
controlled. We include it in this chapter because much of the
information displayed in the mode line relates to the enabled major and
minor modes.
@ -942,8 +1016,10 @@ line numbers).
buffer is shown in the window, or when the buffer's modified-status
changes from @code{nil} to @code{t} or vice-versa. If you modify any of
the variables referenced by @code{mode-line-format} (@pxref{Mode Line
Variables}), you may want to force an update of the mode line so as to
display the new information.
Variables}), or any other variables and data structures that affect how
text is displayed (@pxref{Display}), you may want to force an update of
the mode line so as to display the new information or display it in
the new way.
@c Emacs 19 feature
@defun force-mode-line-update
@ -984,9 +1060,9 @@ constructs as their values.
The default value of @code{mode-line-format} incorporates the values
of variables such as @code{mode-name} and @code{minor-mode-alist}.
Because of this, very few modes need to alter @code{mode-line-format}.
For most purposes, it is sufficient to alter the variables referenced by
@code{mode-line-format}.
Because of this, very few modes need to alter @code{mode-line-format}
itself. For most purposes, it is sufficient to alter some of the
variables that @code{mode-line-format} refers to.
A mode line construct may be a list, a symbol, or a string. If the
value is a list, each element may be a list, a symbol, or a string.
@ -1053,7 +1129,11 @@ directory.
'mode-line-modified
"%b--"
@end group
(getenv "HOST") ; @r{One element is not constant.}
@group
;; @r{Note that this is evaluated while making the list.}
;; @r{It makes a mode line construct which is just a string.}
(getenv "HOST")
@end group
":"
'default-directory
" "
@ -1111,8 +1191,8 @@ sets @code{global-mode-string} to refer to the variable
load information.
The @samp{%M} construct substitutes the value of
@code{global-mode-string}, but this is obsolete, since the variable is
included directly in the mode line.
@code{global-mode-string}, but that is obsolete, since the variable is
included in the mode line from @code{mode-line-format}.
@end defvar
@defvar mode-name
@ -1151,9 +1231,9 @@ minor-mode-alist
@end group
@end example
@code{minor-mode-alist} is not buffer-local. The variables mentioned
in the alist should be buffer-local if the minor mode can be enabled
separately in each buffer.
@code{minor-mode-alist} itself is not buffer-local. Each variable
mentioned in the alist should be buffer-local if its minor mode can be
enabled separately in each buffer.
@end defvar
@defvar mode-line-process
@ -1171,24 +1251,30 @@ This variable holds the default @code{mode-line-format} for buffers
that do not override it. This is the same as @code{(default-value
'mode-line-format)}.
The default value of @code{default-mode-line-format} is:
The default value of @code{default-mode-line-format} is this list:
@example
@group
(""
("-"
mode-line-mule-info
mode-line-modified
mode-line-frame-identification
mode-line-buffer-identification
@end group
" "
global-mode-string
@group
" %[("
mode-name
@end group
@group
mode-line-process
minor-mode-alist
"%n"
")%]----"
")%]--"
@end group
@group
(which-func-mode ("" which-func-format "--"))
(line-number-mode "L%l--")
(column-number-mode "C%c--")
(-3 . "%p")
"-%-")
@end group
@ -1293,6 +1379,575 @@ The value of @code{global-mode-string}. Currently, only
@code{display-time} modifies the value of @code{global-mode-string}.
@end table
@node Imenu
@section Imenu
@cindex Imenu
@dfn{Imenu} is a feature that constructs a buffer index for a buffer.
The buffer index contains the names and positions of the definitions or
portions of in the buffer, so the user can pick one of themand move to
it. This section explains how to customize Imenu for a major mode. The
usual and simplest way is to set the variable
@code{imenu-generic-expression}.
@defvar imenu-generic-expression
This variable, if non-@code{nil}, specifies regular expressions for
finding definitions for Imenu. In the simplest case, elements should
look like this:
@example
(@var{menu-title} @var{regexp} @var{subexp})
@end example
Here, if @var{menu-title} is non-@code{nil}, it says that the matches
for this element should go in a submenu of the buffer index;
@var{menu-title} itself specifies the name for the submenu. If
@var{menu-title} is @code{nil}, the matches for this element go directly
in the top level of the buffer index.
The second item in the list, @var{regexp}, is a regular expression
(@pxref{Regular Expressions}); wherever it matches, that is a definition
to be mentioned in the buffer index. The third item, @var{subexp},
indicates which subexpression in @var{regexp} contains the name for the
definition.
An element can also look like this:
@example
(@var{menu-title} @var{regexp} @var{index} @var{function} @var{arguments}@dots{})
@end example
Each match for this element creates a special index item which, if
selected by the user, calls @var{function} with arguments
@var{item-name}, the buffer position, and @var{arguments}.
For Emacs Lisp mode, @var{pattern} could look like this:
@example
@group
((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
@end group
@group
("*Vars*" "^\\s-*(def\\(var\\|const\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2)
@end group
@group
("*Types*"
"^\\s-*(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
@end group
@end example
This variable is local in all buffers, if it is set.
@end defvar
@defvar imenu-case-fold-search
This variable controls whether the regular expression matching for Imenu
is case-sensitive: @code{t}, the default, means matching should ignore
case.
This variable is local in all buffers, if it is set.
@end defvar
Another way to customize Imenu for a major mode is to set the
variables @code{imenu-prev-index-position-function} and
@code{imenu-extract-index-name-function}.
@defvar imenu-prev-index-position-function
If this variable is non-@code{nil}, its value should be a function for
finding the next definition to mention in the buffer index, moving
backwards in the file.
The function should leave point at the place to be connected to the
index item, and it should return @code{nil} when it doesn't find another
item.
This variable is local in all buffers, if it is set.
@end defvar
@defvar imenu-extract-index-name-function
If this variable is non-@code{nil}, its value should be a function to
return the name for a definition, assuming point is at that definition.
This variable is local in all buffers, if it is set.
@end defvar
@defvar imenu-create-index-function
This variable specifies the function to use for creating a buffer index.
The function should take no arguments, and return an index for the
current buffer. It is called within @code{save-excursion}, so where it
leaves point makes no difference.
The default value is a function that uses
@code{imenu-generic-expression} to produce the index alist. If you
specify a different function, then @code{imenu-generic-expression} is
not used.
The variable @code{imenu-create-index-function} is local in all buffers,
if it is set.
@end defvar
@defvar imenu-index-alist
This variable holds the index alist for the current buffer.
It is local in each buffer, once it is set.
Simple elements in the alist look like @code{(@var{index-name}
. @var{index-position})}. Selecting a simple element has the effect of
moving to position @var{index-position} in the buffer.
Special elements look like @code{(@var{index-name} @var{position}
@var{function} @var{arguments}@dots{})}. Selecting a special element
performs
@example
(funcall @var{function} @var{index-name} @var{position} @var{arguments}@dots{})
@end example
A nested sub-alist element looks like @code{(@var{index-name}
@var{sub-alist})}.
@end defvar
@node Font Lock Mode
@section Font Lock Mode
@cindex Font Lock Mode
@dfn{Font Lock mode} is a feature that automatically attaches
@code{face} properties to certain parts of the buffer based on their
syntactic role. How it parses the buffer depends on the major mode;
most major modes define a set of syntactic criteria for which faces to
use, in which contexts. This section explains how to customize Font
Lock for a particular language---in other words, for a particular major
mode.
Font Lock mode finds text to highlight in two ways: through syntactic
parsing based on the syntax table, and through searching (usually for
regular expressions). Syntactic fontification happens first; it finds
comments and string constants, and highlights them using
@code{font-lock-comment-face} and @code{font-lock-string-face}
(@pxref{Faces for Font Lock}: Search-based fontification follows.
@menu
* Font Lock Basics::
* Search-based Fontification::
* Other Font Lock Variables::
* Levels of Font Lock::
* Faces for Font Lock::
@end menu
@node Font Lock Basics
@subsection Font Lock Basics
There are several variables that control how Font Lock mode highlights
text. But major modes should not set any of these variables directly.
Instead, it should set @code{font-lock-defaults} as a local variable.
The value assigned to this variable is used, if and when Font Lock mode
is enabled, to set all the other variables.
@defvar font-lock-defaults
This variable is set by major modes, as a buffer-local variable, to
specify how to fontify text in that mode. The value should look like
this:
@example
(@var{keywords} @var{keywords-only} @var{case-fold}
@var{syntax-alist} @var{syntax-begin} @var{other-vars}@dots{})
@end example
The first element, @var{keywords}, indirectly specifies the value of
@code{font-lock-keywords}. It can be a symbol, a variable whose value
is list to use for @code{font-lock-keywords}. It can also be a list of
several such symbols, one for each possible level of fontification. The
first symbol specifies how to do level 1 fontification, the second
symbol how to do level 2, and so on.
The second element, @var{keywords-only}, specifies the value of the
variable @code{font-lock-keywords-only}. If this is is non-@code{nil},
syntactic fontification (strings and comments) is not performed.
The third element, @var{case-fold}, specifies the value of
@code{font-lock-case-fold-search}. If it is non-@code{nil}, Font Lock
mode ignores case when obeying @code{font-lock-keywords}.
If the fourth element, @var{syntax-alist}, is non-@code{nil}, it should be
a list of cons cells of the form @code{(@var{char-or-string}
. @var{string})}. These are used to set up a syntax table for
fontification (@pxref{Syntax Table Functions}). The resulting syntax
table is stored in @code{font-lock-syntax-table}.
The fifth element, @var{syntax-begin}, specifies the value of
@code{font-lock-beginning-of-syntax-function}. See below for an
explanation of what this value means.
Any further elements @var{other-vars} are have form
@code{(@var{variable} . @var{value})}. This kind of element means to
make @var{variable} buffer-local and then set it to @var{value}. This
is used to set other variables that affect fontification.
@end defvar
@node Search-based Fontification
@subsection Search-based Fontification
The most important variable for customizing Font Lock mode is
@code{font-lock-keywords}. It specifies the search criteria for
search-based fontification.
@defvar font-lock-keywords
This variable's value is a list of the keywords to highlight. Be
careful when composing regexps for this list; a poorly written pattern
can dramatically slow things down!
@end defvar
Each element of @code{font-lock-keywords} specifies how to find
certain cases of text, and how to highlight those cases. An element
should have one of these forms:
@table @code
@item @var{regexp}
Highlight all matches for @var{regexp} using
@code{font-lock-keyword-face}. For example,
@example
;; @r{Highlight discrete occurrences of @samp{foo}}
;; @r{using @code{font-lock-keyword-face}.}
"\\<foo\\>"
@end example
The function @code{regexp-opt} (@pxref{Syntax of Regexps}) is often
useful for calculating complex regular expressions to match a number of
different keywords.
@item @var{function}
Find text by calling @var{function}, and highlight the matches
it finds using @code{font-lock-keyword-face}.
When @var{function} is called, it receives one argument, the limit of
the search. It should return non-@code{nil} if it succeeds, and set the
match data to describe the match that was found.
@item (@var{matcher} . @var{match})
In this kind of element, @var{matcher} stands for either a regular
expression or a function, as described above. The @sc{cdr},
@var{match}, specifies which subexpression of @var{matcher} should be
highlighted (instead of the entire text that matched @var{matcher}).
@example
;; @r{Highlight the @samp{bar} in each occurrences of @samp{fubar},}
;; @r{using @code{font-lock-keyword-face}.}
("fu\\(bar\\)" . 1)
@end example
If you use @code{regexp-opt} to produce a regular expression for
@var{matcher}, then you can use @code{regexp-opt-depth} (@pxref{Syntax
of Regexps}) to calculate the value for @var{match}.
@item (@var{matcher} . @var{facename})
In this kind of element, @var{facename} is an expression whose value
specifies the face name to use for highlighting.
@example
;; @r{Highlight occurrences of @samp{fubar},}
;; @r{using the face which is the value of @code{fubar-face}.}
("fubar" . fubar-face)
@end example
@item (@var{matcher} . @var{highlighter})
In this kind of element, @var{highlighter} is a list
which specifies how to highlight matches found by @var{matcher}.
It has the form
@example
(@var{subexp} @var{facename} @var{override} @var{laxmatch})
@end example
The @sc{car}, @var{subexp}, is an integer specifying which subexpression
of the match to fontify (0 means the entire matching text).
@var{facename}, specifies the face, as described above.
The last two values in @var{highlighter}, @var{override} and
@var{laxmatch}, are flags. If @var{override} is @code{t}, this element
can override existing fontification made by previous elements of
@code{font-lock-keywords}. If it is @code{keep}, then each character is
fontified if it has not been fontified already by some other element.
If it is @code{prepend}, the face @var{facename} is added to the
beginning of the @code{face} property. If it is @code{append}, the face
@var{facename} is added to the end of the @code{face} property.
If @var{laxmatch} is non-@code{nil}, it means there should be no error
if there is no subexpression numbered @var{subexp} in @var{matcher}.
Here are some examples of elements of this kind, and what they do:
@smallexample
;; @r{Highlight occurrences of either @samp{foo} or @samp{bar},}
;; @r{using @code{foo-bar-face}, even if they have already been highlighted.}
;; @r{@code{foo-bar-face} should be a variable whose value is a face.}
("foo\\|bar" 0 foo-bar-face t)
;; @r{Highlight the first subexpression within each occurrences}
;; @r{that the function @code{fubar-match} finds,}
;; @r{using the face which is the value of @code{fubar-face}.}
(fubar-match 1 fubar-face)
@end smallexample
@item (@var{matcher} @var{highlighters}@dots{})
This sort of element specifies several @var{highlighter} lists for a
single @var{matcher}. In order for this to be useful, each
@var{highlighter} should have a different value of @var{subexp}; that is,
each one should apply to a different subexpression of @var{matcher}.
@ignore
@item (@var{matcher} . @var{anchored})
In this kind of element, @var{anchored} acts much like a
@var{highlighter}, but it is more complex and can specify multiple
successive searches.
For highlighting single items, typically only @var{highlighter} is
required. However, if an item or (typically) items are to be
highlighted following the instance of another item (the anchor) then
@var{anchored} may be required.
It has this format:
@example
(@var{submatcher} @var{pre-match-form} @var{post-match-form} @var{highlighters}@dots{})
@end example
@c I can't parse this text -- rms
where @var{submatcher} is much like @var{matcher}, with one
exception---see below. @var{pre-match-form} and @var{post-match-form}
are evaluated before the first, and after the last, instance
@var{anchored}'s @var{submatcher} is used. Therefore they can be used
to initialise before, and cleanup after, @var{submatcher} is used.
Typically, @var{pre-match-form} is used to move to some position
relative to the original @var{submatcher}, before starting with
@var{anchored}'s @var{submatcher}. @var{post-match-form} might be used
to move, before resuming with @var{anchored}'s parent's @var{matcher}.
For example, an element of the form highlights (if not already highlighted):
@example
("\\<anchor\\>" (0 anchor-face) ("\\<item\\>" nil nil (0 item-face)))
@end example
Discrete occurrences of @samp{anchor} in the value of
@code{anchor-face}, and subsequent discrete occurrences of @samp{item}
(on the same line) in the value of @code{item-face}. (Here
@var{pre-match-form} and @var{post-match-form} are @code{nil}.
Therefore @samp{item} is initially searched for starting from the end of
the match of @samp{anchor}, and searching for subsequent instance of
@samp{anchor} resumes from where searching for @samp{item} concluded.)
The above-mentioned exception is as follows. The limit of the
@var{submatcher} search defaults to the end of the line after
@var{pre-match-form} is evaluated. However, if @var{pre-match-form}
returns a position greater than the position after @var{pre-match-form}
is evaluated, that position is used as the limit of the search. It is
generally a bad idea to return a position greater than the end of the
line; in other words, the @var{submatcher} search should not span lines.
@item (@var{matcher} @var{highlighters-or-anchoreds} ...)
@end ignore
@item (eval . @var{form})
Here @var{form} is an expression. to be evaluated the first time
this value of @code{font-lock-keywords} is used in a buffer.
Its value should be another element of one of these forms.
@end table
@strong{Warning:} Do not design an element of @code{font-lock-keywords}
to match text which spans lines; this does not work reliably. While
@code{font-lock-fontify-buffer} handles multi-line patterns correctly,
updating when you edit the buffer does not, since it considers text one
line at a time.
@defvar font-lock-syntactic-keywords
Font Lock mode can be used to update @code{syntax-table} properties
automatically. This is useful in languages for which a single
syntax table by itself is not sufficient.
This variable enables and controls the feature. Its value should
be a list of elements of this form:
@example
(@var{matcher} @var{subexp} @var{syntax} @var{override} @var{laxmatch})
@end example
The parts of this element have the same meanings as in the corresponding
sort of element of @code{font-lock-keywords},
@example
(@var{matcher} @var{subexp} @var{facename} @var{override} @var{laxmatch})
@end example
However, instead of specifying the value @var{facename} to use for the
@code{face} property, it specifies the value @var{syntax} to use for the
@code{syntax-table} property. Here, @var{syntax} can be a variable
whose value is a syntax table, a syntax entry of the form
@code{(@var{syntax-code} . @var{matching-char})}, or an expression whose
value is one of those two types.
@end defvar
@node Other Font Lock Variables
@subsection Other Font Lock Variables
This section describes additional variables that a major mode
can set by means of @code{font-lock-defaults}.
@defvar font-lock-keywords-only
Non-@code{nil} means Font Lock should not fontify comments or strings
syntactictally; it should only fontify based on @code{font-lock-keywords}.
@end defvar
@ignore
Other variables include those for buffer-specialised fontification functions,
`font-lock-fontify-buffer-function', `font-lock-unfontify-buffer-function',
`font-lock-fontify-region-function', `font-lock-unfontify-region-function',
`font-lock-inhibit-thing-lock' and `font-lock-maximum-size'.
@end ignore
@defvar font-lock-keywords-case-fold-search
Non-@code{nil} means that regular expression matching for
patterns in @code{font-lock-keywords} is case-insensitive.
@end defvar
@defvar font-lock-beginning-of-syntax-function
If this variable is non-@code{nil}, it should be a function to use to
move back outside of a syntactic block.
@c Simon, WHEN is this variable used?
@c In what situation does Font Lock mode look for the
@c beginning of a syntactic block?
This function is called with no arguments. It should leave point at the
beginning of any enclosing syntactic block. Typical values are
@code{beginning-of-line} (i.e., the start of the line is known to be
outside a syntactic block), or @code{beginning-of-defun} for programming
modes or @code{backward-paragraph} for textual modes (i.e., the
mode-dependent function is known to move outside a syntactic block).
If the value is @code{nil}, the beginning of the buffer is used as a
position outside of a syntactic block, in the worst case.
@end defvar
@defvar font-lock-syntax-table
This variable specifies the syntax table to use for fontification of
comments and strings.
@end defvar
@defvar font-lock-mark-block-function
If this variable is non-@code{nil}, it should be a function with no args
used to mark an enclosing range of text for refontification when the
text in the buffer changes. A good choice of this function chooses a
range of text large enough to give proper results, but not too large so
that refontification becomes slow.
Typical values are @code{mark-defun} for programming modes or
@code{mark-paragraph} for textual modes (i.e., the mode-dependent
function is known to put point and mark around a text block relevant to
that mode).
@c Simon, WHEN is this variable used?
@c In what situation does Font Lock mode look for the
@c beginning of a syntactic block?
@end defvar
@node Levels of Font Lock
@subsection Levels of Font Lock
Many major modes offer three different levels of fontification. You
can define multiple levels by using a list of symbols for @var{keywords}
in @code{font-lock-defaults}. Each symbol specifies one level of
fontification; it is up to the user to choose one of these levels. The
chosen level's symbol value is used to initialize
@code{font-lock-keywords}.
@itemize @bullet
@item
Level 1: highlight function declarations, file directives (such as include or
import directives), strings and comments. The idea is speed, so only
the most important and top-level components are fontified.
@item
Level 2: in addition to level 1, highlight all language keywords (with
keyword-face) including type names (using type-face), constant values
(with reference-face, e.g., "true" and "false" or case/switch
constants). The idea is that all reserved words should be fontified
appropriately.
@item
Level 3: in addition to level 2, highlight all symbols that are defined
in function and variable declarations, and all builtin functions,
wherever they appear. The idea is that all declared objects should be
fontified.
@end itemize
@node Faces for Font Lock
@subsection Faces for Font Lock
You can make Font Lock mode use any face, but several faces are
defined specifically for Font Lock mode. Each of these symbols is both
a face name, and a variable whose default value is the symbol itself.
Thus, the default value of @code{font-lock-comment-face} is
@code{font-lock-comment-face}. This means you can write
@code{font-lock-comment-face} in a context such as
@code{font-lock-keywords} where a face-name-valued expression is used.
@table @code
@item font-lock-comment-face
@vindex font-lock-comment-face
@kindex font-lock-comment-face @r{(face name)}
Used (typically) for comments.
@item font-lock-string-face
@vindex font-lock-string-face
@kindex font-lock-string-face @r{(face name)}
Used (typically) for string constants.
@item font-lock-keyword-face
@vindex font-lock-keyword-face
@kindex font-lock-keyword-face @r{(face name)}
Used (typically) for keywords---names that have special syntactic
significance, like @code{for} and @code{if} in C.
@item font-lock-builtin-face
@vindex font-lock-builtin-face
@kindex font-lock-builtin-face @r{(face name)}
Used (typically) for built-in function names.
@item font-lock-function-name-face
@vindex font-lock-function-name-face
@kindex font-lock-function-name-face @r{(face name)}
Used (typically) for the name of a function being defined or declared,
in a function definition or declaration.
@item font-lock-variable-name-face
@vindex font-lock-variable-name-face
@kindex font-lock-variable-name-face @r{(face name)}
Used (typically) for the name of a variable being defined or declared,
in a variable definition or declaration.
@item font-lock-type-face
@vindex font-lock-type-face
@kindex font-lock-type-face @r{(face name)}
Used (typically) for names of user-defined data types,
where they are defined and where they are used.
@item font-lock-constant-face
@vindex font-lock-constant-face
@kindex font-lock-constant-face @r{(face name)}
Used (typically) for constant names.
@item font-lock-warning-face
@vindex font-lock-warning-face
@kindex font-lock-warning-face @r{(face name)}
Used (typically) for constructs that are peculiar, or that greatly
change the meaning of other text. For example, this is used for
@samp{;;;###autoload} cookies in Emacs Lisp, and for @code{#error}
directives in C.
@end table
@node Hooks
@section Hooks
@cindex hooks
@ -1303,6 +1958,7 @@ provides hooks for the sake of customization. Most often, hooks are set
up in the @file{.emacs} file, but Lisp programs can set them also.
@xref{Standard Hooks}, for a list of standard hook variables.
@cindex normal hook
Most of the hooks in Emacs are @dfn{normal hooks}. These variables
contain lists of functions to be called with no arguments. When the
hook name ends in @samp{-hook}, that tells you it is normal. We try to
@ -1322,8 +1978,9 @@ the valid kinds of functions that @code{funcall} accepts (@pxref{What Is
a Function}). Most normal hook variables are initially void;
@code{add-hook} knows how to deal with this.
@cindex abnormal hook
If the hook variable's name does not end with @samp{-hook}, that
indicates it is probably an abnormal hook; you should look at its
indicates it is probably an @dfn{abnormal hook}; you should look at its
documentation to see how to use the hook properly.
If the variable's name ends in @samp{-functions} or @samp{-hooks},
@ -1379,9 +2036,11 @@ specified.
If a hook variable has a non-@code{nil} value, that value may be a
function or a list of functions. If the value is a function (either a
lambda expression or a symbol with a function definition), it is
called. If it is a list, the elements are called, in order.
The hook functions are called with no arguments.
lambda expression or a symbol with a function definition), it is called.
If it is a list, the elements are called, in order. The hook functions
are called with no arguments. Nowadays, storing a single function in
the hook variable is semi-obsolete; you should always use a list of
functions.
For example, here's how @code{emacs-lisp-mode} runs its mode hook:

68
lispref/numbers.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/numbers
@node Numbers, Strings and Characters, Lisp Data Types, Top
@ -17,10 +17,6 @@ numbers are numbers with fractional parts, such as @minus{}4.5, 0.0, or
second power, and is multiplied by 1.5. Floating point values are not
exact; they have a fixed, limited amount of precision.
Support for floating point numbers is a new feature in Emacs 19, and it
is controlled by a separate compilation option, so you may encounter a site
where Emacs does not support them.
@menu
* Integer Basics:: Representation and range of integers.
* Float Basics:: Representation and range of floating point.
@ -120,34 +116,26 @@ negative integer @minus{}134,217,728:
@result{} 1000 0000 0000 0000 0000 0000 0000
@end example
Many of the following functions accept markers for arguments as well
as integers. (@xref{Markers}.) More precisely, the actual arguments to
such functions may be either integers or markers, which is why we often
give these arguments the name @var{int-or-marker}. When the argument
Many of the functions described in this chapter accept markers for
arguments in place of numbers. (@xref{Markers}.) Since the actual
arguments to such functions may be either numbers or markers, we often
give these arguments the name @var{number-or-marker}. When the argument
value is a marker, its position value is used and its buffer is ignored.
@ignore
In version 19, except where @emph{integer} is specified as an
argument, all of the functions for markers and integers also work for
floating point numbers.
@end ignore
@node Float Basics
@section Floating Point Basics
@cindex @code{LISP_FLOAT_TYPE} configuration macro
Emacs version 19 supports floating point numbers, if compiled with the
macro @code{LISP_FLOAT_TYPE} defined. The precise range of floating
point numbers is machine-specific; it is the same as the range of the C
data type @code{double} on the machine in question.
Floating point numbers are useful for representing numbers that are
not integral. The precise range of floating point numbers is
machine-specific; it is the same as the range of the C data type
@code{double} on the machine you are using.
The printed representation for floating point numbers requires either
a decimal point (with at least one digit following), an exponent, or
both. For example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2},
@samp{1.5e3}, and @samp{.15e4} are five ways of writing a floating point
number whose value is 1500. They are all equivalent. You can also use
a minus sign to write negative floating point numbers, as in
@samp{-1.0}.
The read-syntax for floating point numbers requires either a decimal
point (with at least one digit following), an exponent, or both. For
example, @samp{1500.0}, @samp{15e2}, @samp{15.0e2}, @samp{1.5e3}, and
@samp{.15e4} are five ways of writing a floating point number whose
value is 1500. They are all equivalent. You can also use a minus sign
to write negative floating point numbers, as in @samp{-1.0}.
@cindex IEEE floating point
@cindex positive infinity
@ -162,8 +150,17 @@ there is no correct answer. For example, @code{(sqrt -1.0)} returns a
NaN. For practical purposes, there's no significant difference between
different NaN values in Emacs Lisp, and there's no rule for precisely
which NaN value should be used in a particular case, so this manual
doesn't try to distinguish them. Emacs Lisp has no read syntax for NaNs
or infinities; perhaps we should create a syntax in the future.
doesn't try to distinguish them. Here are the read syntaxes for
these numbers:
@table @asis
@item positive infinity
@samp{1.0e+INF}
@item negative infinity
@samp{-1.0e+INF}
@item Not-a-number
@samp{0.0e+NaN}.
@end table
You can use @code{logb} to extract the binary exponent of a floating
point number (or estimate the logarithm of an integer):
@ -172,6 +169,13 @@ point number (or estimate the logarithm of an integer):
This function returns the binary exponent of @var{number}. More
precisely, the value is the logarithm of @var{number} base 2, rounded
down to an integer.
@example
(logb 10)
@result{} 3
(logb 10.0e20)
@result{} 69
@end example
@end defun
@node Predicates on Numbers
@ -232,7 +236,7 @@ compare them, then you test whether two values are the same
of the objects.
At present, each integer value has a unique Lisp object in Emacs Lisp.
Therefore, @code{eq} is equivalent @code{=} where integers are
Therefore, @code{eq} is equivalent to @code{=} where integers are
concerned. It is sometimes convenient to use @code{eq} for comparing an
unknown value with an integer, because @code{eq} does not report an
error if the unknown value is not a number---it accepts arguments of any
@ -428,11 +432,11 @@ This function adds its arguments together. When given no arguments,
@end example
@end defun
@defun - &optional number-or-marker &rest other-numbers-or-markers
@defun - &optional number-or-marker &rest more-numbers-or-markers
The @code{-} function serves two purposes: negation and subtraction.
When @code{-} has a single argument, the value is the negative of the
argument. When there are multiple arguments, @code{-} subtracts each of
the @var{other-numbers-or-markers} from @var{number-or-marker},
the @var{more-numbers-or-markers} from @var{number-or-marker},
cumulatively. If there are no arguments, the result is 0.
@example

298
lispref/objects.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/objects
@node Lisp Data Types, Numbers, Introduction, Top
@ -66,8 +66,10 @@ to use these types can be found in later chapters.
output generated by the Lisp printer (the function @code{prin1}) for
that object. The @dfn{read syntax} of an object is the format of the
input accepted by the Lisp reader (the function @code{read}) for that
object. Most objects have more than one possible read syntax. Some
types of object have no read syntax; except for these cases, the printed
object. @xref{Read and Print}.
Most objects have more than one possible read syntax. Some types of
object have no read syntax; except for these cases, the printed
representation of an object is also a read syntax for it.
In other languages, an expression is text; it has no other form. In
@ -143,6 +145,8 @@ latter are unique to Emacs Lisp.
* Array Type:: Arrays include strings and vectors.
* String Type:: An (efficient) array of characters.
* Vector Type:: One-dimensional arrays.
* Char-Table Type:: One-dimensional sparse arrays indexed by characters.
* Bool-Vector Type:: One-dimensional arrays of @code{t} or @code{nil}.
* Function Type:: A piece of executable code you can call from elsewhere.
* Macro Type:: A method of expanding an expression into another
expression, more fundamental but less pretty.
@ -196,9 +200,9 @@ leading @samp{+} or a final @samp{.}.
@node Floating Point Type
@subsection Floating Point Type
Emacs version 19 supports floating point numbers (though there is a
compilation option to disable them). The precise range of floating
point numbers is machine-specific.
Emacs supports floating point numbers (though there is a compilation
option to disable them). The precise range of floating point numbers is
machine-specific.
The printed representation for floating point numbers requires either
a decimal point (with at least one digit following), an exponent, or
@ -221,9 +225,10 @@ common to work with @emph{strings}, which are sequences composed of
characters. @xref{String Type}.
Characters in strings, buffers, and files are currently limited to the
range of 0 to 255---eight bits. If you store a larger integer into a
string, buffer or file, it is truncated to that range. Characters that
represent keyboard input have a much wider range.
range of 0 to 524287---nineteen bits. But not all values in that range
are valid character codes. Characters that represent keyboard input
have a much wider range, so they can modifier keys such as Control, Meta
and Shift.
@cindex read syntax for characters
@cindex printed representation for characters
@ -272,8 +277,7 @@ way to write the space character. If the character is @samp{\}, you
You can express the characters Control-g, backspace, tab, newline,
vertical tab, formfeed, return, and escape as @samp{?\a}, @samp{?\b},
@samp{?\t}, @samp{?\n}, @samp{?\v}, @samp{?\f}, @samp{?\r}, @samp{?\e},
respectively. Those values are 7, 8, 9, 10, 11, 12, 13, and 27 in
decimal. Thus,
respectively. Thus,
@example
?\a @result{} 7 ; @r{@kbd{C-g}}
@ -306,10 +310,10 @@ equivalent to @samp{?\^I} and to @samp{?\^i}:
?\^I @result{} 9 ?\C-I @result{} 9
@end example
For use in strings and buffers, you are limited to the control
characters that exist in @sc{ASCII}, but for keyboard input purposes,
you can turn any character into a control character with @samp{C-}. The
character codes for these non-@sc{ASCII} control characters include the
In strings and buffers, the only control characters allowed are those
that exist in @sc{ASCII}; but for keyboard input purposes, you can turn
any character into a control character with @samp{C-}. The character
codes for these non-@sc{ASCII} control characters include the
@iftex
$2^{26}$
@end iftex
@ -359,11 +363,11 @@ $2^{7}$
@ifinfo
2**7
@end ifinfo
bit indicates a meta character, so the meta
characters that can fit in a string have codes in the range from 128 to
255, and are the meta versions of the ordinary @sc{ASCII} characters.
(In Emacs versions 18 and older, this convention was used for characters
outside of strings as well.)
bit attached to an ASCII character indicates a meta character; thus, the
meta characters that can fit in a string have codes in the range from
128 to 255, and are the meta versions of the ordinary @sc{ASCII}
characters. (In Emacs versions 18 and older, this convention was used
for characters outside of strings as well.)
The read syntax for meta characters uses @samp{\M-}. For example,
@samp{?\M-A} stands for @kbd{M-A}. You can use @samp{\M-} together with
@ -372,9 +376,10 @@ syntax for a character. Thus, you can write @kbd{M-A} as @samp{?\M-A},
or as @samp{?\M-\101}. Likewise, you can write @kbd{C-M-b} as
@samp{?\M-\C-b}, @samp{?\C-\M-b}, or @samp{?\M-\002}.
The case of an ordinary letter is indicated by its character code as
part of @sc{ASCII}, but @sc{ASCII} has no way to represent whether a
control character is upper case or lower case. Emacs uses the
The case of a graphic character is indicated by its character code;
for example, @sc{ASCII} distinguishes between the characters @samp{a}
and @samp{A}. But @sc{ASCII} has no way to represent whether a control
character is upper case or lower case. Emacs uses the
@iftex
$2^{25}$
@end iftex
@ -407,8 +412,9 @@ bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
@cindex @samp{\} in character constant
@cindex backslash in character constant
@cindex octal character code
Finally, the most general read syntax consists of a question mark
followed by a backslash and the character code in octal (up to three
Finally, the most general read syntax for a character represents the
character code in either octal or hex. To use octal, write a question
mark followed by a backslash and the octal character code (up to three
octal digits); thus, @samp{?\101} for the character @kbd{A},
@samp{?\001} for the character @kbd{C-a}, and @code{?\002} for the
character @kbd{C-b}. Although this syntax can represent any @sc{ASCII}
@ -422,6 +428,18 @@ important than the @sc{ASCII} representation.
@end group
@end example
To use hex, write a question mark followed by a backslash, @samp{x},
and the hexadecimal character code. You can use any number of hex
digits, so you can represent any character code in this way.
Thus, @samp{?\x41} for the character @kbd{A}, @samp{?\x1} for the
character @kbd{C-a}, and @code{?\x8c0} for the character
@iftex
@`a.
@end iftex
@ifinfo
@samp{a} with grave accent.
@end ifinfo
A backslash is allowed, and harmless, preceding any character without
a special escape meaning; thus, @samp{?\+} is equivalent to @samp{?+}.
There is no reason to add a backslash before most characters. However,
@ -788,49 +806,36 @@ the names of Lisp symbols, as messages for the user, and to represent
text extracted from buffers. Strings in Lisp are constants: evaluation
of a string returns the same string.
@xref{Strings and Characters}, for functions that operate on strings.
@menu
* Syntax for Strings::
* Non-ASCII in Strings::
* Nonprinting Characters::
* Text Props and Strings::
@end menu
@node Syntax for Strings
@subsubsection Syntax for Strings
@cindex @samp{"} in strings
@cindex double-quote in strings
@cindex @samp{\} in strings
@cindex backslash in strings
The read syntax for strings is a double-quote, an arbitrary number of
characters, and another double-quote, @code{"like this"}. The Lisp
reader accepts the same formats for reading the characters of a string
as it does for reading single characters (without the question mark that
begins a character literal). You can enter a nonprinting character such
as tab, @kbd{C-a} or @kbd{M-C-A} using the convenient escape sequences,
like this: @code{"\t, \C-a, \M-\C-a"}. You can include a double-quote
in a string by preceding it with a backslash; thus, @code{"\""} is a
string containing just a single double-quote character.
(@xref{Character Type}, for a description of the read syntax for
characters.)
If you use the @samp{\M-} syntax to indicate a meta character in a
string constant, this sets the
@iftex
$2^{7}$
@end iftex
@ifinfo
2**7
@end ifinfo
bit of the character in the string.
This is not the same representation that the meta modifier has in a
character on its own (not inside a string). @xref{Character Type}.
Strings cannot hold characters that have the hyper, super, or alt
modifiers; they can hold @sc{ASCII} control characters, but no others.
They do not distinguish case in @sc{ASCII} control characters.
The printed representation of a string consists of a double-quote, the
characters it contains, and another double-quote. However, you must
escape any backslash or double-quote characters in the string with a
backslash, like this: @code{"this \" is an embedded quote"}.
characters, and another double-quote, @code{"like this"}. To include a
double-quote in a string, precede it with a backslash; thus, @code{"\""}
is a string containing just a single double-quote character. Likewise,
you can include a backslash by preceding it with another backslash, like
this: @code{"this \\ is a single embedded backslash"}.
@cindex newline in strings
The newline character is not special in the read syntax for strings;
if you write a new line between the double-quotes, it becomes a
character in the string. But an escaped newline---one that is preceded
by @samp{\}---does not become part of the string; i.e., the Lisp reader
ignores an escaped newline while reading a string.
@cindex newline in strings
ignores an escaped newline while reading a string. An escaped space
@w{@samp{\ }} is likewise ignored.
@example
"It is useful to include newlines
@ -842,11 +847,73 @@ in documentation strings,
but the newline is ignored if escaped."
@end example
A string can hold properties of the text it contains, in addition to
the characters themselves. This enables programs that copy text between
strings and buffers to preserve the properties with no special effort.
@xref{Text Properties}. Strings with text properties have a special
read and print syntax:
@node Non-ASCII in Strings
@subsubsection Non-ASCII Characters in Strings
You can include a non-@sc{ASCII} international character in a string
constant by writing it literally. There are two text representations
for non-@sc{ASCII} characters in Emacs strings (and in buffers): unibyte
and multibyte. If the string constant is read from a multibyte source,
then the character is read as a multibyte character, and that makes the
string multibyte. If the string constant is read from a unibyte source,
then the character is read as unibyte and that makes the string unibyte.
You can also represent a multibyte non-@sc{ASCII} character with its
character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
greater than 256.) Any character which is not a valid hex digit
terminates this construct. If the character that would follow is a hex
digit, write @samp{\ } to terminate the hex escape---for example,
@samp{\x8c0\ } represents one character, @samp{a} with grave accent.
@samp{\ } in a string constant is just like backslash-newline; it does
not contribute any character to the string, but it does terminate the
preceding hex escape.
Using a multibyte hex escape forces the string to multibyte. You can
represent a unibyte non-@sc{ASCII} character with its character code,
which must be in the range from 128 (0200 octal) to 255 (0377 octal).
This forces a unibyte string.
@xref{Text Representations}, for more information about the two
text representations.
@node Nonprinting Characters
@subsubsection Nonprinting Characters in Strings
Strings cannot hold characters that have the hyper, super, or alt
modifiers; the only control or meta characters they can hold are the
@sc{ASCII} control characters. Strings do not distinguish case in
@sc{ASCII} control characters.
You can use the same backslash escape-sequences in a string constant
as in character literals (but do not use the question mark that begins a
character constant). For example, you can write a string containing the
nonprinting characters tab, @kbd{C-a} and @kbd{M-C-a}, with commas and
spaces between them, like this: @code{"\t, \C-a, \M-\C-a"}.
@xref{Character Type}, for a description of the read syntax for
characters.
If you use the @samp{\M-} syntax to indicate a meta character in a
string constant, this sets the
@iftex
$2^{7}$
@end iftex
@ifinfo
2**7
@end ifinfo
bit of the character in the string. This construct works only with
ASCII characters. Note that the same meta characters have a different
representation when not in a string. @xref{Character Type}.
@node Text Props and Strings
@subsubsection Text Properties in Strings
A string can hold properties for the characters it contains, in
addition to the characters themselves. This enables programs that copy
text between strings and buffers to copy the text's properties with no
special effort. @xref{Text Properties}, for an explanation of what text
properties mean. Strings with text properties use a special read and
print syntax:
@example
#("@var{characters}" @var{property-data}...)
@ -863,9 +930,18 @@ of three as follows:
@noindent
The elements @var{beg} and @var{end} are integers, and together specify
a range of indices in the string; @var{plist} is the property list for
that range.
that range. For example,
@xref{Strings and Characters}, for functions that work on strings.
@example
#("foo bar" 0 3 (face bold) 3 4 nil 4 7 (face italic))
@end example
@noindent
represents a string whose textual contents are @samp{foo bar}, in which
the first three characters have a @code{face} property with value
@code{bold}, and the last three have a @code{face} property with value
@code{italic}. (The fourth character has no text properties so its
property list is @code{nil}.)
@node Vector Type
@subsection Vector Type
@ -887,6 +963,44 @@ for evaluation.
@xref{Vectors}, for functions that work with vectors.
@node Char-Table Type
@subsection Char-Table Type
A @dfn{char-table} is a one-dimensional array of elements of any type,
indexed by character codes. Char-tables have certain extra features to
make them more useful for many jobs that involve assigning information
to character codes---for example, a char-table can have a parent to
inherit from, a default value, and a small number of extra slots to use for
special purposes. A char-table can also specify a single value for
a whole character set.
The printed representation of a char-table is like a vector
except that there is an extra @samp{#} at the beginning.
@xref{Char-Tables}, for special functions to operate on char-tables.
@node Bool-Vector Type
@subsection Bool-Vector Type
A @dfn{bool-vector} is a one-dimensional array of elements that
must be @code{t} or @code{nil}.
The printed representation of a Bool-vector is like a string, except
that it begins with @samp{#&} followed by the length. The string
constant that follows actually specifies the contents of the bool-vector
as a bitmap---each ``character'' in the string contains 8 bits, which
specify the next 8 elements of the bool-vector (1 stands for @code{t},
and 0 for @code{nil}). If the length is not a multiple of 8, the
printed representation describes extra elements, but these really
make no difference.
@example
(make-bool-vector 3 t)
@result{} #&3"\377"
(make-bool-vector 3 nil)
@result{} #&3"\0""
@end example
@node Function Type
@subsection Function Type
@ -922,6 +1036,10 @@ is a Lisp function object, including the @code{lambda} symbol.
a macro as far as Emacs is concerned. @xref{Macros}, for an explanation
of how to write a macro.
@strong{Warning}: Lisp macros and keyboard macros (@pxref{Keyboard
Macros}) are entirely different things. When we use the word ``macro''
without qualification, we mean a Lisp macro, not a keyboard macro.
@node Primitive Function Type
@subsection Primitive Function Type
@cindex special forms
@ -939,7 +1057,8 @@ primitive. However, this does matter if you try to substitute a
function written in Lisp for a primitive of the same name. The reason
is that the primitive function may be called directly from C code.
Calls to the redefined function from Lisp will use the new definition,
but calls from C code may still use the built-in definition.
but calls from C code may still use the built-in definition. Therefore,
@strong{we discourage redefinition of primitive functions}.
The term @dfn{function} refers to all Emacs functions, whether written
in Lisp or C. @xref{Function Type}, for information about the
@ -1227,18 +1346,22 @@ keys, local as well as global keymaps, and changing key bindings.
@node Syntax Table Type
@subsection Syntax Table Type
A @dfn{syntax table} is a vector of 256 integers. Each element of the
vector defines how one character is interpreted when it appears in a
A @dfn{syntax table} is a char-table which specifies the syntax of
each character, for word and list parsing. Each element of the syntax
table defines how one character is interpreted when it appears in a
buffer. For example, in C mode (@pxref{Major Modes}), the @samp{+}
character is punctuation, but in Lisp mode it is a valid character in a
symbol. These modes specify different interpretations by changing the
syntax table entry for @samp{+}, at index 43 in the syntax table.
Syntax tables are used only for scanning text in buffers, not for
reading Lisp expressions. The table the Lisp interpreter uses to read
expressions is built into the Emacs source code and cannot be changed;
thus, to change the list delimiters to be @samp{@{} and @samp{@}}
instead of @samp{(} and @samp{)} would be impossible.
Syntax tables are used only to control primitives that scan text in
buffers, not for reading Lisp expressions. The syntax that the Lisp
interpreter uses to read expressions is built into the Emacs source code
and cannot be changed; thus, to change the list delimiters to be
@samp{@{} and @samp{@}} instead of @samp{(} and @samp{)} would be
impossible. (Some Lisp systems provide ways to redefine the read
syntax, but we decided to leave this feature out of Emacs Lisp for
simplicity.)
@xref{Syntax Tables}, for details about syntax classes and how to make
and modify syntax tables.
@ -1248,18 +1371,18 @@ and modify syntax tables.
A @dfn{display table} specifies how to display each character code.
Each buffer and each window can have its own display table. A display
table is actually a vector of length 262. @xref{Display Tables}.
table is actually a char-table. @xref{Display Tables}.
@node Overlay Type
@subsection Overlay Type
An @dfn{overlay} specifies temporary alteration of the display
appearance of a part of a buffer. It contains markers delimiting a
range of the buffer, plus a property list (a list whose elements are
alternating property names and values). Overlays are used to present
parts of the buffer temporarily in a different display style. They have
no read syntax, and print in hash notation, giving the buffer name and
range of positions.
An @dfn{overlay} specifies properties that apply to a part of a
buffer. Each overlay applies to a specified range of the buffer, and
contains a property list (a list whose elements are alternating property
names and values). Overlay properties are used to present parts of the
buffer temporarily in a different display style. Overlays have no read
syntax, and print in hash notation, giving the buffer name and range of
positions.
@xref{Overlays}, for how to create and use overlays.
@ -1284,7 +1407,7 @@ pass an argument to @code{+} that it cannot handle:
@example
@group
(+ 2 'a)
@error{} Wrong type argument: integer-or-marker-p, a
@error{} Wrong type argument: number-or-marker-p, a
@end group
@end example
@ -1355,6 +1478,9 @@ with references to further information.
@item framep
@xref{Frames, framep}.
@item functionp
@xref{Functions, functionp}.
@item integer-or-marker-p
@xref{Predicates on Markers, integer-or-marker-p}.
@ -1572,10 +1698,10 @@ arguments to see if their elements are the same. So, if two objects are
@end group
@end example
Comparison of strings is case-sensitive and takes account of text
properties as well as the characters in the strings. To compare
two strings' characters without comparing their text properties,
use @code{string=} (@pxref{Text Comparison}).
Comparison of strings is case-sensitive, but does not take account of
text properties---it compares only the characters in the strings.
A unibyte string never equals a multibyte string unless the
contents are entirely @sc{ASCII} (@pxref{Text Representations}).
@example
@group

149
lispref/os.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/os
@node System Interface, Display, Processes, Top
@ -120,8 +120,9 @@ It runs @code{window-setup-hook}. @xref{Window Systems}.
@item
It displays copyleft, nonwarranty, and basic use information, provided
there were no remaining command line arguments (a few steps above) and
the value of @code{inhibit-startup-message} is @code{nil}.
there were no remaining command line arguments (a few steps above),
the value of @code{inhibit-startup-message} is @code{nil}, and the
buffer is still empty.
@end enumerate
@defopt inhibit-startup-message
@ -375,8 +376,9 @@ value.
These functions are called with no arguments. They can access the
command-line argument under consideration through the variable
@code{argi}. The remaining arguments (not including the current one)
are in the variable @code{command-line-args-left}.
@code{argi}, which is bound temporarily at this point. The remaining
arguments (not including the current one) are in the variable
@code{command-line-args-left}.
When a function recognizes and processes the argument in @code{argi}, it
should return a non-@code{nil} value to say it has dealt with that
@ -432,7 +434,7 @@ subprocesses that are running. This is done in the function
@defvar kill-emacs-query-functions
After asking the standard questions, @code{save-buffers-kill-emacs}
calls the functions in the list @code{kill-buffer-query-functions}, in
calls the functions in the list @code{kill-emacs-query-functions}, in
order of appearance, with no arguments. These functions can ask for
additional confirmation from the user. If any of them returns
@code{nil}, Emacs is not killed.
@ -610,9 +612,9 @@ systems.
@end defvar
@defvar system-configuration
This variable holds the three-part configuration name for the
hardware/software configuration of your system, as a string. The
convenient way to test parts of this string is with @code{string-match}.
This variable holds the GNU configuration name for the hardware/software
configuration of your system, as a string. The convenient way to test
parts of this string is with @code{string-match}.
@end defvar
@defun system-name
@ -719,10 +721,12 @@ containing the Emacs executable.
@end defvar
@defun load-average
This function returns the current 1-minute, 5-minute and 15-minute
load averages in a list. The values are integers that are 100 times
the system load averages. (The load averages indicate the number of
processes trying to run.)
This function returns the current 1-minute, 5-minute and 15-minute load
averages in a list. The values are integers that are 100 times the
system load averages, which indicate the average number of processes
trying to run. It would be more logical to use floating point numbers,
but this function was introduced before Emacs supported floating point
numbers, and it is not worth changing it now.
@example
@group
@ -742,6 +746,12 @@ lewis@@rocky[5] % uptime
This function returns the process @sc{id} of the Emacs process.
@end defun
@tindex tty-erase-char
@defvar tty-erase-char
This variable holds the erase character that was selected
in the system's terminal driver, before Emacs was started.
@end defvar
@defun setprv privilege-name &optional setp getprv
This function sets or resets a VMS privilege. (It does not exist on
Unix.) The first arg is the privilege name, as a string. The second
@ -757,6 +767,19 @@ indicating whether the privilege is currently enabled.
@node User Identification
@section User Identification
@defvar init-file-user
This variable says which user's init files should be used by Emacs---or
@code{nil} if none. The value reflects command line options such as
@samp{-q} or @samp{-u @var{user}}.
Lisp packages that load files of customizations, or any other sort of
user profile, should obey this variable in deciding where to find it.
They should load the profile of the user name found in this variable.
If @code{init-file-user} is @code{nil}, meaning that the @samp{-q}
option was used, then Lisp packages should not load any customization
files or user profile.
@end defvar
@defvar user-mail-address
This holds the nominal email address of the user who is using Emacs.
Emacs normally sets this variable to a default value after reading your
@ -789,8 +812,9 @@ This function returns the user name corresponding to Emacs's real
environment variables @code{LOGNAME} and @code{USER}.
@end defun
@defun user-full-name
This function returns the full name of the user.
@defun user-full-name &optional uid
This function returns the full name of the logged-in user---or the value
of the environment variables @code{NAME}, if that is set.
@example
@group
@ -798,6 +822,10 @@ This function returns the full name of the user.
@result{} "Bil Lewis"
@end group
@end example
If @var{uid} is non-@code{nil}, then it should be an integer, a user-id,
or a string, a login name. Then @code{user-full-name} returns the full
name corresponding to that user-id or login name.
@end defun
@vindex user-full-name
@ -837,7 +865,7 @@ string. The format of the string is unvarying; the number of characters
used for each part is always the same, so you can reliably use
@code{substring} to extract pieces of it. It is wise to count the
characters from the beginning of the string rather than from the end, as
additional information may be added at the end.
additional information may some day be added at the end.
@c Emacs 19 feature
The argument @var{time-value}, if given, specifies a time to format
@ -996,6 +1024,16 @@ This stands for the year with century.
@item %Z
This stands for the time zone abbreviation.
@end table
You can also specify the field width and type of padding for any of
these @samp{%}-constructs. This works as in @code{printf}: you write
the field width as digits in the middle of a @samp{%}-construct. If you
start the field width with 0, it means to pad with zeros.
For example, @samp{%S} specifies the number of seconds since the minute;
@samp{%03S} means to pad this with zeros to 3 positions, @samp{%_3S} to
pad with spaces to 3 positions. Plain @samp{%3S} pads with zeros,
because that is how @samp{%S} normally pads to two positions.
@end defun
@defun decode-time time
@ -1046,9 +1084,10 @@ before you call @code{encode-time}.
The optional argument @var{zone} defaults to the current time zone and
its daylight savings time rules. If specified, it can be either a list
(as you would get from @code{current-time-zone}) or an integer (as you
would get from @code{decode-time}). The specified zone is used without
any further alteration for daylight savings time.
(as you would get from @code{current-time-zone}), a string as in the
@code{TZ} environment variable, or an integer (as you would get from
@code{decode-time}). The specified zone is used without any further
alteration for daylight savings time.
If you pass more than seven arguments to @code{encode-time}, the first
six are used as @var{seconds} through @var{year}, the last argument is
@ -1059,6 +1098,10 @@ feature makes it possible to use the elements of a list returned by
@example
(apply 'encode-time (decode-time @dots{}))
@end example
You can perform simple date arithmetic by using out-of-range values for
the @var{sec}, @var{minute}, @var{hour}, @var{day}, and @var{month}
arguments; for example, day 0 means the day preceding the given month.
@end defun
@node Timers
@ -1104,9 +1147,13 @@ relative time measured in seconds.
The argument @var{repeat} specifies how often to repeat the call. If
@var{repeat} is @code{nil}, there are no repetitions; @var{function} is
called just once, at @var{time}. If @var{repeat} is a number, it
specifies a repetition period measured in seconds. In any case,
@var{repeat} has no effect on when @emph{first} call takes
place---@var{time} alone specifies that.
specifies a repetition period measured in seconds.
In most cases, @var{repeat} has no effect on when @emph{first} call
takes place---@var{time} alone specifies that. There is one exception:
if @var{time} is @code{t}, then the timer runs whenever the time is a
multiple of @var{repeat} seconds after the epoch. This is useful for
functions like @code{display-time}.
The function @code{run-at-time} returns a timer value that identifies
the particular scheduled future action. You can use this value to call
@ -1295,19 +1342,18 @@ be virtually pressed.
@defvar keyboard-translate-table
This variable is the translate table for keyboard characters. It lets
you reshuffle the keys on the keyboard without changing any command
bindings. Its value must be a string or @code{nil}.
bindings. Its value is normally a char-table, or else @code{nil}.
If @code{keyboard-translate-table} is a string, then each character read
from the keyboard is looked up in this string and the character in the
string is used instead. If the string is of length @var{n}, character codes
@var{n} and up are untranslated.
If @code{keyboard-translate-table} is a char-table, then each character
read from the keyboard is looked up in this character. If the value
found there is non-@code{nil}, then it is used instead of the
actual input character.
In the example below, we set @code{keyboard-translate-table} to a
string of 128 characters. Then we fill it in to swap the characters
@kbd{C-s} and @kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}.
Subsequently, typing @kbd{C-\} has all the usual effects of typing
@kbd{C-s}, and vice versa. (@xref{Flow Control} for more information on
this subject.)
char-table. Then we fill it in to swap the characters @kbd{C-s} and
@kbd{C-\} and the characters @kbd{C-q} and @kbd{C-^}. Subsequently,
typing @kbd{C-\} has all the usual effects of typing @kbd{C-s}, and vice
versa. (@xref{Flow Control} for more information on this subject.)
@cindex flow control example
@example
@ -1317,20 +1363,18 @@ this subject.)
(interactive)
@end group
@group
(let ((the-table (make-string 128 0)))
(let ((i 0))
(while (< i 128)
(aset the-table i i)
(setq i (1+ i))))
(setq keyboard-translate-table
(make-char-table 'keyboard-translate-table nil)))
@end group
;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
(aset the-table ?\034 ?\^s)
(aset the-table ?\^s ?\034)
@group
;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
(aset the-table ?\036 ?\^q)
(aset the-table ?\^q ?\036)
(setq keyboard-translate-table the-table)))
;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
(aset keyboard-translate-table ?\034 ?\^s)
(aset keyboard-translate-table ?\^s ?\034)
@end group
@group
;; @r{Swap @kbd{C-q} and @kbd{C-^}.}
(aset keyboard-translate-table ?\036 ?\^q)
(aset keyboard-translate-table ?\^q ?\036))
@end group
@end example
@ -1343,7 +1387,7 @@ translation.
@defun keyboard-translate from to
This function modifies @code{keyboard-translate-table} to translate
character code @var{from} into character code @var{to}. It creates
or enlarges the translate table if necessary.
the keyboard translate table if necessary.
@end defun
The remaining translation features translate subsequences of key
@ -1351,10 +1395,11 @@ sequences being read. They are implemented in @code{read-key-sequence}
and have no effect on @code{read-char}.
@defvar function-key-map
This variable holds a keymap that describes the character sequences
sent by function keys on an ordinary character terminal. This keymap
uses the same data structure as other keymaps, but is used differently: it
specifies translations to make while reading event sequences.
This variable holds a keymap that describes the character sequences sent
by function keys on an ordinary character terminal. This keymap has the
same structure as other keymaps, but is used differently: it specifies
translations to make while reading key sequences, rather than bindings
for key sequences.
If @code{function-key-map} ``binds'' a key sequence @var{k} to a vector
@var{v}, then when @var{k} appears as a subsequence @emph{anywhere} in a
@ -1430,7 +1475,7 @@ to turn the character that follows into a Hyper character:
(defun hyperify (prompt)
(let ((e (read-event)))
(vector (if (numberp e)
(logior (lsh 1 20) e)
(logior (lsh 1 24) e)
(if (memq 'hyper (event-modifiers e))
e
(add-event-modifier "H-" e))))))
@ -1631,11 +1676,11 @@ terminals, this problem is gradually being cured. For the mean time,
Emacs provides a convenient way of enabling flow control if you want it:
call the function @code{enable-flow-control}.
@defun enable-flow-control
@deffn Command enable-flow-control
This function enables use of @kbd{C-s} and @kbd{C-q} for output flow
control, and provides the characters @kbd{C-\} and @kbd{C-^} as aliases
for them using @code{keyboard-translate-table} (@pxref{Translating Input}).
@end defun
@end deffn
You can use the function @code{enable-flow-control-on} in your
@file{.emacs} file to enable flow control automatically on certain

21
lispref/positions.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/positions
@node Positions, Markers, Frames, Top
@ -287,8 +287,9 @@ The return value of @code{goto-line} is the difference between
@var{line} and the line number of the line to which point actually was
able to move (in the full buffer, before taking account of narrowing).
Thus, the value is positive if the scan encounters the real end of the
buffer. The value is zero if scan encounters the end of the accessible
portion but not the real end of the buffer.
buffer before finding the specified line. The value is zero if scan
encounters the end of the accessible portion but not the real end of the
buffer.
In an interactive call, @var{line} is the numeric prefix argument if
one has been provided. Otherwise @var{line} is read in the minibuffer.
@ -457,9 +458,9 @@ This function moves point to the start of the screen line @var{count}
screen lines down from the screen line containing point. If @var{count}
is negative, it moves up instead.
@code{vertical-motion} returns the number of lines moved. The value may
be less in absolute value than @var{count} if the beginning or end of
the buffer was reached.
@code{vertical-motion} returns the number of screen lines over which it
moved point. The value may be less in absolute value than @var{count}
if the beginning or end of the buffer was reached.
The window @var{window} is used for obtaining parameters such as the
width, the horizontal scrolling, and the display table. But
@ -531,7 +532,7 @@ The result @var{prevhpos} is the horizontal position one character back
from @var{pos}. The result @var{contin} is @code{t} if the last line
was continued after (or within) the previous character.
For example, to find the buffer position of column @var{col} of line
For example, to find the buffer position of column @var{col} of screen line
@var{line} of a certain window, pass the window's display start location
as @var{from} and the window's upper-left coordinates as @var{frompos}.
Pass the buffer's @code{(point-max)} as @var{to}, to limit the scan to
@ -693,7 +694,7 @@ comes back" twice.
@defun skip-chars-backward character-set &optional limit
This function moves point backward, skipping characters that match
@var{character-set}, until @var{limit}. It just like
@var{character-set}, until @var{limit}. It is just like
@code{skip-chars-forward} except for the direction of motion.
@end defun
@ -796,7 +797,7 @@ of the current region (point and the mark, with the smallest first).
This function sets the accessible portion of the current buffer to
include just the current page. An optional first argument
@var{move-count} non-@code{nil} means to move forward or backward by
@var{move-count} pages and then narrow. The variable
@var{move-count} pages and then narrow to one page. The variable
@code{page-delimiter} specifies where pages start and end
(@pxref{Standard Regexps}).
@ -833,7 +834,7 @@ before you try it.
If @var{body} changes the current buffer, @code{save-restriction} still
restores the restrictions on the original buffer (the buffer whose
restructions it saved from), but it does not restore the identity of the
restrictions it saved from), but it does not restore the identity of the
current buffer.
@code{save-restriction} does @emph{not} restore point and the mark; use

206
lispref/processes.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/processes
@node Processes, System Interface, Abbrevs, Top
@ -80,18 +80,20 @@ Expansion}).
Each of the subprocess-creating functions has a @var{buffer-or-name}
argument which specifies where the standard output from the program will
go. If @var{buffer-or-name} is @code{nil}, that says to discard the
output unless a filter function handles it. (@xref{Filter Functions},
and @ref{Read and Print}.) Normally, you should avoid having multiple
processes send output to the same buffer because their output would be
intermixed randomly.
go. It should be a buffer or a buffer name (which will create the
buffer if it does not already exist). It can also be @code{nil}, which
says to discard the output unless a filter function handles it.
(@xref{Filter Functions}, and @ref{Read and Print}.) Normally, you
should avoid having multiple processes send output to the same buffer
because their output would be intermixed randomly.
@cindex program arguments
All three of the subprocess-creating functions have a @code{&rest}
argument, @var{args}. The @var{args} must all be strings, and they are
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.
characters and other shell constructs have no special meanings in these
strings, since the whole strings are passed directly to the specified
program.
@strong{Please note:} The argument @var{program} contains only the
name of the program; it may not contain any command-line arguments. You
@ -144,15 +146,19 @@ user types another @kbd{C-g}, that kills the subprocess instantly with
@code{SIGKILL} and quits immediately. @xref{Quitting}.
The synchronous subprocess functions returned @code{nil} in version
18. In version 19, they return an indication of how the process
terminated.
18. Now they return an indication of how the process terminated.
The output from a synchronous subprocess is generally decoded using a
coding system, much like text read from a file. The input sent to a
subprocess by @code{call-process-region} is encoded using a coding
system, much like text written into a file. @xref{Coding Systems}.
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
it to finish.
The standard input for the process comes from file @var{infile} if
@var{infile} is not @code{nil} and from @file{/dev/null} otherwise.
@var{infile} is not @code{nil}, and from @file{/dev/null} otherwise.
The argument @var{destination} says where to put the process output.
Here are the possibilities:
@ -247,8 +253,9 @@ of @code{call-process}:
@defun call-process-region start end program &optional delete destination display &rest args
This function sends the text between @var{start} to @var{end} as
standard input to a process running @var{program}. It deletes the text
sent if @var{delete} is non-@code{nil}; this is useful when @var{buffer}
is @code{t}, to insert the output in the current buffer.
sent if @var{delete} is non-@code{nil}; this is useful when
@var{destination} is @code{t}, to insert the output in the current
buffer in place of the input.
The arguments @var{destination} and @var{display} control what to do
with the output from the subprocess, and whether to update the display
@ -305,6 +312,12 @@ inputinput@point{}
@end smallexample
@end defun
@tindex shell-command-to-string
@defun shell-command-to-string command
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
@node MS-DOS Subprocesses
@section MS-DOS Subprocesses
@ -346,8 +359,8 @@ This function creates a new asynchronous subprocess and starts the
program @var{program} running in it. It returns a process object that
stands for the new subprocess in Lisp. The argument @var{name}
specifies the name for the process object; if a process with this name
already exists, then @var{name} is modified (by adding @samp{<1>}, etc.)
to be unique. The buffer @var{buffer-or-name} is the buffer to
already exists, then @var{name} is modified (by appending @samp{<1>},
etc.) to be unique. The buffer @var{buffer-or-name} is the buffer to
associate with the process.
The remaining arguments, @var{args}, are strings that specify command
@ -388,7 +401,8 @@ Process my-process finished
This function is like @code{start-process} except that it uses a shell
to execute the specified command. The argument @var{command} is a shell
command name, and @var{command-args} are the arguments for the shell
command.
command. The variable @code{shell-file-name} specifies which shell to
use.
@end defun
@defvar process-connection-type
@ -400,11 +414,11 @@ used, when available. Otherwise, pipes are used.
@sc{pty}s are usually preferable for processes visible to the user, as
in Shell mode, because they allow job control (@kbd{C-c}, @kbd{C-z},
etc.) to work between the process and its children whereas pipes do not.
For subprocesses used for internal purposes by programs, it is often
better to use a pipe, because they are more efficient. In addition, the
total number of @sc{pty}s is limited on many systems and it is good not
to waste them.
etc.) to work between the process and its children, whereas pipes do
not. For subprocesses used for internal purposes by programs, it is
often better to use a pipe, because they are more efficient. In
addition, the total number of @sc{pty}s is limited on many systems and
it is good not to waste them.
The value @code{process-connection-type} is used when
@code{start-process} is called. So you can specify how to communicate
@ -535,6 +549,13 @@ process is started and remains constant as long as the process exists.
This function returns the name of @var{process}.
@end defun
@tindex process-contact
@defun process-contact process
This function returns @code{t} for an ordinary child process, and
@code{(@var{hostname} @var{service})} for a net connection
(@pxref{Network}).
@end defun
@defun process-status process-name
This function returns the status of @var{process-name} as a symbol.
The argument @var{process-name} must be a process, a buffer, a
@ -582,8 +603,8 @@ For a network connection, @code{process-status} returns one of the symbols
@code{open} or @code{closed}. The latter means that the other side
closed the connection, or Emacs did @code{delete-process}.
In earlier Emacs versions (prior to version 19), the status of a network
connection was @code{run} if open, and @code{exit} if closed.
In Emacs version 18, the status of a network connection was @code{run}
if open, and @code{exit} if closed.
@end defun
@defun process-exit-status process
@ -600,6 +621,26 @@ instead of a terminal (see @code{process-connection-type} in
@ref{Asynchronous Processes}).
@end defun
@tindex process-coding-system
@defun process-coding-system process
This function returns a cons cell describing the coding systems in use
for decoding output from @var{process} and for encoding input to
@var{process} (@pxref{Coding Systems}). The value has this form:
@example
(@var{coding-system-for-decoding}
. @var{coding-system-for-encoding})
@end example
@end defun
@tindex set-process-coding-system
@defun set-process-coding-system process decoding-system encoding-system
This function specifies the coding systems to use for subsequent output
from and input to @var{process}. It will use @var{decoding-system} to
decode subprocess output, and @var{encoding-system} to encode subprocess
input.
@end defun
@node Input to Processes
@section Sending Input to Processes
@cindex process input
@ -614,6 +655,10 @@ data appears on the ``standard input'' of the subprocess.
the other characters, to force them through. For most programs,
these @sc{eof}s do no harm.
Subprocess input is normally encoded using a coding system before the
subprocess receives it, much like text written into a file.
@xref{Coding Systems}.
@defun process-send-string process-name string
This function sends @var{process-name} the contents of @var{string} as
standard input. The argument @var{process-name} must be a process or
@ -744,10 +789,11 @@ This function stops the process @var{process-name} by sending the
signal @code{SIGTSTP}. Use @code{continue-process} to resume its
execution.
On systems with job control, the ``stop character'' (usually @kbd{C-z})
sends this signal (outside of Emacs). When @var{current-group} is
non-@code{nil}, you can think of this function as ``typing @kbd{C-z}''
on the terminal Emacs uses to communicate with the subprocess.
On systems with job control, outside of Emacs)\, the ``stop character''
(usually @kbd{C-z}) normally sends this signal. When
@var{current-group} is non-@code{nil}, you can think of this function as
``typing @kbd{C-z}'' on the terminal Emacs uses to communicate with the
subprocess.
@end defun
@defun continue-process &optional process-name current-group
@ -775,6 +821,10 @@ called the @dfn{filter function} can be called to act on the output. If
the process has no buffer and no filter function, its output is
discarded.
Subprocess output is normally decoded using a coding system before the
buffer or filter function receives it, much like text read from a file.
@xref{Coding Systems}.
@menu
* Process Buffers:: If no filter, output is put in a buffer.
* Filter Functions:: Filter functions accept output from the process.
@ -828,8 +878,8 @@ example of a filter function that uses @code{process-mark} is found at
the end of the following section.
When the user is expected to enter input in the process buffer for
transmission to the process, the process marker is useful for
distinguishing the new input from previous output.
transmission to the process, the process marker separates the new input
from previous output.
@end defun
@defun set-process-buffer process buffer
@ -841,7 +891,7 @@ associated with no buffer.
@defun get-buffer-process buffer-or-name
This function returns the process associated with @var{buffer-or-name}.
If there are several processes associated with it, then one is chosen.
(Presently, the one chosen is the one most recently created.) It is
(Currently, the one chosen is the one most recently created.) It is
usually a bad idea to have more than one process associated with the
same buffer.
@ -867,9 +917,9 @@ then @emph{all} output from that process is passed to the filter. The
process buffer is used directly for output from the process only when
there is no filter.
A filter function must accept two arguments: the associated process and
a string, which is the output. The function is then free to do whatever it
chooses with the output.
A filter function must accept two arguments: the associated process
and a string, which is output just received from it. The function is
then free to do whatever it chooses with the output.
A filter function runs only while Emacs is waiting (e.g., for terminal
input, or for time to elapse, or for process output). This avoids the
@ -897,61 +947,61 @@ filter function. @xref{Debugger}.
process's buffer, mimicking the actions of Emacs when there is no
filter. Such filter functions need to use @code{set-buffer} in order to
be sure to insert in that buffer. To avoid setting the current buffer
semipermanently, these filter functions must use @code{unwind-protect}
to make sure to restore the previous current buffer. They should also
update the process marker, and in some cases update the value of point.
Here is how to do these things:
semipermanently, these filter functions must save and restore the
current buffer. They should also update the process marker, and in some
cases update the value of point. Here is how to do these things:
@smallexample
@group
(defun ordinary-insertion-filter (proc string)
(let ((old-buffer (current-buffer)))
(unwind-protect
(let (moving)
(set-buffer (process-buffer proc))
(setq moving (= (point) (process-mark proc)))
(with-current-buffer (process-buffer proc)
(let ((moving (= (point) (process-mark proc))))
@end group
@group
(save-excursion
;; @r{Insert the text, moving the process-marker.}
(goto-char (process-mark proc))
(insert string)
(set-marker (process-mark proc) (point)))
(if moving (goto-char (process-mark proc))))
(set-buffer old-buffer))))
(save-excursion
;; @r{Insert the text, advancing the process marker.}
(goto-char (process-mark proc))
(insert string)
(set-marker (process-mark proc) (point)))
(if moving (goto-char (process-mark proc))))))
@end group
@end smallexample
@noindent
The reason to use an explicit @code{unwind-protect} rather than letting
@code{save-excursion} restore the current buffer is so as to preserve
the change in point made by @code{goto-char}.
The reason to use @code{with-current-buffer}, rather than using
@code{save-excursion} to save and restore the current buffer, is so as
to preserve the change in point made by the second call to
@code{goto-char}.
To make the filter force the process buffer to be visible whenever new
text arrives, insert the following line just before the
@code{unwind-protect}:
@code{with-current-buffer} construct:
@smallexample
(display-buffer (process-buffer proc))
@end smallexample
To force point to move to the end of the new output no matter where
it was previously, eliminate the variable @code{moving} and call
To force point to the end of the new output, no matter where it was
previously, eliminate the variable @code{moving} and call
@code{goto-char} unconditionally.
In earlier Emacs versions, every filter function that did regexp
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically; filter functions never need to do it
explicitly. @xref{Match Data}.
In earlier Emacs versions, every filter function that did regular
expression searching or matching had to explicitly save and restore the
match data. Now Emacs does this automatically for filter functions;
they never need to do it explicitly. @xref{Match Data}.
A filter function that writes the output into the buffer of the
process should check whether the buffer is still alive. If it tries to
insert into a dead buffer, it will get an error. If the buffer is dead,
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}.
insert into a dead buffer, it will get an error. The expression
@code{(buffer-name (process-buffer @var{process}))} returns @code{nil}
if the buffer is dead.
The output to the function may come in chunks of any size. A program
that produces the same output twice in a row may send it as one batch
of 200 characters one time, and five batches of 40 characters the next.
that produces the same output twice in a row may send it as one batch of
200 characters one time, and five batches of 40 characters the next. If
the filter looks for certain text strings in the subprocess output, make
sure to handle the case where one of these strings is split across two
or more batches of output.
@defun set-process-filter process filter
This function gives @var{process} the filter function @var{filter}. If
@ -1007,15 +1057,15 @@ there is no filter function:
;; @r{Insert input in the buffer specified by @code{my-shell-buffer}}
;; @r{and make sure that buffer is shown in some window.}
(defun my-process-filter (proc str)
(let ((cur (selected-window))
(pop-up-windows t))
(pop-to-buffer my-shell-buffer)
(let ((cur (selected-window))
(pop-up-windows t))
(pop-to-buffer my-shell-buffer)
@end group
@group
(goto-char (point-max))
(insert str)
(set-marker (process-mark proc) (point-max))
(select-window cur)))
(goto-char (point-max))
(insert str)
(set-marker (process-mark proc) (point-max))
(select-window cur)))
@end group
@end smallexample
@end ignore
@ -1113,10 +1163,10 @@ programs was running when the sentinel was started. However, if
off. This makes it possible to use the Lisp debugger to debug the
sentinel. @xref{Debugger}.
In earlier Emacs versions, every sentinel that did regexp searching or
matching had to explicitly save and restore the match data. Now Emacs
does this automatically; sentinels never need to do it explicitly.
@xref{Match Data}.
In earlier Emacs versions, every sentinel that did regular expression
searching or matching had to explicitly save and restore the match data.
Now Emacs does this automatically for sentinels; they never need to do
it explicitly. @xref{Match Data}.
@defun set-process-sentinel process sentinel
This function associates @var{sentinel} with @var{process}. If
@ -1156,10 +1206,10 @@ was not.
@section Transaction Queues
@cindex transaction queue
You can use a @dfn{transaction queue} for more convenient communication
with subprocesses using transactions. First use @code{tq-create} to
create a transaction queue communicating with a specified process. Then
you can call @code{tq-enqueue} to send a transaction.
You can use a @dfn{transaction queue} to communicate with a subprocess
using transactions. First use @code{tq-create} to create a transaction
queue communicating with a specified process. Then you can call
@code{tq-enqueue} to send a transaction.
@defun tq-create process
This function creates and returns a transaction queue communicating with

145
lispref/searching.texi
View file

@ -1,9 +1,9 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/searching
@node Searching and Matching, Syntax Tables, Text, Top
@node Searching and Matching, Syntax Tables, Non-ASCII Characters, Top
@chapter Searching and Matching
@cindex searching
@ -38,14 +38,18 @@ interactively. If you do so, they prompt for the search string;
@var{limit} and @var{noerror} are set to @code{nil}, and @var{repeat}
is set to 1.
These search functions convert the search string to multibyte if the
buffer is multibyte; they convert the search string to unibyte if the
buffer is unibyte. @xref{Text Representations}.
@deffn Command search-forward string &optional limit noerror repeat
This function searches forward from point for an exact match for
This function searches forward from point for an exact match for
@var{string}. If successful, it sets point to the end of the occurrence
found, and returns the new value of point. If no match is found, the
value and side effects depend on @var{noerror} (see below).
@c Emacs 19 feature
In the following example, point is initially at the beginning of the
In the following example, point is initially at the beginning of the
line. Then @code{(search-forward "fox")} moves point after the last
letter of @samp{fox}:
@ -66,20 +70,20 @@ The quick brown fox@point{} jumped over the lazy dog.
@end group
@end example
The argument @var{limit} specifies the upper bound to the search. (It
The argument @var{limit} specifies the upper bound to the search. (It
must be a position in the current buffer.) No match extending after
that position is accepted. If @var{limit} is omitted or @code{nil}, it
defaults to the end of the accessible portion of the buffer.
@kindex search-failed
What happens when the search fails depends on the value of
What happens when the search fails depends on the value of
@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
error is signaled. If @var{noerror} is @code{t}, @code{search-forward}
returns @code{nil} and does nothing. If @var{noerror} is neither
@code{nil} nor @code{t}, then @code{search-forward} moves point to the
upper bound and returns @code{nil}. (It would be more consistent now
to return the new position of point in that case, but some programs
may depend on a value of @code{nil}.)
upper bound and returns @code{nil}. (It would be more consistent now to
return the new position of point in that case, but some existing
programs may depend on a value of @code{nil}.)
If @var{repeat} is supplied (it must be a positive number), then the
search is repeated that many times (each time starting at the end of the
@ -214,16 +218,16 @@ possible. Thus, @samp{o*} matches any number of @samp{o}s (including no
expression. Thus, @samp{fo*} has a repeating @samp{o}, not a repeating
@samp{fo}. It matches @samp{f}, @samp{fo}, @samp{foo}, and so on.
The matcher processes a @samp{*} construct by matching, immediately,
as many repetitions as can be found. Then it continues with the rest
of the pattern. If that fails, backtracking occurs, discarding some
of the matches of the @samp{*}-modified construct in case that makes
it possible to match the rest of the pattern. For example, in matching
@samp{ca*ar} against the string @samp{caaar}, the @samp{a*} first
tries to match all three @samp{a}s; but the rest of the pattern is
The matcher processes a @samp{*} construct by matching, immediately, as
many repetitions as can be found. Then it continues with the rest of
the pattern. If that fails, backtracking occurs, discarding some of the
matches of the @samp{*}-modified construct in the hope that that will
make it possible to match the rest of the pattern. For example, in
matching @samp{ca*ar} against the string @samp{caaar}, the @samp{a*}
first tries to match all three @samp{a}s; but the rest of the pattern is
@samp{ar} and there is only @samp{r} left to match, so this try fails.
The next alternative is for @samp{a*} to match only two @samp{a}s.
With this choice, the rest of the regexp matches successfully.@refill
The next alternative is for @samp{a*} to match only two @samp{a}s. With
this choice, the rest of the regexp matches successfully.@refill
Nested repetition operators can be extremely slow if they specify
backtracking loops. For example, it could take hours for the regular
@ -242,7 +246,7 @@ matches the strings @samp{car} and @samp{caaaar} but not the string
@item ?
@cindex @samp{?} in regexp
is a postfix operator, similar to @samp{*} except that it can match the
is a postfix operator, similar to @samp{*} except that it must match the
preceding expression either once or not at all. For example,
@samp{ca?r} matches @samp{car} or @samp{cr}; nothing else.
@ -265,6 +269,19 @@ starting and ending characters with a @samp{-} between them. Thus,
intermixed freely with individual characters, as in @samp{[a-z$%.]},
which matches any lower case ASCII letter or @samp{$}, @samp{%} or
period.
You cannot always match all non-@sc{ASCII} characters with the regular
expression @samp{[\200-\377]}. This works when searching a unibyte
buffer or string (@pxref{Text Representations}), but not in a multibyte
buffer or string, because many non-@sc{ASCII} characters have codes
above octal 0377. However, the regular expression @samp{[^\000-\177]}
does match all non-@sc{ASCII} characters, in both multibyte and unibyte
representations, because only the @sc{ASCII} characters are excluded.
The beginning and end of a range must be in the same character set
(@pxref{Character Sets}). Thus, @samp{[a-\x8c0]} is invalid because
@samp{a} is in the @sc{ASCII} character set but the character 0x8c0
(@samp{a} with grave accent) is in the Latin-1 character set.
Note that the usual regexp special characters are not special inside a
character set. A completely different set of special characters exists
@ -424,9 +441,9 @@ matches any character that is not a word constituent.
matches any character whose syntax is @var{code}. Here @var{code} is a
character that represents a syntax code: thus, @samp{w} for word
constituent, @samp{-} for whitespace, @samp{(} for open parenthesis,
etc. Represent a character of whitespace (which can be a newline) by
either @samp{-} or a space character. @xref{Syntax Tables}, for a list
of syntax codes and the characters that stand for them.
etc. To represent whitespace syntax, use either @samp{-} or a space
character. @xref{Syntax Class Table}, for a list of syntax codes and
the characters that stand for them.
@item \S@var{code}
@cindex @samp{\S} in regexp
@ -513,6 +530,37 @@ whitespace:
@end example
@end defun
@tindex regexp-opt
@defun regexp-opt strings &optional paren
This function returns an efficient regular expression that will match
any of the strings @var{strings}. This is useful when you need to make
matching or searching as fast as possible---for example, for Font Lock
mode.
If the optional argument @var{paren} is non-@code{nil}, then the
returned regular expression is always enclosed by at least one
parentheses-grouping construct.
This simplified definition of @code{regexp-opt} produces a
regular expression which is equivalent to the actual value
(but not as efficient):
@example
(defun regexp-opt (strings paren)
(let ((open-paren (if paren "\\(" ""))
(close-paren (if paren "\\)" "")))
(concat open-paren
(mapconcat 'regexp-quote strings "\\|")
close-paren)))
@end example
@end defun
@tindex regexp-opt-depth
@defun regexp-opt-depth regexp
This function returns the total number of grouping constructs
(parenthesised expressions) in @var{regexp}.
@end defun
@node Regexp Example
@comment node-name, next, previous, up
@subsection Complex Regexp Example
@ -565,11 +613,11 @@ repeated zero or more times.
@item \\($\\|@ $\\|\t\\|@ @ \\)
The third part of the pattern matches the whitespace that follows the
end of a sentence: the end of a line, or a tab, or two spaces. The
double backslashes mark the parentheses and vertical bars as regular
expression syntax; the parentheses delimit a group and the vertical bars
separate alternatives. The dollar sign is used to match the end of a
line.
end of a sentence: the end of a line (optionally with a space), or a
tab, or two spaces. The double backslashes mark the parentheses and
vertical bars as regular expression syntax; the parentheses delimit a
group and the vertical bars separate alternatives. The dollar sign is
used to match the end of a line.
@item [ \t\n]*
Finally, the last part of the pattern matches any additional whitespace
@ -588,6 +636,10 @@ Search, , Regular Expression Search, emacs, The GNU Emacs Manual}. Here
we describe only the search functions useful in programs. The principal
one is @code{re-search-forward}.
These search functions convert the regular expression to multibyte if
the buffer is multibyte; they convert the regular expression to unibyte
if the buffer is unibyte. @xref{Text Representations}.
@deffn Command re-search-forward regexp &optional limit noerror repeat
This function searches forward in the current buffer for a string of
text that is matched by the regular expression @var{regexp}. The
@ -599,7 +651,13 @@ If @var{limit} is non-@code{nil} (it must be a position in the current
buffer), then it is the upper bound to the search. No match extending
after that position is accepted.
What happens when the search fails depends on the value of
If @var{repeat} is supplied (it must be a positive number), then the
search is repeated that many times (each time starting at the end of the
previous time's match). If all these successive searches succeed, the
function succeeds, moving point and returning its new value. Otherwise
the function fails.
What happens when the function fails depends on the value of
@var{noerror}. If @var{noerror} is @code{nil}, a @code{search-failed}
error is signaled. If @var{noerror} is @code{t},
@code{re-search-forward} does nothing and returns @code{nil}. If
@ -607,12 +665,6 @@ error is signaled. If @var{noerror} is @code{t},
@code{re-search-forward} moves point to @var{limit} (or the end of the
buffer) and returns @code{nil}.
If @var{repeat} is supplied (it must be a positive number), then the
search is repeated that many times (each time starting at the end of the
previous time's match). If these successive searches succeed, the
function succeeds, moving point and returning its new value. Otherwise
the search fails.
In the following example, point is initially before the @samp{T}.
Evaluating the search call moves point to the end of that line (between
the @samp{t} of @samp{hat} and the newline).
@ -740,9 +792,6 @@ possibilities and found all matches, so they can report the longest
match, as required by POSIX. This is much slower, so use these
functions only when you really need the longest match.
In Emacs versions prior to 19.29, these functions did not exist, and
the functions described above implemented full POSIX backtracking.
@defun posix-search-forward regexp &optional limit noerror repeat
This is like @code{re-search-forward} except that it performs the full
backtracking specified by the POSIX standard for regular expression
@ -879,9 +928,10 @@ The ``key bindings'' are not commands, just symbols that are meaningful
to the functions that use this map.
@item
Prefix keys are not supported; each key binding must be for a single event
key sequence. This is because the functions don't use read key sequence to
get the input; instead, they read a single event and look it up ``by hand.''
Prefix keys are not supported; each key binding must be for a
single-event key sequence. This is because the functions don't use
@code{read-key-sequence} to get the input; instead, they read a single
event and look it up ``by hand.''
@end itemize
@end defvar
@ -995,6 +1045,11 @@ should make sure that the current buffer when you call
matching.
@end defun
@defun match-string-no-properties count
This function is like @code{match-string} except that the result
has no text properties.
@end defun
@defun match-beginning count
This function returns the position of the start of text matched by the
last regular expression searched for, or a subexpression of it.
@ -1240,7 +1295,7 @@ useful for writing code that can run in Emacs 18. Here is how:
@group
(let ((data (match-data)))
(unwind-protect
@dots{} ; @r{May change the original match data.}
@dots{} ; @r{Ok to change the original match data.}
(set-match-data data)))
@end group
@end example
@ -1280,9 +1335,9 @@ associated with it still exists.
By default, searches in Emacs ignore the case of the text they are
searching through; if you specify searching for @samp{FOO}, then
@samp{Foo} or @samp{foo} is also considered a match. Regexps, and in
particular character sets, are included: thus, @samp{[aB]} would match
@samp{a} or @samp{A} or @samp{b} or @samp{B}.
@samp{Foo} or @samp{foo} is also considered a match. This applies to
regular expressions, too; thus, @samp{[aB]} would match @samp{a} or
@samp{A} or @samp{b} or @samp{B}.
If you do not want this feature, set the variable
@code{case-fold-search} to @code{nil}. Then all letters must match
@ -1296,7 +1351,7 @@ Buffer-Local}.) Alternatively, you may change the value of
distinctions differently. When given a lower case letter, it looks for
a match of either case, but when given an upper case letter, it looks
for an upper case letter only. But this has nothing to do with the
searching functions Lisp functions use.
searching functions used in Lisp code.
@defopt case-replace
This variable determines whether the replacement functions should

203
lispref/sequences.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/sequences
@node Sequences Arrays Vectors, Symbols, Lists, Top
@ -52,6 +52,8 @@ elements of strings are all characters.
* Array Functions:: Functions specifically for arrays.
* Vectors:: Special characteristics of Emacs Lisp vectors.
* Vector Functions:: Functions specifically for vectors.
* Char-Tables:: How to work with char-tables.
* Bool-Vectors:: How to work with bool-vectors.
@end menu
@node Sequence Functions
@ -140,6 +142,8 @@ Returns the number of elements in @var{sequence}. If @var{sequence} is
a cons cell that is not a list (because the final @sc{cdr} is not
@code{nil}), a @code{wrong-type-argument} error is signaled.
@xref{List Elements}, for the related function @code{safe-list}.
@example
@group
(length '(1 2 3))
@ -241,7 +245,7 @@ They occupy one-fourth the space of a vector of the same elements.
@item
Strings are printed in a way that shows the contents more clearly
as characters.
as text.
@item
Strings can hold text properties. @xref{Text Properties}.
@ -260,12 +264,12 @@ Sequence Input}.
@node Array Functions
@section Functions that Operate on Arrays
In this section, we describe the functions that accept both strings
and vectors.
In this section, we describe the functions that accept all types of
arrays.
@defun arrayp object
This function returns @code{t} if @var{object} is an array (i.e., either a
vector or a string).
This function returns @code{t} if @var{object} is an array (i.e., a
vector, a string, a bool-vector or a char-table).
@example
@group
@ -326,7 +330,11 @@ x
@end example
If @var{array} is a string and @var{object} is not a character, a
@code{wrong-type-argument} error results.
@code{wrong-type-argument} error results. If @var{array} is a string
and @var{object} is character, but @var{object} does not use the same
number of bytes as the character currently stored in @code{(aref
@var{object} @var{index})}, that is also an error. @xref{Chars and
Bytes}.
@end defun
@defun fillarray array object
@ -363,13 +371,12 @@ are often useful for objects known to be arrays. @xref{Sequence Functions}.
Arrays in Lisp, like arrays in most languages, are blocks of memory
whose elements can be accessed in constant time. A @dfn{vector} is a
general-purpose array; its elements can be any Lisp objects. (The other
kind of array in Emacs Lisp is the @dfn{string}, whose elements must be
characters.) Vectors in Emacs serve as syntax tables (vectors of
integers), as obarrays (vectors of symbols), and in keymaps (vectors of
commands). They are also used internally as part of the representation
of a byte-compiled function; if you print such a function, you will see
a vector in it.
general-purpose array; its elements can be any Lisp objects. (By
contrast, a string can hold only characters as elements.) Vectors in
Emacs are used for obarrays (vectors of symbols), and as part of keymaps
(vectors of commands). They are also used internally as part of the
representation of a byte-compiled function; if you print such a
function, you will see a vector in it.
In Emacs Lisp, the indices of the elements of a vector start from zero
and count up from there.
@ -384,7 +391,7 @@ evaluation: the result of evaluating it is the same vector. This does
not evaluate or even examine the elements of the vector.
@xref{Self-Evaluating Forms}.
Here are examples of these principles:
Here are examples illustrating these principles:
@example
@group
@ -444,9 +451,9 @@ each initialized to @var{object}.
@defun vconcat &rest sequences
@cindex copying vectors
This function returns a new vector containing all the elements of the
@var{sequences}. The arguments @var{sequences} may be lists, vectors,
or strings. If no @var{sequences} are given, an empty vector is
returned.
@var{sequences}. The arguments @var{sequences} may be any kind of
arrays, including lists, vectors, or strings. If no @var{sequences} are
given, an empty vector is returned.
The value is a newly constructed vector that is not @code{eq} to any
existing vector.
@ -491,3 +498,163 @@ list with the same elements (@pxref{Building Lists}):
@result{} (1 two (quote (three)) "four" [five])
@end group
@end example
@node Char-Tables
@section Char-Tables
@cindex char-tables
A char-table is much like a vector, except that it is indexed by
character codes. Any valid character code, without modifiers, can be
used as an index in a char-table. You can access a char-table with
@code{aref} and @code{aset}, just like a vector.
@cindex extra slots of char-table
@cindex subtype of char-table
Each char-table has a @dfn{subtype} which is a symbol. In order to be
a valid subtype, a symbol must have a @code{char-table-extra-slots}
property which is an integer between 0 and 10. This integer specifies
the number of @dfn{extra slots} in the char-table.
@cindex parent of char-table
A char-table can have a @dfn{parent}. which is another char-table. If
it does, then whenever the char-table specifies @code{nil} for a
particular character @var{c}, it inherits the value specified in the
parent. In other words, @code{(aref @var{char-table} @var{c})} returns
the value from the parent of @var{char-table} if @var{char-table} itself
specifies @code{nil}.
@cindex default value of char-table
A char-table can also have a @dfn{default value}. If so, then
@code{(aref @var{char-table} @var{c})} returns the default value
whenever the char-table does not specify any other non-@code{nil} value.
@tindex make-char-table
@defun make-char-table subtype &optional init
Return a newly created char-table, with subtype @var{subtype}. Each
element is initialized to @var{init}, which defaults to @code{nil}. You
cannot alter the subtype of a char-table after the char-table is
created.
@end defun
@tindex char-table-p
@defun char-table-p object
This function returns @code{t} if @code{object} is a char-table,
otherwise @code{nil}.
@end defun
@tindex char-table-subtype
@defun char-table-subtype char-table
This function returns the subtype symbol of @var{char-table}.
@end defun
@tindex set-char-table-default
@defun set-char-table-default char-table new-default
This function sets the default value of @var{char-table} to
@var{new-default}.
There is no special function to access the default value of a char-table.
To do that, use @code{(char-table-range @var{char-table} nil)}.
@end defun
@tindex char-table-parent
@defun char-table-parent char-table
This function returns the parent of @var{char-table}. The parent is
always either @code{nil} or another char-table.
@end defun
@tindex set-char-table-parent
@defun set-char-table-parent char-table new-parent
This function sets the parent of @var{char-table} to @var{new-parent}.
@end defun
@tindex char-table-extra-slot
@defun char-table-extra-slot char-table n
This function returns the contents of extra slot @var{n} of
@var{char-table}. The number of extra slots in a char-table is
determined by its subtype.
@end defun
@tindex set-char-table-extra-slot
@defun set-char-table-extra-slot char-table n value
This function stores @var{value} in extra slot @var{n} of
@var{char-table}.
@end defun
A char-table can specify an element value for a single character code;
it can also specify a value for an entire character set.
@tindex char-table-range
@defun char-table-range char-table range
This returns the value specified in @var{char-table} for a range of
characters @var{range}. Here @var{range} may be
@table @asis
@item @code{nil}
Refers to the default value.
@item @var{char}
Refers to the element for character @var{char}.
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
@end table
@end defun
@tindex set-char-table-range
@defun set-char-table-range char-table range value
This function set the value in @var{char-table} for a range of
characters @var{range}. Here @var{range} may be
@table @asis
@item @code{nil}
Refers to the default value.
@item @code{t}
Refers to the whole range of character codes.
@item @var{char}
Refers to the element for character @var{char}.
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
@end table
@end defun
@tindex map-char-table
@defun map-char-table function char-table
This function calls @var{function} for each element of @var{char-table}.
@var{function} is called with two arguments, a key and a value. The key
is a possible @var{range} argument for @code{char-table-range}, and the
value is @code{(char-table-range @var{char-table} @var{key})}. Invalid
character codes are never used as the key.
Overall, the keys-value pairs passed to @var{function} describe all the
values stored in @var{char-table}.
@end defun
@node Bool-Vectors
@section Bool-vectors
@cindex Bool-vectors
A bool-vector is much like a vector, except that it stores only the
values @code{t} and @code{nil}. If you try to store any non-@code{nil}
value into an element of the bool-vector, that actually stores @code{t}
there.
There are two special functions for working with bool-vectors; aside
from that, you manipulate them with same functions used for other kinds
of arrays.
@tindex make-bool-vector
@defun make-bool-vector length initial
Return a new book-vector of @var{length} elements,
each one initialized to @var{initial}.
@end defun
@defun bool-vector-p object
This returns @code{t} if @var{object} is a bool-vector,
and @code{nil} otherwise.
@end defun

40
lispref/streams.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/streams
@node Read and Print, Minibuffers, Debugging, Top
@ -38,8 +38,9 @@ is the read syntax for a cons cell whose @sc{car} is @code{a} and whose
@sc{cdr} is the number 5.
@dfn{Printing} a Lisp object means producing text that represents that
object---converting the object to its printed representation. Printing
the cons cell described above produces the text @samp{(a .@: 5)}.
object---converting the object to its @dfn{printed representation}
(@pxref{Printed Representation}). Printing the cons cell described
above produces the text @samp{(a .@: 5)}.
Reading and printing are more or less inverse operations: printing the
object that results from reading a given piece of text often produces
@ -57,7 +58,7 @@ three kinds of exceptions:
@itemize @bullet
@item
Printing can produce text that cannot be read. For example, buffers,
windows, frames, subprocesses and markers print into text that starts
windows, frames, subprocesses and markers print as text that starts
with @samp{#}; if you try to read this text, you get an error. There is
no way to read those data types.
@ -112,6 +113,7 @@ character). When that happens, @var{function} should save the argument
and arrange to return it on the next call. This is called
@dfn{unreading} the character; it happens when the Lisp reader reads one
character too many and wants to ``put it back where it came from''.
In this case, it makes no difference what value @var{function} returns.
@item @code{t}
@cindex @code{t} input stream
@ -163,7 +165,7 @@ whitespace preceding the significant text.
In Emacs 18, reading a symbol discarded the delimiter terminating the
symbol. Thus, point would end up at the beginning of @samp{contents}
rather than after @samp{the}. The Emacs 19 behavior is superior because
rather than after @samp{the}. The current behavior is superior because
it correctly handles input such as @samp{bar(foo)}, where the
open-parenthesis that ends one object is needed as the beginning of
another object.
@ -515,7 +517,8 @@ contents more clearly.
@node Output Functions
@section Output Functions
This section describes the Lisp functions for printing Lisp objects.
This section describes the Lisp functions for printing Lisp
objects---converting objects into their printed representation.
@cindex @samp{"} in printing
@cindex @samp{\} in printing
@ -661,6 +664,23 @@ See @code{format}, in @ref{String Conversion}, for other ways to obtain
the printed representation of a Lisp object as a string.
@end defun
@tindex with-output-to-string
@defmac with-output-to-string body...
This macro executes the @var{body} forms with standard-output set up so
that all output feeds into a string. Then it returns that string.
For example, if the current buffer name is @samp{foo},
@example
(with-output-to-string
(princ "The buffer is ")
(princ (buffer-name)))
@end example
@noindent
returns @code{"The buffer is foo"}.
@end defmac
@node Output Variables
@section Variables Affecting Output
@ -706,9 +726,9 @@ In the second expression, the local binding of
@defvar print-length
@cindex printing limits
The value of this variable is the maximum number of elements of a list,
vector or bitvector that will be printed. If an object being printed has
more than this many elements, it is abbreviated with an ellipsis.
The value of this variable is the maximum number of elements to print in
any list, vector or bool-vector. If an object being printed has more
than this many elements, it is abbreviated with an ellipsis.
If the value is @code{nil} (the default), then there is no limit.
@ -730,6 +750,4 @@ The value of this variable is the maximum depth of nesting of
parentheses and brackets when printed. Any list or vector at a depth
exceeding this limit is abbreviated with an ellipsis. A value of
@code{nil} (which is the default) means no limit.
This variable exists in version 19 and later versions.
@end defvar

249
lispref/strings.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/strings
@node Strings and Characters, Lists, Numbers, Top
@ -25,6 +25,7 @@ keyboard character events.
* Basics: String Basics. Basic properties of strings and characters.
* Predicates for Strings:: Testing whether an object is a string or char.
* Creating Strings:: Functions to allocate new strings.
* Modifying Strings:: Altering the contents of an existing string.
* Text Comparison:: Comparing characters or strings.
* String Conversion:: Converting characters or strings and vice versa.
* Formatting Strings:: @code{format}: Emacs's analog of @code{printf}.
@ -40,12 +41,10 @@ characters. Characters are represented in Emacs Lisp as integers;
whether an integer was intended as a character or not is determined only
by how it is used. Thus, strings really contain integers.
The length of a string (like any array) is fixed and independent of
the string contents, and cannot be altered. Strings in Lisp are
@emph{not} terminated by a distinguished character code. (By contrast,
strings in C are terminated by a character with @sc{ASCII} code 0.)
This means that any character, including the null character (@sc{ASCII}
code 0), is a valid element of a string.@refill
The length of a string (like any array) is fixed, and cannot be
altered once the string exists. Strings in Lisp are @emph{not}
terminated by a distinguished character code. (By contrast, strings in
C are terminated by a character with @sc{ASCII} code 0.)
Since strings are considered arrays, you can operate on them with the
general array functions. (@xref{Sequences Arrays Vectors}.) For
@ -53,10 +52,13 @@ example, you can access or change individual characters in a string
using the functions @code{aref} and @code{aset} (@pxref{Array
Functions}).
Each character in a string is stored in a single byte. Therefore,
numbers not in the range 0 to 255 are truncated when stored into a
string. This means that a string takes up much less memory than a
vector of the same length.
There are two text representations for non-@sc{ASCII} characters in
Emacs strings (and in buffers): unibyte and multibyte (@pxref{Text
Representations}). @sc{ASCII} characters always occupy one byte in a
string; in fact, there is no real difference between the two
representation for a string which is all @sc{ASCII}. For most Lisp
programming, you don't need to be concerned with these two
representations.
Sometimes key sequences are represented as strings. When a string is
a key sequence, string elements in the range 128 to 255 represent meta
@ -66,9 +68,10 @@ events in the range 128 to 255.
Strings cannot hold characters that have the hyper, super or alt
modifiers; they can hold @sc{ASCII} control characters, but no other
control characters. They do not distinguish case in @sc{ASCII} control
characters. @xref{Character Type}, for more information about
representation of meta and other modifiers for keyboard input
characters.
characters. If you want to store such characters in a sequence, such as
a key sequence, you must use a vector instead of a string.
@xref{Character Type}, for more information about representation of meta
and other modifiers for keyboard input characters.
Strings are useful for holding regular expressions. You can also
match regular expressions against strings (@pxref{Regexp Search}). The
@ -84,6 +87,8 @@ strings also copy the properties of the characters being copied.
@xref{Text}, for information about functions that display strings or
copy them into buffers. @xref{Character Type}, and @ref{String Type},
for information about the syntax of characters and strings.
@xref{Non-ASCII Characters}, for functions to convert between text
representations and encode and decode character codes.
@node Predicates for Strings
@section The Predicates for Strings
@ -123,6 +128,16 @@ putting strings together, or by taking them apart.
@code{make-list} (@pxref{Building Lists}).
@end defun
@tindex string
@defun string &rest characters
This returns a string containing the characters @var{characters}.
@example
(string ?a ?b ?c)
@result{} "abc"
@end example
@end defun
@defun substring string start &optional end
This function returns a new string which consists of those characters
from @var{string} in the range from (and including) the character at the
@ -191,6 +206,9 @@ A @code{wrong-type-argument} error is signaled if either @var{start} or
error is signaled if @var{start} indicates a character following
@var{end}, or if either integer is out of range for @var{string}.
@code{substring} actually allows vectors as well as strings for
the first argument.
Contrast this function with @code{buffer-substring} (@pxref{Buffer
Contents}), which returns a string containing a portion of the text in
the current buffer. The beginning of a string is at index 0, but the
@ -251,6 +269,66 @@ description of @code{mapconcat} in @ref{Mapping Functions},
Lists}.
@end defun
@tindex split-string
@defun split-string string separators
Split @var{string} into substrings in between matches for the regular
expression @var{separators}. Each match for @var{separators} defines a
splitting point; the substrings between the splitting points are made
into a list, which is the value. If @var{separators} is @code{nil} (or
omitted), the default is @code{"[ \f\t\n\r\v]+"}.
For example,
@example
(split-string "Soup is good food" "o")
@result{} ("S" "up is g" "" "d f" "" "d")
(split-string "Soup is good food" "o+")
@result{} ("S" "up is g" "d f" "d")
@end example
When there is a match adjacent to the beginning or end of the string,
this does not cause a null string to appear at the beginning or end
of the list:
@example
(split-string "out to moo" "o+")
@result{} ("ut t" " m")
@end example
Empty matches do count, when not adjacent to another match:
@example
(split-string "Soup is good food" "o*")
@result{}("S" "u" "p" " " "i" "s" " " "g" "d" " " "f" "d")
(split-string "Nice doggy!" "")
@result{}("N" "i" "c" "e" " " "d" "o" "g" "g" "y" "!")
@end example
@end defun
@node Modifying Strings
@section Modifying Strings
The most basic way to alter the contents of an existing string is with
@code{aset} (@pxref{Array Functions}). @code{(aset @var{string}
@var{idx} @var{char})} stores @var{char} into @var{string} at index
@var{idx}. Each character occupies one or more bytes, and if @var{char}
needs a different number of bytes from the character already present at
that index, @code{aset} gets an error.
A more powerful function is @code{store-substring}:
@tindex store-substring
@defun store-substring string idx obj
This function alters part of the contents of the string @var{string}, by
storing @var{obj} starting at index @var{idx}. The argument @var{obj}
may be either a character or a (smaller) string.
Since it is impossible to change the length of an existing string, it is
an error if @var{obj} doesn't fit within @var{string}'s actual length,
or if it requires a different number of bytes from the characters
currently present at that point in @var{string}.
@end defun
@need 2000
@node Text Comparison
@section Comparison of Characters and Strings
@ -264,10 +342,9 @@ in case if @code{case-fold-search} is non-@code{nil}.
@example
(char-equal ?x ?x)
@result{} t
(char-to-string (+ 256 ?x))
@result{} "x"
(char-equal ?x (+ 256 ?x))
@result{} t
(let ((case-fold-search nil))
(char-equal ?x ?X))
@result{} nil
@end example
@end defun
@ -284,9 +361,13 @@ match exactly; case is significant.
@result{} nil
@end example
The function @code{string=} ignores the text properties of the
two strings. To compare strings in a way that compares their text
properties also, use @code{equal} (@pxref{Equality Predicates}).
The function @code{string=} ignores the text properties of the two
strings. When @code{equal} (@pxref{Equality Predicates}) compares two
strings, it uses @code{string=}.
If the arguments contain non-@sc{ASCII} characters, and one is unibyte
while the other is multibyte, then they cannot be equal. @xref{Text
Representations}.
@end defun
@defun string-equal string1 string2
@ -308,7 +389,8 @@ Pairs of characters are compared by their @sc{ASCII} codes. Keep in
mind that lower case letters have higher numeric values in the
@sc{ASCII} character set than their upper case counterparts; numbers and
many punctuation characters have a lower numeric value than upper case
letters.
letters. A unibyte non-@sc{ASCII} character is always less than any
multibyte non-@sc{ASCII} character (@pxref{Text Representations}).
@example
@group
@ -360,7 +442,9 @@ for a kind of string comparison; see @ref{Regexp Search}.
strings and integers. @code{format} and @code{prin1-to-string}
(@pxref{Output Functions}) can also convert Lisp objects into strings.
@code{read-from-string} (@pxref{Input Functions}) can ``convert'' a
string representation of a Lisp object into an object.
string representation of a Lisp object into an object. The functions
@code{string-make-multibyte} and @code{string-make-unibyte} convert the
text representation of a string (@pxref{Converting Representations}).
@xref{Documentation}, for functions that produce textual descriptions
of text characters and general input events
@ -433,15 +517,20 @@ negative.
See also the function @code{format} in @ref{Formatting Strings}.
@end defun
@defun string-to-number string
@defun string-to-number string base
@cindex string to number
This function returns the numeric value of the characters in
@var{string}, read in base ten. It skips spaces and tabs at the
beginning of @var{string}, then reads as much of @var{string} as it can
interpret as a number. (On some systems it ignores other whitespace at
the beginning, not just spaces and tabs.) If the first character after
the ignored whitespace is not a digit or a minus sign, this function
returns 0.
@var{string}. If @var{base} is non-@code{nil}, integers are converted
in that base. If @var{base} is @code{nil}, then base ten is used.
Floating point conversion always uses base ten; we have not implemented
other radices for floating point numbers, because that would be much
more work and does not seem useful.
The parsing skips spaces and tabs at the beginning of @var{string}, then
reads as much of @var{string} as it can interpret as a number. (On some
systems it ignores other whitespace at the beginning, not just spaces
and tabs.) If the first character after the ignored whitespace is not a
digit or a minus sign, this function returns 0.
@example
(string-to-number "256")
@ -458,6 +547,21 @@ returns 0.
@code{string-to-int} is an obsolete alias for this function.
@end defun
Here are some other functions that can convert to or from a string:
@table @code
@item concat
@code{concat} can convert a vector or a list into a string.
@xref{Creating Strings}.
@item vconcat
@code{vconcat} can convert a string into a vector. @xref{Vector
Functions}.
@item append
@code{append} can convert a string into a list. @xref{Building Lists}.
@end table
@node Formatting Strings
@comment node-name, next, previous, up
@section Formatting Strings
@ -514,16 +618,18 @@ meaningless.
@table @samp
@item %s
Replace the specification with the printed representation of the object,
made without quoting. Thus, strings are represented by their contents
alone, with no @samp{"} characters, and symbols appear without @samp{\}
characters.
made without quoting (that is, using @code{princ}, not
@code{print}---@pxref{Output Functions}). Thus, strings are represented
by their contents alone, with no @samp{"} characters, and symbols appear
without @samp{\} characters.
If there is no corresponding object, the empty string is used.
@item %S
Replace the specification with the printed representation of the object,
made with quoting. Thus, strings are enclosed in @samp{"} characters,
and @samp{\} characters appear where necessary before special characters.
made with quoting (that is, using @code{prin1}---@pxref{Output
Functions}). Thus, strings are enclosed in @samp{"} characters, and
@samp{\} characters appear where necessary before special characters.
If there is no corresponding object, the empty string is used.
@ -593,7 +699,7 @@ of the object contains fewer characters than this, then it is padded.
The padding is on the left if the prefix is positive (or starts with
zero) and on the right if the prefix is negative. The padding character
is normally a space, but if the numeric prefix starts with a zero, zeros
are used for padding.
are used for padding. Here are some examples of padding:
@example
(format "%06d is padded on the left with zeros" 123)
@ -728,41 +834,48 @@ has the same result as @code{upcase}.
table}. A case table specifies the mapping between upper case and lower
case letters. It affects both the string and character case conversion
functions (see the previous section) and those that apply to text in the
buffer (@pxref{Case Changes}). You need a case table if you are using a
language which has letters other than the standard @sc{ASCII} letters.
buffer (@pxref{Case Changes}).
A case table is a list of this form:
A case table is a char-table whose subtype is @code{case-table}. This
char-table maps each character into the corresponding lower case
character It has three extra slots, which are related tables:
@example
(@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences})
@end example
@table @var
@item upcase
The upcase table maps each character into the corresponding upper
case character.
@item canonicalize
The canonicalize table maps all of a set of case-related characters
into some one of them.
@item equivalences
The equivalences table maps each of a set of case-related characters
into the next one in that set.
@end table
@noindent
where each element is either @code{nil} or a string of length 256. The
element @var{downcase} says how to map each character to its lower-case
equivalent. The element @var{upcase} maps each character to its
upper-case equivalent. If lower and upper case characters are in
one-to-one correspondence, use @code{nil} for @var{upcase}; then Emacs
deduces the upcase table from @var{downcase}.
In simple cases, all you need to specify is the mapping to lower-case;
the three related tables will be calculated automatically from that one.
For some languages, upper and lower case letters are not in one-to-one
correspondence. There may be two different lower case letters with the
same upper case equivalent. In these cases, you need to specify the
maps for both directions.
maps for both lower case and upper case.
The element @var{canonicalize} maps each character to a canonical
The extra table @var{canonicalize} maps each character to a canonical
equivalent; any two characters that are related by case-conversion have
the same canonical equivalent character.
the same canonical equivalent character. For example, since @samp{a}
and @samp{A} are related by case-conversion, they should have the same
canonical equivalent character (which should be either @samp{a} for both
of them, or @samp{A} for both of them).
The element @var{equivalences} is a map that cyclicly permutes each
equivalence class (of characters with the same canonical equivalent).
(For ordinary @sc{ASCII}, this would map @samp{a} into @samp{A} and
@samp{A} into @samp{a}, and likewise for each set of equivalent
characters.)
The extra table @var{equivalences} is a map that cyclicly permutes
each equivalence class (of characters with the same canonical
equivalent). (For ordinary @sc{ASCII}, this would map @samp{a} into
@samp{A} and @samp{A} into @samp{a}, and likewise for each set of
equivalent characters.)
When you construct a case table, you can provide @code{nil} for
@var{canonicalize}; then Emacs fills in this string from @var{upcase}
and @var{downcase}. You can also provide @code{nil} for
@var{canonicalize}; then Emacs fills in this string from the lower case
and upper case mappings. You can also provide @code{nil} for
@var{equivalences}; then Emacs fills in this string from
@var{canonicalize}. In a case table that is actually in use, those
components are non-@code{nil}. Do not try to specify @var{equivalences}
@ -797,22 +910,21 @@ This sets the current buffer's case table to @var{table}.
@end defun
The following three functions are convenient subroutines for packages
that define non-@sc{ASCII} character sets. They modify a string
@var{downcase-table} provided as an argument; this should be a string to
be used as the @var{downcase} part of a case table. They also modify
the standard syntax table. @xref{Syntax Tables}.
that define non-@sc{ASCII} character sets. They modify the specified
case table @var{case-table}; they also modify the standard syntax table.
@xref{Syntax Tables}.
@defun set-case-syntax-pair uc lc downcase-table
@defun set-case-syntax-pair uc lc case-table
This function specifies a pair of corresponding letters, one upper case
and one lower case.
@end defun
@defun set-case-syntax-delims l r downcase-table
@defun set-case-syntax-delims l r case-table
This function makes characters @var{l} and @var{r} a matching pair of
case-invariant delimiters.
@end defun
@defun set-case-syntax char syntax downcase-table
@defun set-case-syntax char syntax case-table
This function makes @var{char} case-invariant, with syntax
@var{syntax}.
@end defun
@ -821,8 +933,3 @@ This function makes @var{char} case-invariant, with syntax
This command displays a description of the contents of the current
buffer's case table.
@end deffn
@cindex ISO Latin 1
@pindex iso-syntax
You can load the library @file{iso-syntax} to set up the standard syntax
table and define a case table for the 8-bit ISO Latin 1 character set.

98
lispref/symbols.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/symbols
@node Symbols, Evaluation, Sequences Arrays Vectors, Top
@ -77,14 +77,14 @@ the specified name before it creates a new one. (In GNU Emacs Lisp,
this lookup uses a hashing algorithm and an obarray; see @ref{Creating
Symbols}.)
In normal usage, the function cell usually contains a function or
macro, as that is what the Lisp interpreter expects to see there
(@pxref{Evaluation}). Keyboard macros (@pxref{Keyboard Macros}),
keymaps (@pxref{Keymaps}) and autoload objects (@pxref{Autoloading}) are
also sometimes stored in the function cell of symbols. We often refer
to ``the function @code{foo}'' when we really mean the function stored
in the function cell of the symbol @code{foo}. We make the distinction
only when necessary.
In normal usage, the function cell usually contains a function
(@pxref{Functions}) or a macro (@pxref{Macros}), as that is what the
Lisp interpreter expects to see there (@pxref{Evaluation}). Keyboard
macros (@pxref{Keyboard Macros}), keymaps (@pxref{Keymaps}) and autoload
objects (@pxref{Autoloading}) are also sometimes stored in the function
cells of symbols. We often refer to ``the function @code{foo}'' when we
really mean the function stored in the function cell of the symbol
@code{foo}. We make the distinction only when necessary.
The property list cell normally should hold a correctly formatted
property list (@pxref{Property Lists}), as a number of functions expect
@ -93,8 +93,8 @@ to see a property list there.
The function cell or the value cell may be @dfn{void}, which means
that the cell does not reference any object. (This is not the same
thing as holding the symbol @code{void}, nor the same as holding the
symbol @code{nil}.) Examining a cell that is void results in an error,
such as @samp{Symbol's value as variable is void}.
symbol @code{nil}.) Examining a function or value cell that is void
results in an error, such as @samp{Symbol's value as variable is void}.
The four functions @code{symbol-name}, @code{symbol-value},
@code{symbol-plist}, and @code{symbol-function} return the contents of
@ -119,13 +119,14 @@ the name of the source file of this chapter of the Emacs Lisp Manual.
The property list cell contains the list @code{(variable-documentation
29529)} which tells the documentation functions where to find the
documentation string for the variable @code{buffer-file-name} in the
@file{DOC} file. (29529 is the offset from the beginning of the
@file{DOC} file to where that documentation string begins.) The
function cell contains the function for returning the name of the file.
@code{buffer-file-name} names a primitive function, which has no read
syntax and prints in hash notation (@pxref{Primitive Function Type}). A
symbol naming a function written in Lisp would have a lambda expression
(or a byte-code object) in this cell.
@file{DOC-@var{version}} file. (29529 is the offset from the beginning
of the @file{DOC-@var{version}} file to where that documentation string
begins---@pxref{Documentation Basics}) The function cell contains the
function for returning the name of the file. @code{buffer-file-name}
names a primitive function, which has no read syntax and prints in hash
notation (@pxref{Primitive Function Type}). A symbol naming a function
written in Lisp would have a lambda expression (or a byte-code object)
in this cell.
@node Definitions, Creating Symbols, Symbol Components, Symbols
@section Defining Symbols
@ -169,7 +170,7 @@ They inform programmers who read the code that certain symbols are
@emph{intended} to be used as variables, or as functions. In addition,
utilities such as @file{etags} and @file{make-docfile} recognize
definitions, and add appropriate information to tag tables and the
@file{emacs/etc/DOC-@var{version}} file. @xref{Accessing Documentation}.
@file{DOC-@var{version}} file. @xref{Accessing Documentation}.
@node Creating Symbols, Property Lists, Definitions, Symbols
@section Creating and Interning Symbols
@ -228,18 +229,14 @@ valid way to create an obarray.} Prime numbers as lengths tend
to result in good hashing; lengths one less than a power of two are also
good.
@strong{Do not try to put symbols in an obarray yourself.} This does
not work---only @code{intern} can enter a symbol in an obarray properly.
@strong{Do not try to intern one symbol in two obarrays.} This would
garble both obarrays, because a symbol has just one slot to hold the
following symbol in the obarray bucket. The results would be
unpredictable.
It is possible for two different symbols to have the same name in
different obarrays; these symbols are not @code{eq} or @code{equal}.
However, this normally happens only as part of the abbrev mechanism
(@pxref{Abbrevs}).
@strong{Do not try to put symbols in an obarray yourself.} This does
not work---only @code{intern} can enter a symbol in an obarray properly.
@cindex CL note---symbol in obarrays
@quotation
@b{Common Lisp note:} In Common Lisp, a single symbol may be interned in
@ -260,8 +257,9 @@ This function returns the string that is @var{symbol}'s name. For example:
@end group
@end example
Changing the string by substituting characters, etc, does change the
name of the symbol, but fails to update the obarray, so don't do it!
@strong{Warning:} Changing the string by substituting characters does
change the name of the symbol, but fails to update the obarray, so don't
do it!
@end defun
@defun make-symbol name
@ -299,6 +297,13 @@ creates a new one, adds it to the obarray, and returns it. If
@end example
@end defun
@cindex CL note---interning existing symbol
@quotation
@b{Common Lisp note:} In Common Lisp, you can intern an existing symbol
in an obarray. In Emacs Lisp, you cannot do this, because the argument
to @code{intern} must be a string, not a symbol.
@end quotation
@defun intern-soft name &optional obarray
This function returns the symbol in @var{obarray} whose name is
@var{name}, or @code{nil} if @var{obarray} has no symbol with that name.
@ -336,10 +341,10 @@ This variable is the standard obarray for use by @code{intern} and
@end defvar
@defun mapatoms function &optional obarray
This function calls @var{function} for each symbol in the obarray
@var{obarray}. It returns @code{nil}. If @var{obarray} is omitted, it
defaults to the value of @code{obarray}, the standard obarray for
ordinary symbols.
This function calls @var{function} once with each symbol in the obarray
@var{obarray}. Then it returns @code{nil}. If @var{obarray} is
omitted, it defaults to the value of @code{obarray}, the standard
obarray for ordinary symbols.
@smallexample
(setq count 0)
@ -388,9 +393,10 @@ symbol (representing a word) in a language-understanding system.
@xref{Text Properties}.
The property names and values in a property list can be any Lisp
objects, but the names are usually symbols. They are compared using
@code{eq}. Here is an example of a property list, found on the symbol
@code{progn} when the compiler is loaded:
objects, but the names are usually symbols. Property list functions
compare the property names using @code{eq}. Here is an example of a
property list, found on the symbol @code{progn} when the compiler is
loaded:
@example
(lisp-indent-function 0 byte-compile byte-compile-progn)
@ -417,16 +423,16 @@ pairs in the property list is not significant since the property names
must be distinct.
Property lists are better than association lists for attaching
information to various Lisp function names or variables. If all the
associations are recorded in one association list, the program will need
to search that entire list each time a function or variable is to be
operated on. By contrast, if the information is recorded in the
property lists of the function names or variables themselves, each
search will scan only the length of one property list, which is usually
short. This is why the documentation for a variable is recorded in a
property named @code{variable-documentation}. The byte compiler
likewise uses properties to record those functions needing special
treatment.
information to various Lisp function names or variables. If your
program keeps all of its associations in one association list, it will
typically need to search that entire list each time it checks for an
association. This could be slow. By contrast, if you keep the same
information in the property lists of the function names or variables
themselves, each search will scan only the length of one property list,
which is usually short. This is why the documentation for a variable is
recorded in a property named @code{variable-documentation}. The byte
compiler likewise uses properties to record those functions needing
special treatment.
However, association lists have their own advantages. Depending on
your application, it may be faster to add an association to the front of
@ -522,7 +528,7 @@ in the place where you got @var{plist}. For example,
(setq my-plist (plist-put my-plist 'foo 69))
@result{} (bar t foo 69)
(setq my-plist (plist-put my-plist 'quux '(a)))
@result{} (quux (a) bar t foo 5)
@result{} (bar t foo 69 quux (a))
@end example
@end defun

360
lispref/syntax.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/syntax
@node Syntax Tables, Abbrevs, Searching and Matching, Top
@ -14,18 +14,20 @@ character. This information is used by the parsing commands, the
complex movement commands, and others to determine where words, symbols,
and other syntactic constructs begin and end. The current syntax table
controls the meaning of the word motion functions (@pxref{Word Motion})
and the list motion functions (@pxref{List Motion}) as well as the
and the list motion functions (@pxref{List Motion}), as well as the
functions in this chapter.
@menu
* Basics: Syntax Basics. Basic concepts of syntax tables.
* Desc: Syntax Descriptors. How characters are classified.
* Syntax Table Functions:: How to create, examine and alter syntax tables.
* Syntax Properties:: Overriding syntax with text properties.
* Motion and Syntax:: Moving over characters with certain syntaxes.
* Parsing Expressions:: Parsing balanced expressions
using the syntax table.
* Standard Syntax Tables:: Syntax tables used by various major modes.
* Syntax Table Internals:: How syntax table information is stored.
* Categories:: Another way of classifying character syntax.
@end menu
@node Syntax Basics
@ -42,9 +44,8 @@ list motion functions (@pxref{List Motion}) as well as the functions in
this chapter.
@end ifinfo
A syntax table is a vector of 256 elements; it contains one entry for
each of the 256 possible characters in an 8-bit byte. Each element is
an integer that encodes the syntax of the character in question.
A syntax table is a char-table (@pxref{Char-Tables}). Each element is
a list that encodes the syntax of the character in question.
Syntax tables are used only for moving across text, not for the Emacs
Lisp reader. Emacs Lisp uses built-in syntactic rules when reading Lisp
@ -65,17 +66,11 @@ table.
A syntax table can inherit the data for some characters from the
standard syntax table, while specifying other characters itself. The
``inherit'' syntax class means ``inherit this character's syntax from
the standard syntax table.'' Most major modes' syntax tables inherit
the syntax of character codes 0 through 31 and 128 through 255. This is
useful with character sets such as ISO Latin-1 that have additional
alphabetic characters in the range 128 to 255. Just changing the
standard syntax for these characters affects all major modes.
the standard syntax table.'' Just changing the standard syntax for a
characters affects all syntax tables which inherit from it.
@defun syntax-table-p object
This function returns @code{t} if @var{object} is a vector of length 256
elements. This means that the vector may be a syntax table. However,
according to this test, any vector of length 256 is considered to be a
syntax table, no matter what its contents.
This function returns @code{t} if @var{object} is a syntax table.
@end defun
@node Syntax Descriptors
@ -106,9 +101,9 @@ character is the character to match; if it is unused, put a space there.
Then come the characters for any desired flags. If no matching
character or flags are needed, one character is sufficient.
For example, the descriptor for the character @samp{*} in C mode is
@samp{@w{. 23}} (i.e., punctuation, matching character slot unused,
second character of a comment-starter, first character of an
For example, the syntax descriptor for the character @samp{*} in C
mode is @samp{@w{. 23}} (i.e., punctuation, matching character slot
unused, second character of a comment-starter, first character of an
comment-ender), and the entry for @samp{/} is @samp{@w{. 14}} (i.e.,
punctuation, matching character slot unused, first character of a
comment-starter, second character of a comment-ender).
@ -125,7 +120,7 @@ comment-starter, second character of a comment-ender).
their meanings, and examples of their use.
@deffn {Syntax class} @w{whitespace character}
@dfn{Whitespace characters} (designated with @w{@samp{@ }} or @samp{-})
@dfn{Whitespace characters} (designated by @w{@samp{@ }} or @samp{-})
separate symbols and words from each other. Typically, whitespace
characters have no other syntactic significance, and multiple whitespace
characters are syntactically equivalent to a single one. Space, tab,
@ -133,14 +128,14 @@ newline and formfeed are almost always classified as whitespace.
@end deffn
@deffn {Syntax class} @w{word constituent}
@dfn{Word constituents} (designated with @samp{w}) are parts of normal
@dfn{Word constituents} (designated by @samp{w}) are parts of normal
English words and are typically used in variable and command names in
programs. All upper- and lower-case letters, and the digits, are typically
word constituents.
@end deffn
@deffn {Syntax class} @w{symbol constituent}
@dfn{Symbol constituents} (designated with @samp{_}) are the extra
@dfn{Symbol constituents} (designated by @samp{_}) are the extra
characters that are used in variable and command names along with word
constituents. For example, the symbol constituents class is used in
Lisp mode to indicate that certain characters may be part of symbol
@ -150,12 +145,12 @@ character that is valid in symbols is underscore (@samp{_}).
@end deffn
@deffn {Syntax class} @w{punctuation character}
@dfn{Punctuation characters} (@samp{.}) are those characters that are
used as punctuation in English, or are used in some way in a programming
language to separate symbols from one another. Most programming
language modes, including Emacs Lisp mode, have no characters in this
class since the few characters that are not symbol or word constituents
all have other uses.
@dfn{Punctuation characters} (designated by @samp{.}) are those
characters that are used as punctuation in English, or are used in some
way in a programming language to separate symbols from one another.
Most programming language modes, including Emacs Lisp mode, have no
characters in this class since the few characters that are not symbol or
word constituents all have other uses.
@end deffn
@deffn {Syntax class} @w{open parenthesis character}
@ -169,8 +164,8 @@ character, and vice versa. Normally, Emacs indicates momentarily the
matching open parenthesis when you insert a close parenthesis.
@xref{Blinking}.
The class of open parentheses is designated with @samp{(}, and that of
close parentheses with @samp{)}.
The class of open parentheses is designated by @samp{(}, and that of
close parentheses by @samp{)}.
In English text, and in C code, the parenthesis pairs are @samp{()},
@samp{[]}, and @samp{@{@}}. In Emacs Lisp, the delimiters for lists and
@ -179,7 +174,7 @@ characters.
@end deffn
@deffn {Syntax class} @w{string quote}
@dfn{String quote characters} (designated with @samp{"}) are used in
@dfn{String quote characters} (designated by @samp{"}) are used in
many languages, including Lisp and C, to delimit string constants. The
same string quote character appears at the beginning and the end of a
string. Such quoted strings do not nest.
@ -201,7 +196,7 @@ other characters in the quotation.
@end deffn
@deffn {Syntax class} @w{escape}
An @dfn{escape character} (designated with @samp{\}) starts an escape
An @dfn{escape character} (designated by @samp{\}) starts an escape
sequence such as is used in C string and character constants. The
character @samp{\} belongs to this class in both C and Lisp. (In C, it
is used thus only inside strings, but it turns out to cause no trouble
@ -212,7 +207,7 @@ Characters in this class count as part of words if
@end deffn
@deffn {Syntax class} @w{character quote}
A @dfn{character quote character} (designated with @samp{/}) quotes the
A @dfn{character quote character} (designated by @samp{/}) quotes the
following character so that it loses its normal syntactic meaning. This
differs from an escape character in that only the character immediately
following is ever affected.
@ -224,7 +219,7 @@ This class is used for backslash in @TeX{} mode.
@end deffn
@deffn {Syntax class} @w{paired delimiter}
@dfn{Paired delimiter characters} (designated with @samp{$}) are like
@dfn{Paired delimiter characters} (designated by @samp{$}) are like
string quote characters except that the syntactic properties of the
characters between the delimiters are not suppressed. Only @TeX{} mode
uses a paired delimiter presently---the @samp{$} that both enters and
@ -232,11 +227,11 @@ leaves math mode.
@end deffn
@deffn {Syntax class} @w{expression prefix}
An @dfn{expression prefix operator} (designated with @samp{'}) is used
for syntactic operators that are part of an expression if they appear
next to one. These characters in Lisp include the apostrophe, @samp{'}
(used for quoting), the comma, @samp{,} (used in macros), and @samp{#}
(used in the read syntax for certain data types).
An @dfn{expression prefix operator} (designated by @samp{'}) is used for
syntactic operators that are considered as part of an expression if they
appear next to one. In Lisp modes, these characters include the
apostrophe, @samp{'} (used for quoting), the comma, @samp{,} (used in
macros), and @samp{#} (used in the read syntax for certain data types).
@end deffn
@deffn {Syntax class} @w{comment starter}
@ -244,24 +239,51 @@ next to one. These characters in Lisp include the apostrophe, @samp{'}
@cindex comment syntax
The @dfn{comment starter} and @dfn{comment ender} characters are used in
various languages to delimit comments. These classes are designated
with @samp{<} and @samp{>}, respectively.
by @samp{<} and @samp{>}, respectively.
English text has no comment characters. In Lisp, the semicolon
(@samp{;}) starts a comment and a newline or formfeed ends one.
@end deffn
@deffn {Syntax class} @w{inherit}
This syntax class does not specify a syntax. It says to look in the
standard syntax table to find the syntax of this character. The
This syntax class does not specify a particular syntax. It says to look
in the standard syntax table to find the syntax of this character. The
designator for this syntax code is @samp{@@}.
@end deffn
@deffn {Syntax class} @w{generic comment delimiter}
A @dfn{generic comment delimiter} character starts or ends a special
kind of comment. @emph{Any} generic comment delimiter matches
@emph{any} generic comment delimiter, but they cannot match a comment
starter or comment ender; generic comment delimiters can only match each
other.
This syntax class is primarily meant for use with the
@code{syntax-table} text property (@pxref{Syntax Properties}). You can
mark any range of characters as forming a comment, by giving the first
and last characters of the range @code{syntax-table} properties
identifying them as generic comment delimiters.
@end deffn
@deffn {Syntax class} @w{generic string delimiter}
A @dfn{generic string delimiter} character starts or ends a string.
This class differs from the string quote class in that @emph{any}
generic string delimiter can match any other generic string delimiter;
but they do not match ordinary string quote characters.
This syntax class is primarily meant for use with the
@code{syntax-table} text property (@pxref{Syntax Properties}). You can
mark any range of characters as forming a string constant, by giving the
first and last characters of the range @code{syntax-table} properties
identifying them as generic string delimiters.
@end deffn
@node Syntax Flags
@subsection Syntax Flags
@cindex syntax flags
In addition to the classes, entries for characters in a syntax table
can include flags. There are six possible flags, represented by the
can specify flags. There are six possible flags, represented by the
characters @samp{1}, @samp{2}, @samp{3}, @samp{4}, @samp{b} and
@samp{p}.
@ -274,7 +296,8 @@ as @samp{*} in C mode, which is a punctuation character, @emph{and} the
second character of a start-of-comment sequence (@samp{/*}), @emph{and}
the first character of an end-of-comment sequence (@samp{*/}).
The flags for a character @var{c} are:
Here is a table of the possible flags for a character @var{c},
and what they mean:
@itemize @bullet
@item
@ -361,10 +384,9 @@ prefix (@samp{'}). @xref{Motion and Syntax}.
altering syntax tables.
@defun make-syntax-table
This function creates a new syntax table. Character codes 0 through
31 and 128 through 255 are set up to inherit from the standard syntax
table. The other character codes are set up by copying what the
standard syntax table says about them.
This function creates a new syntax table. Character codes 32 through
127 are set up by copying the syntax from the standard syntax table.
All other codes are set up to inherit from the standard syntax table.
Most major mode syntax tables are created in this way.
@end defun
@ -428,7 +450,7 @@ signaled if @var{char} is not a character.
@defun char-syntax character
This function returns the syntax class of @var{character}, represented
by its mnemonic designator character. This @emph{only} returns the
by its mnemonic designator character. This returns @emph{only} the
class, not any matching parenthesis or flags.
An error is signaled if @var{char} is not a character.
@ -469,6 +491,39 @@ This function returns the current syntax table, which is the table for
the current buffer.
@end defun
@node Syntax Properties
@section Syntax Properties
@kindex syntax-table @r{(text property)}
When the syntax table is not flexible enough to specify the syntax of a
language, you can use @code{syntax-table} text properties to override
the syntax table for specific character occurrences in the buffer.
@xref{Text Properties}.
The valid values of @code{syntax-table} text property are
@table @asis
@item @var{syntax-table}
If the property value is a syntax table, that table is used instead of
the current buffer's syntax table to determine the syntax for this
occurrence of the character.
@item @code{(@var{syntax-code} . @var{matching-char})}
A cons cell of this format specifies the syntax for this
occurrence of the character.
@item @code{nil}
If the property is @code{nil}, the character's syntax is determined from
the current syntax table in the usual way.
@end table
@tindex parse-sexp-lookup-properties
@defvar parse-sexp-lookup-properties
If this is non-@code{nil}, the syntax scanning functions pay attention
to syntax text properties. Otherwise they use only the current syntax
table.
@end defvar
@node Motion and Syntax
@section Motion and Syntax
@ -535,15 +590,18 @@ The depth starts at 0, or at whatever is given in @var{state}.
If the fourth argument @var{stop-before} is non-@code{nil}, parsing
stops when it comes to any character that starts a sexp. If
@var{stop-comment} is non-@code{nil}, parsing stops when it comes to the
start of a comment.
start of a comment. If @var{stop-comment} is the symbol
@code{syntax-table}, parsing stops after the start of a comment or a
string, or the of a comment or a string, whichever comes first.
@cindex parse state
The fifth argument @var{state} is an eight-element list of the same
form as the value of this function, described below. The return value
of one call may be used to initialize the state of the parse on another
call to @code{parse-partial-sexp}.
The fifth argument @var{state} is a nine-element list of the same form
as the value of this function, described below. (It is ok to omit the
last element of the nine.) The return value of one call may be used to
initialize the state of the parse on another call to
@code{parse-partial-sexp}.
The result is a list of eight elements describing the final state of
The result is a list of nine elements describing the final state of
the parse:
@enumerate 0
@ -563,7 +621,8 @@ terminated; @code{nil} if none.
@item
@cindex inside string
Non-@code{nil} if inside a string. More precisely, this is the
character that will terminate the string.
character that will terminate the string, or @code{t} if a generic
string delimiter character should terminate it.
@item
@cindex inside comment
@ -577,7 +636,15 @@ character that will terminate the string.
The minimum parenthesis depth encountered during this scan.
@item
@code{t} if inside a comment of style ``b''.
What kind of comment is active: @code{nil} for a comment of style ``a'',
@code{t} for a comment of style ``b'', and @code{syntax-table} for
a comment that should be ended by a generic comment delimiter character.
@item
The string or comment start position. While inside a comment, this is
the position where the comment began; while inside a string, this is the
position where the string began. When outside of strings and comments,
this element is @code{nil}.
@end enumerate
Elements 0, 3, 4, 5 and 7 are significant in the argument @var{state}.
@ -589,8 +656,8 @@ that have nested parentheses.
@defun scan-lists from count depth
This function scans forward @var{count} balanced parenthetical groupings
from character number @var{from}. It returns the character position
where the scan stops.
from position @var{from}. It returns the position where the scan stops.
If @var{count} is negative, the scan moves backwards.
If @var{depth} is nonzero, parenthesis depth counting begins from that
value. The only candidates for stopping are places where the depth in
@ -608,16 +675,17 @@ returned.
@end defun
@defun scan-sexps from count
This function scans forward @var{count} sexps from character position
@var{from}. It returns the character position where the scan stops.
This function scans forward @var{count} sexps from position @var{from}.
It returns the position where the scan stops. If @var{count} is
negative, the scan moves backwards.
Scanning ignores comments if @code{parse-sexp-ignore-comments} is
non-@code{nil}.
If the scan reaches the beginning or end of (the accessible part of) the
buffer in the middle of a parenthetical grouping, an error is signaled.
If it reaches the beginning or end between groupings but before count is
used up, @code{nil} is returned.
buffer while in the middle of a parenthetical grouping, an error is
signaled. If it reaches the beginning or end between groupings but
before count is used up, @code{nil} is returned.
@end defun
@defvar parse-sexp-ignore-comments
@ -676,14 +744,19 @@ function.)
@section Syntax Table Internals
@cindex syntax table internals
Each element of a syntax table is an integer that encodes the syntax
of one character: the syntax class, possible matching character, and
flags. Lisp programs don't usually work with the elements directly; the
Lisp programs don't usually work with the elements directly; the
Lisp-level syntax table functions usually work with syntax descriptors
(@pxref{Syntax Descriptors}).
(@pxref{Syntax Descriptors}). Nonetheless, here we document the
internal format.
The low 8 bits of each element of a syntax table indicate the
syntax class.
Each element of a syntax table is a cons cell of the form
@code{(@var{syntax-code} . @var{matching-char})}. The @sc{car},
@var{syntax-code}, is an integer that encodes the syntax class, and any
flags. The @sc{cdr}, @var{matching-char}, is non-@code{nil} if
a character to match was specified.
This table gives the value of @var{syntax-code} which corresponds
to each syntactic type.
@table @asis
@item @i{Integer}
@ -716,8 +789,153 @@ comment-start
comment-end
@item 13
inherit
@item 14
comment-fence
@item 15
string-fence
@end table
The next 8 bits are the matching opposite parenthesis (if the
character has parenthesis syntax); otherwise, they are not meaningful.
The next 6 bits are the flags.
For example, the usual syntax value for @samp{(} is @code{(4 . 41)}.
(41 is the character code for @samp{)}.)
The flags are encoded in higher order bits, starting 16 bits from the
least significant bit. This table gives the power of two which
corresponds to each syntax flag.
@table @samp
@item @i{Flag}
@i{Bit value}
@item 1
@code{(lsh 1 16)}
@item 2
@code{(lsh 1 17)}
@item 3
@code{(lsh 1 18)}
@item 4
@code{(lsh 1 19)}
@item p
@code{(lsh 1 20)}
@item b
@code{(lsh 1 21)}
@end table
@node Categories
@section Categories
@cindex categories of characters
@dfn{Categories} provide an alternate way of classifying characters
syntactically. You can define a large number of categories, and then
independently assign each character to one or more of them. Unlike
syntax classes, categories are not mutually exclusive; it is normal for
one character to belong to several categories.
Each buffer has a @dfn{category table} which records which categories
are defined and also which characters belong to each category. Each
category table defines its own categories. Each category has a name,
which is an @sc{ASCII} printing character in the range @w{@samp{ }} to
@samp{~}. You specify the name of a category when you define it with
@code{define-category}.
The category table is actually a char-table (@pxref{Char-Tables}).
The element of the category table at index @var{c} is a @dfn{category
set}---a bool-vector---that indicates which categories character @var{c}
belongs to. In this category set, if the element at index @var{cat} is
@code{t}, that means category @var{cat} is a member of the set, and that
character @var{c} belongs to category @var{cat}.
@defun define-category char docstring &optional table
This function defines a new category, with name @var{char} and
documentation @var{docstring}.
The new category is defined for category table @var{table}, which
defaults to the current buffer's category table.
@end defun
@defun category-docstring category &optional table
This function returns the documentation string of category @var{category}
in category table @var{table}.
@example
(category-docstring ?a)
@result{} "ASCII"
(category-docstring ?l)
@result{} "Latin"
@end example
@end defun
@defun get-unused-category table
This function returns a category name (a character) which is not
currently defined in @var{table}. If none is still available, it
returns @code{nil},
@end defun
@defun category-table
This function returns the current buffer's category table.
@end defun
@defun category-table-p object
This function returns @code{t} if @var{object} is a category table,
otherwise @code{nil}.
@end defun
@defun standard-category-table
This function returns the standard category table.
@end defun
@defun copy-category-table &optional table
This function constructs a copy of @var{table} and returns it. If
@var{table} is not supplied (or is @code{nil}), it returns a copy of the
current category table. Otherwise, an error is signaled if @var{table}
is not a category table.
@end defun
@defun set-category-table table
This function makes @var{table} the category table for the current
buffer. It returns @var{table}.
@end defun
@defun make-category-set categories
This function returns a new category set---a bool-vector---whose initial
contents are the categories listed in the string @var{categories}. The
elements of @var{categories} should be category names; the new category
set has @code{t} for each of those categories, and @code{nil} for all
other categories.
@example
(make-category-set "al")
@result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example
@end defun
@defun char-category-set char
This function returns the category set for character @var{char}. This
is the bool-vector which records which categories the character
@var{char} belongs to. The function @code{char-category-set} does not
allocate storage, because it returns the same bool-vector that exists in
the category table.
@example
(char-category-set ?a)
@result{} #&128"\0\0\0\0\0\0\0\0\0\0\0\0\2\20\0\0"
@end example
@end defun
@defun category-set-mnemonics category-set
This function converts the category set @var{category-set} into a string
containing the names of all the categories that are members of the set.
@example
(category-set-mnemonics (char-category-set ?a))
@result{} "al"
@end example
@end defun
@defun modify-category-entry character category &optional table reset
This function modifies the category set of @var{character} in category
table @var{table} (which defaults to the current buffer's category
table).
Normally, it modifies the category set by adding @var{category} to it.
But if @var{reset} is non-@code{nil}, then it deletes @var{category}
instead.
@end defun

340
lispref/text.texi
View file

@ -1,9 +1,9 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/text
@node Text, Searching and Matching, Markers, Top
@node Text, Non-ASCII Characters, Markers, Top
@chapter Text
@cindex text
@ -130,7 +130,7 @@ the text. See also @code{point-max} in @xref{Point}.
@defun bolp
This function returns @code{t} if point is at the beginning of a line.
@xref{Text Lines}. The beginning of the buffer (or its accessible
@xref{Text Lines}. The beginning of the buffer (or of its accessible
portion) always counts as the beginning of a line.
@end defun
@ -190,7 +190,7 @@ alist:
@example
(setq flammable
(assoc (buffer-substring start end)
(assoc (buffer-substring-no-properties start end)
'(("wood" . t) ("paper" . t)
("steel" . nil) ("asbestos" . nil))))
@end example
@ -201,8 +201,8 @@ copied from the buffer would make the comparisons fail.
@end defun
@defun buffer-string
This function returns the contents of the accessible portion of the
current buffer as a string. This is the portion between
This function returns the contents of the entire accessible portion of
the current buffer as a string. This is the portion between
@code{(point-min)} and @code{(point-max)} (@pxref{Narrowing}).
@example
@ -219,6 +219,29 @@ This is the contents of buffer foo
@end example
@end defun
@defun thing-at-point thing
Return the @var{thing} around or next to point, as a string.
The argument @var{thing} is a symbol which specifies a kind of syntactic
entity. Possibilities include @code{symbol}, @code{list}, @code{sexp},
@code{defun}, @code{filename}, @code{url}, @code{word}, @code{sentence},
@code{whitespace}, @code{line}, @code{page}, and others.
@example
---------- Buffer: foo ----------
Gentlemen may cry ``Pea@point{}ce! Peace!,''
but there is no peace.
---------- Buffer: foo ----------
(thing-at-point 'word)
@result{} "Peace"
(thing-at-point 'line)
@result{} "Gentlemen may cry ``Peace! Peace!,''\n"
(thing-at-point 'whitespace)
@result{} nil
@end example
@end defun
@node Comparing Text
@section Comparing Text
@cindex comparing buffer text
@ -301,7 +324,7 @@ unless all @var{args} are either strings or characters. The value is
This function is unlike the other insertion functions in that it
relocates markers initially pointing at the insertion point, to point
after the inserted text. If an overlat begins the insertion point, the
after the inserted text. If an overlay begins the insertion point, the
inserted text falls outside the overlay; if a nonempty overlay ends at
the insertion point, the inserted text falls inside that overlay.
@end defun
@ -720,8 +743,8 @@ list.
command that calls this function is a ``kill command'' (and should
probably have @samp{kill} in its name). @code{kill-region} puts the
newly killed text in a new element at the beginning of the kill ring or
adds it to the most recent element. It uses the @code{last-command}
variable to determine whether the previous command was a kill command,
adds it to the most recent element. It determines automatically (using
@code{last-command}) whether the previous command was a kill command,
and if so appends the killed text to the most recent entry.
@deffn Command kill-region start end
@ -750,8 +773,9 @@ The command does not set @code{this-command} to @code{kill-region}, so a
subsequent kill command does not append to the same kill ring entry.
Don't call @code{copy-region-as-kill} in Lisp programs unless you aim to
support Emacs 18. For Emacs 19, it is better to use @code{kill-new} or
@code{kill-append} instead. @xref{Low-Level Kill Ring}.
support Emacs 18. For newer Emacs versions, it is better to use
@code{kill-new} or @code{kill-append} instead. @xref{Low-Level Kill
Ring}.
@end deffn
@node Yank Commands
@ -863,7 +887,7 @@ If the value is a function, @code{kill-new} and @code{kill-append} call
it with the new first element of the kill ring as an argument.
The normal use of this hook is to set the X server's primary selection
to the newly killed text.
from the newly killed text.
@end defvar
@node Internals of Kill Ring
@ -959,7 +983,7 @@ Here are the kinds of elements an undo list can have:
@table @code
@item @var{integer}
This kind of element records a previous value of point. Ordinary cursor
motion does not get any sort of undo record, but deletion commands use
motion does not get any sort of undo record, but deletion operations use
these entries to record where point was before the command.
@item (@var{beg} . @var{end})
@ -1178,10 +1202,10 @@ described above.
@end defopt
@deffn Command fill-region-as-paragraph start end &optional justify
This command considers a region of text as a paragraph and fills it. If
the region was made up of many paragraphs, the blank lines between
paragraphs are removed. This function justifies as well as filling when
@var{justify} is non-@code{nil}.
This command considers a region of text as a single paragraph and fills
it. If the region was made up of many paragraphs, the blank lines
between paragraphs are removed. This function justifies as well as
filling when @var{justify} is non-@code{nil}.
In an interactive call, any prefix argument requests justification.
@ -1262,10 +1286,10 @@ The fill prefix follows the left margin whitespace, if any.
@end defopt
@defopt fill-column
This buffer-local variable specifies the maximum width of filled
lines. Its value should be an integer, which is a number of columns.
All the filling, justification and centering commands are affected by
this variable, including Auto Fill mode (@pxref{Auto Filling}).
This buffer-local variable specifies the maximum width of filled lines.
Its value should be an integer, which is a number of columns. All the
filling, justification, and centering commands are affected by this
variable, including Auto Fill mode (@pxref{Auto Filling}).
As a practical matter, if you are writing text for other people to
read, you should set @code{fill-column} to no more than 70. Otherwise
@ -1384,14 +1408,14 @@ rearranges the order of the elements of a list (@pxref{Rearrangement}).
The values returned by these functions are not meaningful.
@defun sort-subr reverse nextrecfun endrecfun &optional startkeyfun endkeyfun
This function is the general text-sorting routine that divides a buffer
into records and sorts them. Most of the commands in this section use
this function.
This function is the general text-sorting routine that subdivides a
buffer into records and then sorts them. Most of the commands in this
section use this function.
To understand how @code{sort-subr} works, consider the whole accessible
portion of the buffer as being divided into disjoint pieces called
@dfn{sort records}. The records may or may not be contiguous; they may
not overlap. A portion of each sort record (perhaps all of it) is
@dfn{sort records}. The records may or may not be contiguous, but they
must not overlap. A portion of each sort record (perhaps all of it) is
designated as the sort key. Sorting rearranges the records in order by
their sort keys.
@ -1445,12 +1469,18 @@ definition for @code{sort-lines}:
;; @r{Note that the first two lines of doc string}
;; @r{are effectively one line when viewed by a user.}
(defun sort-lines (reverse beg end)
"Sort lines in region alphabetically.
"Sort lines in region alphabetically;\
argument means descending order.
Called from a program, there are three arguments:
@end group
@group
REVERSE (non-nil means reverse order),
and BEG and END (the region to sort)."
REVERSE (non-nil means reverse order),\
BEG and END (region to sort).
The variable `sort-fold-case' determines\
whether alphabetic case affects
the sort order.
@end group
@group
(interactive "P\nr")
(save-restriction
(narrow-to-region beg end)
@ -1478,6 +1508,9 @@ its @code{sort-subr} call looks like this:
'forward-paragraph)
@end group
@end example
Markers pointing into any sort records are left with no useful
position after @code{sort-subr} returns.
@end defun
@deffn Command sort-regexp-fields reverse record-regexp key-regexp start end
@ -1491,17 +1524,15 @@ comparing the first characters of each, the second characters of each,
and so on. If a mismatch is found, it means that the sort keys are
unequal; the sort key whose character is less at the point of first
mismatch is the lesser sort key. The individual characters are compared
according to their numerical values. Since Emacs uses the @sc{ASCII}
character set, the ordering in that set determines alphabetical order.
@c version 19 change
according to their numerical character codes in the Emacs character set.
The value of the @var{record-regexp} argument specifies how to divide
the buffer into sort records. At the end of each record, a search is
done for this regular expression, and the text that matches it is the
next record. For example, the regular expression @samp{^.+$}, which
matches lines with at least one character besides a newline, would make
each such line into a sort record. @xref{Regular Expressions}, for a
description of the syntax and meaning of regular expressions.
done for this regular expression, and the text that matches it is taken
as the next record. For example, the regular expression @samp{^.+$},
which matches lines with at least one character besides a newline, would
make each such line into a sort record. @xref{Regular Expressions}, for
a description of the syntax and meaning of regular expressions.
The value of the @var{key-regexp} argument specifies what part of each
record is the sort key. The @var{key-regexp} could match the whole
@ -1613,11 +1644,12 @@ and so cannot work properly on text containing tab characters. Use
characters from the beginning of the buffer) and a column position
(counting screen characters from the beginning of a line).
A character counts according to the number of columns it occupies on
the screen. This means control characters count as occupying 2 or 4
columns, depending upon the value of @code{ctl-arrow}, and tabs count as
occupying a number of columns that depends on the value of
@code{tab-width} and on the column where the tab begins. @xref{Usual Display}.
These functions count each character according to the number of
columns it occupies on the screen. This means control characters count
as occupying 2 or 4 columns, depending upon the value of
@code{ctl-arrow}, and tabs count as occupying a number of columns that
depends on the value of @code{tab-width} and on the column where the tab
begins. @xref{Usual Display}.
Column number computations ignore the width of the window and the
amount of horizontal scrolling. Consequently, a column value can be
@ -1886,7 +1918,7 @@ following:
@end group
@end example
In this example, point is between the @samp{m} and @samp{p} of
In this next example, point is between the @samp{m} and @samp{p} of
@samp{jumped}:
@example
@ -1910,9 +1942,9 @@ The quick brown fox jum @point{}ped.
@deffn Command indent-relative-maybe
@comment !!SourceFile indent.el
This command indents the current line like the previous nonblank line.
It calls @code{indent-relative} with @code{t} as the @var{unindented-ok}
argument. The return value is unpredictable.
This command indents the current line like the previous nonblank line,
by calling @code{indent-relative} with @code{t} as the
@var{unindented-ok} argument. The return value is unpredictable.
If the previous nonblank line has no indent points beyond the current
column, this command does nothing.
@ -1933,10 +1965,11 @@ Display}). Note that the @key{TAB} character as input uses this tab
stop feature only in a few major modes, such as Text mode.
@deffn Command tab-to-tab-stop
This command inserts spaces or tabs up to the next tab stop column
defined by @code{tab-stop-list}. It searches the list for an element
greater than the current column number, and uses that element as the
column to indent to. It does nothing if no such element is found.
This command inserts spaces or tabs before point, up to the next tab
stop column defined by @code{tab-stop-list}. It searches the list for
an element greater than the current column number, and uses that element
as the column to indent to. It does nothing if no such element is
found.
@end deffn
@defopt tab-stop-list
@ -2104,6 +2137,8 @@ along with the characters; this includes such diverse functions as
them back.
* Lazy Properties:: Computing text properties in a lazy fashion
only when text is examined.
* Clickable Text:: Using text properties to make regions of text
do something when you click on them.
* Not Intervals:: Why text properties do not use
Lisp-visible text intervals.
@end menu
@ -2188,13 +2223,13 @@ If @var{object} is @code{nil}, it defaults to the current buffer.
@end defun
@defun add-text-properties start end props &optional object
This function modifies the text properties for the text between
This function adds or overrides text properties for the text between
@var{start} and @var{end} in the string or buffer @var{object}. If
@var{object} is @code{nil}, it defaults to the current buffer.
The argument @var{props} specifies which properties to change. It
should have the form of a property list (@pxref{Property Lists}): a list
whose elements include the property names followed alternately by the
The argument @var{props} specifies which properties to add. It should
have the form of a property list (@pxref{Property Lists}): a list whose
elements include the property names followed alternately by the
corresponding values.
The return value is @code{t} if the function actually changed some
@ -2253,30 +2288,31 @@ from the specified range of text. Here's an example:
@end example
@end defun
See also the function @code{buffer-substring-no-properties}
See also the function @code{buffer-substring-no-properties}
(@pxref{Buffer Contents}) which copies text from the buffer
but does not copy its properties.
@node Property Search
@subsection Property Search Functions
@subsection Text Property Search Functions
In typical use of text properties, most of the time several or many
In typical use of text properties, most of the time several or many
consecutive characters have the same value for a property. Rather than
writing your programs to examine characters one by one, it is much
faster to process chunks of text that have the same property value.
Here are functions you can use to do this. They use @code{eq} for
Here are functions you can use to do this. They use @code{eq} for
comparing property values. In all cases, @var{object} defaults to the
current buffer.
For high performance, it's very important to use the @var{limit}
For high performance, it's very important to use the @var{limit}
argument to these functions, especially the ones that search for a
single property---otherwise, they may spend a long time scanning to the
end of the buffer, if the property you are interested in does not change.
Remember that a position is always between two characters; the position
returned by these functions is between two characters with different
properties.
These functions do not move point; instead, they return a position (or
@code{nil}). Remember that a position is always between two characters;
the position returned by these functions is between two characters with
different properties.
@defun next-property-change pos &optional object limit
The function scans the text forward from position @var{pos} in the
@ -2341,6 +2377,20 @@ position less than or equal to @var{pos}; it equals @var{pos} only if
@var{limit} equals @var{pos}.
@end defun
@tindex next-char-property-change
@defun next-char-property-change position &optional limit
This is like @code{next-property-change} except that it considers
overlay properties as well as text properties. There is no @var{object}
operand because this function operates only on the current buffer. It
returns the next address at which either kind of property changes.
@end defun
@tindex previous-char-property-change
@defun previous-char-property-change position &optional limit
This is like @code{next-char-property-change}, but scans back from
@var{position} instead of forward.
@end defun
@defun text-property-any start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} has a property @var{prop} whose value is
@ -2354,9 +2404,9 @@ for @var{object} is the current buffer.
@defun text-property-not-all start end prop value &optional object
This function returns non-@code{nil} if at least one character between
@var{start} and @var{end} has a property @var{prop} whose value differs
from @var{value}. More precisely, it returns the position of the
first such character. Otherwise, it returns @code{nil}.
@var{start} and @var{end} does not have a property @var{prop} with value
@var{value}. More precisely, it returns the position of the first such
character. Otherwise, it returns @code{nil}.
The optional fifth argument, @var{object}, specifies the string or
buffer to scan. Positions are relative to @var{object}. The default
@ -2384,8 +2434,16 @@ of the symbol serve as defaults for the properties of the character.
@kindex face @r{(text property)}
You can use the property @code{face} to control the font and color of
text. Its value is a face name or a list of face names. @xref{Faces},
for more information. This feature may be temporary; in the future, we
may replace it with other ways of specifying how to display text.
for more information.
If the property value is a list, elements may also have the form
@code{(foreground-color . @var{color-name})} or @code{(background-color
. @var{color-name})}. These elements specify just the foreground color
or just the background color; therefore, there is no need to create a
face for each color that you want to use.
@xref{Font Lock Mode}, for information on how to update @code{face}
properties automatically based on the contents of the text.
@item mouse-face
@kindex mouse-face @r{(text property)}
@ -2397,10 +2455,16 @@ that all text between the character and where the mouse is have the same
@item local-map
@cindex keymap of character
@kindex local-map @r{(text property)}
You can specify a different keymap for a portion of the text by means of
a @code{local-map} property. The property's value for the character
after point, if non-@code{nil}, replaces the buffer's local map.
@xref{Active Keymaps}.
You can specify a different keymap for some of the text in a buffer by
means of the @code{local-map} property. The property's value for the
character after point, if non-@code{nil}, is used for key lookup instead
of the buffer's local map. If the property value is a symbol, the
symbol's function definition is used as the keymap. @xref{Active
Keymaps}.
@item syntax-table
The @code{syntax-table} property overrides what the syntax table says
about this particular character. @xref{Syntax Properties}.
@item read-only
@cindex read-only character
@ -2489,15 +2553,16 @@ functions (which may be the same function). In any case, all the
@code{point-left} functions are called first, followed by all the
@code{point-entered} functions.
A primitive function may examine characters at various positions
without moving point to those positions. Only an actual change in the
value of point runs these hook functions.
It is possible using @code{char-after} to examine characters at various
positions without moving point to those positions. Only an actual
change in the value of point runs these hook functions.
@end table
@defvar inhibit-point-motion-hooks
When this variable is non-@code{nil}, @code{point-left} and
@code{point-entered} hooks are not run, and the @code{intangible}
property has no effect.
property has no effect. Do not set this variable globally; bind it with
@code{let}.
@end defvar
@node Format Properties
@ -2591,13 +2656,17 @@ Insert the strings @var{strings}, just like the function
adjoining text.
@end defun
@xref{Insertion}, for the ordinary insertion functions which do not
inherit.
@node Saving Properties
@subsection Saving Text Properties in Files
@cindex text properties in files
@cindex saving text properties
You can save text properties in files, and restore text properties
when inserting the files, using these two hooks:
You can save text properties in files (along with the text itself),
and restore the same text properties when visiting or inserting the
files, using these two hooks:
@defvar write-region-annotate-functions
This variable's value is a list of functions for @code{write-region} to
@ -2612,8 +2681,8 @@ buffer.
Each function should return a list of elements of the form
@code{(@var{position} . @var{string})}, where @var{position} is an
integer specifying the relative position in the text to be written, and
@var{string} is the annotation to add there.
integer specifying the relative position within the text to be written,
and @var{string} is the annotation to add there.
Each list returned by one of these functions must be already sorted in
increasing order by @var{position}. If there is more than one function,
@ -2650,10 +2719,10 @@ properties in files, using these hooks, and thus to experiment with
various data formats and find good ones. Eventually we hope users
will produce good, general extensions we can install in Emacs.
We suggest not trying to handle arbitrary Lisp objects as property
names or property values---because a program that general is probably
difficult to write, and slow. Instead, choose a set of possible data
types that are reasonably flexible, and not too hard to encode.
We suggest not trying to handle arbitrary Lisp objects as text property
names or values---because a program that general is probably difficult
to write, and slow. Instead, choose a set of possible data types that
are reasonably flexible, and not too hard to encode.
@xref{Format Conversion}, for a related feature.
@ -2704,6 +2773,79 @@ well as others, to the characters they operate on. That way, they avoid
being called over and over for the same text.
@end defvar
@node Clickable Text
@subsection Defining Clickable Text
@cindex clickable text
There are two ways to set up @dfn{clickable text} in a buffer.
There are typically two parts of this: to make the text highlight
when the mouse is over it, and to make a mouse button do something
when you click it on that part of the text.
Highlighting is done with the @code{mouse-face} text property.
Here is an example of how Dired does it:
@smallexample
(condition-case nil
(if (dired-move-to-filename)
(put-text-property (point)
(save-excursion
(dired-move-to-end-of-filename)
(point))
'mouse-face 'highlight))
(error nil))
@end smallexample
@noindent
The first two arguments to @code{put-text-property} specify the
beginning and end of the text.
The usual way to make the mouse do something when you click it
on this text is to define @code{mouse-2} in the major mode's
keymap. The job of checking whether the click was on clickable text
is done by the command definition. Here is how Dired does it:
@smallexample
(defun dired-mouse-find-file-other-window (event)
"In dired, visit the file or directory name you click on."
(interactive "e")
(let (file)
(save-excursion
(set-buffer (window-buffer (posn-window (event-end event))))
(save-excursion
(goto-char (posn-point (event-end event)))
(setq file (dired-get-filename))))
(select-window (posn-window (event-end event)))
(find-file-other-window (file-name-sans-versions file t))))
@end smallexample
@noindent
The reason for the outer @code{save-excursion} construct is to avoid
changing the current buffer; the reason for the inner one is to avoid
permanently altering point in the buffer you click on. In this case,
Dired uses the function @code{dired-get-filename} to determine which
file to visit, based on the position found in the event.
Instead of defining a mouse command for the major mode, you can define
a key binding for the clickable text itself, using the @code{local-map}
text property:
@example
(let ((map (make-sparse-keymap)))
(define-key-binding map [mouse-2] 'operate-this-button)
(put-text-property (point)
(save-excursion
(dired-move-to-end-of-filename)
(point))
'local-map map))
@end example
@noindent
This method makes it possible to define different commands for various
clickable pieces of text. Also, the major mode definition (or the
global definition) remains available for the rest of the text in the
buffer.
@node Not Intervals
@subsection Why Text Properties are not Intervals
@cindex intervals
@ -2744,7 +2886,7 @@ questions of the form, ``What are the properties of this character?''
So we have decided these are the only questions that make sense; we have
not implemented asking questions about where intervals start or end.
In practice, you can usually use the property search functions in
In practice, you can usually use the text property search functions in
place of explicit interval boundaries. You can think of them as finding
the boundaries of intervals, assuming that intervals are always
coalesced whenever possible. @xref{Property Search}.
@ -2822,7 +2964,6 @@ Emacs Lisp by a character that is its name.
The functions in this section return unpredictable values unless
otherwise stated.
@c Will change in version 19
@defvar register-alist
This variable is an alist of elements of the form @code{(@var{name} .
@ -2830,10 +2971,11 @@ This variable is an alist of elements of the form @code{(@var{name} .
register that has been used.
The object @var{name} is a character (an integer) identifying the
register. The object @var{contents} is a string, marker, or list
representing the register contents. A string represents text stored in
the register. A marker represents a position. A list represents a
rectangle; its elements are strings, one per line of the rectangle.
register. The object @var{contents} is a string, marker, window
configuration, frame configuration, or list representing the register
contents. A string represents text stored in the register. A marker
represents a position. A list represents a rectangle; its elements are
strings, one per line of the rectangle.
@end defvar
@defun get-register reg
@ -2963,14 +3105,14 @@ will interfere in bizarre ways with the editing operations that call
them.
@defvar before-change-functions
This variable holds a list of a functions to call before any buffer
This variable holds a list of functions to call before any buffer
modification. Each function gets two arguments, the beginning and end
of the region that is about to change, represented as integers. The
buffer that is about to change is always the current buffer.
@end defvar
@defvar after-change-functions
This variable holds a list of a functions to call after any buffer
This variable holds a list of functions to call after any buffer
modification. Each function receives three arguments: the beginning and
end of the region just changed, and the length of the text that existed
before the change. All three arguments are integers. The buffer that's
@ -2985,6 +3127,22 @@ a @code{before-change-functions} function that calls @code{chars-in-region}
(@pxref{Chars and Bytes}).
@end defvar
@tindex combine-after-change-calls
@defmac combine-after-change-calls body...
The macro executes @var{body} normally, but arranges to call the
after-change functions just once for a series of several changes---if
that seems safe.
If a program makes several text changes in the same area of the buffer,
using the macro @code{combine-after-change-calls} around that part of
the program can make it run considerably faster when after-change hooks
are in use.
@strong{Warning:} You must not alter the values of
@code{after-change-functions} and @code{after-change-function} within
the body of a @code{combine-after-change-calls} form.
@end defmac
@defvar before-change-function
This obsolete variable holds one function to call before any buffer
modification (or @code{nil} for no function). It is called just like

51
lispref/tips.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/tips
@node Tips, GNU Emacs Internals, Calendar, Top
@ -105,8 +105,7 @@ name that ends in @samp{-flag}.
@item
Please do not define @kbd{C-c @var{letter}} as a key in your major
modes. These sequences are reserved for users; they are the
@strong{only} sequences reserved for users, so we cannot do without
them.
@strong{only} sequences reserved for users, so do not block them.
Instead, define sequences consisting of @kbd{C-c} followed by a control
character, a digit, or certain punctuation characters. These sequences
@ -131,12 +130,12 @@ Function keys @key{F5} through @key{F9} without modifier keys are
reserved for users to define.
@item
You should not bind @kbd{C-h} following any prefix character (including
Do not bind @kbd{C-h} following any prefix character (including
@kbd{C-c}). If you don't bind @kbd{C-h}, it is automatically available
as a help character for listing the subcommands of the prefix character.
@item
You should not bind a key sequence ending in @key{ESC} except following
Do not bind a key sequence ending in @key{ESC} except following
another @key{ESC}. (That is, it is ok to bind a sequence ending in
@kbd{@key{ESC} @key{ESC}}.)
@ -151,10 +150,10 @@ shift key held down. These events include @kbd{S-mouse-1},
users.
@item
Modes should redefine @kbd{mouse-2} as a command to follow some sort of
reference in the text of a buffer, if users usually would not want to
alter the text in that buffer by hand. Modes such as Dired, Info,
Compilation, and Occur redefine it in this way.
Special major modes used for read-only text should usually redefine
@kbd{mouse-2} and @key{RET} to trace some sort of reference in the text.
Modes such as Dired, Info, Compilation, and Occur redefine it in this
way.
@item
When a package provides a modification of ordinary Emacs behavior, it is
@ -196,7 +195,7 @@ of the intended features of your program. The mark is a user-level
feature, so it is incorrect to change the mark except to supply a value
for the user's benefit. @xref{The Mark}.
In particular, don't use these functions:
In particular, don't use any of these functions:
@itemize @bullet
@item
@ -278,10 +277,30 @@ to split them in one or two significant places.
@item
Please put a copyright notice on the file if you give copies to anyone.
Use the same lines that appear at the top of the Lisp files in Emacs
itself. If you have not signed papers to assign the copyright to the
Foundation, then place your name in the copyright notice in place of the
Foundation's name.
Use a message like this one:
@smallexample
;; Copyright (C) @var{year} @var{name}
;; This program is free software; you can redistribute it and/or
;; modify it under the terms of the GNU General Public License as
;; published by the Free Software Foundation; either version 2 of
;; the License, or (at your option) any later version.
;; This program is distributed in the hope that it will be
;; useful, but WITHOUT ANY WARRANTY; without even the implied
;; warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
;; PURPOSE. See the GNU General Public License for more details.
;; You should have received a copy of the GNU General Public
;; License along with this program; if not, write to the Free
;; Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
;; MA 02111-1307 USA
@end smallexample
If you have signed papers to assign the copyright to the Foundation,
then use @samp{Free Software Foundation, Inc.} as @var{name}.
Otherwise, use your name.
@end itemize
@node Compilation Tips
@ -308,7 +327,7 @@ is calling another compiled function.
@item
Using the primitive list-searching functions @code{memq}, @code{member},
@code{assq}, or @code{assoc} is even faster than explicit iteration. It
may be worth rearranging a data structure so that one of these primitive
can be worth rearranging a data structure so that one of these primitive
search functions can be used.
@item
@ -575,7 +594,7 @@ Manipulating Comments, emacs, The GNU Emacs Manual}.
@cindex header comments
@cindex library header comments
Emacs 19 has conventions for using special comments in Lisp libraries
Emacs has conventions for using special comments in Lisp libraries
to divide them into sections and give information such as who wrote
them. This section explains these conventions. First, an example:

235
lispref/variables.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/variables
@node Variables, Functions, Control Structures, Top
@ -96,10 +96,14 @@ x
@vindex t
@kindex setting-constant
Emacs Lisp has two special symbols, @code{nil} and @code{t}, that
always evaluate to themselves. These symbols cannot be rebound, nor can
their value cells be changed. An attempt to change the value of
@code{nil} or @code{t} signals a @code{setting-constant} error.
In Emacs Lisp, certain symbols normally evaluate to themselves.
These include @code{nil} and @code{t}, as well as any symbol whose
name starts with @samp{:}.
The symbols @code{nil} and @code{t} @emph{always} evaluate to
themselves. These symbols cannot be rebound, nor can their values be
changed. Any attempt to change the value of @code{nil} or @code{t}
signals a @code{setting-constant} error.
@example
@group
@ -179,9 +183,9 @@ bound to the result of evaluating @var{value-form}. If @var{value-form}
is omitted, @code{nil} is used.
All of the @var{value-form}s in @var{bindings} are evaluated in the
order they appear and @emph{before} any of the symbols are bound. Here
is an example of this: @code{Z} is bound to the old value of @code{Y},
which is 2, not the new value, 1.
order they appear and @emph{before} binding any of the symbols to them.
Here is an example of this: @code{Z} is bound to the old value of
@code{Y}, which is 2, not the new value of @code{Y}, which is 1.
@example
@group
@ -277,9 +281,9 @@ have any value.
using @code{makunbound}.
@defun makunbound symbol
This function makes the current binding of @var{symbol} void.
This function makes the current variable binding of @var{symbol} void.
Subsequent attempts to use this symbol's value as a variable will signal
the error @code{void-variable}, unless or until you set it again.
the error @code{void-variable}, unless and until you set it again.
@code{makunbound} returns @var{symbol}.
@ -388,13 +392,14 @@ provide information to utilities such as @code{etags} and
variables in a program.
The difference between @code{defconst} and @code{defvar} is primarily
a matter of intent, serving to inform human readers of whether programs
will change the variable. Emacs Lisp does not restrict the ways in
which a variable can be used based on @code{defconst} or @code{defvar}
a matter of intent, serving to inform human readers of whether the value
should ever change. Emacs Lisp does not restrict the ways in which a
variable can be used based on @code{defconst} or @code{defvar}
declarations. However, it does make a difference for initialization:
@code{defconst} unconditionally initializes the variable, while
@code{defvar} initializes it only if it is void.
@ignore
One would expect user option variables to be defined with
@code{defconst}, since programs do not change them. Unfortunately, this
has bad results if the definition is in a library that is not preloaded:
@ -402,30 +407,29 @@ has bad results if the definition is in a library that is not preloaded:
loaded. Users would like to be able to set user options in their init
files, and override the default values given in the definitions. For
this reason, user options must be defined with @code{defvar}.
@end ignore
@defspec defvar symbol [value [doc-string]]
This special form defines @var{symbol} as a value and initializes it.
The definition informs a person reading your code that @var{symbol} is
used as a variable that programs are likely to set or change. It is
also used for all user option variables except in the preloaded parts of
Emacs. Note that @var{symbol} is not evaluated; the symbol to be
This special form defines @var{symbol} as a variable and can also
initialize and document it. The definition informs a person reading
your code that @var{symbol} is used as a variable that might be set or
changed. Note that @var{symbol} is not evaluated; the symbol to be
defined must appear explicitly in the @code{defvar}.
If @var{symbol} already has a value (i.e., it is not void), @var{value}
is not even evaluated, and @var{symbol}'s value remains unchanged. If
@var{symbol} is void and @var{value} is specified, @code{defvar}
evaluates it and sets @var{symbol} to the result. (If @var{value} is
omitted, the value of @var{symbol} is not changed in any case.)
If @var{symbol} is void and @var{value} is specified, @code{defvar}
evaluates it and sets @var{symbol} to the result. But if @var{symbol}
already has a value (i.e., it is not void), @var{value} is not even
evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
is omitted, the value of @var{symbol} is not changed in any case.
When you evaluate a top-level @code{defvar} form with @kbd{C-M-x} in
Emacs Lisp mode (@code{eval-defun}), a special feature of
@code{eval-defun} evaluates it as a @code{defconst}. The purpose of
this is to make sure the variable's value is reinitialized, when you ask
for it specifically.
@code{eval-defun} arranges to set the variable unconditionally even if
the variable already has a value.
If @var{symbol} has a buffer-local binding in the current buffer,
@code{defvar} sets the default value, not the local value.
@xref{Buffer-Local Variables}.
@code{defvar} sets the default (buffer-independent) value, not the
buffer-local value. @xref{Buffer-Local Variables}.
If the @var{doc-string} argument appears, it specifies the documentation
for the variable. (This opportunity to specify documentation is one of
@ -436,9 +440,12 @@ Emacs help functions (@pxref{Documentation}) look for this property.
If the first character of @var{doc-string} is @samp{*}, it means that
this variable is considered a user option. This lets users set the
variable conventiently using the commands @code{set-variable} and
@code{edit-options}.
@code{edit-options}. However, it is better to use @code{defcustom}
instead of @code{defvar}, for user option variables, to specify
customization information. @xref{Customization}.
For example, this form defines @code{foo} but does not set its value:
Here are some examples. This form defines @code{foo} but does not
initialize it:
@example
@group
@ -447,8 +454,8 @@ For example, this form defines @code{foo} but does not set its value:
@end group
@end example
The following example sets the value of @code{bar} to @code{23}, and
gives it a documentation string:
This example initializes the value of @code{bar} to @code{23}, and gives
it a documentation string:
@example
@group
@ -460,12 +467,12 @@ gives it a documentation string:
The following form changes the documentation string for @code{bar},
making it a user option, but does not change the value, since @code{bar}
already has a value. (The addition @code{(1+ 23)} is not even
performed.)
already has a value. (The addition @code{(1+ nil)} would get an error
if it were evaluated, but since it is not evaluated, there is no error.)
@example
@group
(defvar bar (1+ 23)
(defvar bar (1+ nil)
"*The normal weight of a bar.")
@result{} bar
@end group
@ -496,22 +503,16 @@ at top level in a file where its value does not matter.
@defspec defconst symbol [value [doc-string]]
This special form defines @var{symbol} as a value and initializes it.
It informs a person reading your code that @var{symbol} has a global
value, established here, that will not normally be changed or locally
bound by the execution of the program. The user, however, may be
welcome to change it. Note that @var{symbol} is not evaluated; the
It informs a person reading your code that @var{symbol} has a standard
global value, established here, that should not be changed by the user
or by other programs. Note that @var{symbol} is not evaluated; the
symbol to be defined must appear explicitly in the @code{defconst}.
@code{defconst} always evaluates @var{value} and sets the global value
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
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
is loaded later.
@code{defconst} always evaluates @var{value}, and sets the value of
@var{symbol} to the result if @var{value} is given. If @var{symbol}
does has a buffer-local binding in the current buffer, @code{defconst}
sets the default value, not the buffer-local value. But you should not
be making the symbol buffer-local if it is defined with @code{defconst}.
Here, @code{pi} is a constant that presumably ought not to be changed
by anyone (attempts by the Indiana State Legislature notwithstanding).
@ -550,7 +551,8 @@ then the variable is a user option.
If a user option variable has a @code{variable-interactive} property,
the @code{set-variable} command uses that value to control reading the
new value for the variable. The property's value is used as if it were
to @code{interactive} (@pxref{Using Interactive}).
to @code{interactive} (@pxref{Using Interactive}). However, this feature
is largely obsoleted by the @code{defcustom} (@pxref{Customization}).
@strong{Warning:} If the @code{defconst} and @code{defvar} special
forms are used while the variable has a local binding, they set the
@ -569,7 +571,7 @@ entire computation of the value into the @code{defvar}, like this:
@example
(defvar my-mode-map
(let ((map (make-sparse-keymap)))
(define-key my-mode-map "\C-c\C-a" 'my-command)
(define-key map "\C-c\C-a" 'my-command)
@dots{}
map)
@var{docstring})
@ -672,7 +674,7 @@ has no local bindings.
@end example
A @code{void-variable} error is signaled if @var{symbol} has neither a
local binding nor a global value.
local binding nor a global one.
@end defun
@node Setting Variables
@ -783,8 +785,8 @@ sets the variable, needs to use @code{set}.
@cindex CL note---@code{set} local
@quotation
@b{Common Lisp note:} In Common Lisp, @code{set} always changes the
symbol's special value, ignoring any lexical bindings. In Emacs Lisp,
all variables and all bindings are (in effect) special, so @code{set}
symbol's ``special'' or dynamic value, ignoring any lexical bindings.
In Emacs Lisp, all variables and all bindings are dynamic, so @code{set}
always affects the most local existing binding.
@end quotation
@end defun
@ -830,7 +832,7 @@ foo ;; @r{@code{foo} was changed.}
@node Variable Scoping
@section Scoping Rules for Variable Bindings
A given symbol @code{foo} may have several local variable bindings,
A given symbol @code{foo} can have several local variable bindings,
established at different places in the Lisp program, as well as a global
binding. The most recently established binding takes precedence over
the others.
@ -853,8 +855,8 @@ 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
are dynamically scoped, like variables in Emacs Lisp.
@b{Common Lisp note:} Variables declared ``special'' in Common Lisp are
dynamically scoped, like all variables in Emacs Lisp.
@end quotation
@menu
@ -880,7 +882,7 @@ definitions:
@end group
@group
(defun user () ; @r{@code{x} is used in @code{user}.}
(defun user () ; @r{@code{x} is used ``free'' in @code{user}.}
(list x))
@end group
@end example
@ -899,7 +901,7 @@ then whatever binding of @code{x} is found, it cannot come from
@code{binder}.
@item
If we define @code{foo} as follows and call @code{binder}, then the
If we define @code{foo} as follows and then call @code{binder}, then the
binding made in @code{binder} will be seen in @code{user}:
@example
@ -910,8 +912,9 @@ binding made in @code{binder} will be seen in @code{user}:
@end example
@item
If we define @code{foo} as follows and call @code{binder}, then the
binding made in @code{binder} @emph{will not} be seen in @code{user}:
However, if we define @code{foo} as follows and then call @code{binder},
then the binding made in @code{binder} @emph{will not} be seen in
@code{user}:
@example
(defun foo (x)
@ -925,6 +928,13 @@ Here, when @code{foo} is called by @code{binder}, it binds @code{x}.
by @code{foo} instead of the one bound by @code{binder}.
@end itemize
Emacs Lisp uses dynamic scoping because simple implementations of
lexical scoping are slow. In addition, every Lisp system needs to offer
dynamic scoping at least as an option; if lexical scoping is the norm,
there must be a way to specify dynamic scoping instead for a particular
variable. It might not be a bad thing for Emacs to offer both, but
implementing it with dynamic scoping only was much easier.
@node Extent
@subsection Extent
@ -940,10 +950,10 @@ that made the binding. Common Lisp and Scheme, for example, support
this, but Emacs Lisp does not.
To illustrate this, the function below, @code{make-add}, returns a
function that purports to add @var{n} to its own argument @var{m}.
This would work in Common Lisp, but it does not work as intended in
Emacs Lisp, because after the call to @code{make-add} exits, the
variable @code{n} is no longer bound to the actual argument 2.
function that purports to add @var{n} to its own argument @var{m}. This
would work in Common Lisp, but it does not do the job in Emacs Lisp,
because after the call to @code{make-add} exits, the variable @code{n}
is no longer bound to the actual argument 2.
@example
(defun make-add (n)
@ -970,7 +980,7 @@ works) may help you understand dynamic binding. This technique is
called @dfn{deep binding} and was used in early Lisp systems.
Suppose there is a stack of bindings: variable-value pairs. At entry
to a function or to a @code{let} form, we can push bindings on the stack
to a function or to a @code{let} form, we can push bindings onto the stack
for the arguments or local variables created there. We can pop those
bindings from the stack at exit from the binding construct.
@ -993,9 +1003,9 @@ symbol.
In shallow binding, setting the variable works by storing a value in
the value cell. Creating a new binding works by pushing the old value
(belonging to a previous binding) on a stack, and storing the local value
in the value cell. Eliminating a binding works by popping the old value
off the stack, into the value cell.
(belonging to a previous binding) onto a stack, and storing the new
local value in the value cell. Eliminating a binding works by popping
the old value off the stack, into the value cell.
We use shallow binding because it has the same results as deep
binding, but runs faster, since there is never a need to search for a
@ -1063,15 +1073,19 @@ are local to a given X terminal; see @ref{Multiple Displays}.)
particular buffer. The binding is in effect when that buffer is
current; otherwise, it is not in effect. If you set the variable while
a buffer-local binding is in effect, the new value goes in that binding,
so the global binding is unchanged; this means that the change is
visible in that buffer alone.
so its other bindings are unchanged. This means that the change is
visible only in the buffer where you made it.
A variable may have buffer-local bindings in some buffers but not in
others. The global binding is shared by all the buffers that don't have
their own bindings. Thus, if you set the variable in a buffer that does
not have a buffer-local binding for it, the new value is visible in all
buffers except those with buffer-local bindings. (Here we are assuming
that there are no @code{let}-style local bindings to complicate the issue.)
The variable's ordinary binding, which is not associated with any
specific buffer, is called the @dfn{default binding}. In most cases,
this is the global binding.
A variable can have buffer-local bindings in some buffers but not in
other buffers. The default binding is shared by all the buffers that
don't have their own bindings for the variable. If you set the variable
in a buffer that does not have a buffer-local binding for it, this sets
the default binding, so the new value is visible in all the buffers that
see the default binding.
The most common use of buffer-local bindings is for major modes to change
variables that control the behavior of commands. For example, C mode and
@ -1083,7 +1097,7 @@ then setting it to the new value for that mode.
The usual way to make a buffer-local binding is with
@code{make-local-variable}, which is what major mode commands use. This
affects just the current buffer; all other buffers (including those yet to
be created) continue to share the global value.
be created) continue to share the default value.
@cindex automatically buffer-local
A more powerful operation is to mark the variable as
@ -1092,21 +1106,21 @@ be created) continue to share the global value.
variable local in all buffers, even those yet to be created. More
precisely, the effect is that setting the variable automatically makes
the variable local to the current buffer if it is not already so. All
buffers start out by sharing the global value of the variable as usual,
buffers start out by sharing the default value of the variable as usual,
but any @code{setq} creates a buffer-local binding for the current
buffer. The new value is stored in the buffer-local binding, leaving
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.
the default binding untouched. The default value can no longer be
changed with @code{setq} in this buffer; you need to use
@code{setq-default} to do that.
@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
scramble the values of the global and local bindings.
@strong{Warning:} When a variable has buffer-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 scramble the values of the buffer-local and default bindings.
To preserve your sanity, avoid that series of actions. If you use
@code{save-excursion} around each piece of code that changes to a
To preserve your sanity, avoid using a variable in that way. If you
use @code{save-excursion} around each piece of code that changes to a
different current buffer, you will not have this problem. Here is an
example of what to avoid:
@ -1126,7 +1140,7 @@ foo @result{} 'a ; @r{The old buffer-local value from buffer @samp{a}}
@end group
@group
(set-buffer "a")
foo @result{} 'temp ; @r{The local value that should be gone}
foo @result{} 'temp ; @r{The local @code{let} value that should be gone}
; @r{is now the buffer-local value in buffer @samp{a}.}
@end group
@end example
@ -1252,30 +1266,30 @@ the current buffer is used.
(mode-name . "Fundamental")
@dots{}
@group
;; @r{Next, non-built-in local variables.}
;; @r{This one is local and void:}
;; @r{Next, non-built-in buffer-local variables.}
;; @r{This one is buffer-local and void:}
foobar
;; @r{This one is local and nonvoid:}
;; @r{This one is buffer-local and nonvoid:}
(bind-me . 69))
@end group
@end example
Note that storing new values into the @sc{cdr}s of cons cells in this
list does @emph{not} change the local values of the variables.
list does @emph{not} change the buffer-local values of the variables.
@end defun
@deffn Command kill-local-variable variable
This function deletes the buffer-local binding (if any) for
@var{variable} (a symbol) in the current buffer. As a result, the
global (default) binding of @var{variable} becomes visible in this
buffer. Usually this results in a change in the value of
@var{variable}, since the global value is usually different from the
buffer-local value just eliminated.
default binding of @var{variable} becomes visible in this buffer. This
typically results in a change in the value of @var{variable}, since the
default value is usually different from the buffer-local value just
eliminated.
If you kill the local binding of a variable that automatically becomes
local when set, this makes the global value visible in the current
buffer. However, if you set the variable again, that will once again
create a local binding for it.
If you kill the buffer-local binding of a variable that automatically
becomes buffer-local when set, this makes the default value visible in
the current buffer. However, if you set the variable again, that will
once again create a buffer-local binding for it.
@code{kill-local-variable} returns @var{variable}.
@ -1294,6 +1308,9 @@ buffer: it sets the local keymap to @code{nil}, the syntax table to the
value of @code{standard-syntax-table}, and the abbrev table to the value
of @code{fundamental-mode-abbrev-table}.
The very first thing this function does is run the normal hook
@code{change-major-mode-hook} (@pxref{Major Mode Conventions}).
Every major mode command begins by calling this function, which has the
effect of switching to Fundamental mode and erasing most of the effects
of the previous major mode. To ensure that this does its job, the
@ -1304,10 +1321,10 @@ variables that major modes set should not be marked permanent.
@c Emacs 19 feature
@cindex permanent local variable
A local variable is @dfn{permanent} if the variable name (a symbol) has a
@code{permanent-local} property that is non-@code{nil}. Permanent
locals are appropriate for data pertaining to where the file came from
or how to save it, rather than with how to edit the contents.
A buffer-local variable is @dfn{permanent} if the variable name (a
symbol) has a @code{permanent-local} property that is non-@code{nil}.
Permanent locals are appropriate for data pertaining to where the file
came from or how to save it, rather than with how to edit the contents.
@node Default Value
@subsection The Default Value of a Buffer-Local Variable
@ -1327,8 +1344,8 @@ this variable.
@c Emacs 19 feature
The special forms @code{defvar} and @code{defconst} also set the
default value (if they set the variable at all), rather than any local
value.
default value (if they set the variable at all), rather than any
buffer-local value.
@defun default-value symbol
This function returns @var{symbol}'s default value. This is the value
@ -1412,7 +1429,7 @@ local
@defun set-default symbol value
This function is like @code{setq-default}, except that @var{symbol} is
evaluated.
an ordinary evaluated argument.
@example
@group

224
lispref/windows.texi
View file

@ -1,6 +1,6 @@
@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/windows
@node Windows, Frames, Buffers, Top
@ -24,12 +24,14 @@ displayed in windows.
* Window Start:: The display-start position controls which text
is on-screen in the window.
* Vertical Scrolling:: Moving text up and down in the window.
* Scrolling Hooks:: Hooks that run when you scroll a window.
* Horizontal Scrolling:: Moving text sideways on the window.
* Size of Window:: Accessing the size of a window.
* Resizing Windows:: Changing the size of a window.
* Coordinates and Windows:: Converting coordinates to windows.
* Window Configurations:: Saving and restoring the state of the screen.
* Window Hooks:: Hooks for scrolling, window size changes,
redisplay going past a certain point,
or window configuration changes.
@end menu
@node Basic Windows
@ -49,7 +51,7 @@ multiple nonoverlapping Emacs windows.
In each frame, at any time, one and only one window is designated as
@dfn{selected within the frame}. The frame's cursor appears in that
window. At ant time, one frame is the selected frame; and the window
window. At any time, one frame is the selected frame; and the window
selected within that frame is @dfn{the selected window}. The selected
window's buffer is usually the current buffer (except when
@code{set-buffer} has been used). @xref{Current Buffer}.
@ -114,16 +116,16 @@ treats the whole terminal screen as one frame.
@cindex tiled windows
Most window systems support arbitrarily located overlapping windows.
In contrast, Emacs windows are @dfn{tiled}; they never overlap, and
together they fill the whole screen or frame. Because of the way
in which Emacs creates new windows and resizes them, you can't create
every conceivable tiling of windows on an Emacs frame. @xref{Splitting
Windows}, and @ref{Size of Window}.
together they fill the whole screen or frame. Because of the way in
which Emacs creates new windows and resizes them, not all conceivable
tilings of windows on an Emacs frame are actually possible.
@xref{Splitting Windows}, and @ref{Size of Window}.
@xref{Display}, for information on how the contents of the
window's buffer are displayed in the window.
@defun windowp object
This function returns @code{t} if @var{object} is a window.
This function returns @code{t} if @var{object} is a window.
@end defun
@node Splitting Windows
@ -721,7 +723,7 @@ the binding of @kbd{C-x b}. It is also used frequently in programs. It
always returns @code{nil}.
@end deffn
@deffn Command switch-to-buffer-other-window buffer-or-name
@deffn Command switch-to-buffer-other-window buffer-or-name &optional norecord
This function makes @var{buffer-or-name} the current buffer and
displays it in a window not currently selected. It then selects that
window. The handling of the buffer is the same as in
@ -732,9 +734,12 @@ If it is the only window, then it is split to make a distinct window for
this purpose. If the selected window is already displaying the buffer,
then it continues to do so, but another window is nonetheless found to
display it in as well.
This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
@end deffn
@defun pop-to-buffer buffer-or-name &optional other-window
@defun pop-to-buffer buffer-or-name &optional other-window norecord
This function makes @var{buffer-or-name} the current buffer and
switches to it in some window, preferably not the window previously
selected. The ``popped-to'' window becomes the selected window within
@ -770,6 +775,9 @@ If @var{buffer-or-name} is a string that does not name an existing
buffer, a buffer by that name is created. The major mode for the new
buffer is set according to the variable @code{default-major-mode}.
@xref{Auto Major Mode}.
This function updates the buffer list just like @code{switch-to-buffer}
unless @var{norecord} is non-@code{nil}.
@end defun
@deffn Command replace-buffer-in-windows buffer
@ -782,6 +790,14 @@ don't care which other buffer is used; you just want to make sure that
This function returns @code{nil}.
@end deffn
@tindex buffer-display-count
@defvar buffer-display-count
This variable is always local in each buffer. When the buffer is
created, @code{buffer-display-count} has value 0. Each time the buffer
is displayed in a window, that increments the value of
@code{buffer-display-count}.
@end defvar
@node Choosing Window
@section Choosing a Window for Display
@ -790,7 +806,7 @@ display a buffer in---@code{display-buffer}. All the higher-level
functions and commands use this subroutine. Here we describe how to use
@code{display-buffer} and how to customize it.
@deffn Command display-buffer buffer-or-name &optional not-this-window
@deffn Command display-buffer buffer-or-name &optional not-this-window frame
This command makes @var{buffer-or-name} appear in some window, like
@code{pop-to-buffer}, but it does not select that window and does not
make the buffer current. The identity of the selected window is
@ -806,6 +822,13 @@ function does nothing.
@code{display-buffer} returns the window chosen to display
@var{buffer-or-name}.
If the argument @var{frame} is non-@code{nil}, it specifies which frames
to check when deciding whether the buffer is already displayed. Its
value means the same thing as in functions @code{get-buffer-window}
(@pxref{Buffers and Windows}). If the buffer is already displayed
in some window on one of these frames, @code{display-buffer} simply
returns that window.
Precisely how @code{display-buffer} finds or creates a window depends on
the variables described below.
@end deffn
@ -972,12 +995,12 @@ initialized from the buffer's point, or from the window point of another
window opened on the buffer if such a window exists.
@item
Selecting a window sets the value of point in its buffer to the window's
value of point. Conversely, deselecting a window sets the window's
value of point from that of the buffer. Thus, when you switch between
windows that display a given buffer, the point value for the selected
window is in effect in the buffer, while the point values for the other
windows are stored in those windows.
Selecting a window sets the value of point in its buffer from the
window's value of point. Conversely, deselecting a window sets the
window's value of point from that of the buffer. Thus, when you switch
between windows that display a given buffer, the point value for the
selected window is in effect in the buffer, while the point values for
the other windows are stored in those windows.
@item
As long as the selected window displays the current buffer, the window's
@ -1293,57 +1316,6 @@ Replaces three keystroke sequence C-u 0 C-l."
@end example
@end deffn
@node Scrolling Hooks
@section Hooks for Vertical Scrolling
This section describes how a Lisp program can take action whenever a
window displays a different part of its buffer or a different buffer.
There are three actions that can change this: scrolling the window,
switching buffers in the window, and changing the size of the window.
The first two actions run @code{window-scroll-functions}; the last runs
@code{window-size-change-functions}. The paradigmatic use of these
hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
Support Modes, emacs, The GNU Emacs Manual}.
@defvar window-scroll-functions
This variable holds a list of functions that Emacs should call before
redisplaying a window with scrolling. It is not a normal hook, because
each function is called with two arguments: the window, and its new
display-start position.
Displaying a different buffer in the window also runs these functions.
These functions cannot expect @code{window-end} (@pxref{Window Start})
to return a meaningful value, because that value is updated only by
redisplaying the buffer. So if one of these functions needs to know the
last character that will fit in the window with its current
display-start position, it has to find that character using
@code{vertical-motion} (@pxref{Screen Lines}).
@end defvar
@defvar window-size-change-functions
This variable holds a list of functions to be called if the size of any
window changes for any reason. The functions are called just once per
redisplay, and just once for each frame on which size changes have
occurred.
Each function receives the frame as its sole argument. There is no
direct way to find out which windows on that frame have changed size, or
precisely how. However, if a size-change function records, at each
call, the existing windows and their sizes, it can also compare the
present sizes and the previous sizes.
Creating or deleting windows counts as a size change, and therefore
causes these functions to be called. Changing the frame size also
counts, because it changes the sizes of the existing windows.
It is not a good idea to use @code{save-window-excursion} (@pxref{Window
Configurations}) in these functions, because that always counts as a
size change, and it would cause these functions to be called over and
over. In most cases, @code{save-selected-window} (@pxref{Selecting
Windows}) is what you need here.
@end defvar
@node Horizontal Scrolling
@section Horizontal Scrolling
@cindex horizontal scrolling
@ -1414,7 +1386,7 @@ If @var{window} is @code{nil}, the selected window is used.
@defun set-window-hscroll window columns
This function sets the number of columns from the left margin that
@var{window} is scrolled to the value of @var{columns}. The argument
@var{window} is scrolled from the value of @var{columns}. The argument
@var{columns} should be zero or positive; if not, it is taken as zero.
The value returned is @var{columns}.
@ -1693,9 +1665,9 @@ The argument @var{coordinates} is a cons cell of this form:
The coordinates @var{x} and @var{y} are measured in characters, and
count from the top left corner of the screen or frame.
The value of @code{coordinates-in-window-p} is non-@code{nil} if the
coordinates are inside @var{window}. The value also indicates what part
of the window the position is in, as follows:
The value returned by @code{coordinates-in-window-p} is non-@code{nil}
if the coordinates are inside @var{window}. The value also indicates
what part of the window the position is in, as follows:
@table @code
@item (@var{relx} . @var{rely})
@ -1726,7 +1698,7 @@ argument because it always uses the frame that @var{window} is on.
@cindex window configurations
@cindex saving window information
A @dfn{window configuration} records the entire layout of a
A @dfn{window configuration} records the entire layout of one
frame---all windows, their sizes, which buffers they contain, what part
of each buffer is displayed, and the values of point and the mark. You
can bring back an entire previous layout by restoring a window
@ -1737,19 +1709,21 @@ configuration instead of a window configuration. @xref{Frame
Configurations}.
@defun current-window-configuration
This function returns a new object representing Emacs's current window
configuration, namely the number of windows, their sizes and current
buffers, which window is the selected window, and for each window the
displayed buffer, the display-start position, and the positions of point
and the mark. An exception is made for point in the current buffer,
whose value is not saved.
This function returns a new object representing the selected frame's
current window configuration, including the number of windows, their
sizes and current buffers, which window is the selected window, and for
each window the displayed buffer, the display-start position, and the
positions of point and the mark. An exception is made for point in the
current buffer, whose value is not saved.
@end defun
@defun set-window-configuration configuration
This function restores the configuration of Emacs's windows and
buffers to the state specified by @var{configuration}. The argument
@var{configuration} must be a value that was previously returned by
@code{current-window-configuration}.
This function restores the configuration of windows and buffers as
specified by @var{configuration}. The argument @var{configuration} must
be a value that was previously returned by
@code{current-window-configuration}. This function operates on the
frame for which @var{configuration} was made, whether that frame is
selected or not.
This function always counts as a window size change and triggers
execution of the @code{window-size-change-functions}. (It doesn't know
@ -1776,7 +1750,7 @@ in sequence, then restores the earlier window configuration. The window
configuration includes the value of point and the portion of the buffer
that is visible. It also includes the choice of selected window.
However, it does not include the value of point in the current buffer;
use @code{save-excursion} if you wish to preserve that.
use @code{save-excursion} also, if you wish to preserve that.
Don't use this construct when @code{save-selected-window} is all you need.
@ -1815,3 +1789,85 @@ This function returns @code{t} if @var{object} is a window configuration.
Primitives to look inside of window configurations would make sense,
but none are implemented. It is not clear they are useful enough to be
worth implementing.
@node Window Hooks
@section Hooks for Window Scrolling and Changes
This section describes how a Lisp program can take action whenever a
window displays a different part of its buffer or a different buffer.
There are three actions that can change this: scrolling the window,
switching buffers in the window, and changing the size of the window.
The first two actions run @code{window-scroll-functions}; the last runs
@code{window-size-change-functions}. The paradigmatic use of these
hooks is Lazy Lock mode; see @ref{Support Modes, Lazy Lock, Font Lock
Support Modes, emacs, The GNU Emacs Manual}.
@defvar window-scroll-functions
This variable holds a list of functions that Emacs should call before
redisplaying a window with scrolling. It is not a normal hook, because
each function is called with two arguments: the window, and its new
display-start position.
Displaying a different buffer in the window also runs these functions.
These functions cannot expect @code{window-end} (@pxref{Window Start})
to return a meaningful value, because that value is updated only by
redisplaying the buffer. So if one of these functions needs to know the
last character that will fit in the window with its current
display-start position, it has to find that character using
@code{vertical-motion} (@pxref{Screen Lines}).
@end defvar
@defvar window-size-change-functions
This variable holds a list of functions to be called if the size of any
window changes for any reason. The functions are called just once per
redisplay, and just once for each frame on which size changes have
occurred.
Each function receives the frame as its sole argument. There is no
direct way to find out which windows on that frame have changed size, or
precisely how. However, if a size-change function records, at each
call, the existing windows and their sizes, it can also compare the
present sizes and the previous sizes.
Creating or deleting windows counts as a size change, and therefore
causes these functions to be called. Changing the frame size also
counts, because it changes the sizes of the existing windows.
It is not a good idea to use @code{save-window-excursion} (@pxref{Window
Configurations}) in these functions, because that always counts as a
size change, and it would cause these functions to be called over and
over. In most cases, @code{save-selected-window} (@pxref{Selecting
Windows}) is what you need here.
@end defvar
@tindex redisplay-end-trigger-functions
@defvar redisplay-end-trigger-functions
This abnormal hook is run whenever redisplay in window uses text that
extends past a specified end trigger position. You set the end trigger
position with the function @code{set-window-redisplay-end-trigger}. The
functions are called with two arguments: the window, and the end trigger
position. Storing @code{nil} for the end trigger position turns off the
feature, and the trigger value is automatically reset to @code{nil} just
after the hook is run.
@end defvar
@tindex set-window-redisplay-end-trigger
@defun set-window-redisplay-end-trigger window position
This function sets @var{window}'s end trigger position at
@var{position}.
@end defun
@tindex window-redisplay-end-trigger
@defun window-redisplay-end-trigger window
This function returns @var{window}'s current end trigger position.
@end defun
@tindex window-configuration-change-hook
@defvar window-configuration-change-hook
A normal hook that is run every time you change the window configuration
of an existing frame. This includes splitting or deleting windows,
changing the sizes of windows, or displaying a different buffer in a
window. The frame whose window configuration has changed is the
selected frame when this hook runs.
@end defvar