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

*** empty log message ***

Browse Source
This commit is contained in:
Richard M. Stallman 1999-07-17 02:15:13 +00:00
parent b92b7c8da4
commit b6954afd99
14 changed files with 529 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
lispref/buffers.texi
View File

@ -29,6 +29,7 @@ not be displayed in any windows.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
* Buffer Gap:: The gap in the buffer.
@end menu
@node Buffer Basics
@ -980,3 +981,26 @@ is not indirect, the value is @code{nil}. Otherwise, the value is
another buffer, which is never an indirect buffer.
@end defun
@node Buffer Gap
@section The Buffer Gap
Emacs buffers are implemented using an invisible @dfn{gap} to make
insertion and deletion faster. Insertion works by filling in part of
the gap, and deletion adds to the gap. Of course, this means that the
gap must first be moved to the locus of the insertion or deletion.
Emacs moves the gap only when you try to insert or delete. This is why
your first editing command in one part of a large buffer, after
previously editing in another far-away part, sometimes involves a
noticeable delay.
This mechanism works invisibly, and Lisp code should never be affected
by the gap's current location, but these functions are available for
getting information about the gap status.
@defun gap-position
This function returns the current gap position in the current buffer.
@end defun
@defun gap-size
This function returns the current gap size of the current buffer.
@end defun

71
lispref/commands.texi
View File

@ -727,6 +727,14 @@ the events in a vector, so you do never need to deal with the complexities
of storing input events in a string (@pxref{Strings of Events}).
@end defun
@tindex clear-this-command-keys
@defun clear-this-command-keys
This function empties out the table of events for
@code{this-command-keys} to return. This is useful after reading a
password, to prevent the password from echoing inadvertently as part of
the next command in certain cases.
@end defun
@defvar last-nonmenu-event
This variable holds the last input event read as part of a key sequence,
not counting events resulting from mouse menus.
@ -1737,6 +1745,7 @@ can use for translating or modifying input events while reading them.
@menu
* Key Sequence Input:: How to read one key sequence.
* Reading One Event:: How to read just one event.
* Invoking the Input Method:: How reading an event uses the input method.
* Quoted Character Input:: Asking the user to specify a character.
* Event Input Misc:: How to reread or throw away input events.
@end menu
@ -1846,21 +1855,22 @@ from the terminal---not counting those generated by keyboard macros.
The lowest level functions for command input are those that read a
single event.
@defun read-event &optional prompt suppress-input-method
@defun read-event &optional prompt inherit-input-method
This function reads and returns the next event of command input, waiting
if necessary until an event is available. Events can come directly from
the user or from a keyboard macro.
If @var{prompt} is non-@code{nil}, it should be a string to display in
the echo area as a prompt. Otherwise, @code{read-event} does not
display any message to indicate it is waiting for input; instead, it
prompts by echoing: it displays descriptions of the events that led to
or were read by the current command. @xref{The Echo Area}.
If the optional argument @var{prompt} is non-@code{nil}, it should be a
string to display in the echo area as a prompt. Otherwise,
@code{read-event} does not display any message to indicate it is waiting
for input; instead, it prompts by echoing: it displays descriptions of
the events that led to or were read by the current command. @xref{The
Echo Area}.
If @var{suppress-input-method} is non-@code{nil}, then the current input
method is disabled for reading this event. If you want to read an event
without input-method processing, always do it this way; don't try binding
@code{input-method-function} (see below).
If @var{inherit-input-method} is non-@code{nil}, then the current input
method (if any) is employed to make it possible to enter a
non-@sc{ASCII} character. Otherwise, input method handling is disabled
for reading this event.
If @code{cursor-in-echo-area} is non-@code{nil}, then @code{read-event}
moves the cursor temporarily to the echo area, to the end of any message
@ -1883,9 +1893,11 @@ right-arrow function key:
@end example
@end defun
@defun read-char
This function reads and returns a character of command input. It
discards any events that are not characters, until it gets a character.
@defun read-char &optional prompt inherit-input-method
This function reads and returns a character of command input. If the
user generates an event which is not a character (i.e. a mouse click or
function key event), @code{read-char} signals an error. The arguments
work as in @code{read-event}.
In the first example, the user types the character @kbd{1} (@sc{ASCII}
code 49). The second example shows a keyboard macro definition that
@ -1913,11 +1925,21 @@ the echo area.
@end example
@end defun
@code{read-event} also invokes the current input method, if any. If
the value of @code{input-method-function} is non-@code{nil}, it should
be a function; when @code{read-event} reads a printing character
(including @key{SPC}) with no modifier bits, it calls that function,
passing the event as an argument.
@defun read-char-exclusive &optional prompt inherit-input-method
This function reads and returns a character of command input. If the
user generates an event which is not a character,
@code{read-char-exclusive} ignores it and reads another event, until it
gets a character. The arguments work as in @code{read-event}.
@end defun
@node Invoking the Input Method
@subsection Invoking the Input Method
The event-reading functions invoke the current input method, if any
(@pxref{Input Methods}). If the value of @code{input-method-function}
is non-@code{nil}, it should be a function; when @code{read-event} reads
a printing character (including @key{SPC}) with no modifier bits, it
calls that function, passing the character as an argument.
@defvar input-method-function
If this is non-@code{nil}, its value specifies the current input method
@ -1943,13 +1965,12 @@ bits.
@code{nil} first, to prevent recursion.
The input method function is not called when reading the second and
subsequent event of a key sequence. Thus, these characters are not
subject to input method processing. It is usually a good idea for the
input method processing to test the values of
@code{overriding-local-map} and @code{overriding-terminal-local-map}; if
either of these variables is non-@code{nil}, the input method should put
its argument into a list and return that list with no further
processing.
subsequent events of a key sequence. Thus, these characters are not
subject to input method processing. The input method function should
test the values of @code{overriding-local-map} and
@code{overriding-terminal-local-map}; if either of these variables is
non-@code{nil}, the input method should put its argument into a list and
return that list with no further processing.
@node Quoted Character Input
@subsection Quoted Character Input

151
lispref/customize.texi
View File

@ -183,12 +183,12 @@ values are legitimate, and how to display the value.
@item :options @var{list}
Specify @var{list} as the list of reasonable values for use in this
option.
option. The user is not restricted to using only these values, but they
are offered as convenient alternatives.
Currently this is meaningful only when the type is @code{hook}. In that
case, the elements of @var{list} should be functions that are useful as
elements of the hook value. The user is not restricted to using only
these functions, but they are offered as convenient alternatives.
This is meaningful only for certain types, currently including
@code{hook}, @code{plist} and @code{alist}. See the definition of the
individual types for a description of how to use @code{:options}.
@item :version @var{version}
This option specifies that the variable was first introduced, or its
@ -267,17 +267,25 @@ Keywords}. Here is an example, from the library @file{paren.el}:
:require 'paren)
@end example
@ignore
Use @code{custom-add-option} to specify that a specific function is
useful as an member of a hook.
If a customization item has a type such as @code{hook} or @code{alist},
which supports @code{:options}, you can add additional options to the
item, outside the @code{defcustom} declaration, by calling
@code{custom-add-option}. For example, if you define a function
@code{my-lisp-mode-initialization} intended to be called from
@code{emacs-lisp-mode-hook}, you might want to add that to the list of
options for @code{emacs-lisp-mode-hook}, but not by editing its
definition. You can do it thus:
@example
(custom-add-option 'emacs-lisp-mode-hook 'my-lisp-mode-initialization)
@end example
@defun custom-add-option symbol option
To the variable @var{symbol} add @var{option}.
To the customization @var{symbol}, add @var{option}.
If @var{symbol} is a hook variable, @var{option} should be a hook
member. For other types variables, the effect is undefined."
The precise effect of adding @var{option} depends on the customization
type of @var{symbol}.
@end defun
@end ignore
Internally, @code{defcustom} uses the symbol property
@code{standard-value} to record the expression for the default value,
@ -376,6 +384,125 @@ You can use the @code{:options} keyword in a hook variable's
@code{defcustom} to specify a list of functions recommended for use in
the hook; see @ref{Variable Definitions}.
@item alist
The value must be a list of cons-cells, the car of each cell
representing a key, and the cdr of the same cell representing and
associated value. The use can add and a delete key/value pairs, and
edit both the key and the value of each pair.
You can specify the key and value types like this:
@example
(alist :key-type @var{key-type}
:value-type @var{value-type})
@end example
@noindent
where @var{key-type} and @var{value-type} are customization type
specifications. The default key type is @code{sexp}, and the default
value type is @code{sexp}.
The user can add any key matching the specified key type, but you can
give some keys a preferential treatment by specifying them with the
@code{:options} (see @ref{Variable Definitions}). The specified keys
will always be shown in the customize buffer (together with a suitable
value), with a checkbox to include or exclude or disable the key/value
pair from the alist. The user will not be able to edit the keys
specified by the @code{:options} keyword argument.
The argument to the @code{:options} keywords should be a list of option
specifications. Ordinarily, the options are simply atoms, which are the
specified keys. For example:
@example
:options '("foo" "bar" "baz")
@end example
@noindent
specifies that there are three ``known'' keys, namely @code{"foo"},
@code{"bar"} and @code{"baz"}, which will always be shown first.
You may want to restrict the value type for specific keys, for example,
the value associated with the @code{"bar"} key can only be an integer.
You can specify this by using a list instead of an atom in the option
specification. The first element will specify the key, like before,
while the second element will specify the value type.
@example
:options '("foo" ("bar" integer) "baz")
@end example
Finally, you may want to change how the key is presented. By default,
the key is simply shown as a @code{const}, since the user cannot change
the special keys specified with the @code{:options} keyword. However,
you may want to use a more specialized type for presenting the key, like
@code{function-item} if you know it is a symbol with a function binding.
This is done by using a customization type specification instead of a
symbol for the key.
@example
:options '("foo" ((function-item some-function) integer) "baz")
@end example
Many alist uses lists with two elements, instead of cons cells. For
example,
@example
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE).")
@end example
@noindent
instead of
@example
(defcustom cons-alist '(("foo" . 1) ("bar" . 2) ("baz" . 3))
"Each element is a cons-cell (KEY . VALUE).")
@end example
Because of the way lists are implemented on top of cons cells, you can
treat @code{list-alist} in the example above as a cons cell alist, where
the value type is a list with a single element containing the real
value.
@example
(defcustom list-alist '(("foo" 1) ("bar" 2) ("baz" 3))
"Each element is a list of the form (KEY VALUE)."
:type '(alist :value-type (group integer)))
@end example
The @code{group} widget is used here instead of @code{list} only because
the formatting is better suited for the purpose.
Similarily, you can have alists with more values associated with each
key, using variations of this trick:
@example
(defcustom person-data '(("brian" 50 t)
("dorith" 55 nil)
("ken" 52 t))
"Alist of people, each element has the form (NAME AGE MALE)."
:type '(alist :value-type (group age boolean)))
(defcustom pets '(("brian")
("dorith" "dog" "guppy")
("ken" "cat"))
"Alist where the KEY is a person, and the VALUE is a list of pets."
:type '(alist :value-type (repeat string)))
@end example
@item plist
The @code{plist} custom type is similar to the @code{alist} (see above),
except that the information is stored as a property list, i.e. a list of
this form:
@example
(@var{key} @var{value} @var{key} @var{value} @var{key} @var{value} @dots{})
@end example
The default @code{:key-type} for @code{plist} is @code{symbol},
rather than @code{sexp}.
@item symbol
The value must be a symbol. It appears in the customization buffer as
the name of the symbol.

44
lispref/display.texi
View File

@ -179,6 +179,14 @@ Minibuffer depth is 0.
@end example
@end defun
@tindex with-temp-message
@defmac with-temp-message message &rest body
This construct displays a message in the echo area temporarily, during
the execution of @var{body}. It displays @var{message}, executes
@var{body}, then returns the value of the last body form while restoring
the previous echo area contents.
@end defmac
@defun message-or-box string &rest arguments
This function displays a message like @code{message}, but may display it
in a dialog box instead of the echo area. If this function is called in
@ -520,9 +528,16 @@ buffer and then present it to the user for perusal rather than for
editing. Many help commands use this feature.
@defspec with-output-to-temp-buffer buffer-name forms@dots{}
This function executes @var{forms} while arranging to insert any
output they print into the buffer named @var{buffer-name}. The buffer
is then shown in some window for viewing, displayed but not selected.
This function executes @var{forms} while arranging to insert any output
they print into the buffer named @var{buffer-name}, which is first
created if necessary, and put into Help mode. Finally, the buffer is
displayed in some window, but not selected.
If the @var{forms} do not change the major mode in the output buffer, so
that it is still Help mode at the end of their execution, then
@code{with-output-to-temp-buffer} makes this buffer read-only at the
end, and also scans it for function and variable names to make them into
clickable cross-references.
The string @var{buffer-name} specifies the temporary buffer, which
need not already exist. The argument must be a string, not a buffer.
@ -536,6 +551,9 @@ that buffer (but screen display and messages in the echo area, although
they are ``output'' in the general sense of the word, are not affected).
@xref{Output Functions}.
Several hooks are available for customizing the behavior
of this construct; they are listed below.
The value of the last form in @var{forms} is returned.
@example
@ -568,14 +586,25 @@ 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
@code{save-selected-window} and with the chosen window and buffer
selected.
@end defvar
@defvar temp-buffer-setup-hook
@tindex temp-buffer-setup-hook
This normal hook is run by @code{with-output-to-temp-buffer} before
evaluating @var{body}. When the hook runs, the help buffer is current.
This hook is normally set up with a function to put the buffer in Help
mode.
@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.
current, and the window it was displayed in is selected. This hook is
normally set up with a function to make the buffer read only, and find
function names and variable names in it, provided the major mode is
still Help mode.
@end defvar
@defun momentary-string-display string position &optional char message
@ -1443,6 +1472,11 @@ table, for any character whose entry in the active display table is
@code{nil}. Thus, when you set up a display table, you need only
specify the characters for which you want special behavior.
These display rules apply to carriage return (character code 13), when
it appears in the buffer. But that character may not appear in the
buffer where you expect it, if it was eliminated as part of end-of-line
conversion (@xref{Coding System Basics}).
These variables affect the way certain characters are displayed on the
screen. Since they change the number of columns the characters occupy,
they also affect the indentation functions. These variables also affect

24
lispref/elisp.texi
View File

@ -12,8 +12,8 @@
@smallbook
@ifinfo
This version is the edition 2.5 of the GNU Emacs Lisp
Reference Manual. It corresponds to Emacs Version 20.3
This Info file contains edition 2.5.1 of the GNU Emacs Lisp
Reference Manual, corresponding to Emacs version 20.4.
@c Please REMEMBER to update edition number in *four* places in this file
@c and also in *one* place in intro.texi
@ -21,7 +21,8 @@ Published by the Free Software Foundation
59 Temple Place, Suite 330
Boston, MA 02111-1307 USA
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc.
Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
Free Software Foundation, Inc.
Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
@ -71,21 +72,22 @@ instead of in the original English.
@titlepage
@title GNU Emacs Lisp Reference Manual
@subtitle For Emacs Version 20.3
@subtitle For Emacs Version 20.4
@c The edition number appears in several places in this file
@c and also in the file intro.texi.
@subtitle Revision 2.5, May 1998
@subtitle Revision 2.5.1, January 1999
@author by Bil Lewis, Dan LaLiberte, Richard Stallman
@author and the GNU Manual Group
@page
@vskip 0pt plus 1filll
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998 Free Software Foundation, Inc.
Copyright @copyright{} 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1998, 1999
Free Software Foundation, Inc.
@sp 2
Edition 2.5 @*
Revised for Emacs Version 20.3,@*
May 1998.@*
Edition 2.5.1 @*
Revised for Emacs Version 20.4,@*
January 1999.@*
@sp 2
ISBN 1-882114-72-8
@ -118,8 +120,8 @@ Cover art by Etienne Suvasa.
@node Top, Copying, (dir), (dir)
@ifinfo
This Info file contains edition 2.5 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 20.3.
This Info file contains edition 2.5.1 of the GNU Emacs Lisp
Reference Manual, corresponding to GNU Emacs version 20.4.
@end ifinfo
@menu

60
lispref/files.texi
View File

@ -83,7 +83,7 @@ not alter it, the fastest way is to use @code{insert-file-contents} in a
temporary buffer. Visiting the file is not necessary and takes longer.
@xref{Reading from Files}.
@deffn Command find-file filename
@deffn Command find-file filename &optional wildcards
This command selects a buffer visiting the file @var{filename},
using an existing buffer if there is one, and otherwise creating a
new buffer and reading the file into it. It also returns that buffer.
@ -98,17 +98,25 @@ like this:
@noindent
(See @code{switch-to-buffer} in @ref{Displaying Buffers}.)
If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file} expands wildcard characters in
@var{filename} and visits all the matching files.
When @code{find-file} is called interactively, it prompts for
@var{filename} in the minibuffer.
@end deffn
@defun find-file-noselect filename &optional nowarn rawfile
@defun find-file-noselect filename &optional nowarn rawfile wildcards
This function is the guts of all the file-visiting functions. It finds
or creates a buffer visiting the file @var{filename}, and returns it.
It uses an existing buffer if there is one, and otherwise creates a new
buffer and reads the file into it. You may make the buffer current or
display it in a window if you wish, but this function does not do so.
If @var{wildcards} is non-@code{nil}, which is always true in an
interactive call, then @code{find-file-noselect} expands wildcard
characters in @var{filename} and visits all the matching files.
When @code{find-file-noselect} uses an existing buffer, it first
verifies that the file has not changed since it was last visited or
saved in that buffer. If the file has changed, then this function asks
@ -146,7 +154,7 @@ visiting the file @var{filename}.
@end example
@end defun
@deffn Command find-file-other-window filename
@deffn Command find-file-other-window filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, but
does so in a window other than the selected window. It may use another
existing window or split a window; see @ref{Displaying Buffers}.
@ -155,7 +163,7 @@ When this command is called interactively, it prompts for
@var{filename}.
@end deffn
@deffn Command find-file-read-only filename
@deffn Command find-file-read-only filename &optional wildcards
This command selects a buffer visiting the file @var{filename}, like
@code{find-file}, but it marks the buffer as read-only. @xref{Read Only
Buffers}, for related functions and variables.
@ -175,6 +183,14 @@ When @code{view-file} is called interactively, it prompts for
@var{filename}.
@end deffn
@tindex find-file-wildcards
@defvar find-file-wildcards
If this variable is non-@code{nil}, then the various @code{find-file}
commands check for wildcard characters and visit all the files that
match them. If this is @code{nil}, then wildcard characters are
not treated specially.
@end defvar
@defvar find-file-hooks
The value of this variable is a list of functions to be called after a
file is visited. The file's local-variables specification (if any) will
@ -560,13 +576,16 @@ interfere with each other. Emacs tries to prevent this situation from
arising by recording a @dfn{file lock} when a file is being modified.
Emacs can then detect the first attempt to modify a buffer visiting a
file that is locked by another Emacs job, and ask the user what to do.
The file lock is really a file, a symbolic link with a special name,
stored in the same directory as the file you are editing.
File locks are not completely reliable when multiple machines can
share file systems. When file locks do not work, it is possible for two
users to make changes simultaneously, but Emacs can still warn the user
who saves second. Also, the detection of modification of a buffer
visiting a file changed on disk catches some cases of simultaneous
editing; see @ref{Modification Time}.
When you access files using NFS, there may be a small probability that
you and another user will both lock the same file ``simultaneously''.
If this happens, it is possible for the two users to make changes
simultaneously, but Emacs will still warn the user who saves second.
Also, the detection of modification of a buffer visiting a file changed
on disk catches some cases of simultaneous editing; see
@ref{Modification Time}.
@defun file-locked-p filename
This function returns @code{nil} if the file @var{filename} is not
@ -583,7 +602,7 @@ some other job.
@end defun
@defun lock-buffer &optional filename
This function locks the file @var{filename}, if the current buffer is
This function locks the file @var{filename}, if the current buffer is
modified. The argument @var{filename} defaults to the current buffer's
visited file. Nothing is done if the current buffer is not visiting a
file, or is not modified.
@ -861,7 +880,7 @@ existing directory, @code{nil} otherwise.
@defun file-regular-p filename
This function returns @code{t} if the file @var{filename} exists and is
a regular file (not a directory, symbolic link, named pipe, terminal, or
a regular file (not a directory, named pipe, terminal, or
other I/O device).
@end defun
@ -997,7 +1016,8 @@ The time of last modification as a list of two integers (as above).
The time of last status change as a list of two integers (as above).
@item
The size of the file in bytes.
The size of the file in bytes. If the size is too large to fit in a
Lisp integer, this is a floating point number.
@item
The file's modes, as a string of ten letters or dashes,
@ -1902,6 +1922,20 @@ This function returns a list of all versions of the file named
@var{file} in directory @var{dirname}.
@end defun
@tindex file-expand-wildcards
@defun file-expand-wildcards pattern &optional full
This function expands the wildcard pattern @var{pattern}, returning
alist of file names that match it.
If @var{pattern} is written as an absolute relative file name,
the values are absolute also.
If @var{pattern} is written as a relative file name, it is interpreted
relative to the current default directory. The file names returned are
normally also relative to the current default directory. However, if
@var{full} is non-@code{nil}, they are absolute.
@end defun
@defun insert-directory file switches &optional wildcard full-directory-p
This function inserts (in the current buffer) a directory listing for
directory @var{file}, formatted with @code{ls} according to

6
lispref/frames.texi
View File

@ -364,7 +364,11 @@ The width of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
@item window-id
The number of the window-system window used by the frame.
The number of the window-system window used by the frame
to contain the actual Emacs windows.
@item outer-window-id
The number of the outermost window-system window used for the whole frame.
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means

12
lispref/keymaps.texi
View File

@ -461,18 +461,20 @@ active keymap.
@end group
@end example
@defun define-prefix-command symbol
@defun define-prefix-command symbol &optional mapvar prompt
@cindex prefix command
This function prepares @var{symbol} for use as a prefix key's binding:
it creates a full keymap and stores it as @var{symbol}'s function
definition. Subsequently binding a key sequence to @var{symbol} will
make that key sequence into a prefix key.
make that key sequence into a prefix key. The return value is @code{symbol}.
This function also sets @var{symbol} as a variable, with the keymap as
its value. It returns @var{symbol}.
its value. But if @var{mapvar} is non-@code{nil}, it sets @var{mapvar}
as a variable instead.
@c In Emacs version 18, only the function definition of @var{symbol} was
@c set, not the value as a variable.
If @var{prompt} is non-@code{nil}, that becomes the overall prompt
string for the keymap. The prompt string is useful for menu keymaps
(@pxref{Menu Keymaps}).
@end defun
@node Active Keymaps

12
lispref/lists.texi
View File

@ -32,7 +32,7 @@ the whole list.
Lists in Lisp are not a primitive data type; they are built up from
@dfn{cons cells}. A cons cell is a data object that represents an
ordered pair. It holds, or ``points to,'' two Lisp objects, one labeled
ordered pair. It holds, or ``refers to,'' two Lisp objects, one labeled
as the @sc{car}, and the other labeled as the @sc{cdr}. These names are
traditional; see @ref{Cons Cell Type}. @sc{cdr} is pronounced
``could-er.''
@ -82,7 +82,7 @@ made from two cons cells:
@end example
Each pair of boxes represents a cons cell. Each box ``refers to'',
``points to'' or ``contains'' a Lisp object. (These terms are
``points to'' or ``holds'' a Lisp object. (These terms are
synonymous.) The first box, which describes the @sc{car} of the first
cons cell, contains the symbol @code{tulip}. The arrow from the
@sc{cdr} box of the first cons cell to the second cons cell indicates
@ -222,7 +222,7 @@ considered a list and @code{not} when it is considered a truth value
@cindex list elements
@defun car cons-cell
This function returns the value pointed to by the first pointer of the
This function returns the value referred to by the first slot of the
cons cell @var{cons-cell}. Expressed another way, this function
returns the @sc{car} of @var{cons-cell}.
@ -244,7 +244,7 @@ or @code{nil}.
@end defun
@defun cdr cons-cell
This function returns the value pointed to by the second pointer of
This function returns the value referred to by the second slot of
the cons cell @var{cons-cell}. Expressed another way, this function
returns the @sc{cdr} of @var{cons-cell}.
@ -672,7 +672,7 @@ different element.
@defun setcar cons object
This function stores @var{object} as the new @sc{car} of @var{cons},
replacing its previous @sc{car}. In other words, it changes the
@sc{car} slot of @var{cons} to point to @var{object}. It returns the
@sc{car} slot of @var{cons} to refer to @var{object}. It returns the
value @var{object}. For example:
@example
@ -775,7 +775,7 @@ x2: |
@defun setcdr cons object
This function stores @var{object} as the new @sc{cdr} of @var{cons},
replacing its previous @sc{cdr}. In other words, it changes the
@sc{cdr} slot of @var{cons} to point to @var{object}. It returns the
@sc{cdr} slot of @var{cons} to refer to @var{object}. It returns the
value @var{object}.
@end defun

4
lispref/loading.texi
View File

@ -640,7 +640,7 @@ error in the evaluating its contents, any function definitions or
@xref{Autoload}.
@end defun
@defun require feature &optional filename
@defun require feature &optional filename noerror
This function checks whether @var{feature} is present in the current
Emacs session (using @code{(featurep @var{feature})}; see below). The
argument @var{feature} must be a symbol.
@ -654,7 +654,7 @@ used.
If loading the file fails to provide @var{feature}, @code{require}
signals an error, @samp{Required feature @var{feature} was not
provided}.
provided}, unless @var{noerror} is non-@code{nil}.
@end defun
@defun featurep feature

145
lispref/nonascii.texi
View File

@ -55,10 +55,17 @@ stored. The first byte of a multibyte character is always in the range
character are always in the range 160 through 255 (octal 0240 through
0377); these values are @dfn{trailing codes}.
Some sequences of bytes do not form meaningful multibyte characters:
for example, a single isolated byte in the range 128 through 255 is
never meaningful. Such byte sequences are not entirely valid, and never
appear in proper multibyte text (since that consists of a sequence of
@emph{characters}); but they can appear as part of ``raw bytes''
(@pxref{Explicit Encoding}).
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.
The representation for a string is determined when the string is
constructed and recorded in the string.
@defvar enable-multibyte-characters
@tindex enable-multibyte-characters
@ -83,9 +90,21 @@ The @samp{--unibyte} command line option does its job by setting the
default value to @code{nil} early in startup.
@end defvar
@defun position-bytes position
@tindex position-bytes
Return the byte-position corresponding to buffer position @var{position}
in the current buffer.
@end defun
@defun byte-to-position byte-position
@tindex byte-to-position
Return the buffer position corresponding to byte-position
@var{byte-position} in the current buffer.
@end defun
@defun multibyte-string-p string
@tindex multibyte-string-p
Return @code{t} if @var{string} contains multibyte characters.
Return @code{t} if @var{string} is a multibyte string.
@end defun
@node Converting Representations
@ -190,6 +209,10 @@ This function sets @code{enable-multibyte-characters} to record which
representation is in use. It also adjusts various data in the buffer
(including overlays, text properties and markers) so that they cover the
same text as they did before.
You cannot use @code{set-buffer-multibyte} on an indirect buffer,
because indirect buffers always inherit the representation of the
base buffer.
@end defun
@defun string-as-unibyte string
@ -198,8 +221,8 @@ 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.
If @var{string} is unibyte already, then the value is @var{string}
itself.
If @var{string} is already a unibyte string, then the value is
@var{string} itself.
@end defun
@defun string-as-multibyte string
@ -208,8 +231,8 @@ 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.
If @var{string} is multibyte already, then the value is @var{string}
itself.
If @var{string} is already a multibyte string, then the value is
@var{string} itself.
@end defun
@node Character Codes
@ -269,8 +292,8 @@ This function returns a list of all defined character set names.
@defun char-charset character
@tindex char-charset
This function returns the name of the character
set that @var{character} belongs to.
This function returns the name of the character set that @var{character}
belongs to.
@end defun
@node Chars and Bytes
@ -291,15 +314,21 @@ 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.
This function returns the dimension of @var{charset}; at present, the
dimension is always 1 or 2.
@end defun
@defun charset-bytes charset
@tindex charset-bytes
This function returns the number of bytes used to represent a character
in character set @var{charset}.
@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-bytes @var{charset})
(charset-dimension @var{charset}))
@end example
@ -311,28 +340,6 @@ 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.
@defun char-bytes character
@tindex char-bytes
This function returns the number of bytes used to represent the
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
(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
@defun split-char character
@tindex split-char
Return a list containing the name of the character set of
@ -406,15 +413,25 @@ 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.
In two peculiar cases, the value includes the symbol @code{unknown}:
@itemize @bullet
@item
When a unibyte buffer contains non-@sc{ASCII} characters.
@item
When a multibyte buffer contains invalid byte-sequences (raw bytes).
@xref{Explicit Encoding}.
@end itemize
@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.
This function returns a list of the character sets that appear in the
string @var{string}. It is just like @code{find-charset-region}, except
that it applies to the contents of @var{string} instead of part of the
current buffer.
@end defun
@node Translation of Characters
@ -478,6 +495,8 @@ subprocess or receives text from a subprocess, it normally performs
character code conversion and end-of-line conversion as specified
by a particular @dfn{coding system}.
How to define a coding system is an arcane matter, not yet documented.
@menu
* Coding System Basics::
* Encoding and I/O::
@ -583,6 +602,9 @@ 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.
However, @code{buffer-file-coding-system} does not affect sending text
to a subprocess.
@end defvar
@defvar save-buffer-coding-system
@ -897,7 +919,7 @@ input, including @code{file-coding-system-alist},
@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.
as well as sending output to subprocesses and net connections.
When a single operation does both input and output, as do
@code{call-process-region} and @code{start-process}, both
@ -944,14 +966,43 @@ write them with @code{write-region} (@pxref{Writing to Files}), and
suppress encoding for that @code{write-region} call by binding
@code{coding-system-for-write} to @code{no-conversion}.
Raw bytes typically contain stray individual bytes with values in the
range 128 through 255, that are legitimate only as part of multibyte
sequences. Even if the buffer is multibyte, Emacs treats each such
individual byte as a character and uses the byte value as its character
code. In this way, character codes 128 through 255 can be found in a
multibyte buffer, even though they are not legitimate multibyte
character codes.
Raw bytes sometimes contain overlong byte-sequences that look like a
proper multibyte character plus extra bytes containing trailing codes.
For most purposes, Emacs treats such a sequence in a buffer or string as
a single character, and if you look at its character code, you get the
value that corresponds to the multibyte character sequence---the extra
bytes are disregarded. This behavior is not quite clean, but raw bytes
are used only in limited places in Emacs, so as a practical matter
problems can be avoided.
proper multibyte character plus extra superfluous trailing codes. For
most purposes, Emacs treats such a sequence in a buffer or string as a
single character, and if you look at its character code, you get the
value that corresponds to the multibyte character
sequence---disregarding the extra trailing codes. This is not quite
clean, but raw bytes are used only in limited ways, so as a practical
matter it is not worth the trouble to treat this case differently.
When a multibyte buffer contains illegitimate byte sequences,
sometimes insertion or deleteion can cause them to coalesce into a
legitimate multibyte character. For example, suppose the buffer
contains the sequence 129 68 192, 68 being the character @samp{D}. If
you delete the @samp{D}, the bytes 129 and 192 become adjacent, and thus
become one multibyte character (Latin-1 A with grave accent). Point
moves to one side or the other of the character, since it cannot be
within a character. Don't be alarmed by this.
Some really peculiar situations prevent proper coalescence. For
example, if you narrow the buffer so that the accessible portion begins
just before the @samp{D}, then delete the @samp{D}, the two surrounding
bytes cannot coalesce because one of them is outside the accessible
portion of the buffer. In this case, the deletion cannot be done, so
@code{delete-region} signals an error.
Here are the functions to perform explicit encoding or decoding. The
decoding functions produce ``raw bytes''; the encoding functions are
meant to operate on ``raw bytes''. All of these functions discard text
properties.
@defun encode-coding-region start end coding-system
@tindex encode-coding-region

59
lispref/objects.texi
View File

@ -232,6 +232,8 @@ Control, Meta and Shift.
@cindex read syntax for characters
@cindex printed representation for characters
@cindex syntax for characters
@cindex @samp{?} in character constant
@cindex question mark in character constant
Since characters are really integers, the printed representation of a
character is a decimal number. This is also a possible read syntax for
a character, but writing characters that way in Lisp programs is a very
@ -389,7 +391,9 @@ $2^{25}$
bit to indicate that the shift key was used in typing a control
character. This distinction is possible only when you use X terminals
or other special terminals; ordinary terminals do not report the
distinction to the computer in any way.
distinction to the computer in any way. The Lisp syntax for
the shift bit is @samp{\S-}; thus, @samp{?\C-\S-o} or @samp{?\C-\S-O}
represents the shifted-control-o character.
@cindex hyper characters
@cindex super characters
@ -408,8 +412,6 @@ Numerically, the
bit values are 2**22 for alt, 2**23 for super and 2**24 for hyper.
@end ifinfo
@cindex @samp{?} in character constant
@cindex question mark in character constant
@cindex @samp{\} in character constant
@cindex backslash in character constant
@cindex octal character code
@ -555,11 +557,17 @@ same object, @code{nil}.
@cindex decrement field of register
@cindex pointers
A @dfn{cons cell} is an object that consists of two pointers or slots,
called the @sc{car} slot and the @sc{cdr} slot. Each slot can
@dfn{point to} or hold to any Lisp object. We also say that the ``the
@sc{car} of this cons cell is'' whatever object its @sc{car} slot
currently points to, and likewise for the @sc{cdr}.
A @dfn{cons cell} is an object that consists of two slots, called the
@sc{car} slot and the @sc{cdr} slot. Each slot can @dfn{hold} or
@dfn{refer to} any Lisp object. We also say that the ``the @sc{car} of
this cons cell is'' whatever object its @sc{car} slot currently holds,
and likewise for the @sc{cdr}.
@quotation
A note to C programmers: in Lisp, we do not distinguish between
``holding'' a value and ``pointing to'' the value, because pointers in
Lisp are implicit.
@end quotation
A @dfn{list} is a series of cons cells, linked together so that the
@sc{cdr} slot of each cons cell holds either the next cons cell or the
@ -573,7 +581,7 @@ divided words into two parts, called the ``address'' part and the
``decrement''; @sc{car} was an instruction to extract the contents of
the address part of a register, and @sc{cdr} an instruction to extract
the contents of the decrement. By contrast, ``cons cells'' are named
for the function @code{cons} that creates them, which in turn is named
for the function @code{cons} that creates them, which in turn was named
for its purpose, the construction of cells.
@cindex atom
@ -588,10 +596,10 @@ right parenthesis.
Upon reading, each object inside the parentheses becomes an element
of the list. That is, a cons cell is made for each element. The
@sc{car} slot of the cons cell points to the element, and its @sc{cdr}
slot points to the next cons cell of the list, which holds the next
@sc{car} slot of the cons cell holds the element, and its @sc{cdr}
slot refers to the next cons cell of the list, which holds the next
element in the list. The @sc{cdr} slot of the last cons cell is set to
point to @code{nil}.
hold @code{nil}.
@cindex box diagrams, for lists
@cindex diagrams, boxed, for lists
@ -613,13 +621,14 @@ list @code{(rose violet buttercup)}:
@end group
@end example
In this diagram, each box represents a slot that can point to any Lisp
object. Each pair of boxes represents a cons cell. Each arrow is a
pointer to a Lisp object, either an atom or another cons cell.
In this diagram, each box represents a slot that can hold or refer to
any Lisp object. Each pair of boxes represents a cons cell. Each arrow
represents a reference to a Lisp object, either an atom or another cons
cell.
In this example, the first box, which holds the @sc{car} of the first
cons cell, points to or ``contains'' @code{rose} (a symbol). The second
box, holding the @sc{cdr} of the first cons cell, points to the next
cons cell, refers to or ``holds'' @code{rose} (a symbol). The second
box, holding the @sc{cdr} of the first cons cell, refers to the next
pair of boxes, the second cons cell. The @sc{car} of the second cons
cell is @code{violet}, and its @sc{cdr} is the third cons cell. The
@sc{cdr} of the third (and last) cons cell is @code{nil}.
@ -791,7 +800,7 @@ functions that work on alists.
@subsection Array Type
An @dfn{array} is composed of an arbitrary number of slots for
pointing to other Lisp objects, arranged in a contiguous block of
holding or referring to other Lisp objects, arranged in a contiguous block of
memory. Accessing any element of an array takes approximately the same
amount of time. In contrast, accessing an element of a list requires
time proportional to the position of the element in the list. (Elements
@ -885,18 +894,16 @@ makes the string multibyte. If the string constant is read from a
unibyte source, then the character is read as unibyte and that makes the
string unibyte.
@c ??? Change this?
You can also represent a multibyte non-@sc{ASCII} character with its
character code, using a hex escape, @samp{\x@var{nnnnnnn}}, with as many
digits as necessary. (Multibyte non-@sc{ASCII} character codes are all
greater than 256.) Any character which is not a valid hex digit
terminates this construct. If the character that would follow is a hex
digit, write @w{@samp{\ }} (backslash and space)
to terminate the hex escape---for example,
@w{@samp{\x8e0\ }} 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.
terminates this construct. If the next character in the string could be
interpreted as a hex digit, write @w{@samp{\ }} (backslash and space) to
terminate the hex escape---for example, @w{@samp{\x8e0\ }} 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.
Using a multibyte hex escape forces the string to multibyte. You can
represent a unibyte non-@sc{ASCII} character with its character code,

15
lispref/processes.texi
View File

@ -693,6 +693,13 @@ subprocess receives it, much like text written into a file. You can use
@code{coding-system-for-write}, if that is non-@code{nil}; or else from
the defaulting mechanism (@pxref{Default Coding Systems}).
Sometimes the system is unable to accept input for that process,
because the input buffer is full. When this happens, the send functions
wait a short while, accepting output from subprocesses, and then try
again. This gives the subprocess a chance to read more of its pending
input and make space in the buffer. It also allows filters, sentinels
and timers to run---so take account of that in writing your code.
@defun process-send-string process-name string
This function sends @var{process-name} the contents of @var{string} as
standard input. The argument @var{process-name} must be a process or
@ -749,6 +756,14 @@ error is signaled if the current buffer has no process.
@end smallexample
@end defun
@defun process-running-child-p process
@tindex process-running-child-p process
This function will tell you whether a subprocess has given control of
its terminal to its own child process. The value is @code{t} if this is
true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
that this is not so.
@end defun
@node Signals to Processes
@section Sending Signals to Processes
@cindex process signals

59
lispref/text.texi
View File

@ -9,9 +9,9 @@
This chapter describes the functions that deal with the text in a
buffer. Most examine, insert, or delete text in the current buffer,
often in the vicinity of point. Many are interactive. All the
functions that change the text provide for undoing the changes
(@pxref{Undo}).
often operating at point or on text adjacent to point. Many are
interactive. All the functions that change the text provide for undoing
the changes (@pxref{Undo}).
Many text-related functions operate on a region of text defined by two
buffer positions passed in arguments named @var{start} and @var{end}.
@ -26,7 +26,9 @@ interactive call, point and the mark are used for these arguments.
@cindex buffer contents
Throughout this chapter, ``text'' refers to the characters in the
buffer, together with their properties (when relevant).
buffer, together with their properties (when relevant). Keep in mind
that point is always between two characters, and the cursor appears on
the character after point.
@menu
* Near Point:: Examining text in the vicinity of point.
@ -53,6 +55,7 @@ buffer, together with their properties (when relevant).
* Transposition:: Swapping two portions of a buffer.
* Registers:: How registers are implemented. Accessing the text or
position stored in a register.
* Base 64:: Conversion to or from base 64 encoding.
* Change Hooks:: Supplying functions to be run when text is changed.
@end menu
@ -3223,6 +3226,54 @@ is non-@code{nil}, @code{transpose-regions} does not do this---it leaves
all markers unrelocated.
@end defun
@node Base 64
@section Base 64 Encoding
@cindex base 64 encoding
Base 64 code is used in email to encode a sequence of 8-bit bytes as a
longer sequence of @sc{ASCII} graphic characters. This section
describes the functions for converting to and from this code.
@defun base64-encode-region beg end &optional no-line-break
@tindex base64-encode-region
This function converts the region from @var{beg} to @var{end}
into base 64 code. It returns the length of the encoded text.
Normally, this function inserts newline characters into the encoded
text, to avoid overlong lines. However, if the optional argument
@var{no-line-break} is non-@code{nil}, these newlines are not added, so
the output is just one long line.
@end defun
@defun base64-encode-string string &optional no-line-break
@tindex base64-encode-string
This function converts the string @var{string} into base 64 code. It
returns a string containing the encoded text.
Normally, this function inserts newline characters into the encoded
text, to avoid overlong lines. However, if the optional argument
@var{no-line-break} is non-@code{nil}, these newlines are not added, so
the result string is just one long line.
@end defun
@defun base64-decode-region beg end
@tindex base64-decode-region
This function converts the region from @var{beg} to @var{end} from base
64 code into the corresponding decoded text. It returns the length of
the decoded text.
The decoding functions ignore newline characters in the encoded text.
@end defun
@defun base64-decode-string string
@tindex base64-decode-string
This function converts the string @var{string} from base 64 code into
the corresponding decoded text. It returns a string containing the
decoded text.
The decoding functions ignore newline characters in the encoded text.
@end defun
@node Change Hooks
@section Change Hooks
@cindex change hooks