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
@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
@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
@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
@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
@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.
-@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?
+Valid character codes for text must be in the range 0 through 255.
+Within this range, there are no invalid character codes.
@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.
-
-@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.
-
-@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.
-@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.
-
-@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 macros @code{when} and @code{unless} have been deleted.
@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}.
+The functions @code{caar}, @code{cadr}, @code{cdar} and @code{cddr}
+no longer exist.
@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}.
+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 Changes in Basic Editing Functions
+Here are changes in handling strings and text.
@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 function @code{substring} works only on strings, not on vectors.
@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}.
+There are no more character categories.
@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.
+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
-The variable @code{overwrite-mode-binary} has been removed.
+@code{format-time-string} no longer supports specified field width
+or specified padding.
@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 functions @code{split-string} and @code{concat-chars} no longer exist.
+Neither does @code{store-substring} or @code{sref}.
@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.
+All printing characters have the same width. Therefore, we have deleted
+@code{char-width}, @code{string-width} and
+@code{truncate-string-to-width}.
@item
-@code{translate-region} is gone.
+We have eliminated the functions @code{next-char-property-change} and
+@code{previous-char-property-change} also.
@item
-The variables @code{before-change-function},
-@code{after-change-function}, and @code{first-change-hook} have been
-eliminated.
+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
-The second argument to @code{insert-abbrev-table-description} is no
-longer optional.
+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 Text Properties
-
-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 are changes in other areas of Emacs Lisp:
@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.
-
-@item
-We got rid of the ``initial file name'' argument to
-@code{read-file-name}.
+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
-Additionally, we removed the 12th element from the list returned by
-@code{file-attributes}.
+The easy-mmode facility for defining minor modes is gone too.
@item
-@code{directory-files} always sorts the list of files. It's not user
-friendly to process the files in any haphazard order.
-
-@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.
+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.
-@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.
+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
-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.
+The ``mail user agent'' feature is gone.
@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}.
+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
-Additionally, we removed the variable @code{x-no-window-manager} and the
-functions @code{x-synchronize} and @code{x-get-resource}.
+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
-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}.
+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
-@code{x-popup-menu} no longer accepts a keymap for its first argument.
+We have got rid of the function @code{access-file}.
@item
-We removed both the function @code{x-rebind-key} and the related
-function @code{x-rebind-keys}.
+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
-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}.
+You can still bind @code{x-resource-class} around a call to
+@code{x-get-resource}, but it won't do anything special.
@item
-We removed the variables @code{pop-up-frames},
-@code{pop-up-frame-function}, @code{display-buffer-function}, and
-@code{other-window-scroll-buffer}.
+Wave goodbye to the hooks @code{before-make-frame-hook},
+@code{after-make-frame-functions}, and
+@code{window-configuration-change-hook},
@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.
+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 Working with Input Events
+@section Onward into the Past!
-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.
+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
-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.
+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
-The documentation functions (@code{single-key-description},
-@code{key-description}, etc.) also no longer accept vectors, but they do
-accept strings.
+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
-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.
+There is no function @code{overlays-in}.
@item
-We removed the @code{unread-command-events} and @code{last-event-frame}
-variables.
+The variable @code{print-length} applies only to lists, not to
+vectors or strings.
@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.
+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
-We eliminated @samp{e} as an interactive specification since it
-was useful only with non-character events.
+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
-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
+The functions @code{keymap-parent} and @code{set-keymap-parent} are
+gone. We expect keymaps to recognize their own parents.
-@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.
+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
-In Emacs 18, you can activate menus only with the mouse. Using them
-with a keyboard was too confusing for too many users.
+The interactive specification @samp{N} is gone now.
@item
-Emacs 18 has no menu bars. All functions and variables related to the
-menu bar have been eliminated.
-@end itemize
+There is no more @code{safe-length}. Don't try to be so safe! Did you
+expect to live forever?
-@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
+We got rid of @code{insert-file-contents-literally}, because
+programmers are too literal-minded anyway.
-@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}.
+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
-We removed the variable
-@code{revert-buffer-insert-file-contents-function}.
+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
-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.
+You can't do date arithmentic with @code{encode-time} any more.
@item
-The variable @code{lisp-indent-hook} has been renamed to
-@code{lisp-indent-function}.
+The functions @code{command-execute} and @code{call-interactively} no
+longer accept the optional argument @var{keys}.
@item
-The variable @code{auto-fill-function} has been renamed to
-@code{auto-fill-hook}.
+@code{get-buffer-window-list} is gone as well.
@item
-The @code{blink-paren-function} has been renamed to
-@code{blink-paren-hook}.
+With the function @code{replace-match}, you can only replace the whole
+match, not a subexpression of it.
@item
-The variable @code{temp-buffer-show-function} has been renamed to
-@code{temp-buffer-show-hook}.
+We eliminated the hooks @code{buffer-access-fontify-functions},
+@code{window-scroll-functions}, and @code{redisplay-end-trigger-functions}.
@end itemize
@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
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
@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.
(@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.
@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
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
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
@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
@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
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
@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
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
@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
@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}.
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
@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)
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)
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
@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
@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
@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
@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,
@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
* 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.
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
@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.
@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;
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
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
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
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}.
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
(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
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
@defun eventp object
This function returns non-@code{nil} if @var{object} is an input event.
+A symbol
@end defun
@menu
@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
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
@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.
@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.
@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-}.
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
@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.
@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,
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:
(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
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.
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
@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
@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
@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}.
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
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
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
@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
@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
@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.
@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,
@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
(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
@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
@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} 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 @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 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
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
@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
@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
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
@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
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}
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
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.
@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
* 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.
@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
@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
@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.
@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
@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
@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)}
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)}
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
@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}.
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
@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.
+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 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.
+@defun set-face-underline-p face underline-p &optional frame
+This function sets the underline attribute of face @var{face}.
+Non-@code{nil} means do underline; @code{nil} means don't.
@end defun
-@defun 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.
+@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
-@defun set-face-underline-p face underline-p &optional frame
-This function sets the underline attribute of face @var{face}.
-Non-@code{nil} means do underline; @code{nil} means don't.
+@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
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.
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
@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
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
(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
@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}.
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
(@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
@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
@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}.
@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
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
@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
@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
* 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.
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.
* 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,
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
* 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.
* 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''.
@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
@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
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.
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
@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
@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
@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
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.
@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
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
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:
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
@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
* 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.
@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
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}.
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
@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
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
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
@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
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
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,
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.
@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}.
@end table
@end defun
-@node Changing File Attributes
+@node Changing Files
@section Changing File Names and Attributes
@cindex renaming files
@cindex copying files
@example
@group
-(add-name-to-file "~/lewis/foo1" "~/lewis/foo2")
+(add-name-to-file "~/lewis/foo" "~/lewis/foo2")
@result{} nil
@end group
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
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
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.
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.
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{:},
@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
@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
@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
@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}.
@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:
@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
@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
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
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
@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:
@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
@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
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
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.
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
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
@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:
@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}.
@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
* 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.
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
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
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
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.
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
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}.
@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}.
@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:
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
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
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
@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
@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
@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}.
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).
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.
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
@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:
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
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
@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
@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
@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}
@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.
-
-@defspec function function-object
-@cindex function quoting
-This special form returns @var{function-object} without evaluating it.
-In this, it is equivalent to @code{quote}. However, it serves as a
-note to the Emacs Lisp compiler that @var{function-object} is intended
-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:
+of simple quotation to quote the anonymous function, like this:
@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)
+(defun double-property (symbol prop)
+ (change-property symbol prop (function (lambda (x) (* 2 x)))))
@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:
+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))
@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.
+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.
+comment:
@example
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
@end example
+@defspec function function-object
+@cindex function quoting
+This special form returns @var{function-object} without evaluating it.
+In this, it is equivalent to @code{quote}. However, it serves as a
+note to the Emacs Lisp compiler that @var{function-object} is intended
+to be used only as a function, and therefore can safely be compiled.
+Contrast this with @code{quote}, in @ref{Quoting}.
+@end defspec
+
See @code{documentation} in @ref{Accessing Documentation}, for a
realistic example using @code{function} and an anonymous function.
@example
@group
(defun foo (x) x)
- @result{} x
+ @result{} foo
@end group
@group
(foo 1)
@end group
@group
(fmakunbound 'foo)
- @result{} x
+ @result{} foo
@end group
@group
(foo 1)
@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:
@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
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
@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}.
@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
@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
@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
@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.
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
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
@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)
@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
@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:
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
@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
@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
@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
@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
@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
@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
@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
@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
@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
(@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
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
|| (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
@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
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.
@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
@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
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.
* 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
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.
-
- 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.
+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.
+
+ 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
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.
-
- 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.
+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.
+
+@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 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
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}
@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
@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
@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}.
-
- In Emacs version 18, only the function definition of @var{symbol} was
-set, not the value as a variable.
+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.
+
+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
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}.
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
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
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
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
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.
@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}
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).
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
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})},
@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}.
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)
@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
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,
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}:
@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
@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
@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
@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
@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 '<))
@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
@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
@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
@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
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
@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
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
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.
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.
@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
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:
@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
@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
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
`(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.
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
@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
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?
@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
* 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
@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,
@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
@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
@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
* 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
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
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
@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:
@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}
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}.
@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}:
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}.
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
@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
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}.
@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? ")
@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? ")
@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
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
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
@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
* 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
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.
@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
@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
@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.
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
@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,
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}.
@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)
@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.
@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
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
@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
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.
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
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.
'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
" "
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
@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
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
@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
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
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},
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:
@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
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.
@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
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):
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
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
@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
@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
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
* 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.
@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
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
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}}
?\^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
@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
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
@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}
@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,
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
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}...)
@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
@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
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
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
@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.
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.
@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
@item framep
@xref{Frames, framep}.
+@item functionp
+@xref{Functions, functionp}.
+
@item integer-or-marker-p
@xref{Predicates on Markers, integer-or-marker-p}.
@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
@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
@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
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
@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.
@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
@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
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
@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
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
@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
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
@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
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
@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
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
@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
(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
+@group
+ ;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
+ (aset keyboard-translate-table ?\034 ?\^s)
+ (aset keyboard-translate-table ?\^s ?\034)
@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-q} and @kbd{C-^}.}
+ (aset keyboard-translate-table ?\036 ?\^q)
+ (aset keyboard-translate-table ?\^q ?\036))
@end group
@end example
@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
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
(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))))))
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
@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
@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.
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
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
@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
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}).
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
@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
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
@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:
@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
@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
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
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
@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
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
@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
@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
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
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
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.
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
@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.
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
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
;; @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
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
@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
@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
@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}:
@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
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
@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.
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
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
@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
@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
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
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
@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).
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
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
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.
@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
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
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
@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
* 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
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))
@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}.
@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
@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
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.
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
@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.
@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
+
@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
@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
@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.
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
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.
@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
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
@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.
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
@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
* 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}.
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
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
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
@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
@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
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
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
@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
@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
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
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
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")
@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
@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.
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)
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.
-
- A case table is a list of this form:
-
-@example
-(@var{downcase} @var{upcase} @var{canonicalize} @var{equivalences})
-@end example
+buffer (@pxref{Case Changes}).
+
+ 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:
+
+@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}
@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
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.
@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
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
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
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
@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
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
@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
@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.
@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)
@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)
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
(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
@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
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
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
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
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).
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,
@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
@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}
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
@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.
@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
@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.
@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
@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}
@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}.
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
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
@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.
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
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
@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
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}.
@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
@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
@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.
+
+ 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.
- The low 8 bits of each element of a syntax table indicate the
-syntax class.
+ This table gives the value of @var{syntax-code} which corresponds
+to each syntactic type.
@table @asis
@item @i{Integer}
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
@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
@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
@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
@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
@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
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
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
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
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
@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})
@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.
@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
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.
;; @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)
'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
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
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
@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
@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.
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
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
@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
@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
@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
@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
@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)}
@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
@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
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
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,
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.
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
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}.
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} .
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
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
(@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
@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
@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
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}}.)
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
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
@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
@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
@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:
@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
@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
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
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}.
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:
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
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
@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
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
@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).
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
@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})
@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
@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
@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.
@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
@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
@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
@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)
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
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)
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.
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
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.
+
+ 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 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.)
+ 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
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
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.
-
- @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.
-
- To preserve your sanity, avoid that series of actions. If you use
-@code{save-excursion} around each piece of code that changes to a
+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 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 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:
@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
(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}.
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
@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
@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
@defun set-default symbol value
This function is like @code{setq-default}, except that @var{symbol} is
-evaluated.
+an ordinary evaluated argument.
@example
@group
@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
* 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
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}.
@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
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
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
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
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
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
@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
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
@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
@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}.
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})
@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
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
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.
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
projects / emacs.git / commitdiff