@cindex advising functions
The @dfn{advice} feature lets you add to the existing definition of a
-function, by @dfn{advising the function}. This a clean method for a
+function, by @dfn{advising the function}. This is a clean method for a
library to customize functions defined by other parts of Emacs---cleaner
-than redefining the function in the usual way.
+than redefining the whole function.
Each piece of advice can be enabled or disabled explicitly. The
enabled pieces of advice for any given function actually take effect
when you activate advice for that function, or when that function is
subsequently defined or redefined.
+ @strong{Usage Note:} Advice is useful for altering the behavior of
+existing calls to an existing function. If you want the new behavior
+for new calls, or for key bindings, it is cleaner to define a new
+function (or a new command) which uses the existing function.
+
@menu
-* Defining Advice::
-* Computed Advice::
-* Activation of Advice::
-* Enabling Advice::
-* Preactivation::
-* Argument Access in Advice::
-* Combined Definition::
+* Simple Advice:: A simple example to explain the basics of advice.
+* Defining Advice:: Detailed description of @code{defadvice}.
+* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice:: Advice doesn't do anything until you activate it.
+* Enabling Advice:: You can enable or disable each piece of advice.
+* Preactivation:: Preactivation is a way of speeding up the
+ loading of compiled advice.
+* Argument Access:: How advice can access the function's arguments.
+* Subr Arguments:: Accessing arguments when advising a primitive.
+* Combined Definition:: How advice is implemented.
@end menu
+@node Simple Advice
+@section A Simple Advice Example
+
+ The command @code{next-line} moves point down vertically one or more
+lines; it is the standard binding of @kbd{C-n}. When used on the last
+line of the buffer, this command inserts a newline to create a line to
+move to (if @code{next-line-add-newlines} is non-@code{nil}).
+
+ Suppose you wanted to add a similar feature to @code{previous-line},
+which would insert a new line at the beginning of the buffer for the
+command to move to. How could you do this?
+
+ You could do it by redefining the whole function, but that is not
+modular. The advice feature provides a cleaner alternative: you can
+effectively add your code to the existing function definition, without
+actually changing or even seeing that definition. Here is how to do
+this:
+
+@example
+(defadvice previous-line (before next-line-at-end (arg))
+ "Insert an empty line when moving up from the top line."
+ (if (and next-line-add-newlines (= arg 1)
+ (save-excursion (beginning-of-line) (bobp)))
+ (progn
+ (beginning-of-line)
+ (newline))))
+@end example
+
+@cindex piece of advice
+ This expression defines a @dfn{piece of advice} for the function
+@code{previous-line}. This piece of advice is named
+@code{next-line-at-end}, and the symbol @code{before} says that it is
+@dfn{before-advice} which should run before the regular definition of
+@code{previous-line}. @code{(arg)} specifies how the advice code can
+refer to the function's arguments.
+
+ When this piece of advice runs, it creates an additional line, in the
+situation where that is appropriate, but does not move point to that
+line. This is the correct way to write the advice, because the normal
+definition will run afterward and will move back to the newly inserted
+line.
+
+ Defining the advice doesn't immediately change the function
+@code{previous-line}. That happens when you @dfn{activate} the advice,
+like this:
+
+@example
+(ad-activate 'previous-line)
+@end example
+
+@noindent
+This is what actually begins to use the advice that has been defined so
+far for the function @code{previous-line}. Henceforth, whenever that
+function is run, whether invoked by the user with @kbd{C-p} or
+@kbd{M-x}, or called from Lisp, it runs the advice first, and its
+regular definition second.
+
+ This example illustrates before-advice, which is one @dfn{class} of
+advice: it runs before the function's base definition. There are two
+other advice classes: @dfn{after-advice}, which runs after the base
+definition, and @dfn{around-advice}, which lets you specify an
+expression to wrap around the invocation of the base definition.
+
@node Defining Advice
@section Defining Advice
describing the entity being advised, but this always includes macros and
special forms.
-The argument @var{name} is the name of the advice, a non-@code{nil}
-symbol. The advice name uniquely identifies one piece of advice, within all
-the pieces of advice in a particular class for a particular
-@var{function}. The name allows you to refer to the piece of
-advice---to redefine it, or to enable or disable it.
-
-Where an ordinary definition has an argument list, an advice definition
-needs several kinds of information.
-
-@var{class} specifies the class of the advice---one of @code{before},
+@cindex class of advice
+@cindex before-advice
+@cindex after-advice
+@cindex around-advice
+@var{class} specifies the @dfn{class} of the advice---one of @code{before},
@code{after}, or @code{around}. Before-advice runs before the function
itself; after-advice runs after the function itself; around-advice is
wrapped around the execution of the function itself. After-advice and
definition completely. (It also overrides lower-positioned pieces of
around-advice).
+The argument @var{name} is the name of the advice, a non-@code{nil}
+symbol. The advice name uniquely identifies one piece of advice, within all
+the pieces of advice in a particular class for a particular
+@var{function}. The name allows you to refer to the piece of
+advice---to redefine it, or to enable or disable it.
+
+In place of the argument list in an ordinary definition, an advice
+definition calls for several different pieces of information.
+
The optional @var{position} specifies where, in the current list of
advice of the specified @var{class}, this new advice should be placed.
It should be either @code{first}, @code{last} or a number that
advice.
The optional @var{arglist} can be used to define the argument list for
-the sake of advice. This argument list should of course be compatible
-with the argument list of the original function, otherwise functions
-that call the advised function with the original argument list in mind
-will break. If more than one piece of advice specifies an argument
+the sake of advice. This becomes the argument list of the combined
+definition that is generated in order to run the advice (@pxref{Combined
+Definition}). Therefore, the advice expressions can use the argument
+variables in this list to access argument values.
+
+This argument list must be compatible with the argument list of the
+original function, so that it can handle the ways the function is
+actually called. If more than one piece of advice specifies an argument
list, then the first one (the one with the smallest position) found in
-the list of all classes of advice will be used.
+the list of all classes of advice is used. Numbers outside the range
+are mapped to the beginning or the end, whichever is closer.
-@var{flags} is a list of symbols that specify further information about
-how to use this piece of advice. Here are the valid symbols and their
-meanings:
+The remaining elements, @var{flags}, is a list of symbols that specify
+further information about how to use this piece of advice. Here are the
+valid symbols and their meanings:
@table @code
@item activate
-Activate all the advice for @var{function} after making this definition.
-This is ignored when @var{function} itself is not defined yet (which is
-known as @dfn{forward advice}).
+Activate the advice for @var{function} now. Changes in a function's
+advice always take effect the next time you activate advice for the
+function; this flag says to do so, for @var{function}, immediately after
+defining this piece of advice.
+
+@cindex forward advice
+This flag has no effect if @var{function} itself is not defined yet (a
+situation known as @dfn{forward advice}), because it is impossible to
+activate an undefined function's advice. However, defining
+@var{function} will automatically activate its advice.
@item protect
Protect this piece of advice against non-local exits and errors in
-preceding code and advice.
+preceding code and advice. Protecting advice makes it a cleanup in an
+@code{unwind-protect} form, so that it will execute even if the
+previous code gets an error or uses @code{throw}. @xref{Cleanups}.
@item compile
-Says that the combined definition which implements advice should be
-byte-compiled. This flag is ignored unless @code{activate} is also
-specified.
+Compile the combined definition that is used to run the advice. This
+flag is ignored unless @code{activate} is also specified.
+@xref{Combined Definition}.
@item disable
-Disable this piece of advice, so that it will not be used
-unless subsequently explicitly enabled.
+Initially disable this piece of advice, so that it will not be used
+unless subsequently explicitly enabled. @xref{Enabling Advice}.
@item preactivate
Activate advice for @var{function} when this @code{defadvice} is
@end table
The optional @var{documentation-string} serves to document this piece of
-advice. If the @code{documentation} function gets the documentation
-for @var{function} when its advice is active, the result will combine
-the documentation strings of all the advice with that of the original
-function.
+advice. When advice is active for @var{function}, the documentation for
+@var{function} (as returned by @code{documentation}) combines the
+documentation strings of all the advice for @var{function} with the
+documentation string of its original function definition.
The optional @var{interactive-form} form can be supplied to change the
interactive behavior of the original function. If more than one piece
@end example
Here @var{protected} and @var{enabled} are flags, and @var{definition}
-is an expression that says what the advice should do.
+is the expression that says what the advice should do. If @var{enabled}
+is @code{nil}, this piece of advice is initially disabled
+(@pxref{Enabling Advice}).
If @var{function} already has one or more pieces of advice in the
specified @var{class}, then @var{position} specifies where in the list
importantly, it permits defining advice for a function before that
function is actually defined.
-When a function is first activated, its original definition is saved,
-and all enabled pieces of advice for that function are combined with the
-original definition to make a new definition. This definition is
-installed, and optionally byte-compiled as well, depending on conditions
-described below.
+When a function's advice is first activated, the function's original
+definition is saved, and all enabled pieces of advice for that function
+are combined with the original definition to make a new definition.
+(Pieces of advice that are currently disabled are not used; see
+@ref{Enabling Advice}.) This definition is installed, and optionally
+byte-compiled as well, depending on conditions described below.
In all of the commands to activate advice, if @var{compile} is @code{t},
the command also compiles the combined definition which implements the
This command activates the advice for @var{function}.
@end deffn
-To activate a function whose advice is already active is not a no-op.
-It is a useful operation which puts into effect any changes in advice
-since the previous activation of the same function.
+To activate advice for a function whose advice is already active is not
+a no-op. It is a useful operation which puts into effect any changes in
+advice since the previous activation of that function's advice.
@deffn Command ad-deactivate function
This command deactivates the advice for @var{function}.
@deffn Command ad-update-regexp regexp &optional compile
This command activates pieces of advice whose names match @var{regexp},
-but only those that are already activated.
-@end deffn
+but only those for functions whose advice is already activated.
-@deffn Command ad-stop-advice
-Turn off automatic advice activation when a function is defined or
-redefined.
+Reactivating a function's advice is useful for putting into effect all
+the changes that have been made in its advice (including enabling and
+disabling specific pieces of advice; @pxref{Enabling Advice}) since the
+last time it was activated.
@end deffn
@deffn Command ad-start-advice
+Turn on automatic advice activation when a function is defined or
+redefined. If you turn on this mode, then advice really does
+take effect immediately when defined.
+@end deffn
+
+@deffn Command ad-stop-advice
Turn off automatic advice activation when a function is defined or
redefined.
@end deffn
(ad-disable-advice 'foo 'before 'my-advice)
@end example
- This call by itself only changes the enable flag for this piece of
-advice. To make this change take effect in the advised definition, you
+This function by itself only changes the enable flag for a piece of
+advice. To make the change take effect in the advised definition, you
must activate the advice for @code{foo} again:
@example
@var{class} on @var{function}.
@end deffn
- You can also disable many pieces of advice at once using a regular
-expression.
+ You can also disable many pieces of advice at once, for various
+functions, using a regular expression. As always, the changes take real
+effect only when you next reactivate advice for the functions in
+question.
@deffn Command ad-disable-regexp regexp
This command disables all pieces of advice whose names match
@code{defadvice} is compiled, that compiles the combined definition
also.
- When the function is subsequently activated, if the enabled advice for
-the function matches what was used to make this combined
-definition. then the existing combined definition is used, and there is
-no need to construct one. Thus, preactivation never causes wrong
+ When the function's advice is subsequently activated, if the enabled
+advice for the function matches what was used to make this combined
+definition, then the existing combined definition is used, thus avoiding
+the need to construct one. Thus, preactivation never causes wrong
results---but it may fail to do any good, if the enabled advice at the
-time of activation doesn't match.
+time of activation doesn't match what was used for preactivation.
Here are some symptoms that can indicate that a preactivation did not
work properly, because of a mismatch.
There is no elegant way to find out why preactivated advice is not being
used. What you can do is to trace the function
@code{ad-cache-id-verification-code} (with the function
-@code{trace-function-background}) before the advised function is
-activated. After activation, check the value returned by
+@code{trace-function-background}) before the advised function's advice
+is activated. After activation, check the value returned by
@code{ad-cache-id-verification-code} for that function: @code{verified}
means that the preactivated advice was used, while other values give
some information about why they were considered inappropriate.
into the advice. If the definition of the original function changes,
the advice might break.
+ Another method is to specify an argument list in the advice itself.
+This avoids the need to know the original function definition's argument
+names, but it has a limitation: all the advice on any particular
+function must use the same argument list, because the argument list
+actually used for all the advice comes from the first piece of advice
+for that function.
+
A more robust method is to use macros that are translated into the
proper access forms at activation time, i.e., when constructing the
advised definition. Access macros access actual arguments by position
These argument constructs are not really implemented as Lisp macros.
Instead they are implemented specially by the advice mechanism.
-@subsection Definition of Subr Argument Lists
+@node Subr Arguments
+@section Definition of Subr Argument Lists
When the advice facility constructs the combined definition, it needs
to know the argument list of the original function. This is not always
For those users who live backwards in time, here is information about
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
+simplicity that results from the absence of many Emacs 20 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.
@item
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{*}.
+@code{defcustom}, which requires you to specify each user option's data
+type and classify options into groups, all you have to do is write a
+@code{defvar}. You should still start the documentation string with
+@samp{*}, though.
@end itemize
Here are changes in the Lisp language itself:
We have got rid of the function @code{access-file}.
@item
-Most of the minibuffer input functions, no longer take a default value as
+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.
non-numbered backup file for file @var{filename}. On Unix, this is just
@var{filename} with a tilde appended.
-The standard definition of this function is as follows:
+The standard definition of this function, on most operating systems, is
+as follows:
@smallexample
@group
@smallexample
@group
(defun make-backup-file-name (filename)
- (concat "." filename "~"))
+ (expand-file-name
+ (concat "." (file-name-nondirectory filename) "~")
+ (file-name-directory filename)))
@end group
@group
@result{} ".backups.texi~"
@end group
@end smallexample
+
+Some parts of Emacs, including some Dired commands, assume that backup
+file names end with @samp{~}. If you do not follow that convention, it
+will not cause serious problems, but these commands may give
+less-than-desirable results.
@end defun
@defun find-backup-file-name filename
Buffers in Emacs editing are objects that have distinct names and hold
text that can be edited. Buffers appear to Lisp programs as a special
-data type. You can think of the contents of a buffer as an extendable
-string; insertions and deletions may occur in any part of the buffer.
-@xref{Text}.
+data type. You can think of the contents of a buffer as a string that
+you can extend; insertions and deletions may occur in any part of the
+buffer. @xref{Text}.
A Lisp buffer object contains numerous pieces of information. Some of
this information is directly accessible to the programmer through
course, that is the subroutine's purpose). Therefore, you should
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
+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):
existing buffer.
@end defun
+@defspec save-current-buffer body...
@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 that buffer
as current. The return value is the value of the last form in
remains current.
@end defmac
-@tindex with-current-buffer
@defmac with-current-buffer buffer body...
+@tindex with-current-buffer
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
abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}).
@end defmac
-@tindex with-temp-buffer
@defmac with-temp-buffer body...
+@tindex with-temp-buffer
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,
@item F
A file name. The file need not exist. Completion, Default, Prompt.
+@item i
+An irrelevant argument. This code always supplies @code{nil} as
+the argument's value. No I/O.
+
@item k
A key sequence (@pxref{Keymap Terminology}). This keeps reading events
until a command (or undefined command) is found in the current key
@cindex evaluated expression argument
A Lisp form is read as with @kbd{x}, but then evaluated so that its
value becomes the argument for the command. Prompt.
+
+@item z
+A coding system name (a symbol). If the user enters null input, the
+argument value is @code{nil}. @xref{Coding Systems}. Completion,
+Existing, Prompt.
+
+@item Z
+A coding system name (a symbol)---but only if this command has a prefix
+argument. With no prefix argument, @samp{Z} provides @code{nil} as the
+argument value. Completion, Existing, Prompt.
@end table
@node Interactive Examples
describes the representation and meaning of input events in detail.
@defun eventp object
-This function returns non-@code{nil} if @var{object} is an input event.
-A symbol
+This function returns non-@code{nil} if @var{object} is an input event
+or event type.
+
+Note that any symbol might be used as an event or an event type.
+@code{eventp} cannot distinguish whether a symbol is intended by Lisp
+code to be used as an event. Instead, it distinguishes whether the
+symbol has actually been used in an event that has been read as input in
+the current Emacs session. If a symbol has not yet been so used,
+@code{eventp} returns @code{nil}.
@end defun
@menu
This kind of event indicates that the user deiconified @var{frame} using
the window manager. Its standard definition is @code{ignore}; since the
frame has already been made visible, Emacs has no work to do.
+
+@cindex @code{mouse-wheel} event
+@item (mouse-wheel @var{position} @var{delta})
+This kind of event is generated by moving a wheel on a mouse (such as
+the MS Intellimouse). Its effect is typically a kind of scroll or zoom.
+
+The element @var{delta} describes the amount and direction of the wheel
+rotation. Its absolute value is the number of increments by which the
+wheel was rotated. A negative @var{delta} indicates that the wheel was
+rotated backwards, towards the user, and a positive @var{delta}
+indicates that the wheel was rotated forward, away from the user.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event.
+
+This kind of event is generated only on some kinds of systems.
+
+@cindex @code{drag-n-drop} event
+@item (drag-n-drop @var{position} @var{files})
+This kind of event is generated when a group of files is
+selected in an application outside of Emacs, and then dragged and
+dropped onto an Emacs frame.
+
+The element @var{position} is a list describing the position of the
+event, in the same format as used in a mouse-click event, and
+@var{files} is the list of file names that were dragged and dropped.
+The usual way to handle this event is by visiting these files.
+
+This kind of event is generated, at present, only on some kinds of
+systems.
@end table
If one of these events arrives in the middle of a key sequence---that
@itemize @bullet
@item
Use vectors instead of strings for key sequences, when you plan to use
-them for anything other than as arguments @code{lookup-key} and
+them for anything other than as arguments to @code{lookup-key} and
@code{define-key}. For example, you can use
@code{read-key-sequence-vector} instead of @code{read-key-sequence}, and
@code{this-command-keys-vector} instead of @code{this-command-keys}.
and key sequences read from keyboard macros being executed.
@end defvar
-@tindex num-nonmacro-input-events
@defvar num-nonmacro-input-events
+@tindex 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
moves the cursor temporarily to the echo area, to the end of any message
displayed there. Otherwise @code{read-event} does not move the cursor.
+If @code{read-event} gets an event is defined as a help character, in
+some cases @code{read-event} processes the event directly without
+returning. @xref{Help Functions}. Certain other events, called
+@dfn{special events}, are also processed directly within
+@code{read-event} (@pxref{Special Events}).
+
Here is what happens if you call @code{read-event} and then press the
right-arrow function key:
@defvar command-history
This variable's value is a list of recent complex commands, each
represented as a form to evaluate. It continues to accumulate all
-complex commands for the duration of the editing session, but all but
-the first (most recent) thirty elements are deleted when a garbage
-collection takes place (@pxref{Garbage Collection}).
+complex commands for the duration of the editing session, but when it
+reaches the maximum size (specified by the variable
+@code{history-length}), the oldest elements are deleted as new ones are
+added.
@example
@group
@c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/compile
-@node Byte Compilation, Advising, Loading, Top
+@node Byte Compilation, Advising Functions, Loading, Top
@chapter Byte Compilation
@cindex byte-code
@cindex compilation
transportable from machine to machine without recompilation. It is not,
however, as fast as true compiled code.
+ Compiling a Lisp file with the Emacs byte compiler always reads the
+file as multibyte text, even if Emacs was started with @samp{--unibyte},
+unless the file specifies otherwise. This is so that compilation gives
+results compatible with running the same file without compilation.
+@xref{Loading Non-ASCII}.
+
In general, any version of Emacs can run byte-compiled code produced
by recent earlier versions of Emacs, but the reverse is not true. A
major incompatible change was introduced in Emacs version 19.29, and
@end deffn
@deffn Command byte-compile-file filename
-This function compiles a file of Lisp code named @var{filename} into
-a file of byte-code. The output file's name is made by appending
-@samp{c} to the end of @var{filename}.
+This function compiles a file of Lisp code named @var{filename} into a
+file of byte-code. The output file's name is made by changing the
+@samp{.el} suffix into @samp{.elc}; if @var{filename} does not end in
+@samp{.el}, it adds @samp{.elc} to the end of @var{filename}.
Compilation works by reading the input file one form at a time. If it
is a definition of a function or macro, the compiled function or macro
@end example
@end defspec
-@tindex when
@defmac when condition then-forms@dots{}
+@tindex when
This is a variant of @code{if} where there are no @var{else-forms},
and possibly several @var{then-forms}. In particular,
@end example
@end defmac
-@tindex condition
@defmac unless condition forms@dots{}
+@tindex condition
This is a variant of @code{if} where there is no @var{then-form}:
@example
@defspec catch tag body@dots{}
@cindex tag on run time stack
-@code{catch} establishes a return point for the @code{throw} function. The
-return point is distinguished from other such return points by @var{tag},
-which may be any Lisp object. The argument @var{tag} is evaluated normally
-before the return point is established.
+@code{catch} establishes a return point for the @code{throw} function.
+The return point is distinguished from other such return points by
+@var{tag}, which may be any Lisp object except @code{nil}. The argument
+@var{tag} is evaluated normally before the return point is established.
With the return point in effect, @code{catch} evaluates the forms of the
@var{body} in textual order. If the forms execute normally, without
display one name.
@table @code
+@item :tag @var{name}
+Use @var{name}, a string, instead of the item's name, to label the item
+in customization menus and buffers.
+
@item :group @var{group}
Put this customization item in group @var{group}. When you use
@code{:group} in a @code{defgroup}, it makes the new group a subgroup of
There are three alternatives you can use for @var{link-data}:
@table @code
-@item :tag @var{name}
-Use @var{name}, a string, instead of the item's name, to label the item
-in customization menus and buffers.
-
@item (custom-manual @var{info-node})
Link to an Info node; @var{info-node} is a string which specifies the
node name, as in @code{"(emacs)Top"}. The link appears as
The way to declare new customization groups is with @code{defgroup}.
-@tindex defgroup
@defmac defgroup group members doc [keyword value]...
+@tindex defgroup
Declare @var{group} as a customization group containing @var{members}.
Do not quote the symbol @var{group}. The argument @var{doc} specifies
the documentation string for the group.
-The arguments @var{members} can be an alist whose elements specify
-customization items to be members of the group; however, normally
+The argument @var{members} is a list specifying an initial set of
+customization items to be members of the group. However, most often
@var{members} is @code{nil}, and you specify the group's members by
using the @code{:group} keyword when defining those members.
-@ignore
-@code{(@var{name} @var{widget})}. Here @var{name} is a symbol, and
-@var{widget} is a widget for editing that symbol. Useful widgets are
-@code{custom-variable} for editing variables, @code{custom-face} for
-editing faces, and @code{custom-group} for editing groups.
-@end ignore
+If you want to specify group members through @var{members}, each element
+should have the form @code{(@var{name} @var{widget})}. Here @var{name}
+is a symbol, and @var{widget} is a widget type for editing that symbol.
+Useful widgets are @code{custom-variable} for a variable,
+@code{custom-face} for a face, and @code{custom-group} for a group.
In addition to the common keywords (@pxref{Common Keywords}), you can
use this keyword in @code{defgroup}:
Use @code{defcustom} to declare user-editable variables.
-@tindex defcustom
@defmac defcustom option default doc [keyword value]...
+@tindex defcustom
Declare @var{option} as a customizable user option variable. Do not
quote @var{option}. The argument @var{doc} specifies the documentation
string for the variable.
If @var{option} is void, @code{defcustom} initializes it to
@var{default}. @var{default} should be an expression to compute the
-value; be careful in writing it, because it can be be evaluated on more
+value; be careful in writing it, because it can be evaluated on more
than one occasion.
-The following additional keywords are defined:
+The following additional keywords are accepted:
@table @code
@item :type @var{type}
these functions, but they are offered as convenient alternatives.
@item :version @var{version}
-This option specifies that the variable's default value was changed in
-Emacs version @var{version}. For example,
+This option specifies that the variable was first introduced, or its
+default value was changed, in Emacs version @var{version}. The value
+@var{version} must be a string. For example,
@example
(defcustom foo-max 34
(defcustom show-paren-mode nil
"Toggle Show Paren mode@enddots{}"
:set (lambda (symbol value)
- (show-paren-mode (or value 0)))
+ (show-paren-mode (or value 0)))
:initialize 'custom-initialize-default
:type 'boolean
:group 'paren-showing
The value must be a directory name, and you can do completion with
@kbd{M-@key{TAB}}.
+@item hook
+The value must be a list of functions (or a single function, but that is
+obsolete usage). This customization type is used for hook variables.
+You can use the @code{:option} in the @code{defcustom} for a hook
+variable to specify functions recommended for use in the hook;
+see @ref{Variable Definitions}.
+
@item symbol
The value must be a symbol. It appears in the customization buffer as
the name of the symbol.
The value must be a variable name, and you can do completion with
@kbd{M-@key{TAB}}.
+@item face
+The value must be a symbol which is a face name, and you can do
+completion with @kbd{M-@key{TAB}}.
+
@item boolean
The value is boolean---either @code{nil} or @code{t}. Note that by
using @code{choice} and @code{const} together (see the next section),
@table @code
@item (restricted-sexp :match-alternatives @var{criteria})
The value may be any Lisp object that satisfies one of @var{criteria}.
-@var{criteria} should be a list, and each elements should be
+@var{criteria} should be a list, and each element should be
one of these possibilities:
@itemize @bullet
@item
-A predicate---that is, a function of one argument that returns non-@code{nil}
-if the argument fits a certain type. This means that objects of that type
-are acceptable.
+A predicate---that is, a function of one argument that has no side
+effects, and returns either @code{nil} or non-@code{nil} according to
+the argument. Using a predicate in the list says that objects for which
+the predicate returns non-@code{nil} are acceptable.
@item
-A quoted constant---that is, @code{'@var{object}}. This means that
-@var{object} itself is an acceptable value.
+A quoted constant---that is, @code{'@var{object}}. This sort of element
+in the list says that @var{object} itself is an acceptable value.
@end itemize
For example,
@example
-(restricted-sexp :match-alternatives (integerp 't 'nil))
+(restricted-sexp :match-alternatives
+ (integerp 't 'nil))
@end example
@noindent
@item (cons @var{car-type} @var{cdr-type})
The value must be a cons cell, its @sc{car} must fit @var{car-type}, and
-its @sc{cdr} must fit @var{cdr-type}. For example, @code{(const string
+its @sc{cdr} must fit @var{cdr-type}. For example, @code{(cons string
symbol)} is a customization type which matches values such as
@code{("foo" . foo)}.
three elements; the first element must be an integer, the second a
string, and the third a function.
-In the customization buffer, the each element is displayed and edited
+In the customization buffer, each element is displayed and edited
separately, according to the type specified for it.
@item (vector @var{element-types}@dots{})
an integer stands for a number of spaces, while a string is text to use
verbatim, you might write the customization type this way,
-@smallexample
+@example
(choice (integer :tag "Number of spaces")
(string :tag "Literal text"))
-@end smallexample
+@end example
@noindent
so that the menu offers @samp{Number of spaces} and @samp{Literal Text}.
@code{:tag} is often used with @code{const}, inside of @code{choice}.
For example,
-@smallexample
+@example
(choice (const :tag "Yes" t)
(const :tag "No" nil)
(const :tag "Ask" foo))
-@end smallexample
+@end example
@item (function-item @var{function})
Like @code{const}, but used for values which are functions. This
@end enumerate
@item :parent
-The parent of a nested widget (e.g. a @code{menu-choice} item or an
+The parent of a nested widget (e.g., a @code{menu-choice} item or an
element of a @code{editable-list} widget).
@item :sibling-args
@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, Advising, Top
+@node Debugging, Read and Print, Advising Functions, Top
@chapter Debugging Lisp Programs
There are three ways to investigate a problem in an Emacs Lisp program,
@itemize @bullet
@item
If the problem occurs when you run the program, you can use a Lisp
-debugger (either the default debugger or Edebug) to investigate what is
-happening during execution.
+debugger to investigate what is happening during execution. In addition
+to the ordinary debugger, Emacs comes with a source level debugger,
+Edebug. This chapter describes both of them.
@item
If the problem is syntactic, so that Lisp cannot even read the program,
@menu
* Debugger:: How the Emacs Lisp debugger is implemented.
+* Edebug:: A source-level Emacs Lisp debugger.
* Syntax Errors:: How to find syntax errors.
* Compilation Errors:: How to find errors that show up in byte compilation.
-* Edebug:: A source-level Emacs Lisp debugger.
@end menu
Another useful debugging tool is the dribble file. When a dribble
@cindex Lisp debugger
@cindex break
- The @dfn{Lisp debugger} provides the ability to suspend evaluation of
-a form. While evaluation is suspended (a state that is commonly known
-as a @dfn{break}), you may examine the run time stack, examine the
-values of local or global variables, or change those values. Since a
-break is a recursive edit, all the usual editing facilities of Emacs are
-available; you can even run programs that will enter the debugger
-recursively. @xref{Recursive Editing}.
+ The ordinary @dfn{Lisp debugger} provides the ability to suspend
+evaluation of a form. While evaluation is suspended (a state that is
+commonly known as a @dfn{break}), you may examine the run time stack,
+examine the values of local or global variables, or change those values.
+Since a break is a recursive edit, all the usual editing facilities of
+Emacs are available; you can even run programs that will enter the
+debugger recursively. @xref{Recursive Editing}.
@menu
* Error Debugging:: Entering the debugger when an error happens.
error.
However, entry to the debugger is not a normal consequence of an
-error. Many commands frequently get Lisp errors when invoked in
-inappropriate contexts (such as @kbd{C-f} at the end of the buffer) and
-during ordinary editing it would be very unpleasant to enter the
-debugger each time this happens. If you want errors to enter the
-debugger, set the variable @code{debug-on-error} to non-@code{nil}.
+error. Many commands frequently cause Lisp errors when invoked
+inappropriately (such as @kbd{C-f} at the end of the buffer), and during
+ordinary editing it would be very inconvenient to enter the debugger
+each time this happens. So if you want errors to enter the debugger, set
+the variable @code{debug-on-error} to non-@code{nil}. (The command
+@code{toggle-debug-on-error} provides an easy way to do this.)
@defopt debug-on-error
This variable determines whether the debugger is called when an error is
signaled and not handled. If @code{debug-on-error} is @code{t}, all
-errors call the debugger. If it is @code{nil}, none call the debugger.
+kinds of errors call the debugger (except those listed in
+@code{debug-ignored-errors}). If it is @code{nil}, none call the
+debugger.
The value can also be a list of error conditions that should call the
debugger. For example, if you set it to the list
@code{(void-variable)}, then only errors about a variable that has no
value invoke the debugger.
-When this variable is non-@code{nil}, Emacs does not catch errors that
-happen in process filter functions and sentinels. Therefore, these
-errors also can invoke the debugger. @xref{Processes}.
+When this variable is non-@code{nil}, Emacs does not create an error
+handler around process filter functions and sentinels. Therefore,
+errors in these functions also invoke the debugger. @xref{Processes}.
@end defopt
@defopt debug-ignored-errors
words, @code{condition-case} gets a chance to handle 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
+If you set @code{debug-on-signal} to a non-@code{nil} value, then the
+debugger gets the first chance at every error; an error will invoke the
+debugger regardless of any @code{condition-case}, if it fits the
+criterion specified by the values of @code{debug-on-error} and
@code{debug-ignored-errors}.
@strong{Warning:} This variable is strong medicine! Various parts of
@end defopt
To debug an error that happens during loading of the @file{.emacs}
-file, use the option @samp{-debug-init}, which binds
-@code{debug-on-error} to @code{t} while @file{.emacs} is loaded and
-inhibits use of @code{condition-case} to catch init-file errors.
+file, use the option @samp{--debug-init}, which binds
+@code{debug-on-error} to @code{t} while @file{.emacs} is loaded, and
+bypasses the @code{condition-case} which normally catches errors in the
+init-file.
If your @file{.emacs} file sets @code{debug-on-error}, the effect may
not last past the end of loading @file{.emacs}. (This is an undesirable
-byproduct of the code that implements the @samp{-debug-init} command
+byproduct of the code that implements the @samp{--debug-init} command
line option.) The best way to make @file{.emacs} set
@code{debug-on-error} permanently is with @code{after-init-hook}, like
this:
You can cause the debugger to be called at a certain point in your
program by writing the expression @code{(debug)} at that point. To do
this, visit the source file, insert the text @samp{(debug)} at the
-proper place, and type @kbd{C-M-x}. Be sure to undo this insertion
-before you save the file!
+proper place, and type @kbd{C-M-x}. @strong{Warning:} if you do this
+for temporary debugging purposes, be sure to undo this insertion before
+you save the file!
The place where you insert @samp{(debug)} must be a place where an
additional form can be evaluated and its value ignored. (If the value
@item c
Exit the debugger and continue execution. When continuing is possible,
it resumes execution of the program as if the debugger had never been
-entered (aside from the effect of any variables or data structures you
-may have changed while inside the debugger).
+entered (aside from any side-effects that you caused by changing
+variable values or data structures while inside the debugger).
Continuing is possible after entry to the debugger due to function entry
or exit, explicit invocation, or quitting. You cannot continue if the
Read a Lisp expression in the minibuffer, evaluate it, and print the
value in the echo area. The debugger alters certain important
variables, and the current buffer, as part of its operation; @kbd{e}
-temporarily restores their outside-the-debugger values so you can
-examine them. This makes the debugger more transparent. By contrast,
-@kbd{M-:} does nothing special in the debugger; it shows you the
-variable values within the debugger.
+temporarily restores their values from outside the debugger, so you can
+examine and change them. This makes the debugger more transparent. By
+contrast, @kbd{M-:} does nothing special in the debugger; it shows you
+the variable values within the debugger.
@item R
Like @kbd{e}, but also save the result of evaluation in the
@node Invoking the Debugger
@subsection Invoking the Debugger
- Here we describe fully the function used to invoke the debugger.
+ Here we describe in full detail the function @code{debug} that is used
+to invoke the debugger.
@defun debug &rest debugger-args
This function enters the debugger. It switches buffers to a buffer
whatever called @code{debug}. This is the only way the function
@code{debug} can return to its caller.
-If the first of the @var{debugger-args} passed to @code{debug} is
-@code{nil} (or if it is not one of the special values in the table
-below), then @code{debug} displays the rest of its arguments at the
-top of the @samp{*Backtrace*} buffer. This mechanism is used to display
-a message to the user.
-
-However, if the first argument passed to @code{debug} is one of the
-following special values, then it has special significance. Normally,
-these values are passed to @code{debug} only by the internals of Emacs
-and the debugger, and not by programmers calling @code{debug}.
+The use of the @var{debugger-args} is that @code{debug} displays the
+rest of its arguments at the top of the @samp{*Backtrace*} buffer, so
+that the user can see them. Except as described below, this is the
+@emph{only} way these arguments are used.
-The special values are:
+However, certain values for first argument to @code{debug} have a
+special significance. (Normally, these values are used only by the
+internals of Emacs, and not by programmers calling @code{debug}.) Here
+is a table of these special values:
@table @code
@item lambda
@code{nil}.
@end defun
+@include edebug.texi
+
@node Syntax Errors
@section Debugging Invalid Lisp Syntax
not, there is a problem in that defun.
However, unmatched parentheses are the most common syntax errors in
-Lisp, and we can give further advice for those cases.
+Lisp, and we can give further advice for those cases. (In addition,
+just moving point through the code with Show Paren mode enabled might
+find the mismatch.)
@menu
* Excess Open:: How to find a spurious open paren or missing close.
successfully, then point is located at the end of the form. In this
case, this technique can't localize the error precisely, but can still
show you which function to check.
-
-@include edebug.texi
@code{truncate-lines} says what to do with them.
@end defopt
+ When horizontal scrolling (@pxref{Horizontal Scrolling}) is in use in
+a window, that forces truncation.
+
You can override the glyphs that indicate continuation or truncation
using the display table; see @ref{Display Tables}.
@end example
@end defun
-@tindex current-message
@defun current-message
+@tindex current-message
This function returns the message currently being displayed in the
echo area, or @code{nil} if there is none.
@end defun
for brief periods of time.
@end defvar
-@tindex echo-area-clear-hook
@defvar echo-area-clear-hook
+@tindex 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
characters echo. Its value must be an integer, which specifies the
number of seconds to wait before echoing. If the user types a prefix
key (such as @kbd{C-x}) and then delays this many seconds before
-continuing, the prefix key is echoed in the echo area. Any subsequent
-characters in the same command will be echoed as well.
+continuing, the prefix key is echoed in the echo area. (Once echoing
+begins in a key sequence, all subsequent characters in the same key
+sequence are echoed immediately.)
If the value is zero, then command input is not echoed.
@end defvar
@cindex invisible text
You can make characters @dfn{invisible}, so that they do not appear on
the screen, with the @code{invisible} property. This can be either a
-text property or a property of an overlay.
+text property (@pxref{Text Properties}) or a property of an overlay
+(@pxref{Overlays}).
In the simplest case, any non-@code{nil} @code{invisible} property makes
a character invisible. This is the default case---if you don't alter
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
+@tindex add-to-invisibility-spec
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
+@tindex remove-from-invisibility-spec
Remove the element @var{element} from @code{buffer-invisibility-spec}.
@end defun
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.
+the second is @code{t} to make the overlay visible, or @code{nil} to
+make it invisible again.
@node Selective Display
@section Selective Display
If this variable is non-@code{nil}, @code{with-output-to-temp-buffer}
calls it as a function to do the job of displaying a help buffer. The
function gets one argument, which is the buffer it should display.
+
+It is a good idea for this function to run @code{temp-buffer-show-hook}
+just as @code{with-output-to-temp-buffer} normally would, inside of
+@code{save-window-excursion} and with the chosen window and buffer
+selected.
+@end defvar
+
+@defvar temp-buffer-show-hook
+This normal hook is run by @code{with-output-to-temp-buffer} after
+displaying the help buffer. When the hook runs, the help buffer is
+current, and the window it was displayed in is selected.
@end defvar
@defun momentary-string-display string position &optional char message
@node Overlay Properties
@subsection Overlay Properties
-Overlay properties are like text properties in some respects, but the
-differences are more important than the similarities. Text properties
-are considered a part of the text; overlays are specifically considered
-not to be part of the text. Thus, copying text between various buffers
-and strings preserves text properties, but does not try to preserve
-overlays. Changing a buffer's text properties marks the buffer as
-modified, while moving an overlay or changing its properties does not.
-Unlike text property changes, overlay changes are not recorded in the
-buffer's undo list.
+Overlay properties are like text properties in that the properties that
+alter how a character is displayed can come from either source. But in
+most respects they are different. Text properties are considered a part
+of the text; overlays are specifically considered not to be part of the
+text. Thus, copying text between various buffers and strings preserves
+text properties, but does not try to preserve overlays. Changing a
+buffer's text properties marks the buffer as modified, while moving an
+overlay or changing its properties does not. Unlike text property
+changes, overlay changes are not recorded in the buffer's undo list.
+@xref{Text Properties}, for comparison.
@table @code
@item priority
@code{intangible} text property. @xref{Special Properties}, for details.
@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
+This property tells incremental search how to make an invisible overlay
+visible, permanently, if the final match overlaps it. @xref{Invisible
Text}.
+@item isearch-open-invisible-temporary
+This property tells incremental search how to make an invisible overlay
+visible, temporarily, during the search. @xref{Invisible Text}.
+
@item before-string
@kindex before-string @r{(overlay property)}
This property's value is a string to add to the display at the beginning
@defun delete-overlay overlay
This function deletes @var{overlay}. The overlay continues to exist as
-a Lisp object, but ceases to be part of the buffer it belonged to, and
-ceases to have any effect on display.
+a Lisp object, but ceases to be attached to the buffer it belonged to,
+and ceases to have any effect on display.
+
+A deleted overlay is not permanently useless. You can give it
+a new buffer position by calling @code{move-overlay}.
@end defun
@defun move-overlay overlay start end &optional buffer
@var{pos}, and ends after @var{pos}.
@end defun
-@tindex overlays-in
@defun overlays-in beg end
+@tindex overlays-in
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
check the width of a character. @xref{Primitive Indent}, and
@ref{Screen Lines}, for related functions.
-@tindex char-width
@defun char-width char
+@tindex char-width
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
+@tindex string-width
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
+@tindex truncate-string-to-width
This function returns the part of @var{string} that fits within
@var{width} columns, as a new string.
@end table
@node Defining Faces
-@section Defining Faces
+@subsection Defining Faces
The way to define a new face is with @code{defface}. This creates a
kind of customization item (@pxref{Customization}) which the user can
customize using the Customization buffer (@pxref{Easy Customization,,,
emacs, The GNU Emacs Manual}).
-@tindex defface
@defmac defface face spec doc [keyword value]...
+@tindex defface
Declare @var{face} as a customizable face that defaults according to
@var{spec}. Do not quote the symbol @var{face}. The argument @var{doc}
specifies the face documentation.
When @code{defface} executes, it defines the face according to
-@var{spec}, then uses any customizations saved in the @file{.emacs} file
-to override that specification.
+@var{spec}, then uses any customizations that were read from the
+@file{.emacs} file to override that specification.
The purpose of @var{spec} is to specify how the face should appear on
different kinds of terminals. It should be an alist whose elements have
subsequent elements of @var{spec} are never used. Normally
@code{t} is used in the last (or only) element of @var{spec}.
-@item an list
+@item a list
If @var{display} is alist, each elements should have the form
@code{(@var{characteristic} @var{value}@dots{})}. Here
@var{characteristic} specifies a way of classifying frames, and the
@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. 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.
+should be a string, either a valid font name for your system or the name
+of an Emacs fontset (@pxref{Fontsets}). 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
-@tindex set-face-bold-p
@defun set-face-bold-p face bold-p &optional frame
+@tindex set-face-bold-p
This function sets the bold attribute of face @var{face}.
Non-@code{nil} means bold; @code{nil} means non-bold.
@end defun
-@tindex set-face-italic-p
@defun set-face-italic-p face italic-p &optional frame
+@tindex set-face-italic-p
This function sets the italic attribute of face @var{face}.
Non-@code{nil} means italic; @code{nil} means non-italic.
@end defun
This function returns the name of the font of face @var{face}.
@end defun
-@tindex face-bold-p
@defun face-bold-p face &optional frame
+@tindex face-bold-p
This function returns the bold attribute of face @var{face}.
@end defun
-@tindex face-italic-p
@defun face-italic-p face &optional frame
+@tindex face-italic-p
This function returns the italic attribute of face @var{face}.
@end defun
This function returns the face number of face @var{face}.
@end defun
-@tindex face-documentation
@defun face-documentation face
+@tindex face-documentation
This function returns the documentation string of face @var{face}, or
@code{nil} if none was specified for it.
@end defun
@item
Character codes 128 through 255 map to sequences of four glyphs, where
the first glyph is the @sc{ASCII} code for @samp{\}, and the others are
-digit characters representing the charatcer code in octal. (A display
+digit characters representing the character code in octal. (A display
table can specify a glyph to use instead of @samp{\}.)
@item
@node Display Table Format
@subsection Display Table Format
- A display table is actually char-table with subtype @code{display-table}.
+ A display table is actually a char-table (@pxref{Char-Tables}) with
+@code{display-table} as its subtype.
@defun make-display-table
This creates and returns a display table. The table initially has
(aset disptab 127 (vector ?^ ??)))
@end example
-@tindex display-table-slot
@defun display-table-slot display-table slot
+@tindex 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{selective-display}, and @code{vertical-border}.
@end defun
-@tindex set-display-table-slot
@defun set-display-table-slot display-table slot value
+@tindex set-display-table-slot
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
careful not to use just beeping when signaling an error is more
appropriate. (@xref{Errors}.)
-@defun ding &optional dont-terminate
+@defun ding &optional do-not-terminate
@cindex keyboard macro termination
This function beeps, or flashes the screen (see @code{visible-bell} below).
It also terminates any keyboard macro currently executing unless
-@var{dont-terminate} is non-@code{nil}.
+@var{do-not-terminate} is non-@code{nil}.
@end defun
-@defun beep &optional dont-terminate
+@defun beep &optional do-not-terminate
This is a synonym for @code{ding}.
@end defun
capability (@samp{vb}).
@end defvar
-@tindex ring-bell-function
@defvar ring-bell-function
+@tindex 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.
+bell.'' Its value should be a function of no arguments.
@end defvar
@node Window Systems
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
+any), and the terminal-specific Lisp code, and running the hook
@code{term-setup-hook}.
This hook is used for internal purposes: setting up communication with
Edebug.
@item
-Automatically reevaluate a list of expressions and
+Automatically re-evaluate a list of expressions and
display their results each time Edebug updates the display.
@item
@cindex Common Lisp (Edebug)
@pindex cl.el @r{(Edebug)}
@pindex cl-specs.el
- Edebug knows how to instrument all the standard special forms, an
-interactive form with an expression argument, anonymous lambda
+ Edebug knows how to instrument all the standard special forms,
+@code{interactive} forms with an expression argument, anonymous lambda
expressions, and other defining forms. Edebug cannot know what a
user-defined macro will do with the arguments of a macro call, so you
-must tell it; @xref{Instrumenting Macro Calls}, for details.
+must tell it; see @ref{Instrumenting Macro Calls}, for details.
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
using, but actually load them only if you use Edebug.
@findex eval-expression @r{(Edebug)}
- To remove instrumentation from a definition, simply reevaluate its
+ To remove instrumentation from a definition, simply re-evaluate its
definition in a way that does not instrument. There are two ways of
evaluating forms that never instrument them: from a file with
@code{load}, and from the minibuffer with @code{eval-expression}
@end table
The @kbd{h} command proceeds to the stop point near the current location
-if point, using a temporary breakpoint. See @ref{Breakpoints}, for more
-about breakpoints.
+of point, using a temporary breakpoint. See @ref{Breakpoints}, for more
+information about breakpoints.
The @kbd{f} command runs the program forward over one expression. More
precisely, it sets a temporary breakpoint at the position that
then type @kbd{b} or @kbd{u} to set or unset a breakpoint there.
Unsetting a breakpoint where none has been set has no effect.
-Reevaluating or reinstrumenting a definition forgets all its breakpoints.
+Re-evaluating or reinstrumenting a definition forgets all its breakpoints.
A @dfn{conditional breakpoint} tests a condition each time the program
gets there. Any errors that occur as a result of evaluating the
@subsection Edebug Views
These Edebug commands let you view aspects of the buffer and window
-status that obtained before entry to Edebug. The outside window
+status as they were before entry to Edebug. The outside window
configuration is the collection of windows and contents that were in
effect outside of Edebug.
buffer with @kbd{C-c C-w}. The @samp{*edebug*} buffer is killed when
you continue execution, and recreated next time it is needed.
-
@node Printing in Edebug
@subsection Printing in Edebug
@defopt edebug-print-length
If non-@code{nil}, bind @code{print-length} to this while printing
results in Edebug. The default value is @code{50}.
-@xref{Printing in Edebug}.
@end defopt
@defopt edebug-print-level
@example
(setq a '(x y))
-(setcar a a))
+(setcar a a)
@end example
@noindent
Custom printing prints this as @samp{Result: #1=(#1# y)}. The
@samp{#1=} notation labels the structure that follows it with the label
-@samp{1}, and the @samp{#1#} notation references the previously labelled
+@samp{1}, and the @samp{#1#} notation references the previously labeled
structure. This notation is used for any shared elements of lists or
vectors.
@cindex frequency counts
@cindex performance analysis
Edebug provides rudimentary coverage testing and display of execution
-frequency. All execution of an instrumented function accumulates
-frequency counts, both before and after evaluation of each instrumented
-expression, even if the execution mode is Go-nonstop. Coverage testing
-is more expensive, so it is done only if @code{edebug-test-coverage} is
-non-@code{nil}. The command @kbd{M-x edebug-display-freq-count}
-displays both the frequency data and the coverage data (if recorded).
+frequency. Coverage testing works by comparing the result of each
+expression with the previous result; coverage is considered OK if two
+different results are found. Thus, to sufficiently test the coverage of
+your code, try to execute it under conditions that evaluate all
+expressions more than once, and produce different results for each
+expression. Coverage testing makes execution slower, so it is only done
+if @code{edebug-test-coverage} is non-@code{nil}. Whether or not
+coverage testing is enabled, frequency counting is performed for all
+execution of an instrumented function, even if the execution mode is
+Go-nonstop.
+
+Use @kbd{M-x edebug-display-freq-count} to display both the
+coverage information and the frequency counts for a definition.
@deffn Command edebug-display-freq-count
This command displays the frequency count data for each line of the
The frequency counts appear as comment lines after each line of code,
and you can undo all insertions with one @code{undo} command. The
counts appear under the @samp{(} before an expression or the @samp{)}
-after an expression, or on the last character of a symbol. Values do
-not appear if they are equal to the previous count on the same line.
+after an expression, or on the last character of a variable. To
+simplify the display, a count is not shown if it is equal to the
+count of an earlier expression on the same line.
The character @samp{=} following the count for an expression says that
-the expression has returned the same value each time it was evaluated
+the expression has returned the same value each time it was evaluated.
This is the only coverage information that Edebug records.
To clear the frequency count and coverage data for a definition,
-reinstrument it.
+simply reinstrument it with @code{eval-defun}.
@end deffn
For example, after evaluating @code{(fac 5)} with a source
@itemize @bullet
@item
@code{max-lisp-eval-depth} and @code{max-specpdl-size} are both
-incremented one time to reduce Edebug's impact on the stack.
-You could, however, still run out of stack space when using Edebug.
+incremented once to reduce Edebug's impact on the stack. You could,
+however, still run out of stack space when using Edebug.
@item
The state of keyboard macro execution is saved and restored. While
@end deffn
Here is a simple example that defines the specification for the
-@code{for} macro described in the Emacs Lisp Reference Manual, followed
-by an alternative, equivalent specification.
+@code{for} example macro (@code{Argument Evaluation}), followed by an
+alternative, equivalent specification.
@example
(def-edebug-spec for
@item a symbol
The symbol must have an Edebug specification which is used instead.
This indirection is repeated until another kind of specification is
-found. This allows you to inherit the specification for another macro.
+found. This allows you to inherit the specification from another macro.
@item a list
The elements of the list describe the types of the arguments of a
@table @code
@item sexp
-A single Lisp object, not unevaluated.
-@c "unevaluated expression" is not meaningful, because
-@c an expression is a Lisp object intended for evaluation.
+A single unevaluated expression, which is not instrumented.
+@c an "expression" is not necessarily intended for evaluation.
@item form
A single evaluated expression, which is instrumented.
@item &define
@kindex &define @r{(Edebug)}
Indicates that the specification is for a defining form. The defining
-form itself is not instrumented (i.e. Edebug does not stop before and
+form itself is not instrumented (that is, Edebug does not stop before and
after the defining form), but forms inside it typically will be
instrumented. The @code{&define} keyword should be the first element in
a list specification.
A sublist specification may be a dotted list and the corresponding list
argument may then be a dotted list. Alternatively, the last @sc{cdr} of a
dotted list specification may be another sublist specification (via a
-grouping or an indirect specification, e.g. @code{(spec . [(more
+grouping or an indirect specification, e.g., @code{(spec . [(more
specs@dots{})])}) whose elements match the non-dotted list arguments.
This is useful in recursive specifications such as in the backquote
example below. Also see the description of a @code{nil} specification
@item arg
The argument, a symbol, is the name of an argument of the defining form.
-However, lambda list keywords (symbols starting with @samp{@code{&}})
+However, lambda-list keywords (symbols starting with @samp{&})
are not allowed.
@item lambda-list
exhausted. Eventually every element of the argument list must be
matched by some element in the specification, and every required element
in the specification must match some argument.
-
-Backtracking is disabled for the remainder of a sublist or group when
-certain conditions occur, described below. Backtracking is reenabled
-when a new alternative is established by @code{&optional}, @code{&rest},
-or @code{&or}. It is also reenabled initially when processing a
-sublist or group specification or an indirect specification.
-
-You might want to disable backtracking to commit to some alternative so
-that Edebug can provide a more specific syntax error message. Normally,
-if no alternative matches, Edebug reports that none matched, but if one
-alternative is committed to, Edebug can report how it failed to match.
-
-First, backtracking is disabled while matching any of the form
-specifications (i.e. @code{form}, @code{body}, @code{def-form}, and
+
+When a syntax error is detected, it might not be reported until much
+later after higher-level alternatives have been exhausted, and with the
+point positioned further from the real error. But if backtracking is
+disabled when an error occurs, it can be reported immediately. Note
+that backtracking is also reenabled automatically in several situations;
+it is reenabled when a new alternative is established by
+@code{&optional}, @code{&rest}, or @code{&or}, or at the start of
+processing a sublist, group, or indirect specification. The effect of
+enabling or disabling backtracking is limited to the remainder of the
+level currently being processed and lower levels.
+
+Backtracking is disabled while matching any of the
+form specifications (that is, @code{form}, @code{body}, @code{def-form}, and
@code{def-body}). These specifications will match any form so any error
must be in the form itself rather than at a higher level.
-Second, backtracking is disabled after successfully matching a quoted
+Backtracking is also disabled after successfully matching a quoted
symbol or string specification, since this usually indicates a
-recognized construct. If you have a set of alternative constructs that
+recognized construct. But if you have a set of alternative constructs that
all begin with the same symbol, you can usually work around this
constraint by factoring the symbol out of the alternatives, e.g.,
@code{["foo" &or [first case] [second case] ...]}.
-Third, backtracking may be explicitly disabled by using the
-@code{gate} specification. This is useful when you know that
-no higher alternatives may apply.
+Most needs are satisfied by these two ways that bactracking is
+automatically disabled, but occasionally it is useful to explicitly
+disable backtracking by using the @code{gate} specification. This is
+useful when you know that no higher alternatives could apply. See the
+example of the @code{let} specification.
@node Specification Examples
@subsubsection Specification Examples
A @code{let} special form has a sequence of bindings and a body. Each
of the bindings is either a symbol or a sublist with a symbol and
-optional value. In the specification below, notice the @code{gate}
+optional expression. In the specification below, notice the @code{gate}
inside of the sublist to prevent backtracking once a sublist is found.
@example
The default value is @code{nil}.
-Also see @code{edebug-tracing}, in @xref{Trace Buffer}.
+Also see @code{edebug-tracing}, in @ref{Trace Buffer}.
@end defopt
@defopt edebug-test-coverage
If non-@code{nil}, Edebug tests coverage of all expressions debugged.
-This is done by comparing the result of each expression
-with the previous result. Coverage is considered OK if two different
-results are found. So to sufficiently test the coverage of your code,
-try to execute it under conditions that evaluate all expressions more
-than once, and produce different results for each expression.
-
-Use @kbd{M-x edebug-display-freq-count} to display the frequency count
-and coverage information for a definition.
@xref{Coverage Testing}.
@end defopt
@settitle GNU Emacs Lisp Reference Manual
@c %**end of header
+@smallbook
+
@ifinfo
This version is the edition 2.5 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 20.3
* Process Type:: A process running on the underlying OS.
* Stream Type:: Receive or send characters.
* Keymap Type:: What function a keystroke invokes.
-* Syntax Table Type:: What a character means.
+* Overlay Type:: How an overlay is represented.
Numbers
* 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}.
-* Character Case:: Case conversion functions.
+* Case Conversion:: Case conversion functions.
Lists
* Compilation Functions:: Byte compilation functions.
* Disassembly:: Disassembling byte-code; how to read byte-code.
+Advising Functions
+
+* Simple Advice:: A simple example to explain the basics of advice.
+* Defining Advice:: Detailed description of @code{defadvice}.
+* Computed Advice:: ...is to @code{defadvice} as @code{fset} is to @code{defun}.
+* Activation of Advice:: Advice doesn't do anything until you activate it.
+* Enabling Advice:: You can enable or disable each piece of advice.
+* Preactivation:: Preactivation is a way of speeding up the
+ loading of compiled advice.
+* Argument Access:: How advice can access the function's arguments.
+* Subr Arguments:: Accessing arguments when advising a primitive.
+* Combined Definition:: How advice is implemented.
+
Debugging Lisp Programs
* Debugger:: How the Emacs Lisp debugger is implemented.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* 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.
+* Window System Selections::Transferring text to and from other X clients.
* Color Names:: Getting the definitions of color names.
* Resources:: Getting resource values from the server.
* Server Data:: Getting info about the X server.
@include index.texi
@node New Symbols, , Index, Top
-@chapter New Symbols Since the Previous Edition
+@unnumbered New Symbols Since the Previous Edition
@printindex tp
@xref{Regular Expressions}.
@item mark-inactive
-@code{Mark inactive"}@*
+@code{"Mark inactive"}@*
@xref{The Mark}.
@item no-catch
@item quote
@pxref{Quoting}
+@item save-current-buffer
+@pxref{Current Buffer}
+
@item save-excursion
@pxref{Excursions}
expressions, and recursive evaluation of function call arguments and
function body forms, as well as explicit calls in Lisp code.
-The default value of this variable is 200. If you set it to a value
+The default value of this variable is 300. If you set it to a value
less than 100, Lisp will reset it to 100 if the given value is reached.
+Entry to the Lisp debugger increases the value, if there is little room
+left, to make sure the debugger itself has room to execute.
@code{max-specpdl-size} provides another limit on nesting.
@xref{Local Variables}.
Many of the file functions take one or more arguments that are file
names. A file name is actually a string. Most of these functions
-expand file name arguments using @code{expand-file-name}, so that
+expand file name arguments by calling @code{expand-file-name}, so that
@file{~} is handled correctly, as are relative file names (including
@samp{../}). These functions don't recognize environment variable
substitutions such as @samp{$HOME}. @xref{File Name Expansion}.
@comment node-name, next, previous, up
@subsection Subroutines of Visiting
- The @code{find-file-noselect} function uses the
-@code{create-file-buffer} and @code{after-find-file} functions as
-subroutines. Sometimes it is useful to call them directly.
+ The @code{find-file-noselect} function uses two important subroutines
+which are sometimes useful in user Lisp code: @code{create-file-buffer}
+and @code{after-find-file}. This section explains how to use them.
@defun create-file-buffer filename
This function creates a suitably named buffer for visiting
if an auto-save file exists and is more recent than the visited file.
The last thing @code{after-find-file} does is call all the functions
-in @code{find-file-hooks}.
+in the list @code{find-file-hooks}.
@end defun
@node Saving Buffers
@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.
+The hook functions in @code{write-file-hooks} are also responsible for
+encoding the data (if desired): they must choose a suitable coding
+system (@pxref{Lisp and Coding Systems}), perform the encoding
+(@pxref{Explicit Encoding}), and set @code{last-coding-system-used} to
+the coding system that was used (@pxref{Specifying Coding Systems}).
+
Do not make this variable buffer-local. To set up buffer-specific hook
functions, use @code{write-contents-hooks} instead.
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}.
+It is possible to read a special file (such as a FIFO or an I/O device)
+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
+@tindex insert-file-contents-literally
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
or a nonexistent file in a directory where files cannot be created.
@end deffn
-@deffn Command write-region start end filename &optional append visit
+@deffn Command write-region start end filename &optional append visit confirm
This function writes the region delimited by @var{start} and @var{end}
in the current buffer into the file specified by @var{filename}.
If @var{append} is non-@code{nil}, then the specified text is appended
to the existing file contents (if any).
+If @var{confirm} is non-@code{nil}, then @code{write-region} asks
+for confirmation if @var{filename} names an existing file.
+
If @var{visit} is @code{t}, then Emacs establishes an association
between the buffer and the file: the buffer is then visiting that file.
It also sets the last file modification time for the current buffer to
files that the user does not need to know about.
@end deffn
-@tindex with-temp-file
@defmac with-temp-file file body...
+@tindex with-temp-file
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
give an error.
@end defun
-@tindex access-file
@defun access-file filename string
+@tindex access-file
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.
@example
@group
-% ls -l fo*
--rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
--rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+% ls -li fo*
+81908 -rw-rw-rw- 1 rms 29 Aug 18 20:32 foo
+84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
@end group
@end example
@example
@group
-(add-name-to-file "~/lewis/foo" "~/lewis/foo2")
+(add-name-to-file "foo" "foo2")
@result{} nil
@end group
@group
-% ls -l fo*
--rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
--rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
--rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
+% ls -li fo*
+81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo
+81908 -rw-rw-rw- 2 rms 29 Aug 18 20:32 foo2
+84302 -rw-rw-rw- 1 rms 24 Aug 18 20:31 foo3
@end group
@end example
-@c !!! Check whether this set of examples is consistent. --rjc 15mar92
- Finally, we evaluate the following:
+Finally, we evaluate the following:
@example
-(add-name-to-file "~/lewis/foo" "~/lewis/foo3" t)
+(add-name-to-file "foo" "foo3" t)
@end example
@noindent
@example
@group
-(add-name-to-file "~/lewis/foo1" "~/lewis/foo3")
+(add-name-to-file "foo1" "foo3")
@result{} nil
@end group
@group
-% ls -l fo*
--rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
--rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
--rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
+% ls -li fo*
+81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo
+81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo2
+81908 -rw-rw-rw- 3 rms 29 Aug 18 20:32 foo3
@end group
@end example
- This function is meaningless on VMS, where multiple names for one file
-are not allowed.
+This function is meaningless on operating systems where multiple names
+for one file are not allowed.
- See also @code{file-nlinks} in @ref{File Attributes}.
+See also @code{file-nlinks} in @ref{File Attributes}.
@end defun
@deffn Command rename-file filename newname &optional ok-if-already-exists
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
+If @var{time} is non-@code{nil}, then this function 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.
@example
(file-relative-name "/foo/bar" "/foo/")
- @result{} "bar")
+ @result{} "bar"
(file-relative-name "/foo/bar" "/hack/")
- @result{} "/foo/bar")
+ @result{} "/foo/bar"
@end example
@end defun
@example
(make-temp-name
(expand-file-name @var{name-of-application}
- (or (getenv "TMPDIR")
- "/tmp/")))
+ temporary-file-directory))
@end example
-@cindex @code{TMPDIR} environment variable.
@noindent
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.
+two different jobs from trying to use the exact same file name. This
+example uses the variable @code{temporary-file-directory} to decide
+where to put the temporary file. All Emacs Lisp programs should
+use @code{temporary-file-directory} for this purpose, to give the user
+a uniform way to specify the directory for all temporary files.
@defun make-temp-name string
-This function generates string that can be used as a unique name. The
-name starts with @var{string}, and ends with a number that is different
-in each Emacs job.
+This function generates string that can be used as a unique file name.
+The name starts with @var{string}, and contains a number that is
+different in each Emacs job.
@example
@group
(make-temp-name "/tmp/foo")
- @result{} "/tmp/foo021304"
+ @result{} "/tmp/foo232J6v"
@end group
@end example
To prevent conflicts among different libraries running in the same
Emacs, each Lisp program that uses @code{make-temp-name} should have its
-own @var{string}. The number added to the end of the name distinguishes
-between the same application running in different Emacs jobs.
+own @var{string}. The number added to the end of @var{string}
+distinguishes between the same application running in different Emacs
+jobs. Additional added characters permit a large number of distinct
+names even in one Emacs job.
@end defun
+@defvar temporary-file-directory
+@cindex @code{TMPDIR} environment variable.
+@cindex @code{TMP} environment variable.
+This variable specifies the directory name for creating temporary files.
+Its value should be a directory name (@pxref{Directory Names}), but it
+is good for Lisp programs to cope if the value is a file name instead.
+(Using the value as the second argument to @code{expand-file-name} is a
+good way to achieve that.)
+
+The default value is determined in a reasonable way for your operating
+system; on GNU and Unix systems it is based on the @code{TMP} and
+@code{TMPDIR} environment variables.
+
+Even if you do not use @code{make-temp-name} to choose the temporary
+file's name, you should still use this variable to decide which
+directory to put the file in.
+@end defvar
+
@node File Name Completion
@subsection File Name Completion
@cindex file name completion subroutines
On GNU and Unix systems, and on some other systems as well,
@code{convert-standard-filename} returns its argument unchanged. On
-some other systems, it alters the name to fit the systems's conventions.
+some other systems, it alters the name to fit the system's conventions.
For example, on MS-DOS the alterations made by this function include
converting a leading @samp{.} to @samp{_}, converting a @samp{_} in 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 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.)
+If @var{full-directory-p} is non-@code{nil}, that means the directory
+listing is expected to show the full contents of a 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
@defvar auto-save-file-format
This variable specifies the format to use for auto-saving. Its value is
a list of format names, just like the value of
-@code{buffer-file-format}; but it is used instead of
-@code{buffer-file-format} for writing auto-save files. This variable
-is always buffer-local in all buffers.
+@code{buffer-file-format}; however, it is used instead of
+@code{buffer-file-format} for writing auto-save files. This variable is
+always buffer-local in all buffers.
@end defvar
horizontally into smaller windows.
@cindex terminal frame
-@cindex X window frame
When Emacs runs on a text-only terminal, it starts with one
@dfn{terminal frame}. If you create additional ones, Emacs displays
one and only one at any given time---on the terminal screen, of course.
+@cindex window frame
When Emacs communicates directly with a supported window system, such
as X Windows, it does not have a terminal frame; instead, it starts with
a single @dfn{window frame}, but you can create more, and Emacs can
Parameters}, for documentation of individual parameters you can specify.
@end defun
-@tindex before-make-frame-hook
@defvar before-make-frame-hook
+@tindex 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
+@tindex after-make-frame-hook
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.
meaningful information in terminal frames.
@table @code
+@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
+@code{DISPLAY} environment variable.
+
@item title
If a frame has a non-@code{nil} title, it appears in the window system's
border for the frame, and also in the mode line of windows in that frame
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
-@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
-@code{DISPLAY} environment variable.
-
@item left
The screen position of the left edge, in pixels, with respect to the
left edge of the screen. The value may be a positive number @var{pos},
@item font
The name of the font for displaying text in the frame. This is a
-string.
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}).
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
toolkit, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
+@ignore
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
Specifying this lets you create an Emacs window inside some other
application's window. (It is not certain this will be implemented; try
it and see if it works.)
+@end ignore
@end table
@node Size and Position
change it.
@end defun
-@tindex focus-follows-mouse
@defopt focus-follows-mouse
+@tindex focus-follows-mouse
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a
You can raise and lower Emacs frame Windows with these functions:
-@deffn Command raise-frame frame
-This function raises frame @var{frame}.
+@deffn Command raise-frame &optional frame
+This function raises frame @var{frame} (default, the selected frame).
@end deffn
-@deffn Command lower-frame frame
-This function lowers frame @var{frame}.
+@deffn Command lower-frame &optional frame
+This function lowers frame @var{frame} (default, the selected frame).
@end deffn
@defopt minibuffer-auto-raise
This function @dfn{warps the mouse} to position @var{x}, @var{y} in
frame @var{frame}. The arguments @var{x} and @var{y} are integers,
giving the position in characters relative to the top left corner of the
-inside of @var{frame}.
+inside of @var{frame}. If @var{frame} is not visible, this function
+does nothing. The return value is not significant.
@end defun
@defun mouse-pixel-position
This function warps the mouse like @code{set-mouse-position} except that
@var{x} and @var{y} are in units of pixels rather than units of
characters. These coordinates are not required to be within the frame.
+
+If @var{frame} is not visible, this function does nothing. The return
+value is not significant.
@end defun
@need 3000
many fonts match the pattern.
@end defun
+@node Fontsets
+@section Fontsets
+
+ A @dfn{fontset} is a list of fonts, each assigned to a range of
+character codes. An individual font cannot display the whole range of
+characters that Emacs supports, but a fontset can. Fontsets have names,
+just as fonts do, and you can use a fontset name in place of a font name
+when you specify the ``font'' for a frame or a face. Here is
+information about defining a fontset under Lisp program control.
+
+@defun create-fontset-from-fontset-spec fontset-spec &optional style noerror
+This function defines a new fontset according to the specification
+string @var{fontset-spec}. The string should have this format:
+
+@smallexample
+@var{fontpattern}, @r{[}@var{charsetname}:@var{fontname}@r{]@dots{}}
+@end smallexample
+
+@noindent
+Whitespace characters before and after the commas are ignored.
+
+The first part of the string, @var{fontpattern}, should have the form of
+a standard X font name, except that the last two fields should be
+@samp{fontset-@var{alias}}.
+
+Each fontset has two names, one long and one short. The long name is
+@var{fontpattern} in its entirety. The short name is
+@samp{fontset-@var{alias}}. You can refer to the fontset by either
+name. If a fontset with the same name already exists, an error is
+signaled, unless @var{noerror} is non-@code{nil}, in which case this
+function does nothing.
+
+The specification string also says which fonts to use in the fontset.
+See below for the details.
+@end defun
+
+ If optional argument @var{style} is specified, it specifies a way to
+modify the fontset. It should be one of @code{bold}, @code{italic}, and
+@code{bold-italic}, and it says to find the bold, italic or bold-italic
+version of each font if possible.
+
+ The construct @samp{@var{charset}:@var{font}} specifies which font to
+use (in this fontset) for one particular character set. Here,
+@var{charset} is the name of a character set, and @var{font} is the font
+to use for that character set. You can use this construct any number of
+times in the specification string.
+
+ For the remaining character sets, those that you don't specify
+explicitly, Emacs chooses a font based on @var{fontpattern}: it replaces
+@samp{fontset-@var{alias}} with a value that names one character set.
+For the @sc{ASCII} character set, @samp{fontset-@var{alias}} is replaced
+with @samp{ISO8859-1}.
+
+ In addition, when several consecutive fields are wildcards, Emacs
+collapses them into a single wildcard. This is to prevent use of
+auto-scaled fonts. Fonts made by scaling larger fonts are not usable
+for editing, and scaling a smaller font is not useful because it is
+better to use the smaller font in its own size, which Emacs does.
+
+ Thus if @var{fontpattern} is this,
+
+@example
+-*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24
+@end example
+
+@noindent
+the font specification for ASCII characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-ISO8859-1
+@end example
+
+@noindent
+and the font specification for Chinese GB2312 characters would be this:
+
+@example
+-*-fixed-medium-r-normal-*-24-*-gb2312*-*
+@end example
+
+ You may not have any Chinese font matching the above font
+specification. Most X distributions include only Chinese fonts that
+have @samp{song ti} or @samp{fangsong ti} in @var{family} field. In
+such a case, @samp{Fontset-@var{n}} can be specified as below:
+
+@smallexample
+Emacs.Fontset-0: -*-fixed-medium-r-normal-*-24-*-*-*-*-*-fontset-24,\
+ chinese-gb2312:-*-*-medium-r-normal-*-24-*-gb2312*-*
+@end smallexample
+
+@noindent
+Then, the font specifications for all but Chinese GB2312 characters have
+@samp{fixed} in the @var{family} field, and the font specification for
+Chinese GB2312 characters has a wild card @samp{*} in the @var{family}
+field.
+
@node Color Names
@section Color Names
@ignore
@defvar x-no-window-manager
-This variable's value is is @code{t} if no X window manager is in use.
+This variable's value is @code{t} if no X window manager is in use.
@end defvar
@end ignore
@dfn{built-in} functions or @dfn{subrs}. (Special forms are also
considered primitives.)
-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}.
+Usually the reason we implement a function as a primitive is either
+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}.
@item lambda expression
A @dfn{lambda expression} is a function written in Lisp.
byte compiler. @xref{Byte-Code Type}.
@end table
-@tindex functionp
@defun functionp object
+@tindex functionp
This function returns @code{t} if @var{object} is any kind of function,
or a special form or macro.
@end defun
it in several symbols using @code{fset}; then each of the symbols is
equally well a name for the same function.
- A symbol used as a function name may also be used as a variable;
-these two uses of a symbol are independent and do not conflict.
-(Some Lisp dialects, such as Scheme, do not distinguish between a
-symbol's value and its function definition; a symbol's value as a variable
-is also its function definition.)
+ 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.) If you have not given a symbol a function
+definition, you cannot use it as a function; whether the symbol has a
+value as a variable makes no difference to this.
@node Defining Functions
@section Defining Functions
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
function @code{funcall}. When you also need to determine at run time
-how may arguments to pass, use @code{apply}.
+how many arguments to pass, use @code{apply}.
@defun funcall function &rest arguments
@code{funcall} calls @var{function} with @var{arguments}, and returns
@example
@group
(defun double-property (symbol prop)
- (change-property symbol prop (function (lambda (x) (* 2 x)))))
+ (change-property symbol prop
+ (function (lambda (x) (* 2 x)))))
@end group
@end example
@noindent
The Lisp compiler cannot assume this list is a function, even though it
looks like one, since it does not know what @code{change-property} will
-do with the list. Perhaps will check whether the @sc{car} of the third
+do with the list. Perhaps it 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.
@example
(function @var{symbol}) @equiv{} (quote @var{symbol}) @equiv{} '@var{symbol}
+@end example
+
+ The read syntax @code{#'} is a short-hand for using @code{function}.
+For example,
+
+@example
+#'(lambda (x) (* x x))
+@end example
+
+@noindent
+is equivalent to
+
+@example
+(function (lambda (x) (* x x)))
@end example
@defspec function function-object
@defun fmakunbound symbol
This function makes @var{symbol}'s function cell void, so that a
subsequent attempt to access this cell will cause a @code{void-function}
-error. (See also @code{makunbound}, in @ref{Local Variables}.)
+error. (See also @code{makunbound}, in @ref{Void Variables}.)
@example
@group
@end smallexample
@end defun
+@defun read-kbd-macro string
+This function is used mainly for operating on keyboard macros, but it
+can also be used as a rough inverse for @code{key-description}. You
+call it with a string containing key descriptions, separated by spaces;
+it returns a string or vector containing the corresponding events.
+(This may or may not be a single valid key sequence, depending on what
+events you use; @pxref{Keymap Terminology}.)
+@end defun
+
@node Help Functions
@section Help Functions
beginning of its documentation string.
@c Emacs 19 feature
-If @var{do-all} is non-@code{nil}, then @code{apropos} also shows
-key bindings for the functions that are found.
+If @var{do-all} is non-@code{nil}, then @code{apropos} also shows key
+bindings for the functions that are found; it also shows all symbols,
+even those that are neither functions nor variables.
In the first of the following examples, @code{apropos} finds all the
symbols with names containing @samp{exec}. (We don't show here the
@defvar help-char
The value of this variable is the help character---the character that
-Emacs recognizes as meaning Help. By default, it stands for 8, which is
-@kbd{C-h}. When Emacs reads this character, if @code{help-form} is
-non-@code{nil} Lisp expression, it evaluates that expression, and
-displays the result in a window if it is a string.
+Emacs recognizes as meaning Help. By default, its value is 8, which
+stands for @kbd{C-h}. When Emacs reads this character, if
+@code{help-form} is a non-@code{nil} Lisp expression, it evaluates that
+expression, and displays the result in a window if it is a string.
Usually the value of @code{help-form}'s value is @code{nil}. Then the
help character has no special meaning at the level of command input, and
subcommands of the prefix key.
@end defvar
-@tindex help-event-list
@defvar help-event-list
+@tindex help-event-list
The value of this variable is a list of event types that serve as
alternative ``help characters.'' These events are handled just like the
event specified by @code{help-char}.
sequence. (The last event is, presumably, the help character.)
@end defun
- The following two functions are found in the library @file{helper}.
-They are for modes that want to provide help without relinquishing
-control, such as the ``electric'' modes. You must load that library
-with @code{(require 'helper)} in order to use them. Their names begin
-with @samp{Helper} to distinguish them from the ordinary help functions.
+ The following two functions are meant for modes that want to provide
+help without relinquishing control, such as the ``electric'' modes.
+Their names begin with @samp{Helper} to distinguish them from the
+ordinary help functions.
@deffn Command Helper-describe-bindings
This command pops up a window displaying a help buffer containing a
@c !!! need xref to where each hook is documented or else document it
@c by specifying what is expected, and when it is called relative to
-@c mode initialization.)
+@c mode initialization.
@table @code
@item activate-mark-hook
@c Emacs 19 feature
The number of floats for which space has been obtained from the
operating system, but that are not currently being used.
+
+@item used-intervals
+The number of intervals in use. Intervals are an internal
+data structure used for representing text properties.
+
+@item free-intervals
+The number of intervals for which space has been obtained
+from the operating system, but that are not currently being used.
@end table
@end deffn
@item local_var_alist
This field contains the association list describing the buffer-local
variable bindings of this buffer, not including the built-in
-buffer-local bindings that that have special slots in the buffer object.
+buffer-local bindings that have special slots in the buffer object.
(Those slots are omitted from this table.) @xref{Buffer-Local
Variables}.
are functions that can also conveniently be called from Lisp programs,
and parameters for customization are ordinary Lisp variables.
- This manual describes Emacs Lisp, presuming considerable familiarity
-with the use of Emacs for editing. (See @cite{The GNU Emacs Manual}
-for this basic information.) Generally speaking, the earlier chapters
-describe features of Emacs Lisp that have counterparts in many
-programming languages, and later chapters describe features that are
-peculiar to Emacs Lisp or relate specifically to editing.
+ This manual attempts to be a full description of Emacs Lisp. For a
+beginner's introduction to Emacs Lisp, see @cite{An Introduction to
+Emacs Lisp Programming}, by Bob Chassell, also published by the Free
+Software Foundation. This manual presumes considerable familiarity with
+the use of Emacs for editing; see @cite{The GNU Emacs Manual} for this
+basic information.
+
+ Generally speaking, the earlier chapters describe features of Emacs
+Lisp that have counterparts in many programming languages, and later
+chapters describe features that are peculiar to Emacs Lisp or relate
+specifically to editing.
This is edition 2.5.
* Caveats:: Flaws and a request for help.
* Lisp History:: Emacs Lisp is descended from Maclisp.
* Conventions:: How the manual is formatted.
+* Version Info:: Which Emacs version is running?
* Acknowledgements:: The authors, editors, and sponsors of this manual.
@end menu
Please mail comments and corrections to
@example
-bug-lisp-manual@@prep.ai.mit.edu
+bug-lisp-manual@@gnu.org
@end example
@noindent
updates. So please attach no significance to the lack of a reply---your
mail @emph{will} be acted on in due time. If you want to contact the
Emacs maintainers more quickly, send mail to
-@code{bug-gnu-emacs@@prep.ai.mit.edu}.
+@code{bug-gnu-emacs@@gnu.org}.
@display
--Bil Lewis, Dan LaLiberte, Richard Stallman
@section Lisp History
@cindex Lisp history
- Lisp (LISt Processing language) was first developed in the late 1950's
+ Lisp (LISt Processing language) was first developed in the late 1950s
at the Massachusetts Institute of Technology for research in artificial
-intelligence. The great power of the Lisp language makes it superior
+intelligence. The great power of the Lisp language makes it ideal
for other purposes as well, such as writing editing commands.
@cindex Maclisp
@cindex Common Lisp
Dozens of Lisp implementations have been built over the years, each
with its own idiosyncrasies. Many of them were inspired by Maclisp,
-which was written in the 1960's at MIT's Project MAC. Eventually the
+which was written in the 1960s at MIT's Project MAC. Eventually the
implementors of the descendants of Maclisp came together and developed a
-standard for Lisp systems, called Common Lisp. In the mean time, Gerry
+standard for Lisp systems, called Common Lisp. In the meantime, Gerry
Sussman and Guy Steele at MIT developed a simplified but very powerful
dialect of Lisp, called Scheme.
GNU Emacs Lisp is largely inspired by Maclisp, and a little by Common
Lisp. If you know Common Lisp, you will notice many similarities.
-However, many of the features of Common Lisp have been omitted or
+However, many features of Common Lisp have been omitted or
simplified in order to reduce the memory requirements of GNU Emacs.
Sometimes the simplifications are so drastic that a Common Lisp user
might be very confused. We will occasionally point out how GNU Emacs
Lisp differs from Common Lisp. If you don't know Common Lisp, don't
worry about it; this manual is self-contained.
+@pindex cl
+ A certain amount of Common Lisp emulation is available via the
+@file{cl} library @xref{Top,, Common Lisp Extension, cl, Common Lisp
+Extensions}.
+
Emacs Lisp is not at all influenced by Scheme; but the GNU project has
-an implementation of Scheme, called Guile. We use Guile for
-extensibility in all new GNU software that calls for extensibility.
+an implementation of Scheme, called Guile. We use Guile in all new GNU
+software that calls for extensibility.
@node Conventions
@section Conventions
* Some Terms:: Explanation of terms we use in this manual.
* nil and t:: How the symbols @code{nil} and @code{t} are used.
* Evaluation Notation:: The format we use for examples of evaluation.
-* Printing Notation:: The format we use for examples that print output.
+* Printing Notation:: The format we use when examples print text.
* Error Messages:: The format we use for examples of errors.
* Buffer Text Notation:: The format we use for buffer contents in examples.
* Format of Descriptions:: Notation for describing functions, variables, etc.
-* Version Info:: Which Emacs version is running?
@end menu
@node Some Terms
@subsection Some Terms
Throughout this manual, the phrases ``the Lisp reader'' and ``the Lisp
-printer'' are used to refer to those routines in Lisp that convert
-textual representations of Lisp objects into actual Lisp objects, and vice
+printer'' refer to those routines in Lisp that convert textual
+representations of Lisp objects into actual Lisp objects, and vice
versa. @xref{Printed Representation}, for more details. You, the
person reading this manual, are thought of as ``the programmer'' and are
-addressed as ``you''. ``The user'' is the person who uses Lisp programs,
-including those you write.
+addressed as ``you''. ``The user'' is the person who uses Lisp
+programs, including those you write.
@cindex fonts
Examples of Lisp code appear in this font or form: @code{(list 1 2
is considered to be @var{true}. However, @code{t} is the preferred way
to represent the truth value @var{true}. When you need to choose a
value which represents @var{true}, and there is no other basis for
-choosing, use @code{t}. The symbol @code{t} always has value @code{t}.
+choosing, use @code{t}. The symbol @code{t} always has the value
+@code{t}.
In Emacs Lisp, @code{nil} and @code{t} are special symbols that always
evaluate to themselves. This is so that you do not need to quote them
When a form is a macro call, it expands into a new form for Lisp to
evaluate. We show the result of the expansion with
-@samp{@expansion{}}. We may or may not show the actual result of the
+@samp{@expansion{}}. We may or may not show the result of the
evaluation of the expanded form.
@example
arguments default to @code{nil}). Do not write @code{&optional} when
you call the function.
- The keyword @code{&rest} (which will always be followed by a single
-argument name) indicates that any number of arguments can follow. The value
-of the single following arguments name will be a list of all these arguments.
-Do not write @code{&rest} when you call the function.
+ The keyword @code{&rest} (which must be followed by a single argument
+name) indicates that any number of arguments can follow. The single
+following argument name will have a value, as a variable, which is a
+list of all these remaining arguments. Do not write @code{&rest} when
+you call the function.
Here is a description of an imaginary function @code{foo}:
Special form descriptions use a more complex notation to specify
optional and repeated arguments because they can break the argument
list down into separate arguments in more complicated ways.
-@samp{@code{@r{[}@var{optional-arg}@r{]}}} means that @var{optional-arg} is
+@samp{@r{[}@var{optional-arg}@r{]}} means that @var{optional-arg} is
optional and @samp{@var{repeated-args}@dots{}} stands for zero or more
arguments. Parentheses are used when several arguments are grouped into
additional levels of list structure. Here is an example:
This imaginary special form implements a loop that executes the
@var{body} forms and then increments the variable @var{var} on each
iteration. On the first iteration, the variable has the value
-@var{from}; on subsequent iterations, it is incremented by 1 (or by
+@var{from}; on subsequent iterations, it is incremented by one (or by
@var{inc} if that is given). The loop exits before executing @var{body}
if @var{var} equals @var{to}. Here is an example:
(terpri))
@end example
-If @var{from} and @var{to} are omitted, then @var{var} is bound to
+If @var{from} and @var{to} are omitted, @var{var} is bound to
@code{nil} before the loop begins, and the loop exits if @var{var} is
non-@code{nil} at the beginning of an iteration. Here is an example:
@node Version Info
@section Version Information
- These functions and variables provide information about which
-version of Emacs is in use.
+ These facilities provide information about which version of Emacs is
+in use.
@deffn Command emacs-version
This function returns a string describing the version of Emacs that is
running. It is useful to include this string in bug reports.
-@example
+@smallexample
@group
(emacs-version)
@result{} "GNU Emacs 20.3.5 (i486-pc-linux-gnulibc1, X toolkit)
of Sat Feb 14 1998 on psilocin.gnu.org"
@end group
-@end example
+@end smallexample
Called interactively, the function prints the same information in the
echo area.
@end deffn
@defvar emacs-build-time
-The value of this variable is the time at which Emacs was built at the
-local site.
+The value of this variable indicates the time at which Emacs was built
+at the local site. It is a list of three integers, like the value
+of @code{current-time} (@pxref{Time of Day}).
@example
@group
emacs-build-time
- @result{} "Tue Jun 6 14:55:57 1995"
+ @result{} (13623 62065 344633)
@end group
@end example
@end defvar
time you build Emacs in any given directory.
@end defvar
- The following two variables have existed since Emacs version 19.23,
+ 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
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 key
-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.
+binding in the keymap, for @sc{ASCII} characters. However, default
+bindings are still meaningful for events other than @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
@item
@cindex @kbd{C-h}
-@code{help-map} is the global definitions for the @kbd{C-h} prefix key.
+@code{help-map} is the global keymap for the @kbd{C-h} prefix key.
@item
@cindex @kbd{C-c}
@cindex @kbd{C-x}
@vindex ctl-x-map
@findex 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{ctl-x-map} is the global keymap used for the @kbd{C-x} prefix key.
+This map is found via the function cell of the symbol
@code{Control-X-prefix}.
@item
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
+symbol @code{Control-X-prefix}, whose function cell holds the keymap
for @kbd{C-x} commands. (The same keymap is also the value of
@code{ctl-x-map}.)
overrides it. Text properties can specify an alternative local map for
certain parts of the buffer; see @ref{Special Properties}.
- Each minor mode may have a keymap; if it does, the keymap is active
+ Each minor mode can have a keymap; if it does, the keymap is active
when the minor mode is enabled.
The variable @code{overriding-local-map}, if non-@code{nil}, specifies
maps. The procedure for searching a single keymap is called @dfn{key
lookup}; see @ref{Key Lookup}.
-Normally, Emacs first searches for the key in the minor mode
-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, before the global map.
+ Normally, Emacs first searches for the key in the minor mode maps, in
+the order specified by @code{minor-mode-map-alist}; 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, before the global map.
@cindex major mode keymap
Since every buffer that uses the same major mode normally uses the
The minibuffer has local keymaps, too; they contain various completion
and exit commands. @xref{Intro to Minibuffers}.
+ Emacs has other keymaps that are used in a different way---translating
+events within @code{read-key-sequence}. @xref{Translating Input}.
+
@xref{Standard Keymaps}, for a list of standard keymaps.
@defvar global-map
Lookup}).
@end defvar
-@tindex minor-mode-overriding-map-alist
@defvar minor-mode-overriding-map-alist
+@tindex 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 appears an element
-@code{minor-mode-overriding-map-alist}, that element overrides any
-element for the same variable in @code{minor-mode-map-alist}.
+. @var{keymap})}.
+
+If a variable appears an element of
+@code{minor-mode-overriding-map-alist}, the map specified by that
+element totally replaces any map specified for the same variable in
+@code{minor-mode-map-alist}.
@code{minor-mode-overriding-map-alist} is automatically buffer-local in
all buffers.
@end smallexample
@end defun
-@deffn Command describe-bindings prefix
+@deffn Command describe-bindings &optional prefix
This function creates a listing of all current key bindings, and
displays it in a buffer named @samp{*Help*}. The text is grouped by
modes---minor modes first, then the major mode, then global bindings.
@code{define-key-after} (@pxref{Modifying Menus}).
@menu
-* Simple Menu Items::
-* Extended Menu Items::
+* Simple Menu Items:: A simple kind of menu key binding,
+ limited in capabilities.
+* Alias Menu Items:: Using command aliases in menu items.
+* Extended Menu Items:: More powerful menu item definitions
+ let you specify keywords to enable
+ various features.
@end menu
@node Simple Menu Items
(@var{item-string} . @var{real-binding})
@end example
+@noindent
The @sc{car}, @var{item-string}, is the string to be displayed in the
menu. It should be short---preferably one to three words. It should
describe the action of the command it corresponds to.
calculates them automatically. Don't mention keyboard equivalents in
the item strings themselves, since that is redundant.
-Sometimes it is useful to make menu items that use the ``same'' command
-but with different enable conditions. You can do this by defining alias
-commands. Here's an example that makes two aliases for
-@code{toggle-read-only} and gives them different enable conditions:
-
-@example
-(defalias 'make-read-only 'toggle-read-only)
-(put 'make-read-only 'menu-enable '(not buffer-read-only))
-(defalias 'make-writable 'toggle-read-only)
-(put 'make-writable 'menu-enable 'buffer-read-only)
-@end example
-
-When using aliases in menus, often it is useful to display the
-equivalent key bindings for the ``real'' command name, not the aliases
-(which typically don't have any key bindings except for the menu
-itself). To request this, give the alias symbol a non-@code{nil}
-@code{menu-alias} property. Thus,
-
-@example
-(put 'make-read-only 'menu-alias t)
-(put 'make-writable 'menu-alias t)
-@end example
-
-@noindent
-causes menu items for @code{make-read-only} and @code{make-writable} to
-show the keyboard bindings for @code{toggle-read-only}.
-
@node Extended Menu Items
@subsubsection Extended Menu Items
+@kindex menu-item
An extended-format menu item is a more flexible and also cleaner
alternative to the simple format. It consists of a list that starts
@item :help @var{help}
The value of this property, @var{help}, is the extra help string (not
-currently used).
+currently used by Emacs).
@item :button (@var{type} . @var{selected})
This property provides a way to define radio buttons and toggle buttons.
@code{:radio}. The @sc{cdr}, @var{selected}, should be a form; the
result of evaluating it says whether this button is currently selected.
+A @dfn{toggle} is a menu item which is labeled as either ``on'' or ``off''
+according to the value of @var{selected}. The command itself should
+toggle @var{selected}, setting it to @code{t} if it is @code{nil},
+and to @code{nil} if it is @code{t}. Here is how the menu item
+to toggle the @code{debug-on-error} flag is defined:
+
+@example
+(menu-item "Debug on Error" toggle-debug-on-error
+ :button (:toggle
+ . (and (boundp 'debug-on-error)
+ debug-on-error))
+@end example
+
+@noindent
+This works because @code{toggle-debug-on-error} is defined as a command
+which toggles the variable @code{debug-on-error}.
+
+@dfn{Radio buttons} are a group of menu items, in which at any time one
+and only one is ``selected.'' There should be a variable whose value
+says which one is selected at any time. The @var{selected} form for
+each radio button in the group should check whether the variable has the
+right value for selecting that button. Clicking on the button should
+set the variable so that the button you clicked on becomes selected.
+
+@item :key-sequence @var{key-sequence}
+This property specifies which key sequence is likely to be bound to the
+same command invoked by this menu item. If you specify the right key
+sequence, that makes preparing the menu for display run much faster.
+
+If you specify the wrong key sequence, it has no effect; before Emacs
+displays @var{key-sequence} in the menu, it verifies that
+@var{key-sequence} is really equivalent to this menu item.
+
+@item :key-sequence nil
+This property indicates that there is normally no key binding which is
+equivalent to this menu item. Using this property saves time in
+preparing the menu for display, because Emacs does not need to search
+the keymaps for a keyboard equivalent for this menu item.
+
+However, if the user has rebound this item's definition to a key
+sequence, Emacs ignores the @code{:keys} property and finds the keyboard
+equivalent anyway.
+
+@item :keys @var{string}
+This property specifies that @var{string} is the string to display
+as the keyboard equivalent for this menu item. You can use
+the @samp{\\[...]} documentation construct in @var{string}.
+
@item :filter @var{filter-fn}
This property provides a way to compute the menu item dynamically.
The property value @var{filter-fn} should be a function of one argument;
function should return the binding to use instead.
@end table
+@node Alias Menu Items
+@subsubsection Alias Menu Items
+
+ Sometimes it is useful to make menu items that use the ``same''
+command but with different enable conditions. The best way to do this
+in Emacs now is with extended menu items; before that feature existed,
+it could be done by defining alias commands and using them in menu
+items. Here's an example that makes two aliases for
+@code{toggle-read-only} and gives them different enable conditions:
+
+@example
+(defalias 'make-read-only 'toggle-read-only)
+(put 'make-read-only 'menu-enable '(not buffer-read-only))
+(defalias 'make-writable 'toggle-read-only)
+(put 'make-writable 'menu-enable 'buffer-read-only)
+@end example
+
+When using aliases in menus, often it is useful to display the
+equivalent key bindings for the ``real'' command name, not the aliases
+(which typically don't have any key bindings except for the menu
+itself). To request this, give the alias symbol a non-@code{nil}
+@code{menu-alias} property. Thus,
+
+@example
+(put 'make-read-only 'menu-alias t)
+(put 'make-writable 'menu-alias t)
+@end example
+
+@noindent
+causes menu items for @code{make-read-only} and @code{make-writable} to
+show the keyboard bindings for @code{toggle-read-only}.
+
@node Mouse Menus
@subsection Menus and the Mouse
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:
+menu bar, and it uses the simple menu item format (@pxref{Simple Menu
+Items}). First we create the keymap, and give it a name:
@example
(defvar menu-bar-print-menu (make-sparse-keymap "Print"))
can do it this way:
@example
-(define-key global-map [C-S-down-mouse-1] menu-bar-print-menu)
+(define-key global-map [C-S-down-mouse-1]
+ menu-bar-print-menu)
+@end example
+
+ We could equally well use an extended menu item (@pxref{Extended Menu
+Items}) for @code{print-region}, like this:
+
+@example
+(define-key menu-bar-print-menu [print-region]
+ '(menu-item "Print Region" print-region
+ :enable (mark-active)))
+@end example
+
+@noindent
+With the extended menu item, the enable condition is specified
+inside the menu item itself. If we wanted to make this
+item disappear from the menu entirely when the mark is inactive,
+we could do it this way:
+
+@example
+(define-key menu-bar-print-menu [print-region]
+ '(menu-item "Print Region" print-region
+ :visible (mark-active)))
@end example
@node Menu Bar
@end example
@end defun
-@tindex safe-length
@defun safe-length list
+@tindex safe-length
This function returns the length of @var{list}, with no risk
of either an error or an infinite loop.
worried that it may be circular, is with @code{length}. @xref{Sequence
Functions}.
-@tindex caar
@defun caar cons-cell
+@tindex caar
This is the same as @code{(car (car @var{cons-cell}))}.
@end defun
-@tindex cadr
@defun cadr cons-cell
+@tindex cadr
This is the same as @code{(car (cdr @var{cons-cell}))}
or @code{(nth 1 @var{cons-cell})}.
@end defun
-@tindex cdar
@defun cdar cons-cell
+@tindex cdar
This is the same as @code{(cdr (car @var{cons-cell}))}.
@end defun
-@tindex cddr
@defun cddr cons-cell
+@tindex cddr
This is the same as @code{(cdr (cdr @var{cons-cell}))}
or @code{(nthcdr 2 @var{cons-cell})}.
@end defun
@end group
@end example
-With the help of @code{apply}, we can append all the lists in a list of
-lists:
+With the help of @code{apply} (@pxref{Calling Functions}), we can append
+all the lists in a list of lists:
@example
@group
increasing order sort, the @var{predicate} should return @code{t} if the
first element is ``less than'' the second, or @code{nil} if not.
+The comparison function @var{predicate} must give reliable results for
+any given pair of arguments, at least within a single call to
+@code{sort}. It must be @dfn{antisymmetric}; that is, if @var{a} is
+less than @var{b}, @var{b} must not be less than @var{a}. It must be
+@dfn{transitive}---that is, if @var{a} is less than @var{b}, and @var{b}
+is less than @var{c}, then @var{a} must be less than @var{c}. If you
+use a comparison function which does not meet these requirements, the
+result of @code{sort} is unpredictable.
+
The destructive aspect of @code{sort} is that it rearranges the cons
cells forming @var{list} by changing @sc{cdr}s. A nondestructive sort
function would create new cons cells to store the elements in their
@end smallexample
@end defun
+ The functions @code{assoc-ignore-representation} and
+@code{assoc-ignore-case} are much like @code{assoc} except using
+@code{compare-strings} to do the comparison. @xref{Text Comparison}.
+
@defun rassoc value alist
This function returns the first association with value @var{value} in
@var{alist}. It returns @code{nil} if no association in @var{alist} has
@menu
* How Programs Do Loading:: The @code{load} function and others.
+* Library Search:: Finding a library to load.
+* Loading Non-ASCII:: Non-@sc{ASCII} characters in Emacs Lisp files.
* Autoload:: Setting up a function to autoload.
* Repeated Loading:: Precautions about loading a file twice.
* Named Features:: Loading a library if it isn't already loaded.
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
+@defun load filename &optional missing-ok nomessage nosuffix must-suffix
This function finds and opens a file of Lisp code, evaluates all the
forms in it, and closes the file.
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 the optional argument @var{must-suffix} is non-@code{nil}, then
+@code{load} insists that the file name used must end in either
+@samp{.el} or @samp{.elc}, unless it contains an explicit directory
+name. If @var{filename} does not contain an explicit directory name,
+and does not end in a suffix, then @code{load} insists on adding one.
+
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-path}. It appends @var{filename} to each of the directories
in @code{load-path}, where @code{nil} stands for the default directory.
@code{load} tries all three possible suffixes in the first directory in
@code{load-path}, then all three suffixes in the second directory, and
-so on.
+so on. @xref{Library Search}.
If you get a warning that @file{foo.elc} is older than @file{foo.el}, it
means you should consider recompiling @file{foo.el}. @xref{Byte
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.
+command if you wish to specify precisely the file name to load.
@end deffn
@deffn Command load-library library
@code{load}, except in how it reads its argument interactively.
@end deffn
+@defvar load-in-progress
+This variable is non-@code{nil} if Emacs is in the process of loading a
+file, and it is @code{nil} otherwise.
+@end defvar
+
+@defvar load-read-function
+This variable specifies an alternate expression-reading function for
+@code{load} and @code{eval-region} to use instead of @code{read}.
+The function should accept one argument, just as @code{read} does.
+
+Normally, the variable's value is @code{nil}, which means those
+functions should use @code{read}.
+@end defvar
+
+ For how @code{load} is used to build Emacs, see @ref{Building Emacs}.
+
+@node Library Search
+@section Library Search
+
+ When Emacs loads a Lisp library, it searches for the library
+in a list of directories specified by the variable @code{load-path}.
+
@defopt load-path
@cindex @code{EMACSLOADPATH} environment variable
The value of this variable is a list of directories to search when
loading files with @code{load}. Each element is a string (which must be
a directory name) or @code{nil} (which stands for the current working
-directory). The value of @code{load-path} is initialized from the
-environment variable @code{EMACSLOADPATH}, if that exists; otherwise its
-default value is specified in @file{emacs/src/paths.h} when Emacs is
-built.
+directory).
+@end defopt
+
+ The value of @code{load-path} is initialized from the environment
+variable @code{EMACSLOADPATH}, if that exists; otherwise its default
+value is specified in @file{emacs/src/paths.h} when Emacs is built.
+Then the list is expanded by adding subdirectories of the directories
+in the list.
-The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
+ The syntax of @code{EMACSLOADPATH} is the same as used for @code{PATH};
@samp{:} (or @samp{;}, according to the operating system) separates
directory names, and @samp{.} is used for the current default directory.
Here is an example of how to set your @code{EMACSLOADPATH} variable from
@c This overfull hbox is OK. --rjc 16mar92
@smallexample
-setenv EMACSLOADPATH .:/user/bil/emacs:/usr/lib/emacs/lisp
+setenv EMACSLOADPATH .:/user/bil/emacs:/usr/local/lib/emacs/lisp
@end smallexample
-Here is how to set it using @code{sh}:
+ Here is how to set it using @code{sh}:
@smallexample
export EMACSLOADPATH
EMACSLOADPATH=.:/user/bil/emacs:/usr/local/lib/emacs/lisp
@end smallexample
-Here is an example of code you can place in a @file{.emacs} file to add
+ Here is an example of code you can place in a @file{.emacs} file to add
several directories to the front of your default @code{load-path}:
@smallexample
@file{/usr/local/lisplib} directory, and the @file{~/emacs} directory,
which are then followed by the standard directories for Lisp code.
-Dumping Emacs uses a special value of @code{load-path}. If the value of
+ Dumping Emacs uses a special value of @code{load-path}. If the value of
@code{load-path} at the end of dumping is unchanged (that is, still the
same special value), the dumped Emacs switches to the ordinary
@code{load-path} value when it starts up, as described above. But if
@code{load-path} has any other value at the end of dumping, that value
is used for execution of the dumped Emacs also.
-Therefore, if you want to change @code{load-path} temporarily for
+ Therefore, if you want to change @code{load-path} temporarily for
loading a few libraries in @file{site-init.el} or @file{site-load.el},
you should bind @code{load-path} locally with @code{let} around the
calls to @code{load}.
-@end defopt
The default value of @code{load-path}, when running an Emacs which has
-been installed on the system, looks like this:
+been installed on the system, includes two special directories (and
+their subdirectories as well):
@smallexample
-("/usr/local/share/emacs/@var{version}/site-lisp"
- "/usr/local/share/emacs/site-lisp"
- "/usr/local/share/emacs/@var{version}/lisp")
+"/usr/local/share/emacs/@var{version}/site-lisp"
@end smallexample
- The last of these three directories is where the Lisp files of Emacs
-itself are installed; the first two are for additional Lisp packages
-installed at your site. The first directory is for locally installed
-packages that belong with a particular Emacs version; the second is for
-locally installed packages that can be used with any installed Emacs
-version.
+@noindent
+and
+
+@smallexample
+"/usr/local/share/emacs/site-lisp"
+@end smallexample
+
+@noindent
+The first one is for locally installed packages for a particular Emacs
+version; the second is for locally installed packages meant for use with
+all installed Emacs versions.
There are several reasons why a Lisp package that works well in one
Emacs version can cause trouble in another. Sometimes packages need
sometimes a newer Emacs version incorporates a version of the package,
and should be used only with that version.
+ Emacs finds these directories' subdirectories and adds them to
+@code{load-path} when it starts up. Both immediate subdirectories and
+subdirectories multiple levels down are added to @code{load-path}.
+
+ Not all subdirectories are included, though. Subdirectories whose
+names do not start with a letter or digit are excluded. Subdirectories
+named @file{RCS} are excluded. Also, a subdirectory which contains a
+file named @file{.nosearch} is excluded. You can use these methods to
+prevent certain subdirectories of the @file{site-lisp} directories from
+being searched.
+
If you run Emacs from the directory where it was built---that is, an
executable that has not been formally installed---then @code{load-path}
normally contains two additional directories. These are the @code{lisp}
and @code{site-lisp} subdirectories of the main build directory. (Both
are represented as absolute file names.)
-@defvar load-in-progress
-This variable is non-@code{nil} if Emacs is in the process of loading a
-file, and it is @code{nil} otherwise.
-@end defvar
-
-@defvar load-read-function
-This variable specifies an alternate expression-reading function for
-@code{load} and @code{eval-region} to use instead of @code{read}.
-The function should accept one argument, just as @code{read} does.
-
-Normally, the variable's value is @code{nil}, which means those
-functions should use @code{read}.
-@end defvar
-
- For 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
tells @code{locate-library} to display the file name in the echo area.
@end deffn
+@node Loading Non-ASCII
+@section Loading Non-ASCII Characters
+
+ When Emacs Lisp programs contain string constants with non-@sc{ASCII}
+characters, these can be represented within Emacs either as unibyte
+strings or as multibyte strings (@pxref{Text Representations}). Which
+representation is used depends on how the file is read into Emacs. If
+it is read with decoding into multibyte representation, the text of the
+Lisp program will be multibyte text, and its string constants will be
+multibyte strings. If a file containing Latin-1 characters (for
+example) is read without decoding, the text of the program will be
+unibyte text, and its string constants will be unibyte strings.
+@xref{Coding Systems}.
+
+ To make the results more predictable, Emacs always performs decoding
+into the multibyte representation when loading Lisp files, even if it
+was started with the @samp{--unibyte} option. This means that string
+constants with non-@sc{ASCII} characters translate into multibyte
+strings. The only exception is when a particular file specifies no
+decoding.
+
+ The reason Emacs is designed this way is so that Lisp programs give
+predictable results, regardless of how Emacs was started. In addition,
+this enables programs that depend on using multibyte text to work even
+in a unibyte Emacs. Of course, such programs should be designed to
+notice whether the user prefers unibyte or multibyte text, by checking
+@code{default-enable-multibyte-characters}, and convert representations
+appropriately.
+
+ In most Emacs Lisp programs, the fact that non-@sc{ASCII} strings are
+multibyte strings should not be noticeable, since inserting them in
+unibyte buffers converts them to unibyte automatically. However, if
+this does make a difference, you can force a particular Lisp file to be
+interpreted as unibyte by writing @samp{-*-coding: raw-text;-*-} in a
+comment on the file's first line. With that designator, the file will
+be unconditionally be interpreted as unibyte, even in an ordinary
+multibyte Emacs session.
+
@node Autoload
@section Autoload
@cindex autoload
source before the real definition. @code{autoload} is the low-level
primitive for autoloading; any Lisp program can call @code{autoload} at
any time. Magic comments are the most convenient way to make a function
-autoload, for packages installed along with Emacs. They do nothing on
-their own, but they serve as a guide for the command
+autoload, for packages installed along with Emacs. These comments do
+nothing on their own, but they serve as a guide for the command
@code{update-file-autoloads}, which constructs calls to @code{autoload}
and arranges to execute them when Emacs is built.
If @var{interactive} is non-@code{nil}, that says @var{function} can be
called interactively. This lets completion in @kbd{M-x} work without
-loading its real definition. The complete interactive specification 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.
+loading @var{function}'s real definition. The complete interactive
+specification 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.
You can autoload macros and keymaps as well as ordinary functions.
Specify @var{type} as @code{macro} if @var{function} is really a macro.
definitions or @code{provide} calls that occurred during the load are
undone. This is to ensure that the next attempt to call any function
autoloading from this file will try again to load the file. If not for
-this, then some of the functions in the file might appear defined, but
-they might fail to work properly for the lack of certain subroutines
-defined later in the file and not loaded successfully.
+this, then some of the functions in the file might be defined by the
+aborted load, but fail to work properly for the lack of certain
+subroutines not loaded successfully because they come later in the file.
If the autoloaded file fails to define the desired Lisp function or
macro, then an error is signaled with data @code{"Autoloading failed to
@findex update-file-autoloads
@findex update-directory-autoloads
- A magic autoload comment looks like @samp{;;;###autoload}, on a line
+ A magic autoload comment consists of @samp{;;;###autoload}, on a line
by itself, just before the real definition of the function in its
autoloadable source file. The command @kbd{M-x update-file-autoloads}
writes a corresponding @code{autoload} call into @file{loaddefs.el}.
@section Repeated Loading
@cindex repeated loading
- You can load one file more than once in an Emacs session. For
+ You can load a given file more than once in an Emacs session. For
example, after you have rewritten and reinstalled a function definition
by editing it in a buffer, you may wish to return to the original
version; you can do this by reloading the file it came from.
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 includes, @samp{(compiled; source is
+displayed when loading the file includes, @samp{(compiled; note, source is
newer)}, to remind you to recompile it.
When writing the forms in a Lisp library file, keep in mind that the
(cons '(leif-mode " Leif") minor-mode-alist)))
@end example
- To add an element to a list just once, use @code{add-to-list}
+ To add an element to a list just once, you can also use @code{add-to-list}
(@pxref{Setting Variables}).
Occasionally you will want to test explicitly whether a library has
@node Eval During Expansion
@subsection Evaluating Macro Arguments in Expansion
- Another problem can happen if you the macro definition itself
+ Another problem can happen if 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
exist.
To avoid these problems, @strong{don't evaluate an argument expression
-while computing the macro expansion.} Instead, substitute the
+while computing the macro expansion}. Instead, substitute the
expression into the macro expansion, so that its value will be computed
as part of executing the expansion. This is how the other examples in
this chapter work.
@vindex menu-bar-help-menu
The keymap which displays the Help menu in the menu bar.
-@tindex menu-bar-mule-menu
@item menu-bar-mule-menu
+@tindex menu-bar-mule-menu
@vindex menu-bar-mule-menu
The keymap which displays the Mule menu in the menu bar.
@end defun
@defun number-or-marker-p object
-This function returns @code{t} if @var{object} is a number (either kind)
-or a marker, @code{nil} otherwise.
+This function returns @code{t} if @var{object} is a number (either
+integer or floating point) or a marker, @code{nil} otherwise.
@end defun
@node Creating Markers
marker.
@defun make-marker
-This functions returns a newly created marker that does not point
+This function returns a newly created marker that does not point
anywhere.
@example
@code{copy-marker} returns a new marker that points to the end of the
buffer.
+@example
+@group
+(copy-marker 0)
+ @result{} #<marker at 1 in markers.texi>
+@end group
+
+@group
+(copy-marker 20000)
+ @result{} #<marker at 7572 in markers.texi>
+@end group
+@end example
+
An error is signaled if @var{marker} is neither a marker nor an
integer.
+@end defun
+
+ Two distinct markers are considered @code{equal} (even though not
+@code{eq}) to each other if they have the same position and buffer, or
+if they both point nowhere.
@example
@group
(equal p q)
@result{} t
@end group
-
-@group
-(copy-marker 0)
- @result{} #<marker at 1 in markers.texi>
-@end group
-
-@group
-(copy-marker 20000)
- @result{} #<marker at 7572 in markers.texi>
-@end group
@end example
-@end defun
@node Information from Markers
@section Information from Markers
@end example
@end defun
- Two distinct markers are considered @code{equal} (even though not
-@code{eq}) to each other if they have the same position and buffer, or
-if they both point nowhere.
-
@node Marker Insertion Types
@section Marker Insertion Types
@code{insert-before-markers} ignores markers' insertion types, always
relocating a marker to point after the inserted text.
-@tindex set-marker-insertion-type
@defun set-marker-insertion-type marker type
+@tindex set-marker-insertion-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
+@tindex marker-insertion-type
This function reports the current insertion type of @var{marker}.
@end defun
One special marker in each buffer is designated @dfn{the mark}. It
records a position for the user for the sake of commands such as
-@kbd{C-w} and @kbd{C-x @key{TAB}}. Lisp programs should set the mark
-only to values that have a potential use to the user, and never for
-their own internal purposes. For example, the @code{replace-regexp}
+@code{kill-region} and @code{indent-rigidly}. Lisp programs should set
+the mark only to values that have a potential use to the user, and never
+for their own internal purposes. For example, the @code{replace-regexp}
command sets the mark to the value of point before doing any
replacements, because this enables the user to move back there
conveniently after the replace is finished.
In most cases, you should not call minibuffer input functions in the
middle of a Lisp function. Instead, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive} spec.
-@xref{Defining Commands}.
+reading the arguments for a command, in the @code{interactive}
+specification. @xref{Defining Commands}.
@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
through the history commands. It should be a string, or @code{nil}. If
@var{read} is non-@code{nil}, then @var{default} is also used as the
input to @code{read}, if the user enters empty input. However, in the
-usual case (where @var{read} is @code{nil}, @code{read-from-minibuffer}
+usual case (where @var{read} is @code{nil}), @code{read-from-minibuffer}
does not return @var{default} when the user enters empty input; it
returns an empty string, @code{""}. In this respect, it is different
from all the other minibuffer input functions in this chapter.
properties are stripped when the value is returned.
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.
+minibuffer inherits the current buffer's input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
If @var{initial-contents} is a string, @code{read-from-minibuffer}
inserts it into the minibuffer, leaving point at the end, before the
@end defvar
@defvar file-name-history
-A history list for file name arguments.
+A history list for file-name arguments.
+@end defvar
+
+@defvar buffer-name-history
+@tindex buffer-name-history
+A history list for buffer-name arguments.
@end defvar
@defvar regexp-history
In most cases, we recommend using @var{default}, and not @var{initial}.
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}.
+minibuffer inherits the current buffer's input method (@pxref{Input
+Methods}) and the setting of @code{enable-multibyte-characters}
+(@pxref{Text Representations}) from whichever buffer was current before
+entering the minibuffer.
Completion ignores case when comparing the input against the possible
matches, if the built-in variable @code{completion-ignore-case} is
In most cases, you should not call these functions in the middle of a
Lisp function. When possible, do all minibuffer input as part of
-reading the arguments for a command, in the @code{interactive} spec.
-@xref{Defining Commands}.
+reading the arguments for a command, in the @code{interactive}
+specification. @xref{Defining Commands}.
@defun read-buffer prompt &optional default existing
This function reads the name of a buffer and returns it as a string.
This function is useful for reading passwords.
-@tindex read-password
@defun read-password prompt default
+@tindex read-password
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
(if text-mode-map
() ; @r{Do not change the keymap if it is already set up.}
(setq text-mode-map (make-sparse-keymap))
- (define-key text-mode-map "\t" 'tab-to-tab-stop)
+ (define-key text-mode-map "\t" 'indent-relative)
(define-key text-mode-map "\es" 'center-line)
(define-key text-mode-map "\eS" 'center-paragraph))
@end group
(cond (lisp-syntax
(set-syntax-table lisp-mode-syntax-table)))
(setq local-abbrev-table lisp-mode-abbrev-table)
- @dots{})
+ @dots{}
@end group
@end smallexample
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
+@tindex easy-mmode-define-minor-mode
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
other variables could have the same effects on the mode line if
@code{mode-line-format} were changed to use them.
-@tindex mode-line-mule-info
@defvar mode-line-mule-info
+@tindex mode-line-mule-info
This variable holds the value of the mode-line construct that displays
information about the language environment, buffer coding system, and
-current input method. @xref{International,,, emacs, The GNU Emacs
-Manual}.
+current input method. @xref{Non-ASCII Characters}.
@end defvar
@defvar mode-line-modified
Changing this variable does not force an update of the mode line.
@end defvar
-@tindex mode-line-frame-identification
@defvar mode-line-frame-identification
+@tindex mode-line-frame-identification
This variable identifies the current frame. The default value is
@code{" "} if you are using a window system which can show multiple
frames, or @code{"-%F "} on an ordinary terminal which shows only one
For Emacs Lisp mode, @var{pattern} could look like this:
+@c should probably use imenu-syntax-alist and \\sw rather than [-A-Za-z0-9+]
@example
@group
((nil "^\\s-*(def\\(un\\|subst\\|macro\\|advice\\)\
@end group
@group
("*Types*"
- "^\\s-*(def\\(type\\|struct\\|class\\|ine-condition\\)\
+ "^\\s-*\
+(def\\(type\\|struct\\|class\\|ine-condition\\)\
\\s-+\\([-A-Za-z0-9+]+\\)" 2))
@end group
@end example
@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 controls whether matching against
+@var{imenu-generic-expression} is case-sensitive: @code{t}, the default,
+means matching should ignore case.
+
+Setting this variable makes it buffer-local in the current buffer.
+@end defvar
+
+@defvar imenu-syntax-alist
+This variable is an alist of syntax table modifiers to use while
+executing @code{imenu--generic-function} to override the syntax table of
+the current buffer. Each element should have this form:
+
+@example
+(@var{characters} . @var{syntax-description})
+@end example
+
+The @sc{car}, @var{characters}, can be either a character or a string.
+The element says to give that character or characters the syntax
+specified by @var{syntax-description}, which is passed to
+@code{modify-syntax-entry} (@pxref{Syntax Table Functions}).
+
+This feature is typically used to give word syntax to characters which
+normally have symbol syntax, and thus to simplify
+@code{imenu-generic-expression} and speed up matching.
+For example, Fortran mode uses it this way:
+
+@example
+ (setq imenu-syntax-alist '(("_$" . "w")))
+@end example
+
+The @code{imenu-generic-expression} patterns can then use @samp{\\sw+}
+instead of @samp{\\(\\sw\\|\\s_\\)\\}. Note that this technique may be
+inconvenient to use when the mode needs to limit the initial character
+of a name to a smaller set of characters
Setting this variable makes it buffer-local in the current buffer.
@end defvar
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},
+variable @code{font-lock-keywords-only}. If this is non-@code{nil},
syntactic fontification (of strings and comments) is not performed.
The third element, @var{case-fold}, specifies the value of
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.
+to initialize 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
@end defvar
@ignore
-Other variables include those for buffer-specialised fontification functions,
+Other variables include those for buffer-specialized 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 example
@end defun
+@defun run-hook-with-args hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions. It calls each of the hook functions, passing
+each of them the arguments @var{args}.
+@end defun
+
+@defun run-hook-with-args-until-failure hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions, and stops as soon as any hook function fails. It
+calls each of the hook functions, passing each of them the arguments
+@var{args}, until some hook function returns @code{nil}. Then it stops.
+@end defun
+
+@defun run-hook-with-args-until-success hook &rest args
+This function is the way to run an abnormal hook which passes arguments
+to the hook functions, and stops as soon as any hook function succeeds.
+It calls each of the hook functions, passing each of them the arguments
+@var{args}, until some hook function returns non-@code{nil}. Then it
+stops.
+@end defun
+
@defun add-hook hook function &optional append local
This function is the handy way to add function @var{function} to hook
variable @var{hook}. The argument @var{function} may be any valid Lisp
* Selecting a Representation::
* Character Codes::
* Character Sets::
-* Scanning Charsets::
* Chars and Bytes::
+* Splitting Characters::
+* Scanning Charsets::
+* Translation of Characters::
* Coding Systems::
-* Lisp and Coding System::
-* Default Coding Systems::
-* Specifying Coding Systems::
-* Explicit Encoding::
-* MS-DOS File Types::
-* MS-DOS Subprocesses::
+* Input Methods::
@end menu
@node Text Representations
byte, and as a result, the full range of Emacs character codes can be
stored. The first byte of a multibyte character is always in the range
128 through 159 (octal 0200 through 0237). These values are called
-@dfn{leading codes}. The first byte determines which character set the
-character belongs to (@pxref{Character Sets}); in particular, it
-determines how many bytes long the sequence is. The second and
-subsequent bytes of a multibyte character are always in the range 160
-through 255 (octal 0240 through 0377).
+@dfn{leading codes}. The second and subsequent bytes of a multibyte
+character are always in the range 160 through 255 (octal 0240 through
+0377).
In a buffer, the buffer-local value of the variable
@code{enable-multibyte-characters} specifies the representation used.
The representation for a string is determined based on the string
contents when the string is constructed.
-@tindex enable-multibyte-characters
@defvar enable-multibyte-characters
+@tindex enable-multibyte-characters
This variable specifies the current buffer's text representation.
If it is non-@code{nil}, the buffer contains multibyte text; otherwise,
it contains unibyte text.
@code{set-buffer-multibyte} to change a buffer's representation.
@end defvar
-@tindex default-enable-multibyte-characters
@defvar default-enable-multibyte-characters
-This variable`s value is entirely equivalent to @code{(default-value
+@tindex default-enable-multibyte-characters
+This variable's value is entirely equivalent to @code{(default-value
'enable-multibyte-characters)}, and setting this variable changes that
-default value. Although setting the local binding of
-@code{enable-multibyte-characters} in a specific buffer is dangerous,
-changing the default value is safe, and it is a reasonable thing to do.
+default value. Setting the local binding of
+@code{enable-multibyte-characters} in a specific buffer is not allowed,
+but changing the default value is supported, and it is a reasonable
+thing to do, because it has no effect on existing buffers.
The @samp{--unibyte} command line option does its job by setting the
default value to @code{nil} early in startup.
@end defvar
-@tindex multibyte-string-p
@defun multibyte-string-p string
+@tindex multibyte-string-p
Return @code{t} if @var{string} contains multibyte characters.
@end defun
unchanged, and likewise 128 through 159. It converts the non-@sc{ASCII}
codes 160 through 255 by adding the value @code{nonascii-insert-offset}
to each character code. By setting this variable, you specify which
-character set the unibyte characters correspond to. For example, if
-@code{nonascii-insert-offset} is 2048, which is @code{(- (make-char
-'latin-iso8859-1 0) 128)}, then the unibyte non-@sc{ASCII} characters
-correspond to Latin 1. If it is 2688, which is @code{(- (make-char
-'greek-iso8859-7 0) 128)}, then they correspond to Greek letters.
+character set the unibyte characters correspond to (@pxref{Character
+Sets}). For example, if @code{nonascii-insert-offset} is 2048, which is
+@code{(- (make-char 'latin-iso8859-1) 128)}, then the unibyte
+non-@sc{ASCII} characters correspond to Latin 1. If it is 2688, which
+is @code{(- (make-char 'greek-iso8859-7) 128)}, then they correspond to
+Greek letters.
Converting multibyte text to unibyte is simpler: it performs
logical-and of each character code with 255. If
the other: converting unibyte text to multibyte and back to unibyte
reproduces the original unibyte text.
-@tindex nonascii-insert-offset
@defvar nonascii-insert-offset
+@tindex nonascii-insert-offset
This variable specifies the amount to add to a non-@sc{ASCII} character
when converting unibyte text to multibyte. It also applies when
-@code{insert-char} or @code{self-insert-command} inserts a character in
-the unibyte non-@sc{ASCII} range, 128 through 255.
+@code{self-insert-command} inserts a character in the unibyte
+non-@sc{ASCII} range, 128 through 255. However, the function
+@code{insert-char} does not perform this conversion.
The right value to use to select character set @var{cs} is @code{(-
-(make-char @var{cs} 0) 128)}. If the value of
+(make-char @var{cs}) 128)}. If the value of
@code{nonascii-insert-offset} is zero, then conversion actually uses the
value for the Latin 1 character set, rather than zero.
@end defvar
-@tindex nonascii-translate-table
-@defvar nonascii-translate-table
+@defvar nonascii-translation-table
+@tindex nonascii-translation-table
This variable provides a more general alternative to
@code{nonascii-insert-offset}. You can use it to specify independently
how to translate each code in the range of 128 through 255 into a
If this is non-@code{nil}, it overrides @code{nonascii-insert-offset}.
@end defvar
-@tindex string-make-unibyte
@defun string-make-unibyte string
+@tindex string-make-unibyte
This function converts the text of @var{string} to unibyte
representation, if it isn't already, and return the result. If
@var{string} is a unibyte string, it is returned unchanged.
@end defun
-@tindex string-make-multibyte
@defun string-make-multibyte string
+@tindex string-make-multibyte
This function converts the text of @var{string} to multibyte
representation, if it isn't already, and return the result. If
@var{string} is a multibyte string, it is returned unchanged.
Sometimes it is useful to examine an existing buffer or string as
multibyte when it was unibyte, or vice versa.
-@tindex set-buffer-multibyte
@defun set-buffer-multibyte multibyte
+@tindex set-buffer-multibyte
Set the representation type of the current buffer. If @var{multibyte}
is non-@code{nil}, the buffer becomes multibyte. If @var{multibyte}
is @code{nil}, the buffer becomes unibyte.
same text as they did before.
@end defun
-@tindex string-as-unibyte
@defun string-as-unibyte string
+@tindex string-as-unibyte
This function returns a string with the same bytes as @var{string} but
treating each byte as a character. This means that the value may have
more characters than @var{string} has.
itself.
@end defun
-@tindex string-as-multibyte
@defun string-as-multibyte string
+@tindex string-as-multibyte
This function returns a string with the same bytes as @var{string} but
treating each multibyte sequence as one character. This means that the
value may have fewer characters than @var{string} has.
@code{greek-iso8859-7} is another, and @code{ascii} is another. An
Emacs character set can hold at most 9025 characters; therefore, in some
cases, characters that would logically be grouped together are split
-into several character sets. For example, one set of Chinese characters
-is divided into eight Emacs character sets, @code{chinese-cns11643-1}
-through @code{chinese-cns11643-7}.
+into several character sets. For example, one set of Chinese
+characters, generally known as Big 5, is divided into two Emacs
+character sets, @code{chinese-big5-1} and @code{chinese-big5-2}.
-@tindex charsetp
@defun charsetp object
+@tindex charsetp
Return @code{t} if @var{object} is a character set name symbol,
@code{nil} otherwise.
@end defun
-@tindex charset-list
@defun charset-list
+@tindex charset-list
This function returns a list of all defined character set names.
@end defun
-@tindex char-charset
@defun char-charset character
-This function returns the the name of the character
+@tindex char-charset
+This function returns the name of the character
set that @var{character} belongs to.
@end defun
-@node Scanning Charsets
-@section Scanning for Character Sets
-
- Sometimes it is useful to find out which character sets appear in a
-part of a buffer or a string. One use for this is in determining which
-coding systems (@pxref{Coding Systems}) are capable of representing all
-of the text in question.
-
-@tindex find-charset-region
-@defun find-charset-region beg end &optional unification
-This function returns a list of the character sets
-that appear in the current buffer between positions @var{beg}
-and @var{end}.
-@end defun
-
-@tindex find-charset-string
-@defun find-charset-string string &optional unification
-This function returns a list of the character sets
-that appear in the string @var{string}.
-@end defun
-
@node Chars and Bytes
@section Characters and Bytes
@cindex bytes and characters
+@cindex introduction sequence
+@cindex dimension (of character set)
In multibyte representation, each character occupies one or more
-bytes. The functions in this section convert between characters and the
-byte values used to represent them. For most purposes, there is no need
-to be concerned with the number of bytes used to represent a character
+bytes. Each character set has an @dfn{introduction sequence}, which is
+one or two bytes long. The introduction sequence is the beginning of
+the byte sequence for any character in the character set. (The
+@sc{ASCII} character set has a zero-length introduction sequence.) The
+rest of the character's bytes distinguish it from the other characters
+in the same character set. Depending on the character set, there are
+either one or two distinguishing bytes; the number of such bytes is
+called the @dfn{dimension} of the character set.
+
+@defun charset-dimension charset
+@tindex charset-dimension
+This function returns the dimension of @var{charset};
+At present, the dimension is always 1 or 2.
+@end defun
+
+ This is the simplest way to determine the byte length of a character
+set's introduction sequence:
+
+@example
+(- (char-bytes (make-char @var{charset}))
+ (charset-dimension @var{charset}))
+@end example
+
+@node Splitting Characters
+@section Splitting Characters
+
+ The functions in this section convert between characters and the byte
+values used to represent them. For most purposes, there is no need to
+be concerned with the sequence of bytes used to represent a character,
because Emacs translates automatically when necessary.
-@tindex char-bytes
@defun char-bytes character
+@tindex char-bytes
This function returns the number of bytes used to represent the
-character @var{character}. In most cases, this is the same as
-@code{(length (split-char @var{character}))}; the only exception is for
-ASCII characters and the codes used in unibyte text, which use just one
-byte.
+character @var{character}. This depends only on the character set that
+@var{character} belongs to; it equals the dimension of that character
+set (@pxref{Character Sets}), plus the length of its introduction
+sequence.
@example
(char-bytes 2248)
@result{} 2
(char-bytes 65)
@result{} 1
-@end example
-
-This function's values are correct for both multibyte and unibyte
-representations, because the non-@sc{ASCII} character codes used in
-those two representations do not overlap.
-
-@example
(char-bytes 192)
@result{} 1
@end example
+
+The reason this function can give correct results for both multibyte and
+unibyte representations is that the non-@sc{ASCII} character codes used
+in those two representations do not overlap.
@end defun
-@tindex split-char
@defun split-char character
+@tindex split-char
Return a list containing the name of the character set of
-@var{character}, followed by one or two byte-values which identify
-@var{character} within that character set.
+@var{character}, followed by one or two byte values (integers) which
+identify @var{character} within that character set. The number of byte
+values is the character set's dimension.
@example
(split-char 2248)
@end example
@end defun
-@tindex make-char
@defun make-char charset &rest byte-values
-Thus function returns the character in character set @var{charset}
-identified by @var{byte-values}. This is roughly the opposite of
-split-char.
+@tindex make-char
+This function returns the character in character set @var{charset}
+identified by @var{byte-values}. This is roughly the inverse of
+@code{split-char}. Normally, you should specify either one or two
+@var{byte-values}, according to the dimension of @var{charset}. For
+example,
@example
(make-char 'latin-iso8859-1 72)
@end example
@end defun
+@cindex generic characters
+ If you call @code{make-char} with no @var{byte-values}, the result is
+a @dfn{generic character} which stands for @var{charset}. A generic
+character is an integer, but it is @emph{not} valid for insertion in the
+buffer as a character. It can be used in @code{char-table-range} to
+refer to the whole character set (@pxref{Char-Tables}).
+@code{char-valid-p} returns @code{nil} for generic characters.
+For example:
+
+@example
+(make-char 'latin-iso8859-1)
+ @result{} 2176
+(char-valid-p 2176)
+ @result{} nil
+(split-char 2176)
+ @result{} (latin-iso8859-1 0)
+@end example
+
+@node Scanning Charsets
+@section Scanning for Character Sets
+
+ Sometimes it is useful to find out which character sets appear in a
+part of a buffer or a string. One use for this is in determining which
+coding systems (@pxref{Coding Systems}) are capable of representing all
+of the text in question.
+
+@defun find-charset-region beg end &optional translation
+@tindex find-charset-region
+This function returns a list of the character sets that appear in the
+current buffer between positions @var{beg} and @var{end}.
+
+The optional argument @var{translation} specifies a translation table to
+be used in scanning the text (@pxref{Translation of Characters}). If it
+is non-@code{nil}, then each character in the region is translated
+through this table, and the value returned describes the translated
+characters instead of the characters actually in the buffer.
+@end defun
+
+@defun find-charset-string string &optional translation
+@tindex find-charset-string
+This function returns a list of the character sets
+that appear in the string @var{string}.
+
+The optional argument @var{translation} specifies a
+translation table; see @code{find-charset-region}, above.
+@end defun
+
+@node Translation of Characters
+@section Translation of Characters
+@cindex character translation tables
+@cindex translation tables
+
+ A @dfn{translation table} specifies a mapping of characters
+into characters. These tables are used in encoding and decoding, and
+for other purposes. Some coding systems specify their own particular
+translation tables; there are also default translation tables which
+apply to all other coding systems.
+
+@defun make-translation-table translations
+This function returns a translation table based on the arguments
+@var{translations}. Each argument---each element of
+@var{translations}---should be a list of the form @code{(@var{from}
+. @var{to})}; this says to translate the character @var{from} into
+@var{to}.
+
+You can also map one whole character set into another character set with
+the same dimension. To do this, you specify a generic character (which
+designates a character set) for @var{from} (@pxref{Splitting Characters}).
+In this case, @var{to} should also be a generic character, for another
+character set of the same dimension. Then the translation table
+translates each character of @var{from}'s character set into the
+corresponding character of @var{to}'s character set.
+@end defun
+
+ In decoding, the translation table's translations are applied to the
+characters that result from ordinary decoding. If a coding system has
+property @code{character-translation-table-for-decode}, that specifies
+the translation table to use. Otherwise, if
+@code{standard-character-translation-table-for-decode} is
+non-@code{nil}, decoding uses that table.
+
+ In encoding, the translation table's translations are applied to the
+characters in the buffer, and the result of translation is actually
+encoded. If a coding system has property
+@code{character-translation-table-for-encode}, that specifies the
+translation table to use. Otherwise the variable
+@code{standard-character-translation-table-for-encode} specifies the
+translation table.
+
+@defvar standard-character-translation-table-for-decode
+This is the default translation table for decoding, for
+coding systems that don't specify any other translation table.
+@end defvar
+
+@defvar standard-character-translation-table-for-encode
+This is the default translation table for encoding, for
+coding systems that don't specify any other translation table.
+@end defvar
+
@node Coding Systems
@section Coding Systems
character code conversion and end-of-line conversion as specified
by a particular @dfn{coding system}.
+@menu
+* Coding System Basics::
+* Encoding and I/O::
+* Lisp and Coding Systems::
+* Default Coding Systems::
+* Specifying Coding Systems::
+* Explicit Encoding::
+* Terminal I/O Encoding::
+* MS-DOS File Types::
+@end menu
+
+@node Coding System Basics
+@subsection Basic Concepts of Coding Systems
+
@cindex character code conversion
@dfn{Character code conversion} involves conversion between the encoding
used inside Emacs and some other encoding. Emacs supports many
conversion unspecified, to be chosen based on the data. @dfn{Variant
coding systems} such as @code{latin-1-unix}, @code{latin-1-dos} and
@code{latin-1-mac} specify the end-of-line conversion explicitly as
-well. Each base coding system has three corresponding variants whose
+well. Most base coding systems have three corresponding variants whose
names are formed by adding @samp{-unix}, @samp{-dos} and @samp{-mac}.
+ The coding system @code{raw-text} is special in that it prevents
+character code conversion, and causes the buffer visited with that
+coding system to be a unibyte buffer. It does not specify the
+end-of-line conversion, allowing that to be determined as usual by the
+data, and has the usual three variants which specify the end-of-line
+conversion. @code{no-conversion} is equivalent to @code{raw-text-unix}:
+it specifies no conversion of either character codes or end-of-line.
+
+ The coding system @code{emacs-mule} specifies that the data is
+represented in the internal Emacs encoding. This is like
+@code{raw-text} in that no code conversion happens, but different in
+that the result is multibyte data.
+
+@defun coding-system-get coding-system property
+@tindex coding-system-get
+This function returns the specified property of the coding system
+@var{coding-system}. Most coding system properties exist for internal
+purposes, but one that you might find useful is @code{mime-charset}.
+That property's value is the name used in MIME for the character coding
+which this coding system can read and write. Examples:
+
+@example
+(coding-system-get 'iso-latin-1 'mime-charset)
+ @result{} iso-8859-1
+(coding-system-get 'iso-2022-cn 'mime-charset)
+ @result{} iso-2022-cn
+(coding-system-get 'cyrillic-koi8 'mime-charset)
+ @result{} koi8-r
+@end example
+
+The value of the @code{mime-charset} property is also defined
+as an alias for the coding system.
+@end defun
+
+@node Encoding and I/O
+@subsection Encoding and I/O
+
+ The principal purpose coding systems is for use in reading and
+writing files. The function @code{insert-file-contents} uses
+a coding system for decoding the file data, and @code{write-region}
+uses one to encode the buffer contents.
+
+ You can specify the coding system to use either explicitly
+(@pxref{Specifying Coding Systems}), or implicitly using the defaulting
+mechanism (@pxref{Default Coding Systems}). But these methods may not
+completely specify what to do. For example, they may choose a coding
+system such as @code{undefined} which leaves the character code
+conversion to be determined from the data. In these cases, the I/O
+operation finishes the job of choosing a coding system. Very often
+you will want to find out afterwards which coding system was chosen.
+
+@defvar buffer-file-coding-system
+@tindex buffer-file-coding-system
+This variable records the coding system that was used for visiting the
+current buffer. It is used for saving the buffer, and for writing part
+of the buffer with @code{write-region}. When those operations ask the
+user to specify a different coding system,
+@code{buffer-file-coding-system} is updated to the coding system
+specified.
+@end defvar
+
+@defvar save-buffer-coding-system
+@tindex save-buffer-coding-system
+This variable specifies the coding system for saving the buffer---but it
+is not used for @code{write-region}. When saving the buffer asks the
+user to specify a different coding system, and
+@code{save-buffer-coding-system} was used, then it is updated to the
+coding system that was specified.
+@end defvar
+
+@defvar last-coding-system-used
+@tindex last-coding-system-used
+I/O operations for files and subprocesses set this variable to the
+coding system name that was used. The explicit encoding and decoding
+functions (@pxref{Explicit Encoding}) set it too.
+
+@strong{Warning:} Since receiving subprocess output sets this variable,
+it can change whenever Emacs waits; therefore, you should use copy the
+value shortly after the function call which stores the value you are
+interested in.
+@end defvar
+
@node Lisp and Coding Systems
@subsection Coding Systems in Lisp
Here are Lisp facilities for working with coding systems;
-@tindex coding-system-list
@defun coding-system-list &optional base-only
+@tindex coding-system-list
This function returns a list of all coding system names (symbols). If
@var{base-only} is non-@code{nil}, the value includes only the
base coding systems. Otherwise, it includes variant coding systems as well.
@end defun
-@tindex coding-system-p
@defun coding-system-p object
+@tindex coding-system-p
This function returns @code{t} if @var{object} is a coding system
name.
@end defun
-@tindex check-coding-system
@defun check-coding-system coding-system
+@tindex check-coding-system
This function checks the validity of @var{coding-system}.
If that is valid, it returns @var{coding-system}.
Otherwise it signals an error with condition @code{coding-system-error}.
@end defun
-@tindex find-safe-coding-system
-@defun find-safe-coding-system from to
-Return a list of proper coding systems to encode a text between
-@var{from} and @var{to}. All coding systems in the list can safely
-encode any multibyte characters in the text.
+@defun coding-system-change-eol-conversion coding-system eol-type
+@tindex coding-system-change-eol-conversion
+This function returns a coding system which is like @var{coding-system}
+except for its in eol conversion, which is specified by @code{eol-type}.
+@var{eol-type} should be @code{unix}, @code{dos}, @code{mac}, or
+@code{nil}. If it is @code{nil}, the returned coding system determines
+the end-of-line conversion from the data.
+@end defun
-If the text contains no multibyte characters, return a list of a single
-element @code{undecided}.
+@defun coding-system-change-text-conversion eol-coding text-coding
+@tindex coding-system-change-text-conversion
+This function returns a coding system which uses the end-of-line
+conversion of @var{eol-coding}, and the text conversion of
+@var{text-coding}. If @var{text-coding} is @code{nil}, it returns
+@code{undecided}, or one of its variants according to @var{eol-coding}.
@end defun
+@defun find-coding-systems-region from to
+@tindex find-coding-systems-region
+This function returns a list of coding systems that could be used to
+encode a text between @var{from} and @var{to}. All coding systems in
+the list can safely encode any multibyte characters in that portion of
+the text.
+
+If the text contains no multibyte characters, the function returns the
+list @code{(undecided)}.
+@end defun
+
+@defun find-coding-systems-string string
+@tindex find-coding-systems-string
+This function returns a list of coding systems that could be used to
+encode the text of @var{string}. All coding systems in the list can
+safely encode any multibyte characters in @var{string}. If the text
+contains no multibyte characters, this returns the list
+@code{(undecided)}.
+@end defun
+
+@defun find-coding-systems-for-charsets charsets
+@tindex find-coding-systems-for-charsets
+This function returns a list of coding systems that could be used to
+encode all the character sets in the list @var{charsets}.
+@end defun
+
+@defun detect-coding-region start end &optional highest
@tindex detect-coding-region
-@defun detect-coding-region start end highest
This function chooses a plausible coding system for decoding the text
from @var{start} to @var{end}. This text should be ``raw bytes''
(@pxref{Explicit Encoding}).
-Normally this function returns is a list of coding systems that could
+Normally this function returns a list of coding systems that could
handle decoding the text that was scanned. They are listed in order of
-decreasing priority, based on the priority specified by the user with
-@code{prefer-coding-system}. But if @var{highest} is non-@code{nil},
-then the return value is just one coding system, the one that is highest
-in priority.
+decreasing priority. But if @var{highest} is non-@code{nil}, then the
+return value is just one coding system, the one that is highest in
+priority.
+
+If the region contains only @sc{ASCII} characters, the value
+is @code{undecided} or @code{(undecided)}.
@end defun
-@tindex detect-coding-string string highest
-@defun detect-coding-string
+@defun detect-coding-string string highest
+@tindex detect-coding-string
This function is like @code{detect-coding-region} except that it
operates on the contents of @var{string} instead of bytes in the buffer.
-@end defun
-
-@defun find-operation-coding-system operation &rest arguments
-This function returns the coding system to use (by default) for
-performing @var{operation} with @var{arguments}. The value has this
-form:
-
-@example
-(@var{decoding-system} @var{encoding-system})
-@end example
-
-The first element, @var{decoding-system}, is the coding system to use
-for decoding (in case @var{operation} does decoding), and
-@var{encoding-system} is the coding system for encoding (in case
-@var{operation} does encoding).
-
-The argument @var{operation} should be an Emacs I/O primitive:
-@code{insert-file-contents}, @code{write-region}, @code{call-process},
-@code{call-process-region}, @code{start-process}, or
-@code{open-network-stream}.
-
-The remaining arguments should be the same arguments that might be given
-to that I/O primitive. Depending on which primitive, one of those
-arguments is selected as the @dfn{target}. For example, if
-@var{operation} does file I/O, whichever argument specifies the file
-name is the target. For subprocess primitives, the process name is the
-target. For @code{open-network-stream}, the target is the service name
-or port number.
-
-This function looks up the target in @code{file-coding-system-alist},
-@code{process-coding-system-alist}, or
-@code{network-coding-system-alist}, depending on @var{operation}.
-@xref{Default Coding Systems}.
@end defun
Here are two functions you can use to let the user specify a coding
system, with completion. @xref{Completion}.
+@defun read-coding-system prompt &optional default
@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 enters null input, @var{default} specifies which coding system
to return. It should be a symbol or a string.
@end defun
-@tindex read-non-nil-coding-system
@defun read-non-nil-coding-system prompt
+@tindex read-non-nil-coding-system
This function reads a coding system using the minibuffer, prompting with
-string @var{prompt},and returns the coding system name as a symbol. If
+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
+ @xref{Process Information}, for how to examine or set the coding
+systems used for I/O to a subprocess.
+
@node Default Coding Systems
-@section Default Coding Systems
+@subsection Default Coding Systems
- These variable specify which coding system to use by default for
-certain files or when running certain subprograms. The idea of these
-variables is that you set them once and for all to the defaults you
-want, and then do not change them again. To specify a particular coding
-system for a particular operation in a Lisp program, don't change these
-variables; instead, override them using @code{coding-system-for-read}
-and @code{coding-system-for-write} (@pxref{Specifying Coding Systems}).
+ This section describes variables that specify the default coding
+system for certain files or when running certain subprograms, and the
+function which which I/O operations use to access them.
+
+ The idea of these variables is that you set them once and for all to the
+defaults you want, and then do not change them again. To specify a
+particular coding system for a particular operation in a Lisp program,
+don't change these variables; instead, override them using
+@code{coding-system-for-read} and @code{coding-system-for-write}
+(@pxref{Specifying Coding Systems}).
-@tindex file-coding-system-alist
@defvar file-coding-system-alist
+@tindex file-coding-system-alist
This variable is an alist that specifies the coding systems to use for
reading and writing particular files. Each element has the form
@code{(@var{pattern} . @var{coding})}, where @var{pattern} is a regular
as described above.
@end defvar
-@tindex process-coding-system-alist
@defvar process-coding-system-alist
+@tindex process-coding-system-alist
This variable is an alist specifying which coding systems to use for a
subprocess, depending on which program is running in the subprocess. It
works like @code{file-coding-system-alist}, except that @var{pattern} is
other coding systems later using @code{set-process-coding-system}.
@end defvar
-@tindex network-coding-system-alist
+ @strong{Warning:} Coding systems such as @code{undecided} which
+determine the coding system from the data do not work entirely reliably
+with asynchronous subprocess output. This is because Emacs processes
+asynchronous subprocess output in batches, as it arrives. If the coding
+system leaves the character code conversion unspecified, or leaves the
+end-of-line conversion unspecified, Emacs must try to detect the proper
+conversion from one batch at a time, and this does not always work.
+
+ Therefore, with an asynchronous subprocess, if at all possible, use a
+coding system which determines both the character code conversion and
+the end of line conversion---that is, one like @code{latin-1-unix},
+rather than @code{undecided} or @code{latin-1}.
+
@defvar network-coding-system-alist
+@tindex network-coding-system-alist
This variable is an alist that specifies the coding system to use for
network streams. It works much like @code{file-coding-system-alist},
with the difference that the @var{pattern} in an element may be either a
stream.
@end defvar
-@tindex default-process-coding-system
@defvar default-process-coding-system
+@tindex default-process-coding-system
This variable specifies the coding systems to use for subprocess (and
network stream) input and output, when nothing else specifies what to
do.
-The value should be a cons cell of the form @code{(@var{output-coding}
-. @var{input-coding})}. Here @var{output-coding} applies to output to
-the subprocess, and @var{input-coding} applies to input from it.
+The value should be a cons cell of the form @code{(@var{input-coding}
+. @var{output-coding})}. Here @var{input-coding} applies to input from
+the subprocess, and @var{output-coding} applies to output to it.
@end defvar
+@defun find-operation-coding-system operation &rest arguments
+@tindex find-operation-coding-system
+This function returns the coding system to use (by default) for
+performing @var{operation} with @var{arguments}. The value has this
+form:
+
+@example
+(@var{decoding-system} @var{encoding-system})
+@end example
+
+The first element, @var{decoding-system}, is the coding system to use
+for decoding (in case @var{operation} does decoding), and
+@var{encoding-system} is the coding system for encoding (in case
+@var{operation} does encoding).
+
+The argument @var{operation} should be an Emacs I/O primitive:
+@code{insert-file-contents}, @code{write-region}, @code{call-process},
+@code{call-process-region}, @code{start-process}, or
+@code{open-network-stream}.
+
+The remaining arguments should be the same arguments that might be given
+to that I/O primitive. Depending on which primitive, one of those
+arguments is selected as the @dfn{target}. For example, if
+@var{operation} does file I/O, whichever argument specifies the file
+name is the target. For subprocess primitives, the process name is the
+target. For @code{open-network-stream}, the target is the service name
+or port number.
+
+This function looks up the target in @code{file-coding-system-alist},
+@code{process-coding-system-alist}, or
+@code{network-coding-system-alist}, depending on @var{operation}.
+@xref{Default Coding Systems}.
+@end defun
+
@node Specifying Coding Systems
-@section Specifying a Coding System for One Operation
+@subsection Specifying a Coding System for One Operation
You can specify the coding system for a specific operation by binding
the variables @code{coding-system-for-read} and/or
@code{coding-system-for-write}.
-@tindex coding-system-for-read
@defvar coding-system-for-read
+@tindex coding-system-for-read
If this variable is non-@code{nil}, it specifies the coding system to
use for reading a file, or for input from a synchronous subprocess.
@end example
When its value is non-@code{nil}, @code{coding-system-for-read} takes
-precedence all other methods of specifying a coding system to use for
+precedence over all other methods of specifying a coding system to use for
input, including @code{file-coding-system-alist},
@code{process-coding-system-alist} and
@code{network-coding-system-alist}.
@end defvar
-@tindex coding-system-for-write
@defvar coding-system-for-write
+@tindex coding-system-for-write
This works much like @code{coding-system-for-read}, except that it
applies to output rather than input. It affects writing to files,
subprocesses, and net connections.
affect it.
@end defvar
-@tindex last-coding-system-used
-@defvar last-coding-system-used
-All I/O operations that use a coding system set this variable
-to the coding system name that was used.
-@end defvar
-
-@tindex inhibit-eol-conversion
@defvar inhibit-eol-conversion
+@tindex inhibit-eol-conversion
When this variable is non-@code{nil}, no end-of-line conversion is done,
no matter which coding system is specified. This applies to all the
Emacs I/O and subprocess primitives, and to the explicit encoding and
decoding functions (@pxref{Explicit Encoding}).
@end defvar
-@tindex keyboard-coding-system
-@defun keyboard-coding-system
-This function returns the coding system that is in use for decoding
-keyboard input---or @code{nil} if no coding system is to be used.
-@end defun
-
-@tindex set-keyboard-coding-system
-@defun set-keyboard-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to
-use for decoding keyboard input. If @var{coding-system} is @code{nil},
-that means do not decode keyboard input.
-@end defun
-
-@tindex terminal-coding-system
-@defun terminal-coding-system
-This function returns the coding system that is in use for encoding
-terminal output---or @code{nil} for no encoding.
-@end defun
-
-@tindex set-terminal-coding-system
-@defun set-terminal-coding-system coding-system
-This function specifies @var{coding-system} as the coding system to use
-for encoding terminal output. If @var{coding-system} is @code{nil},
-that means do not encode terminal output.
-@end defun
-
- See also the functions @code{process-coding-system} and
-@code{set-process-coding-system}. @xref{Process Information}.
-
- See also @code{read-coding-system} in @ref{High-Level Completion}.
-
@node Explicit Encoding
-@section Explicit Encoding and Decoding
+@subsection Explicit Encoding and Decoding
@cindex encoding text
@cindex decoding text
suppress encoding for that @code{write-region} call by binding
@code{coding-system-for-write} to @code{no-conversion}.
-@tindex encode-coding-region
@defun encode-coding-region start end coding-system
+@tindex encode-coding-region
This function encodes the text from @var{start} to @var{end} according
to coding system @var{coding-system}. The encoded text replaces the
original text in the buffer. The result of encoding is ``raw bytes,''
but the buffer remains multibyte if it was multibyte before.
@end defun
-@tindex encode-coding-string
@defun encode-coding-string string coding-system
+@tindex encode-coding-string
This function encodes the text in @var{string} according to coding
system @var{coding-system}. It returns a new string containing the
encoded text. The result of encoding is a unibyte string of ``raw bytes.''
@end defun
-@tindex decode-coding-region
@defun decode-coding-region start end coding-system
+@tindex decode-coding-region
This function decodes the text from @var{start} to @var{end} according
to coding system @var{coding-system}. The decoded text replaces the
original text in the buffer. To make explicit decoding useful, the text
before decoding ought to be ``raw bytes.''
@end defun
-@tindex decode-coding-string
@defun decode-coding-string string coding-system
+@tindex decode-coding-string
This function decodes the text in @var{string} according to coding
system @var{coding-system}. It returns a new string containing the
decoded text. To make explicit decoding useful, the contents of
@var{string} ought to be ``raw bytes.''
@end defun
+@node Terminal I/O Encoding
+@subsection Terminal I/O Encoding
+
+ Emacs can decode keyboard input using a coding system, and encode
+terminal output. This kind of decoding and encoding does not set
+@code{last-coding-system-used}.
+
+@defun keyboard-coding-system
+@tindex keyboard-coding-system
+This function returns the coding system that is in use for decoding
+keyboard input---or @code{nil} if no coding system is to be used.
+@end defun
+
+@defun set-keyboard-coding-system coding-system
+@tindex set-keyboard-coding-system
+This function specifies @var{coding-system} as the coding system to
+use for decoding keyboard input. If @var{coding-system} is @code{nil},
+that means do not decode keyboard input.
+@end defun
+
+@defun terminal-coding-system
+@tindex terminal-coding-system
+This function returns the coding system that is in use for encoding
+terminal output---or @code{nil} for no encoding.
+@end defun
+
+@defun set-terminal-coding-system coding-system
+@tindex set-terminal-coding-system
+This function specifies @var{coding-system} as the coding system to use
+for encoding terminal output. If @var{coding-system} is @code{nil},
+that means do not encode terminal output.
+@end defun
+
@node MS-DOS File Types
-@section MS-DOS File Types
+@subsection MS-DOS File Types
@cindex DOS file types
@cindex MS-DOS file types
@cindex Windows file types
@cindex binary files and text files
Emacs on MS-DOS and on MS-Windows recognizes certain file names as
-text files or binary files. For a text file, Emacs always uses DOS
-end-of-line conversion. For a binary file, Emacs does no end-of-line
-conversion and no character code conversion.
+text files or binary files. By ``binary file'' we mean a file of
+literal byte values that are not necessary meant to be characters.
+Emacs does no end-of-line conversion and no character code conversion
+for a binary file. Meanwhile, when you create a new file which is
+marked by its name as a ``text file'', Emacs uses DOS end-of-line
+conversion.
@defvar buffer-file-type
This variable, automatically buffer-local in each buffer, records the
-file type of the buffer's visited file. The value is @code{nil} for
-text, @code{t} for binary. When a buffer does not specify a coding
-system with @code{buffer-file-coding-system}, this variable is used by
-the function @code{find-buffer-file-type-coding-system} to determine
-which coding system to use when writing the contents of the buffer.
+file type of the buffer's visited file. When a buffer does not specify
+a coding system with @code{buffer-file-coding-system}, this variable is
+used to determine which coding system to use when writing the contents
+of the buffer. It should be @code{nil} for text, @code{t} for binary.
+If it is @code{t}, the coding system is @code{no-conversion}.
+Otherwise, @code{undecided-dos} is used.
+
+Normally this variable is set by visiting a file; it is set to
+@code{nil} if the file was visited without any actual conversion.
@end defvar
@defopt file-name-buffer-file-type-alist
@code{file-name-buffer-file-type-alist} says nothing about the type.
If this variable is non-@code{nil}, then these files are treated as
-binary. Otherwise, nothing special is done for them---the coding system
-is deduced solely from the file contents, in the usual Emacs fashion.
+binary: the coding system @code{no-conversion} is used. Otherwise,
+nothing special is done for them---the coding system is deduced solely
+from the file contents, in the usual Emacs fashion.
@end defopt
-@node MS-DOS Subprocesses
-@section MS-DOS Subprocesses
-
- On Microsoft operating systems, these variables provide an alternative
-way to specify the kind of end-of-line conversion to use for input and
-output. The variable @code{binary-process-input} applies to input sent
-to the subprocess, and @code{binary-process-output} applies to output
-received from it. A non-@code{nil} value means the data is ``binary,''
-and @code{nil} means the data is text.
-
-@defvar binary-process-input
-If this variable is @code{nil}, convert newlines to @sc{crlf} sequences in
-the input to a synchronous subprocess.
+@node Input Methods
+@section Input Methods
+@cindex input methods
+
+ @dfn{Input methods} provide convenient ways of entering non-@sc{ASCII}
+characters from the keyboard. Unlike coding systems, which translate
+non-@sc{ASCII} characters to and from encodings meant to be read by
+programs, input methods provide human-friendly commands. (@xref{Input
+Methods,,, emacs, The GNU Emacs Manual}, for information on how users
+use input methods to enter text.) How to define input methods is not
+yet documented in this manual, but here we describe how to use them.
+
+ Each input method has a name, which is currently a string;
+in the future, symbols may also be usable as input method names.
+
+@tindex current-input-method
+@defvar current-input-method
+This variable holds the name of the input method now active in the
+current buffer. (It automatically becomes local in each buffer when set
+in any fashion.) It is @code{nil} if no input method is active in the
+buffer now.
@end defvar
-@defvar binary-process-output
-If this variable is @code{nil}, convert @sc{crlf} sequences to newlines in
-the output from a synchronous subprocess.
+@tindex default-input-method
+@defvar default-input-method
+This variable holds the default input method for commands that choose an
+input method. Unlike @code{current-input-method}, this variable is
+normally global.
@end defvar
+
+@tindex set-input-method
+@defun set-input-method input-method
+This function activates input method @var{input-method} for the current
+buffer. It also sets @code{default-input-method} to @var{input-method}.
+If @var{input-method} is @code{nil}, this function deactivates any input
+method for the current buffer.
+@end defun
+
+@tindex read-input-method-name
+@defun read-input-method-name prompt &optional default inhibit-null
+This function reads an input method name with the minibuffer, prompting
+with @var{prompt}. If @var{default} is non-@code{nil}, that is returned
+by default, if the user enters empty input. However, if
+@var{inhibit-null} is non-@code{nil}, empty input signals an error.
+
+The returned value is a string.
+@end defun
+
+@tindex input-method-alist
+@defvar input-method-alist
+This variable defines all the supported input methods.
+Each element defines one input method, and should have the form:
+
+@example
+(@var{input-method} @var{language-env} @var{activate-func} @var{title} @var{description} @var{args}...)
+@end example
+
+Here @var{input-method} is the input method name, a string; @var{env} is
+another string, the name of the language environment this input method
+is recommended for. (That serves only for documentation purposes.)
+
+@var{title} is a string to display in the mode line while this method is
+active. @var{description} is a string describing this method and what
+it is good for.
+
+@var{activate-func} is a function to call to activate this method. The
+@var{args}, if any, are passed as arguments to @var{activate-func}. All
+told, the arguments to @var{activate-func} are @var{input-method} and
+the @var{args}.
+@end defun
+
+
can, even for comparing integers, just in case we change the
representation of integers in a future Emacs version.
+ Sometimes it is useful to compare numbers with @code{equal}; it treats
+two numbers as equal if they have the same data type (both integers, or
+both floating point) and the same value. By contrast, @code{=} can
+treat an integer and a floating point number as equal.
+
There is another wrinkle: because floating point arithmetic is not
exact, it is often a bad idea to check for equality of two floating
point values. Usually it is better to test for approximate equality.
@end defun
@defun abs number
-This returns the absolute value of @var{number}.
+This function returns the absolute value of @var{number}.
@end defun
@node Numeric Conversions
(towards negative infinity).
If @var{divisor} is specified, @var{number} is divided by @var{divisor}
-before the floor is taken; this is the division operation that
-corresponds to @code{mod}. An @code{arith-error} results if
-@var{divisor} is 0.
+before the floor is taken; this uses the kind of division operation that
+corresponds to @code{mod}, rounding downward. An @code{arith-error}
+results if @var{divisor} is 0.
@end defun
@defun ceiling number
@section Rounding Operations
@cindex rounding without conversion
-The functions @code{ffloor}, @code{fceiling}, @code{fround} and
+The functions @code{ffloor}, @code{fceiling}, @code{fround}, and
@code{ftruncate} take a floating point argument and return a floating
point result whose value is a nearby integer. @code{ffloor} returns the
nearest integer below; @code{fceiling}, the nearest integer above;
@end defun
@defun exp arg
-This is the exponential function; it returns @i{e} to the power
-@var{arg}. @i{e} is a fundamental mathematical constant also called the
-base of natural logarithms.
+This is the exponential function; it returns
+@tex
+$e$
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+to the power @var{arg}.
+@tex
+$e$
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+is a fundamental mathematical constant also called the base of natural
+logarithms.
@end defun
@defun log arg &optional base
This function returns the logarithm of @var{arg}, with base @var{base}.
-If you don't specify @var{base}, the base @var{e} is used. If @var{arg}
+If you don't specify @var{base}, the base
+@tex
+$e$
+@end tex
+@ifinfo
+@i{e}
+@end ifinfo
+is used. If @var{arg}
is negative, the result is a NaN.
@end defun
@cindex alt characters
The X Window System defines three other modifier bits that can be set
in a character: @dfn{hyper}, @dfn{super} and @dfn{alt}. The syntaxes
-for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. Thus,
-@samp{?\H-\M-\A-x} represents @kbd{Alt-Hyper-Meta-x}.
+for these bits are @samp{\H-}, @samp{\s-} and @samp{\A-}. (Case is
+significant in these prefixes.) Thus, @samp{?\H-\M-\A-x} represents
+@kbd{Alt-Hyper-Meta-x}.
@tex
Numerically, the
bit values are $2^{22}$ for alt, $2^{23}$ for super and $2^{24}$ for hyper.
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
+digit, write @w{@samp{\ }} to terminate the hex escape---for example,
+@w{@samp{\x8c0\ }} represents one character, @samp{a} with grave accent.
+@w{@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.
@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
+nonprinting characters tab and @kbd{C-a}, with commas and spaces between
+them, like this: @code{"\t, \C-a"}. @xref{Character Type}, for a
+description of the read syntax for characters.
+
+ However, not all of the characters you can write with backslash
+escape-sequences are valid in strings. The only control characters that
+a string can hold are the @sc{ASCII} control characters. Strings do not
+distinguish case in @sc{ASCII} control characters.
+
+ Properly speaking, strings cannot hold meta characters; but when a
+string is to be used as a key sequence, there is a special convention
+that allows the meta versions of @sc{ASCII} characters to be put in a
+string. If you use the @samp{\M-} syntax to indicate a meta character
+in a string constant, this sets the
@tex
$2^{7}$
@end tex
@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}.
+bit of the character in the string. If the string is used in
+@code{define-key} or @code{lookup-key}, this numeric code is translated
+into the equivalent meta character. @xref{Character Type}.
+
+ Strings cannot hold characters that have the hyper, super, or alt
+modifiers.
@node Text Props and Strings
@subsubsection Text Properties in Strings
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}.)
+property list is @code{nil}. It is not actually necessary to mention
+ranges with @code{nil} as the property list, since any characters not
+mentioned in any range will default to having no properties.)
@node Vector Type
@subsection Vector Type
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.
+and 0 for @code{nil}). The least significant bits of the character are
+the lowest-numbered elements of the bool-vector. If the length is not a
+multiple of 8, the printed representation shows extra elements, but
+these extras really make no difference.
@example
(make-bool-vector 3 t)
- @result{} #&3"\377"
+ @result{} #&3"\007"
(make-bool-vector 3 nil)
- @result{} #&3"\0""
+ @result{} #&3"\0"
;; @r{These are equal since only the first 3 bits are used.}
-(equal #&3"\377" #&3"\340")
+(equal #&3"\377" #&3"\007")
@result{} t
@end example
@section Editing Types
@cindex editing types
- The types in the previous section used for general programming
+ The types in the previous section are used for general programming
purposes, and most of them are common to most Lisp dialects. Emacs Lisp
provides several additional data types for purposes connected with
editing.
@node Frame Type
@subsection Frame Type
- A @var{frame} is a rectangle on the screen that contains one or more
+ A @dfn{frame} is a rectangle on the screen that contains one or more
Emacs windows. A frame initially contains a single main window (plus
perhaps a minibuffer window) which you can subdivide vertically or
horizontally into smaller windows.
@example
@group
(selected-frame)
- @result{} #<frame emacs@@mole.gnu.ai.mit.edu 0xdac80>
+ @result{} #<frame emacs@@psilocin.gnu.org 0xdac80>
@end group
@end example
@end group
@end example
-(The @code{make-symbol} function returns an uninterned symbol that is
-not interned in the standard @code{obarray}. When uninterned symbols
-are in use, symbol names are no longer unique. Distinct symbols with
-the same name are not @code{eq}. @xref{Creating Symbols}.)
+The @code{make-symbol} function returns an uninterned symbol, distinct
+from the symbol that is used if you write the name in a Lisp expression.
+Distinct symbols with the same name are not @code{eq}. @xref{Creating
+Symbols}.
@example
@group
it is started up is as follows:
@enumerate
+@item
+It adds subdirectories to @code{load-path}, by running the file
+named @file{subdirs.el} in each directory that is listed.
+
+@item
+It sets the language environment and the terminal coding system,
+if requested by environment variables such as @code{LANG}.
+
@item
It loads the initialization library for the window system, if you are
using a window system. This library's name is
@cindex @file{site-start.el}
@item
-It loads the file @file{~/.emacs}, unless @samp{-q} was specified on the
-command line. (This is not done in @samp{-batch} mode.) The @samp{-u}
-option can specify another user name whose home directory should be used
-instead of @file{~}.
+It loads the file @file{~/.emacs}, unless @samp{-q} or @samp{-batch} was
+specified on the command line. The @samp{-u} option can specify another
+user name whose home directory should be used instead of @file{~}.
@item
It loads the library @file{default}, unless @code{inhibit-default-init}
"@var{your-login-name}")
@end example
-Simply setting @code{inhibit-startup-echo-area-message} to your login
-name is not sufficient to inhibit the message; Emacs explicitly checks
-whether @file{.emacs} contains an expression as shown above. Your login
-name must appear in the expression as a Lisp string constant.
+Emacs explicitly checks for an expression as shown above in your
+@file{.emacs} file; your login name must appear in the expression as a
+Lisp string constant. Other methods of setting
+@code{inhibit-startup-echo-area-message} to the same value do not
+inhibit the startup message.
This way, you can easily inhibit the message for yourself if you wish,
but thoughtless copying of your @file{.emacs} file will not inhibit the
@end defopt
@defvar before-init-hook
-@defvarx after-init-hook
-These two normal hooks are run just before, and just after, loading of
-the user's init file, @file{default.el}, and/or @file{site-start.el}.
+This normal hook is run, once, just before loading of all the init files
+(the user's init file, @file{default.el}, and/or @file{site-start.el}).
+@end defvar
+
+@defvar after-init-hook
+This normal hook is run, once, just after loading of all the init files
+(the user's init file, @file{default.el}, and/or @file{site-start.el}),
+before the terminal-specific initialization.
@end defvar
@node Terminal-Specific
@cindex terminal-specific initialization
Each terminal type can have its own Lisp library that Emacs loads when
-run on that type of terminal. For a terminal type named @var{termtype},
-the library is called @file{term/@var{termtype}}. Emacs finds the file
-by searching the @code{load-path} directories as it does for other
-files, and trying the @samp{.elc} and @samp{.el} suffixes. Normally,
-terminal-specific Lisp library is located in @file{emacs/lisp/term}, a
-subdirectory of the @file{emacs/lisp} directory in which most Emacs Lisp
-libraries are kept.@refill
-
- The library's name is constructed by concatenating the value of the
-variable @code{term-file-prefix} and the terminal type. Normally,
-@code{term-file-prefix} has the value @code{"term/"}; changing this
-is not recommended.
+run on that type of terminal. The library's name is constructed by
+concatenating the value of the variable @code{term-file-prefix} and the
+terminal type. Normally, @code{term-file-prefix} has the value
+@code{"term/"}; changing this is not recommended. Emacs finds the file
+in the normal manner, by searching the @code{load-path} directories, and
+trying the @samp{.elc} and @samp{.el} suffixes.
The usual function of a terminal-specific library is to enable special
keys to send sequences that Emacs can recognize. It may also need to
This function returns the name of the machine you are running on.
@example
(system-name)
- @result{} "prep.ai.mit.edu"
+ @result{} "www.gnu.org"
@end example
@end defun
containing the Emacs executable.
@end defvar
-@defun load-average
+@defun load-average &optional use-float
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.
+averages in a list.
+
+By default, the values are integers that are 100 times the system load
+averages, which indicate the average number of processes trying to run.
+If @var{use-float} is non-@code{nil}, then they are returned
+as floating point numbers instead.
@example
@group
(load-average)
@result{} (169 48 36)
@end group
+@group
+(load-average t)
+ @result{} (1.69 0.48 0.36)
+@end group
@group
lewis@@rocky[5] % uptime
This function returns the process @sc{id} of the Emacs process.
@end defun
-@tindex tty-erase-char
@defvar tty-erase-char
+@tindex tty-erase-char
This variable holds the erase character that was selected
in the system's terminal driver, before Emacs was started.
@end defvar
zone.
@defun current-time-string &optional time-value
-This function returns the current time and date as a humanly-readable
+This function returns the current time and date as a human-readable
string. The format of the string is unvarying; the number of characters
used for each part is always the same, so you can reliably use
@code{substring} to extract pieces of it. It is wise to count the
You can also specify the field width and type of padding for any of
these @samp{%}-sequences. This works as in @code{printf}: you write
the field width as digits in the middle of a @samp{%}-sequences. If you
-start the field width with 0, it means to pad with zeros.
+start the field width with @samp{0}, it means to pad with zeros. If you
+start the field width with @samp{_}, it means to pad with spaces.
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
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.
+
+The operating system puts limits on the range of possible time values;
+if you try to encode a time that is out of range, an error results.
@end defun
@node Timers
The time @var{time} is specified as a string.
Absolute times may be specified in a wide variety of formats, and tries
-to accept all common date formats. One valid format is
-@samp{@var{hour}:@var{min}:@var{sec} @var{timezone}
-@var{month}/@var{day}/@var{year}}, where all fields are numbers; the
-format that @code{current-time-string} returns is also allowed.
+to accept all common date formats. Valid formats include these two,
+
+@example
+@var{year}-@var{month}-@var{day} @var{hour}:@var{min}:@var{sec} @var{timezone}
+
+@var{hour}:@var{min}:@var{sec} @var{timezone} @var{month}/@var{day}/@var{year}
+@end example
+
+@noindent
+where in both examples all fields are numbers; the format that
+@code{current-time-string} returns is also allowed, and many others
+as well.
To specify a relative time, use numbers followed by units.
For example:
executes all the @var{timeout-forms} and returns the value of the last
of them.
-This macro works by set a timer to run after @var{seconds} seconds. If
+This macro works by setting a timer to run after @var{seconds} seconds. If
@var{body} finishes before that time, it cancels the timer. If the
timer actually runs, it terminates execution of @var{body}, then
executes @var{timeout-forms}.
@code{nil}, Emacs is using @sc{cbreak} mode.
@item flow
is non-@code{nil} if Emacs uses @sc{xon/xoff} (@kbd{C-q}, @kbd{C-s})
-flow control for output to the terminal. This value has effect when
-unless @var{interrupt} is @code{nil}.
+flow control for output to the terminal. This value is meaningful only
+when @var{interrupt} is @code{nil}.
@item meta
is @code{t} if Emacs treats the eighth bit of input characters as
the meta bit; @code{nil} means Emacs clears the eighth bit of every
@end group
@group
(setq keyboard-translate-table
- (make-char-table 'keyboard-translate-table nil)))
+ (make-char-table 'keyboard-translate-table nil))
@end group
@group
;; @r{Swap @kbd{C-s} and @kbd{C-\}.}
@deffn Command forward-word count
This function moves point forward @var{count} words (or backward if
-@var{count} is negative). Normally it returns @code{t}. If this motion
-encounters the beginning or end of the buffer, or the limits of the
-accessible portion when narrowing is in effect, point stops there
-and the value is @code{nil}.
+@var{count} is negative). More precisely, it keeps moving until it
+moves across a word-constituent character and encounters a
+word-separator character, then returns @code{t}.
+
+If this motion encounters the beginning or end of the buffer, or the
+limits of the accessible portion when narrowing is in effect, point
+stops there and the value is @code{nil}.
In an interactive call, @var{count} is set to the numeric prefix
argument.
These functions scan text to determine where screen lines break, and
thus take time proportional to the distance scanned. If you intend to
use them heavily, Emacs provides caches which may improve the
-performance of your code. @xref{Text Lines, cache-long-line-scans}.
+performance of your code. @xref{Truncation, cache-long-line-scans}.
@defun vertical-motion count &optional window
The argument @var{offsets} is either @code{nil} or a cons cell of the
form @code{(@var{hscroll} . @var{tab-offset})}. Here @var{hscroll} is
the number of columns not being displayed at the left margin; most
-callers get this from @code{window-hscroll}. Meanwhile,
+callers get this by calling @code{window-hscroll}. Meanwhile,
@var{tab-offset} is the offset between column numbers on the screen and
column numbers in the buffer. This can be nonzero in a continuation
line, when the previous screen lines' widths do not add up to a multiple
The @code{save-excursion} special form is the standard way to switch
buffers or move point within one part of a program and avoid affecting
-the rest of the program. It is used more than 500 times in the Lisp
+the rest of the program. It is used more than 4000 times in the Lisp
sources of Emacs.
@code{save-excursion} does not save the values of point and the mark for
@end example
@end defspec
+ @strong{Warning:} Ordinary insertion of text adjacent to the saved
+point value relocates the saved value, just as it relocates all markers.
+Therefore, when the saved point value is restored, it normally comes
+after the inserted text.
+
Although @code{save-excursion} saves the location of the mark, it does
not prevent functions which modify the buffer from setting
@code{deactivate-mark}, and thus causing the deactivation of the mark
This method yields correct results if @var{body} does further narrowing.
However, @code{save-restriction} can become confused if the body widens
-and then make changes outside the range of the saved narrowing. When
+and then makes changes outside the range of the saved narrowing. When
this is what you want to do, @code{save-restriction} is not the right
tool for the job. Here is what you must use instead:
@menu
* Subprocess Creation:: Functions that start subprocesses.
+* Shell Arguments:: Quoting an argument to pass it to a shell.
* Synchronous Processes:: Details of using synchronous subprocesses.
* Asynchronous Processes:: Starting up an asynchronous subprocess.
* Deleting Processes:: Eliminating an asynchronous subprocess.
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}.
-On Microsoft operating systems, additional variables control
-the conversion for end-of-line (@pxref{MS-DOS Subprocesses}).
@defun call-process program &optional infile destination display &rest args
This function calls @var{program} in a separate process and waits for
@end table
If @var{display} is non-@code{nil}, then @code{call-process} redisplays
-the buffer as output is inserted. Otherwise the function does no
-redisplay, and the results become visible on the screen only when Emacs
-redisplays that buffer in the normal course of events.
+the buffer as output is inserted. (However, if the coding system chosen
+for decoding output is @code{undecided}, meaning deduce the encoding
+from the actual data, then redisplay sometimes cannot continue once
+non-@sc{ASCII} characters are encountered. There are fundamental
+reasons why it is hard to fix this.) Otherwise the function
+@code{call-process} does no redisplay, and the results become visible on
+the screen only when Emacs redisplays that buffer in the normal course
+of events.
The remaining arguments, @var{args}, are strings that specify command
line arguments for the program.
@end smallexample
@end defun
-@tindex shell-command-to-string
@defun shell-command-to-string command
+@tindex shell-command-to-string
This function executes @var{command} (a string) as a shell command,
then returns the command's output as a string.
@end defun
@cindex asynchronous subprocess
After an @dfn{asynchronous process} is created, Emacs and the Lisp
-program both continue running immediately. The process may thereafter
-run in parallel with Emacs, and the two may communicate with each other
-using the functions described in following sections. Here we describe
-how to create an asynchronous process with @code{start-process}.
+program both continue running immediately. The process thereafter runs
+in parallel with Emacs, and the two can communicate with each other
+using the functions described in following sections. However,
+communication is only partially asynchronous: Emacs sends data to the
+process only when certain functions are called, and Emacs accepts data
+from the process only when Emacs is waiting for input or for a time
+delay.
+
+ Here we describe how to create an asynchronous process.
@defun start-process name buffer-or-name program &rest args
This function creates a new asynchronous subprocess and starts the
This function returns the name of @var{process}.
@end defun
-@tindex process-contact
@defun process-contact process
+@tindex process-contact
This function returns @code{t} for an ordinary child process, and
@code{(@var{hostname} @var{service})} for a net connection
(@pxref{Network}).
@ref{Asynchronous Processes}).
@end defun
-@tindex process-coding-system
@defun process-coding-system process
+@tindex process-coding-system
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:
@end example
@end defun
-@tindex set-process-coding-system
@defun set-process-coding-system process decoding-system encoding-system
+@tindex set-process-coding-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
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}.
+subprocess receives it, much like text written into a file. You can use
+@code{set-process-coding-system} to specify which coding system to use
+(@pxref{Process Information}). Otherwise, the coding system comes from
+@code{coding-system-for-write}, if that is non-@code{nil}; or else from
+the defaulting mechanism (@pxref{Default Coding Systems}).
@defun process-send-string process-name string
This function sends @var{process-name} the contents of @var{string} as
the process has no buffer and no filter function, its output is
discarded.
+ Output from a subprocess can arrive only while Emacs is waiting: when
+reading terminal input, in @code{sit-for} and @code{sleep-for}
+(@pxref{Waiting}), and in @code{accept-process-output} (@pxref{Accepting
+Output}). This minimizes the problem of timing errors that usually
+plague parallel programming. For example, you can safely create a
+process and only then specify its buffer or filter function; no output
+can arrive before you finish, if the code in between does not call any
+primitive that waits.
+
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}.
+You can use @code{set-process-coding-system} to specify which coding
+system to use (@pxref{Process Information}). Otherwise, the coding
+system comes from @code{coding-system-for-read}, if that is
+non-@code{nil}; or else from the defaulting mechanism (@pxref{Default
+Coding Systems}).
+
+ @strong{Warning:} Coding systems such as @code{undecided} which
+determine the coding system from the data do not work entirely reliably
+with asynchronous subprocess output. This is because Emacs has to
+process asynchronous subprocess output in batches, as it arrives. Emacs
+must try to detect the proper coding system from one batch at a time,
+and this does not always work. Therefore, if at all possible, use a
+coding system which determines both the character code conversion and
+the end of line conversion---that is, one like @code{latin-1-unix},
+rather than @code{undecided} or @code{latin-1}.
@menu
* Process Buffers:: If no filter, output is put in a buffer.
process buffer is used directly for output from the process only when
there is no filter.
+ The filter function can only be called when Emacs is waiting for
+something, because process output arrives only at such times. Emacs
+waits when reading terminal input, in @code{sit-for} and
+@code{sleep-for} (@pxref{Waiting}), and in @code{accept-process-output}
+(@pxref{Accepting 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
-timing errors that could result from running filters at random places in
-the middle of other Lisp programs. You may explicitly cause Emacs to
-wait, so that filter functions will run, by calling @code{sit-for} or
-@code{sleep-for} (@pxref{Waiting}), or @code{accept-process-output}
-(@pxref{Accepting Output}). Emacs is also waiting when the command loop
-is reading input.
-
Quitting is normally inhibited within a filter function---otherwise,
the effect of typing @kbd{C-g} at command level or to quit a user
command would be unpredictable. If you want to permit quitting inside a
middle of other Lisp programs. A program can wait, so that sentinels
will run, by calling @code{sit-for} or @code{sleep-for}
(@pxref{Waiting}), or @code{accept-process-output} (@pxref{Accepting
-Output}). Emacs is also waiting when the command loop is reading input.
+Output}). Emacs also allows sentinels to run when the command loop is
+reading input.
Quitting is normally inhibited within a sentinel---otherwise, the
effect of typing @kbd{C-g} at command level or to quit a user command
Nested repetition operators can be extremely slow if they specify
backtracking loops. For example, it could take hours for the regular
-expression @samp{\(x+y*\)*a} to match the sequence
-@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}. The slowness is because
-Emacs must try each imaginable way of grouping the 35 @samp{x}'s before
-concluding that none of them can work. To make sure your regular
-expressions run fast, check nested repetitions carefully.
+expression @samp{\(x+y*\)*a} to try to match the sequence
+@samp{xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxz}, before it ultimately fails.
+The slowness is because Emacs must try each imaginable way of grouping
+the 35 @samp{x}'s before concluding that none of them can work. To make
+sure your regular expressions run fast, check nested repetitions
+carefully.
@item @samp{+}
@cindex @samp{+} in regexp
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.
+(@samp{A} with grave accent) is in the Emacs character set for Latin-1.
Note that the usual regexp special characters are not special inside a
character alternative. A completely different set of characters are
can act. It is poor practice to depend on this behavior; quote the
special character anyway, regardless of where it appears.@refill
-For the most part, @samp{\} followed by any character matches only
-that character. However, there are several exceptions: two-character
-sequences starting with @samp{\} which have special meanings. The
-second character in the sequence is always an ordinary character on
-their own. Here is a table of @samp{\} constructs.
+For the most part, @samp{\} followed by any character matches only that
+character. However, there are several exceptions: two-character
+sequences starting with @samp{\} which have special meanings. (The
+second character in such a sequence is always ordinary when used on its
+own.) Here is a table of @samp{\} constructs.
@table @samp
@item \|
@item
To enclose a complicated expression for the postfix operators @samp{*},
@samp{+} and @samp{?} to operate on. Thus, @samp{ba\(na\)*} matches
-@samp{bananana}, etc., with any (zero or more) number of @samp{na}
-strings.@refill
+@samp{ba}, @samp{bana}, @samp{banana}, @samp{bananana}, etc., with any
+number (zero or more) of @samp{na} strings.
@item
To record a matched substring for future reference.
@end example
@end defun
-@tindex regexp-opt
@defun regexp-opt strings &optional paren
+@tindex regexp-opt
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
@end example
@end defun
-@tindex regexp-opt-depth
@defun regexp-opt-depth regexp
+@tindex regexp-opt-depth
This function returns the total number of grouping constructs
(parenthesized expressions) in @var{regexp}.
@end defun
expressions can have subexpressions---after a simple string search, the
only information available is about the entire match.
+ A search which fails may or may not alter the match data. In the
+past, a failing search did not do this, but we may change it in the
+future.
+
@defun match-string count &optional in-string
This function returns, as a string, the text matched in the last search
or match operation. It returns the entire text if @var{count} is zero,
@sc{cdr} is not @code{nil}), a @code{wrong-type-argument} error is
signaled.
-@xref{List Elements}, for the related function @code{safe-list}.
+@xref{List Elements}, for the related function @code{safe-length}.
@example
@group
@end group
@group
(elt [1 2 3 4] 4)
- @error{}Args out of range: [1 2 3 4], 4
+ @error{} Args out of range: [1 2 3 4], 4
@end group
@group
(elt [1 2 3 4] -1)
- @error{}Args out of range: [1 2 3 4], -1
+ @error{} Args out of range: [1 2 3 4], -1
@end group
@end example
requires access time that is proportional to the position of the element
in the list.
- Emacs defines four types of array, both of which are one-dimensional:
-@dfn{strings}, @dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}.
-A vector is a general array; its elements can be any Lisp objects. A
-string is a specialized array; its elements must be characters (i.e.,
-integers between 0 and 255). Each type of array has its own read
-syntax. @xref{String Type}, and @ref{Vector Type}.
+ Emacs defines four types of array, all one-dimensional: @dfn{strings},
+@dfn{vectors}, @dfn{bool-vectors} and @dfn{char-tables}. A vector is a
+general array; its elements can be any Lisp objects. A string is a
+specialized array; its elements must be characters (i.e., integers
+between 0 and 255). Each type of array has its own read syntax.
+@xref{String Type}, and @ref{Vector Type}.
All four kinds of array share these characteristics:
@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}.
+@var{object} @var{index})}, that is also an error. @xref{Splitting
+Characters}.
@end defun
@defun fillarray array object
@node Char-Tables
@section Char-Tables
@cindex char-tables
+@cindex extra slots of char-table
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's
-elements with @code{aref} and @code{aset}, as with any array.
-Char-tables are constants when evaluated.
+elements with @code{aref} and @code{aset}, as with any array. In
+addition, a char-table can have @dfn{extra slots} to hold additional
+data not associated with particular character codes. Char-tables are
+constants when evaluated.
-@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.
+ Each char-table has a @dfn{subtype} which is a symbol. The subtype
+has two purposes: to distinguish char-tables meant for different uses,
+and to control the number of extra slots. For example, display tables
+are char-tables with @code{display-table} as the subtype, and syntax
+tables are char-tables with @code{syntax-table} as the subtype. A valid
+subtype 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
@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
+@tindex make-char-table
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
all char-tables have room for any valid character code as an index.
@end defun
-@tindex char-table-p
@defun char-table-p object
+@tindex char-table-p
This function returns @code{t} if @var{object} is a char-table,
otherwise @code{nil}.
@end defun
-@tindex char-table-subtype
@defun char-table-subtype char-table
+@tindex char-table-subtype
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
+@tindex set-char-table-default
This function sets the default value of @var{char-table} to
@var{new-default}.
To do that, use @code{(char-table-range @var{char-table} nil)}.
@end defun
-@tindex char-table-parent
@defun char-table-parent char-table
+@tindex char-table-parent
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
+@tindex set-char-table-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
+@tindex char-table-extra-slot
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
+@tindex set-char-table-extra-slot
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
+@tindex char-table-range
This returns the value specified in @var{char-table} for a range of
-characters @var{range}. Here @var{range} may be
+characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
@item @code{nil}
Refers to the default value.
@item @var{char}
-Refers to the element for character @var{char}.
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name. @xref{Splitting Characters}, for a description of generic characters.
@end table
@end defun
-@tindex set-char-table-range
@defun set-char-table-range char-table range value
+@tindex set-char-table-range
This function set the value in @var{char-table} for a range of
-characters @var{range}. Here @var{range} may be
+characters @var{range}. Here are the possibilities for @var{range}:
@table @asis
@item @code{nil}
Refers to the whole range of character codes.
@item @var{char}
-Refers to the element for character @var{char}.
+Refers to the element for character @var{char}
+(supposing @var{char} is a valid character code).
@item @var{charset}
Refers to the value specified for the whole character set
@var{charset} (@pxref{Character Sets}).
+
+@item @var{generic-char}
+A generic character stands for a character set; specifying the generic
+character as argument is equivalent to specifying the character set
+name. @xref{Splitting Characters}, for a description of generic characters.
@end table
@end defun
-@tindex map-char-table
@defun map-char-table function char-table
+@tindex map-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 @var{key}.
+is a possible @var{range} argument for @code{char-table-range}---either
+a valid character or a generic character---and the value is
+@code{(char-table-range @var{char-table} @var{key})}.
Overall, the key-value pairs passed to @var{function} describe all the
values stored in @var{char-table}.
+
+The return value is always @code{nil}; to make this function useful,
+@var{function} should have side effects. For example,
+here is how to examine each element of the syntax table:
+
+@example
+(map-char-table
+ #'(lambda (key value)
+ (setq accumulator
+ (cons (list key value) accumulator)))
+ (syntax-table))
+@result{}
+((475008 nil) (474880 nil) (474752 nil) (474624 nil)
+ ... (5 (3)) (4 (3)) (3 (3)) (2 (3)) (1 (3)) (0 (3)))
+@end example
@end defun
@node Bool-Vectors
from that, you manipulate them with same functions used for other kinds
of arrays.
-@tindex make-bool-vector
@defun make-bool-vector length initial
+@tindex make-bool-vector
Return a new book-vector of @var{length} elements,
each one initialized to @var{initial}.
@end defun
@defun bool-vector-p object
+@tindex bool-vector-p
This returns @code{t} if @var{object} is a bool-vector,
and @code{nil} otherwise.
@end defun
@end example
@noindent
-Note that the open and close parentheses remains in the list. The Lisp
+Note that the open and close parentheses remain in the list. The Lisp
reader encountered the open parenthesis, decided that it ended the
input, and unread it. Another attempt to read from the stream at this
point would read @samp{()} and return @code{nil}.
The output characters are inserted into the buffer that @var{marker}
points into, at the marker position. The marker position advances as
characters are inserted. The value of point in the buffer has no effect
-on printing when the stream is a marker.
+on printing when the stream is a marker, and this kind of printing
+does not move point.
@item @var{function}
@cindex function output stream
The output characters are passed to @var{function}, which is responsible
for storing them away. It is called with a single character as
-argument, as many times as there are characters to be output, and is
-free to do anything at all with the characters it receives.
+argument, as many times as there are characters to be output, and
+is responsible for storing the characters wherever you want to put them.
@item @code{t}
@cindex @code{t} output stream
@item @code{nil}
@cindex @code{nil} output stream
-@code{nil} specified as an output stream means to the value of
+@code{nil} specified as an output stream means to use the value of
@code{standard-output} instead; that value is the @dfn{default output
-stream}, and must be a non-@code{nil} output stream.
+stream}, and must not be @code{nil}.
@item @var{symbol}
A symbol as output stream is equivalent to the symbol's function
@example
@group
---------- Buffer: foo ----------
-"This is the @point{}output"
+This is the @point{}output
---------- Buffer: foo ----------
@end group
@group
---------- Buffer: foo ----------
-"This is t
+This is t
"More output for foo."
-he @point{}output"
+he @point{}output
---------- Buffer: foo ----------
@end group
purpose of the output is to look nice for humans, then it is usually
better to print without quoting.
- Printing a self-referent Lisp object in the normal way would require
-an infinite amount of text, and could even result in stack overflow.
-Emacs detects such recursion and prints @samp{#@var{level}} instead of
-recursively printing an object already being printed. For example, here
-@samp{#0} indicates a recursive reference to the object at level 0 of
-the current print operation:
+ Lisp objects can refer to themselves. Printing a self-referential
+object in the normal way would require an infinite amount of text, and
+the attempt could cause infinite recursion. Emacs detects such
+recursion and prints @samp{#@var{level}} instead of recursively printing
+an object already being printed. For example, here @samp{#0} indicates
+a recursive reference to the object at level 0 of the current print
+operation:
@example
(setq foo (list nil))
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.
+@tindex with-output-to-string
+This macro executes the @var{body} forms with @code{standard-output} set
+up to feed output into a string. Then it returns that string.
For example, if the current buffer name is @samp{foo},
* 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}.
+* Formatting Strings:: @code{format}: Emacs's analogue of @code{printf}.
* Case Conversion:: Case conversion functions.
* Case Tables:: Customizing case conversion.
@end menu
see @ref{Sequences Arrays Vectors}, and @ref{Arrays}.
@defun stringp object
- This function returns @code{t} if @var{object} is a string, @code{nil}
+This function returns @code{t} if @var{object} is a string, @code{nil}
otherwise.
@end defun
@defun char-or-string-p object
- This function returns @code{t} if @var{object} is a string or a
+This function returns @code{t} if @var{object} is a string or a
character (i.e., an integer), @code{nil} otherwise.
@end defun
putting strings together, or by taking them apart.
@defun make-string count character
- This function returns a string made up of @var{count} repetitions of
+This function returns a string made up of @var{count} repetitions of
@var{character}. If @var{count} is negative, an error is signaled.
@example
@code{make-list} (@pxref{Building Lists}).
@end defun
-@tindex string
@defun string &rest characters
+@tindex string
This returns a string containing the characters @var{characters}.
@example
@example
(concat "abc" "-def")
@result{} "abc-def"
-(concat "abc" (list 120 (+ 256 121)) [122])
+(concat "abc" (list 120 121) [122])
@result{} "abcxyz"
;; @r{@code{nil} is an empty sequence.}
(concat "abc" nil "-def")
@end example
@noindent
-The second example above shows how characters stored in strings are
-taken modulo 256. In other words, each character in the string is
-stored in one byte.
-
The @code{concat} function always constructs a new string that is
not @code{eq} to any existing string.
Lists}.
@end defun
-@tindex split-string
@defun split-string string separators
+@tindex split-string
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
A more powerful function is @code{store-substring}:
-@tindex store-substring
@defun store-substring string idx obj
+@tindex store-substring
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.
@defun string-lessp string1 string2
@code{string-lessp} is another name for @code{string<}.
+@end defun
+
+@defun compare-strings string1 start1 end1 string2 start2 end2 &optional ignore-case
+@tindex compare-strings
+This function compares a specified part of @var{string1} with a
+specified part of @var{string2}. The specified part of @var{string1}
+runs from index @var{start1} up to index @var{end1} (default, the end of
+the string). The specified part of @var{string2} runs from index
+@var{start2} up to index @var{end2} (default, the end of the string).
+
+The strings are both converted to multibyte for the comparison
+(@pxref{Text Representations}) so that a unibyte string can be usefully
+compared with a multibyte string. If @var{ignore-case} is
+non-@code{nil}, then case is ignored as well.
+
+If the specified portions of the two strings match, the value is
+@code{t}. Otherwise, the value is an integer which indicates how many
+leading characters agree, and which string is less. Its absolute value
+is one plus the number of characters that agree at the beginning of the
+two strings. The sign is negative if @var{string1} (or its specified
+portion) is less.
+@end defun
+
+@defun assoc-ignore-case key alist
+@tindex assoc-ignore-case
+This function works like @code{assoc}, except that @var{key} must be a
+string, and comparison is done using @code{compare-strings}.
+Case differences are ignored in this comparison.
+@end defun
+
+@defun assoc-ignore-representation key alist
+@tindex assoc-ignore-representation
+This function works like @code{assoc}, except that @var{key} must be a
+string, and comparison is done using @code{compare-strings}.
+Case differences are significant.
@end defun
See also @code{compare-buffer-substrings} in @ref{Comparing Text}, for
See also the function @code{format} in @ref{Formatting Strings}.
@end defun
-@defun string-to-number string base
+@defun string-to-number string &optional base
@cindex string to number
This function returns the numeric value of the characters in
@var{string}. If @var{base} is non-@code{nil}, integers are converted
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.
+digit or a plus or minus sign, this function returns 0.
@example
(string-to-number "256")
for which there are no corresponding values) cause unpredictable
behavior. Any extra values to be formatted are ignored.
- Certain format specifications require values of particular types.
-However, no error is signaled if the value actually supplied fails to
-have the expected type. Instead, the output is likely to be
-meaningless.
+ Certain format specifications require values of particular types. If
+you supply a value that doesn't fit the requirements, an error is
+signaled.
Here is a table of valid format specifications:
@item %g
Replace the specification with notation for a floating point number,
-using either exponential notation or decimal-point notation whichever
+using either exponential notation or decimal-point notation, whichever
is shorter.
@item %%
@cindex case conversion in Lisp
The character case functions change the case of single characters or
-of the contents of strings. The functions convert only alphabetic
-characters (the letters @samp{A} through @samp{Z} and @samp{a} through
-@samp{z}); other characters are not altered. The functions do not
-modify the strings that are passed to them as arguments.
+of the contents of strings. The functions normally convert only
+alphabetic characters (the letters @samp{A} through @samp{Z} and
+@samp{a} through @samp{z}, as well as non-ASCII letters); other
+characters are not altered. (You can specify a different case
+conversion mapping by specifying a case table---@pxref{Case Tables}.)
+
+ These functions do not modify the strings that are passed to them as
+arguments.
The examples below use the characters @samp{X} and @samp{x} which have
@sc{ASCII} codes 88 and 120 respectively.
@defun upcase-initials string
This function capitalizes the initials of the words in @var{string}.
without altering any letters other than the initials. It returns a new
-string whose contents are a copy of @var{string-or-char}, in which each
-word has been converted to upper case.
+string whose contents are a copy of @var{string}, in which each word has
+been converted to upper case.
The definition of a word is any sequence of consecutive characters that
are assigned to the word constituent syntax class in the current syntax
@end example
@end defun
+ @xref{Text Comparison}, for functions that compare strings; some of
+them ignore case differences, or can optionally ignore case differences.
+
@node Case Tables
@section The Case Table
case character.
@item canonicalize
The canonicalize table maps all of a set of case-related characters
-into some one of them.
+into a particular member of that set.
@item equivalences
-The equivalences table maps each of a set of case-related characters
-into the next one in that set.
+The equivalences table maps each one of a set of case-related characters
+into the next character in that set.
@end table
In simple cases, all you need to specify is the mapping to lower-case;
documentation string for the variable @code{buffer-file-name} in the
@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.
+begins---see @ref{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
@cindex text parsing
A @dfn{syntax table} specifies the syntactic textual function of each
-character. This information is used by the parsing commands, the
+character. This information is used by the @dfn{parsing functions}, the
complex movement commands, and others to determine where words, symbols,
and other syntactic constructs begin and end. The current syntax table
controls the meaning of the word motion functions (@pxref{Word Motion})
the current syntax table in the usual way.
@end table
-@tindex parse-sexp-lookup-properties
@defvar parse-sexp-lookup-properties
+@tindex 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.
to each syntactic type.
@multitable @columnfractions .05 .3 .3 .3
-@item@tab
+@item
+@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
@tab
@i{Integer} @i{Class}
-@item@tab
+@item
+@tab
0 @ @ whitespace
@tab
5 @ @ close parenthesis
@tab
10 @ @ character quote
-@item@tab
+@item
+@tab
1 @ @ punctuation
@tab
6 @ @ expression prefix
@tab
11 @ @ comment-start
-@item@tab
+@item
+@tab
2 @ @ word
@tab
7 @ @ string quote
@tab
12 @ @ comment-end
-@item@tab
+@item
+@tab
3 @ @ symbol
@tab
8 @ @ paired delimiter
@tab
13 @ @ inherit
-@item@tab
+@item
+@tab
4 @ @ open parenthesis
@tab
9 @ @ escape
@tab
14 @ @ comment-fence
-@item@tab
+@item
+@tab
15 @ string-fence
@end multitable
corresponds to each syntax flag.
@multitable @columnfractions .05 .3 .3 .3
-@item@tab
+@item
+@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
@tab
@i{Prefix} @i{Flag}
-@item@tab
+@item
+@tab
@samp{1} @ @ @code{(lsh 1 16)}
@tab
@samp{3} @ @ @code{(lsh 1 18)}
@tab
@samp{p} @ @ @code{(lsh 1 20)}
-@item@tab
+@item
+@tab
@samp{2} @ @ @code{(lsh 1 17)}
@tab
@samp{4} @ @ @code{(lsh 1 19)}
@defun buffer-string
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}).
+the current buffer as a string. It is equivalent to
+
+@example
+(buffer-substring (point-min) (point-max))
+@end example
@example
@group
characters specified as separate arguments, not part of a string or
buffer, inherit their text properties from the neighboring text.
+ The insertion functions convert text from unibyte to multibyte in
+order to insert in a multibyte buffer, and vice versa---if the text
+comes from a string or from a buffer. However, they do not convert
+unibyte character codes 128 through 255 to multibyte characters, not
+even if the current buffer is a multibyte buffer. @xref{Converting
+Representations}.
+
@defun insert &rest args
This function inserts the strings and/or characters @var{args} into the
current buffer, at point, moving point forward. In other words, it
number (@code{nil} means 1), and @var{character} must be a character.
The value is @code{nil}.
+This function does not convert unibyte character codes 128 through 255
+to multibyte characters, not even if the current buffer is a multibyte
+buffer. @xref{Converting Representations}.
+
If @var{inherit} is non-@code{nil}, then the inserted characters inherit
sticky text properties from the two characters before and after the
insertion point. @xref{Sticky Properties}.
The value returned is always @code{nil}.
@end deffn
-@tindex backward-delete-char-untabify-method
@defopt backward-delete-char-untabify-method
+@tindex backward-delete-char-untabify-method
This option specifies how @code{backward-delete-char-untabify} should
deal with whitespace. Possible values include @code{untabify}, the
default, meaning convert a tab to many spaces and delete one;
any whitespace at the join and in some cases replacing it with one
space. If @var{join-following-p} is non-@code{nil},
@code{delete-indentation} joins this line to the following line
-instead. The value is @code{nil}.
+instead. The function returns @code{nil}.
If there is a fill prefix, and the second of the lines being joined
starts with the prefix, then @code{delete-indentation} deletes the
@end deffn
@defun fixup-whitespace
-This function replaces all the white space surrounding point with either
+This function replaces all the whitespace surrounding point with either
one space or no space, according to the context. It returns @code{nil}.
At the beginning or end of a line, the appropriate amount of space is
When kill commands are interwoven with other commands, each kill
command makes a new entry in the kill ring. Multiple kill commands in
-succession build up a single entry in the kill ring, which would be
-yanked as a unit; the second and subsequent consecutive kill commands
-add text to the entry made by the first one.
+succession build up a single kill-ring entry, which would be yanked as a
+unit; the second and subsequent consecutive kill commands add text to
+the entry made by the first one.
For yanking, one entry in the kill ring is designated the ``front'' of
the ring. Some yank commands ``rotate'' the ring by designating a
oldest one comes the newest one, and before the newest one goes the
oldest.
-The value is always @code{nil}.
+The return value is always @code{nil}.
@end deffn
@node Low-Level Kill Ring
(@pxref{Window System Selections}).
@defun current-kill n &optional do-not-move
-The function @code{current-kill} rotates the yanking pointer which
-designates the ``front'' of the kill ring by @var{n} places (from newer
+The function @code{current-kill} rotates the yanking pointer, which
+designates the ``front'' of the kill ring, by @var{n} places (from newer
kills to older ones), and returns the text at that place in the ring.
If the optional second argument @var{do-not-move} is non-@code{nil},
self-inserting characters continue.
All buffer modifications add a boundary whenever the previous undoable
-change was made in some other buffer. This way, a command that modifies
-several buffers makes a boundary in each buffer it changes.
+change was made in some other buffer. This is to ensure that
+each command makes a boundary in each buffer where it makes changes.
Calling this function explicitly is useful for splitting the effects of
a command into more than one unit. For example, @code{query-replace}
You cannot specify any other buffer.
@end deffn
-@defun buffer-disable-undo &optional buffer
-@defunx buffer-flush-undo &optional buffer
+@deffn Command buffer-disable-undo &optional buffer
+@deffnx Command buffer-flush-undo &optional buffer
@cindex disable undo
This function discards the undo list of @var{buffer}, and disables
further recording of undo information. As a result, it is no longer
the undo list of @var{buffer} is already disabled, this function
has no effect.
-This function returns @code{nil}. It cannot be called interactively.
+This function returns @code{nil}.
The name @code{buffer-flush-undo} is not considered obsolete, but the
preferred name is @code{buffer-disable-undo}.
-@end defun
+@end deffn
As editing continues, undo lists get longer and longer. To prevent
them from using up all available memory space, garbage collection trims
In an interactive call, any prefix argument requests justification.
+@cindex Adaptive Fill mode
In Adaptive Fill mode, which is enabled by default, calling the function
@code{fill-region-as-paragraph} on an indented paragraph when there is
no fill prefix uses the indentation of the second line of the paragraph
@section Margins for Filling
@defopt fill-prefix
-This variable specifies a string of text that appears at the beginning
+This buffer-local variable specifies a string of text that appears at
+the beginning
of normal text lines and should be disregarded when filling them. Any
line that fails to start with the fill prefix is considered the start of
a paragraph; so is any line that starts with the fill prefix followed by
The fill prefix follows the left margin whitespace, if any.
@end defopt
-@defopt fill-column
+@defvar 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
read, you should set @code{fill-column} to no more than 70. Otherwise
the line will be too long for people to read comfortably, and this can
make the text seem clumsy.
-@end defopt
+@end defvar
@defvar default-fill-column
The value of this variable is the default value for @code{fill-column} in
becomes buffer-local when set in any fashion.
@end defvar
-@tindex fill-nobreak-predicate
@defvar fill-nobreak-predicate
+@tindex fill-nobreak-predicate
This variable gives major modes a way to specify not to break a line at
certain places. Its value should be a function. This function is
called during filling, with no arguments and with point located at the
@deffn Command indent-for-tab-command
This command calls the function in @code{indent-line-function} to indent
-the current line; except that if that function is
-@code{indent-to-left-margin}, it calls @code{insert-tab} instead. (That
+the current line; however, if that function is
+@code{indent-to-left-margin}, @code{insert-tab} is called instead. (That
is a trivial command that inserts a tab character.)
@end deffn
@defvar indent-region-function
The value of this variable is a function that can be used by
-@code{indent-region} as a short cut. You should design the function so
+@code{indent-region} as a short cut. It should take two arguments, the
+start and end of the region. You should design the function so
that it will produce the same results as indenting the lines of the
region one by one, but presumably faster.
@var{limit} equals @var{pos}.
@end defun
-@tindex next-char-property-change
@defun next-char-property-change position &optional limit
+@tindex next-char-property-change
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
+@tindex previous-char-property-change
This is like @code{next-char-property-change}, but scans back from
@var{position} instead of forward.
@end defun
before the change. All three arguments are integers. The buffer that's
about to change is always the current buffer.
-The length of the old text is measured in bytes; it is the difference
-between the buffer positions before and after that text, before the
-change. As for the changed text, its length in bytes is simply the
-difference between the first two arguments. If you want the length
-in @emph{characters} of the text before the change, you should use
-a @code{before-change-functions} function that calls @code{chars-in-region}
-(@pxref{Chars and Bytes}).
+The length of the old text the difference between the buffer positions
+before and after that text as it was before the change. As for the
+changed text, its length is simply the difference between the first two
+arguments.
@end defvar
-@tindex combine-after-change-calls
@defmac combine-after-change-calls body...
+@tindex combine-after-change-calls
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 you write a function that you think ought to be added to Emacs under
a certain name, such as @code{twiddle-files}, don't call it by that name
in your program. Call it @code{mylib-twiddle-files} in your program,
-and send mail to @samp{bug-gnu-emacs@@prep.ai.mit.edu} suggesting we add
+and send mail to @samp{bug-gnu-emacs@@gnu.org} suggesting we add
it to Emacs. If and when we do, we can change the name easily enough.
If one prefix is insufficient, your package may use two or three
name that ends in @samp{-flag}.
@item
+@cindex reserved keys
+@cindex keys, reserved
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 do not block them.
If you bind a variable in one function, and use it or set it in another
function, the compiler warns about the latter function unless the
variable has a definition. But often these variables have short names,
-and it is not clean for Lisp packages to define such variables names.
+and it is not clean for Lisp packages to define such variable names.
Therefore, you should rename the variable to start with the name prefix
used for the other functions and variables in your package.
@cindex profiling
@cindex timing programs
@cindex @file{profile.el}
-Use the @file{profile} library to profile your program. See the file
-@file{profile.el} for instructions.
+@cindex @file{elp.el}
+Profile your program with the @file{profile} library or the @file{elp}
+library. See the files @file{profile.el} and @file{elp.el} for
+instructions.
@item
Use iteration rather than recursion whenever possible.
handled specially.
For example, the following input will show you that @code{aref} is
-compiled specially (@pxref{Array Functions}) while @code{elt} is not
-(@pxref{Sequence Functions}):
+compiled specially (@pxref{Array Functions}):
@example
@group
(get 'aref 'byte-compile)
@result{} byte-compile-two-args
@end group
-
-@group
-(get 'elt 'byte-compile)
- @result{} nil
-@end group
@end example
@item
convention, with single-quotes for all symbols.)
@end ifinfo
-For example:
+Help mode automatically creates hyperlinks when documentation strings
+use symbol names inside single quotes, when the symbol has either a
+function or a variable definition. You do not need to do anything
+special to make use of this feature. However, when a symbol has both a
+function definition and a variable definition, and you want to refer to
+just one of them, you can specify which one by writing one of the words
+@samp{variable}, @samp{option}, @samp{function}, or @samp{command},
+immediately before the symbol name. (Case makes no difference in
+recognizing these indicator words.) For example, if you write
+
+@example
+This function sets the variable `buffer-file-name'.
+@end example
+
+@noindent
+then the hyperlink will refer only to the variable documentation of
+@code{buffer-file-name}, and not to its function documentation.
+
+If a symbol has a function definition and/or a variable definition, but
+those are irrelevant to the use of the symbol that you are documenting,
+you can write the word @samp{symbol} before the symbol name to prevent
+making any hyperlink. For example,
@example
-The value of `swim-speed' specifies how fast to swim.
-Possible values are t for high speed, nil for low speed,
-and `medium' for medium speed.
+If the argument KIND-OF-RESULT is the symbol `list',
+this function returns a list of all the objects
+that satisfy the criterion.
@end example
+@noindent
+does not make a hyperlink to the documentation, irrelevant here, of the
+function @code{list}.
+
@item
Don't write key sequences directly in documentation strings. Instead,
use the @samp{\\[@dots{}]} construct to stand for them. For example,
@item Keywords
This line lists keywords for the @code{finder-by-keyword} help command.
+Please use that command to see a list of the meaningful keywords.
+
This field is important; it's how people will find your package when
they're looking for things by topic area. To separate the keywords, you
can use spaces, commas, or both.
@table @samp
@item ;;; Commentary:
This begins introductory comments that explain how the library works.
-It should come right after the copying permissions.
+It should come right after the copying permissions, terminated by a
+@samp{Change Log}, @samp{History} or @samp{Code} comment line. This
+text is used by the Finder package, so it should make sense in that
+context.
+
+@item ;;; Documentation
+This has been used in some files in place of @samp{;;; Commentary:},
+but @samp{;;; Commentary:} is preferred.
-@item ;;; Change log:
+@item ;;; Change Log:
This begins change log information stored in the library file (if you
store the change history there). For most of the Lisp
files distributed with Emacs, the change history is kept in the file
@file{ChangeLog} and not in the source file at all; these files do
-not have a @samp{;;; Change log:} line.
+not have a @samp{;;; Change Log:} line.
@item ;;; Code:
This begins the actual code of the program.
with @samp{:}. These symbols cannot be rebound, nor can their values be
changed. Any attempt to set or bind @code{nil} or @code{t} signals a
@code{setting-constant} error. The same is true for a symbol whose name
-starts with @samp{:}, except that you are allowed to set such symbol to
+starts with @samp{:}, except that you are allowed to set such a symbol to
itself.
@example
@end group
@end example
-@tindex keyword-symbols-constant-flag
@defvar keyword-symbols-constant-flag
+@tindex keyword-symbols-constant-flag
If this variable is @code{nil}, you are allowed to set and bind symbols
whose names start with @samp{:} as you wish. This is to make it
possible to run old Lisp programs which do that.
@end itemize
Variables can also have buffer-local bindings (@pxref{Buffer-Local
-Variables}); a few variables have terminal-local bindings
-(@pxref{Multiple Displays}). These kinds of bindings work somewhat like
-ordinary local bindings, but they are localized depending on ``where''
-you are in Emacs, rather than localized in time.
+Variables}) and frame-local bindings (@pxref{Frame-Local Variables}); a
+few variables have terminal-local bindings (@pxref{Multiple Displays}).
+These kinds of bindings work somewhat like ordinary local bindings, but
+they are localized depending on ``where'' you are in Emacs, rather than
+localized in time.
@defvar max-specpdl-size
@cindex variable limit error
@cindex evaluation error
@cindex infinite recursion
- This variable defines the limit on the total number of local variable
+This variable defines the limit on the total number of local variable
bindings and @code{unwind-protect} cleanups (@pxref{Nonlocal Exits})
that are allowed before signaling an error (with data @code{"Variable
binding depth exceeds max-specpdl-size"}).
- This limit, with the associated error when it is exceeded, is one way
+This limit, with the associated error when it is exceeded, is one way
that Lisp avoids infinite recursion on an ill-defined function.
-
- The default value is 600.
-
- @code{max-lisp-eval-depth} provides another limit on depth of nesting.
+@code{max-lisp-eval-depth} provides another limit on depth of nesting.
@xref{Eval}.
+
+The default value is 600. Entry to the Lisp debugger increases the
+value, if there is little room left, to make sure the debugger itself
+has room to execute.
@end defvar
@node Void Variables
evaluated, and @var{symbol}'s value remains unchanged. If @var{value}
is omitted, the value of @var{symbol} is not changed in any case.
+If @var{symbol} has a buffer-local binding in the current buffer,
+@code{defvar} operates on the default value, which is buffer-independent,
+not the current (buffer-local) binding. It sets the default value if
+the default value is void. @xref{Buffer-Local Variables}.
+
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} 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 (buffer-independent) value, not the
-buffer-local value. @xref{Buffer-Local Variables}.
+@code{eval-defun} arranges to set the variable unconditionally, without
+testing whether its value is void.
If the @var{doc-string} argument appears, it specifies the documentation
for the variable. (This opportunity to specify documentation is one of
@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}.
+does have 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 buffer-local bindings for a symbol that 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).
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}). However, this feature
-is largely obsoleted by the @code{defcustom} (@pxref{Customization}).
+is largely obsoleted by @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
This section describes buffer-local bindings; for frame-local
bindings, see the following section, @ref{Frame-Local Variables}. (A few
-variables have bindings that are local to a X terminal; see
+variables have bindings that are local to each X terminal; see
@ref{Multiple Displays}.)
@menu
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:
+different current buffer, you will not have this problem
+(@pxref{Excursions}). Here is an example of what to avoid:
@example
@group
(setq lcl (buffer-local-variables))
;; @r{First, built-in variables local in all buffers:}
@result{} ((mark-active . nil)
- (buffer-undo-list nil)
+ (buffer-undo-list . nil)
(mode-name . "Fundamental")
@dots{}
@group
This function also resets certain other information pertaining to the
buffer: it sets the local keymap to @code{nil}, the syntax table to the
-value of @code{standard-syntax-table}, and the abbrev table to the value
-of @code{fundamental-mode-abbrev-table}.
+value of @code{(standard-syntax-table)}, the case table to
+@code{(standard-case-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} (see below).
@code{symbol-value}.
@end defun
-@defspec setq-default symbol value
-This sets the default value of @var{symbol} to @var{value}. It does not
-evaluate @var{symbol}, but does evaluate @var{value}. The value of the
-@code{setq-default} form is @var{value}.
+@defspec setq-default [symbol form]@dots{}
+This special form gives each @var{symbol} a new default value, which is
+the result of evaluating the corresponding @var{form}. It does not
+evaluate @var{symbol}, but does evaluate @var{form}. The value of the
+@code{setq-default} form is the value of the last @var{form}.
If a @var{symbol} is not buffer-local for the current buffer, and is not
marked automatically buffer-local, @code{setq-default} has the same
To enable frame-local bindings for a certain variable, call the function
@code{make-variable-frame-local}.
-@defun make-variable-frame-local variable
+@deffn Command make-variable-frame-local variable
Enable the use of frame-local bindings for @var{variable}. This does
not in itself create any frame-local bindings for the variable; however,
if some frame already has a value for @var{variable} as a frame
parameter, that value automatically becomes a frame-local binding.
-If the variable is terminal-local, this function signals an error. Such
-variables cannot have buffer-local bindings as well. @xref{Multiple
-Displays}. A few variables that are implemented specially in Emacs
-can be (and usually are) buffer-local, but can never be frame-local.
-@end defun
+If the variable is terminal-local, this function signals an error,
+because such variables cannot have frame-local bindings as well.
+@xref{Multiple Displays}. A few variables that are implemented
+specially in Emacs can be (and usually are) buffer-local, but can never
+be frame-local.
+@end deffn
Buffer-local bindings take precedence over frame-local bindings. Thus,
consider a variable @code{foo}: if the current buffer has a buffer-local
@defun set-window-buffer window buffer-or-name
This function makes @var{window} display @var{buffer-or-name} as its
-contents. It returns @code{nil}.
+contents. It returns @code{nil}. This is the fundamental primitive
+for changing which buffer is displayed in a window, and all ways
+of doing that call this function.
@example
@group
@end itemize
@end defun
+@defvar buffer-display-time
+@tindex buffer-display-time
+This variable records the time at which a buffer was last made visible
+in a window. It is always local in each buffer; each time
+@code{set-window-buffer} is called, it sets this variable to
+@code{(current-time)} in the specified buffer (@pxref{Time of Day}).
+When a buffer is first created, @code{buffer-display-count} starts out
+with the value @code{nil}.
+@end defvar
+
@node Displaying Buffers
@section Displaying Buffers in Windows
@cindex switching to a buffer
@ifinfo
@xref{Buffers and Windows}, for
@end ifinfo
-low-level functions that give you more precise control.
+low-level functions that give you more precise control. All of these
+functions work by calling @code{set-window-buffer}.
Do not use the functions in this section in order to make a buffer
current so that a Lisp program can access or modify it; they are too
This function returns @code{nil}.
@end deffn
-@tindex buffer-display-count
-@defvar buffer-display-count
-This variable is always buffer-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
@section Horizontal Scrolling
@cindex horizontal scrolling
- Because we read English first from top to bottom and second from left
-to right, horizontal scrolling is not like vertical scrolling. Vertical
-scrolling involves selection of a contiguous portion of text to display.
-Horizontal scrolling causes part of each line to go off screen. The
-amount of horizontal scrolling is therefore specified as a number of
-columns rather than as a position in the buffer. It has nothing to do
-with the display-start position returned by @code{window-start}.
+ Because we read English from left to right in the ``inner loop'', and
+from top to bottom in the ``outer loop'', horizontal scrolling is not
+like vertical scrolling. Vertical scrolling involves selection of a
+contiguous portion of text to display, but horizontal scrolling causes
+part of each line to go off screen. The amount of horizontal scrolling
+is therefore specified as a number of columns rather than as a position
+in the buffer. It has nothing to do with the display-start position
+returned by @code{window-start}.
Usually, no horizontal scrolling is in effect; then the leftmost
column is at the left edge of the window. In this state, scrolling to
Windows}) is what you need here.
@end defvar
-@tindex redisplay-end-trigger-functions
@defvar redisplay-end-trigger-functions
+@tindex 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
after the hook is run.
@end defvar
-@tindex set-window-redisplay-end-trigger
@defun set-window-redisplay-end-trigger window position
+@tindex set-window-redisplay-end-trigger
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
+@tindex window-redisplay-end-trigger
This function returns @var{window}'s current end trigger position.
@end defun
-@tindex window-configuration-change-hook
@defvar window-configuration-change-hook
+@tindex 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
projects / emacs.git / commitdiff