Mercurial > hg > xemacs-beta
annotate man/lispref/buffers.texi @ 4885:6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
lisp/ChangeLog addition:
2010-01-24 Aidan Kehoe <kehoea@parhasard.net>
Correct the semantics of #'member*, #'eql, #'assoc* in the
presence of bignums; change the integerp byte code to fixnump
semantics.
* bytecomp.el (fixnump, integerp, byte-compile-integerp):
Change the integerp byte code to fixnump; add a byte-compile
method to integerp using fixnump and numberp and avoiding a
funcall most of the time, since in the non-core contexts where
integerp is used, it's mostly distinguishing between fixnums and
things that are not numbers at all.
* byte-optimize.el (side-effect-free-fns, byte-after-unbind-ops)
(byte-compile-side-effect-and-error-free-ops):
Replace the integerp bytecode with fixnump; add fixnump to the
side-effect-free-fns. Add the other extended number type
predicates to the list in passing.
* obsolete.el (floatp-safe): Mark this as obsolete.
* cl.el (eql): Go into more detail in the docstring here. Don't
bother checking whether both arguments are numbers; one is enough,
#'equal will fail correctly if they have distinct types.
(subst): Replace a call to #'integerp (deciding whether to use
#'memq or not) with one to #'fixnump.
Delete most-positive-fixnum, most-negative-fixnum from this file;
they're now always in C, so they can't be modified from Lisp.
* cl-seq.el (member*, assoc*, rassoc*):
Correct these functions in the presence of bignums.
* cl-macs.el (cl-make-type-test): The type test for a fixnum is
now fixnump. Ditch floatp-safe, use floatp instead.
(eql): Correct this compiler macro in the presence of bignums.
(assoc*): Correct this compiler macro in the presence of bignums.
* simple.el (undo):
Change #'integerp to #'fixnump here, since we use #'delq with the
same value as ELT a few lines down.
src/ChangeLog addition:
2010-01-24 Aidan Kehoe <kehoea@parhasard.net>
Fix problems with #'eql, extended number types, and the hash table
implementation; change the Bintegerp bytecode to fixnump semantics
even on bignum builds, since #'integerp can have a fast
implementation in terms of #'fixnump for most of its extant uses,
but not vice-versa.
* lisp.h: Always #include number.h; we want the macros provided in
it, even if the various number types are not available.
* number.h (NON_FIXNUM_NUMBER_P): New macro, giving 1 when its
argument is of non-immediate number type. Equivalent to FLOATP if
WITH_NUMBER_TYPES is not defined.
* elhash.c (lisp_object_eql_equal, lisp_object_eql_hash):
Use NON_FIXNUM_NUMBER_P in these functions, instead of FLOATP,
giving more correct behaviour in the presence of the extended
number types.
* bytecode.c (Bfixnump, execute_optimized_program):
Rename Bintegerp to Bfixnump; change its semantics to reflect the
new name on builds with bignum support.
* data.c (Ffixnump, Fintegerp, syms_of_data, vars_of_data):
Always make #'fixnump available, even on non-BIGNUM builds;
always implement #'integerp in this file, even on BIGNUM builds.
Move most-positive-fixnum, most-negative-fixnum here from
number.c, so they are Lisp constants even on builds without number
types, and attempts to change or bind them error.
Use the NUMBERP and INTEGERP macros even on builds without
extended number types.
* data.c (fixnum_char_or_marker_to_int):
Rename this function from integer_char_or_marker_to_int, to better
reflect the arguments it accepts.
* number.c (Fevenp, Foddp, syms_of_number):
Never provide #'integerp in this file. Remove #'oddp,
#'evenp; their implementations are overridden by those in cl.el.
* number.c (vars_of_number):
most-positive-fixnum, most-negative-fixnum are no longer here.
man/ChangeLog addition:
2010-01-23 Aidan Kehoe <kehoea@parhasard.net>
Generally: be careful to say fixnum, not integer, when talking
about fixed-precision integral types. I'm sure I've missed
instances, both here and in the docstrings, but this is a decent
start.
* lispref/text.texi (Columns):
Document where only fixnums, not integers generally, are accepted.
(Registers):
Remove some ancient char-int confoundance here.
* lispref/strings.texi (Creating Strings, Creating Strings):
Be more exact in describing where fixnums but not integers in
general are accepted.
(Creating Strings): Use a more contemporary example to illustrate
how concat deals with lists including integers about #xFF. Delete
some obsolete documentation on same.
(Char Table Types): Document that only fixnums are accepted as
values in syntax tables.
* lispref/searching.texi (String Search, Search and Replace):
Be exact in describing where fixnums but not integers in general
are accepted.
* lispref/range-tables.texi (Range Tables): Be exact in describing
them; only fixnums are accepted to describe ranges.
* lispref/os.texi (Killing XEmacs, User Identification)
(Time of Day, Time Conversion):
Be more exact about using fixnum where only fixed-precision
integers are accepted.
* lispref/objects.texi (Integer Type): Be more exact (and
up-to-date) about the possible values for
integers. Cross-reference to documentation of the bignum extension.
(Equality Predicates):
(Range Table Type):
(Array Type): Use fixnum, not integer, to describe a
fixed-precision integer.
(Syntax Table Type): Correct some English syntax here.
* lispref/numbers.texi (Numbers): Change the phrasing here to use
fixnum to mean the fixed-precision integers normal in emacs.
Document that our terminology deviates from that of Common Lisp,
and that we're working on it.
(Compatibility Issues): Reiterate the Common Lisp versus Emacs
Lisp compatibility issues.
(Comparison of Numbers, Arithmetic Operations):
* lispref/commands.texi (Command Loop Info, Working With Events):
* lispref/buffers.texi (Modification Time):
Be more exact in describing where fixnums but not integers in
general are accepted.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Sun, 24 Jan 2010 15:21:27 +0000 |
| parents | 576fb035e263 |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/buffers.info | |
| 6 @node Buffers, Windows, Backups and Auto-Saving, Top | |
| 7 @chapter Buffers | |
| 8 @cindex buffer | |
| 9 | |
| 10 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
| 11 are used to hold the contents of files that are being visited; there may | |
| 12 also be buffers that are not visiting files. While several buffers may | |
| 13 exist at one time, exactly one buffer is designated the @dfn{current | |
| 14 buffer} at any time. Most editing commands act on the contents of the | |
| 15 current buffer. Each buffer, including the current buffer, may or may | |
| 444 | 16 not be displayed in any window. |
| 428 | 17 |
| 18 @menu | |
| 19 * Buffer Basics:: What is a buffer? | |
| 20 * Current Buffer:: Designating a buffer as current | |
| 21 so primitives will access its contents. | |
| 22 * Buffer Names:: Accessing and changing buffer names. | |
| 23 * Buffer File Name:: The buffer file name indicates which file is visited. | |
| 24 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. | |
| 25 * Modification Time:: Determining whether the visited file was changed | |
| 26 ``behind XEmacs's back''. | |
| 27 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. | |
| 28 * The Buffer List:: How to look at all the existing buffers. | |
| 29 * Creating Buffers:: Functions that create buffers. | |
| 30 * Killing Buffers:: Buffers exist until explicitly killed. | |
| 31 * Indirect Buffers:: An indirect buffer shares text with some other buffer. | |
| 32 @end menu | |
| 33 | |
| 34 @node Buffer Basics | |
| 35 @section Buffer Basics | |
| 36 | |
| 37 @ifinfo | |
| 38 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
| 39 are used to hold the contents of files that are being visited; there may | |
| 40 also be buffers that are not visiting files. While several buffers may | |
| 41 exist at one time, exactly one buffer is designated the @dfn{current | |
| 42 buffer} at any time. Most editing commands act on the contents of the | |
| 43 current buffer. Each buffer, including the current buffer, may or may | |
| 44 not be displayed in any windows. | |
| 45 @end ifinfo | |
| 46 | |
| 47 Buffers in Emacs editing are objects that have distinct names and hold | |
| 48 text that can be edited. Buffers appear to Lisp programs as a special | |
| 442 | 49 data type. You can think of the contents of a buffer as an extendible |
| 428 | 50 string; insertions and deletions may occur in any part of the buffer. |
| 51 @xref{Text}. | |
| 52 | |
| 53 A Lisp buffer object contains numerous pieces of information. Some of | |
| 54 this information is directly accessible to the programmer through | |
| 55 variables, while other information is accessible only through | |
| 56 special-purpose functions. For example, the visited file name is | |
| 57 directly accessible through a variable, while the value of point is | |
| 58 accessible only through a primitive function. | |
| 59 | |
| 60 Buffer-specific information that is directly accessible is stored in | |
| 61 @dfn{buffer-local} variable bindings, which are variable values that are | |
| 62 effective only in a particular buffer. This feature allows each buffer | |
| 63 to override the values of certain variables. Most major modes override | |
| 64 variables such as @code{fill-column} or @code{comment-column} in this | |
| 65 way. For more information about buffer-local variables and functions | |
| 66 related to them, see @ref{Buffer-Local Variables}. | |
| 67 | |
| 68 For functions and variables related to visiting files in buffers, see | |
| 69 @ref{Visiting Files} and @ref{Saving Buffers}. For functions and | |
| 70 variables related to the display of buffers in windows, see | |
| 71 @ref{Buffers and Windows}. | |
| 72 | |
| 73 @defun bufferp object | |
| 74 This function returns @code{t} if @var{object} is a buffer, | |
| 75 @code{nil} otherwise. | |
| 76 @end defun | |
| 77 | |
| 78 @node Current Buffer | |
| 79 @section The Current Buffer | |
| 80 @cindex selecting a buffer | |
| 81 @cindex changing to another buffer | |
| 82 @cindex current buffer | |
| 83 | |
| 84 There are, in general, many buffers in an Emacs session. At any time, | |
| 85 one of them is designated as the @dfn{current buffer}. This is the | |
| 86 buffer in which most editing takes place, because most of the primitives | |
| 87 for examining or changing text in a buffer operate implicitly on the | |
| 88 current buffer (@pxref{Text}). Normally the buffer that is displayed on | |
| 89 the screen in the selected window is the current buffer, but this is not | |
| 90 always so: a Lisp program can designate any buffer as current | |
| 91 temporarily in order to operate on its contents, without changing what | |
| 92 is displayed on the screen. | |
| 93 | |
| 94 The way to designate a current buffer in a Lisp program is by calling | |
| 95 @code{set-buffer}. The specified buffer remains current until a new one | |
| 96 is designated. | |
| 97 | |
| 98 When an editing command returns to the editor command loop, the | |
| 99 command loop designates the buffer displayed in the selected window as | |
| 100 current, to prevent confusion: the buffer that the cursor is in when | |
| 101 Emacs reads a command is the buffer that the command will apply to. | |
| 102 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to | |
| 103 switch visibly to a different buffer so that the user can edit it. For | |
| 104 this, you must use the functions described in @ref{Displaying Buffers}. | |
| 105 | |
| 106 However, Lisp functions that change to a different current buffer | |
| 107 should not depend on the command loop to set it back afterwards. | |
| 108 Editing commands written in XEmacs Lisp can be called from other programs | |
| 109 as well as from the command loop. It is convenient for the caller if | |
| 110 the subroutine does not change which buffer is current (unless, of | |
| 111 course, that is the subroutine's purpose). Therefore, you should | |
| 112 normally use @code{set-buffer} within a @code{save-excursion} that will | |
| 113 restore the current buffer when your function is done | |
| 114 (@pxref{Excursions}). Here is an example, the code for the command | |
| 115 @code{append-to-buffer} (with the documentation string abridged): | |
| 116 | |
| 117 @example | |
| 118 @group | |
| 119 (defun append-to-buffer (buffer start end) | |
| 120 "Append to specified buffer the text of the region. | |
| 121 @dots{}" | |
| 122 (interactive "BAppend to buffer: \nr") | |
| 123 (let ((oldbuf (current-buffer))) | |
| 124 (save-excursion | |
| 125 (set-buffer (get-buffer-create buffer)) | |
| 126 (insert-buffer-substring oldbuf start end)))) | |
| 127 @end group | |
| 128 @end example | |
| 129 | |
| 130 @noindent | |
| 131 This function binds a local variable to the current buffer, and then | |
| 132 @code{save-excursion} records the values of point, the mark, and the | |
| 133 original buffer. Next, @code{set-buffer} makes another buffer current. | |
| 134 Finally, @code{insert-buffer-substring} copies the string from the | |
| 135 original current buffer to the new current buffer. | |
| 136 | |
| 444 | 137 If the buffer appended to happens to be displayed in some window, |
| 428 | 138 the next redisplay will show how its text has changed. Otherwise, you |
| 139 will not see the change immediately on the screen. The buffer becomes | |
| 140 current temporarily during the execution of the command, but this does | |
| 141 not cause it to be displayed. | |
| 142 | |
| 143 If you make local bindings (with @code{let} or function arguments) for | |
| 144 a variable that may also have buffer-local bindings, make sure that the | |
| 145 same buffer is current at the beginning and at the end of the local | |
| 146 binding's scope. Otherwise you might bind it in one buffer and unbind | |
| 147 it in another! There are two ways to do this. In simple cases, you may | |
| 148 see that nothing ever changes the current buffer within the scope of the | |
| 149 binding. Otherwise, use @code{save-excursion} to make sure that the | |
| 150 buffer current at the beginning is current again whenever the variable | |
| 151 is unbound. | |
| 152 | |
| 153 It is not reliable to change the current buffer back with | |
| 154 @code{set-buffer}, because that won't do the job if a quit happens while | |
| 155 the wrong buffer is current. Here is what @emph{not} to do: | |
| 156 | |
| 157 @example | |
| 158 @group | |
| 159 (let (buffer-read-only | |
| 160 (obuf (current-buffer))) | |
| 161 (set-buffer @dots{}) | |
| 162 @dots{} | |
| 163 (set-buffer obuf)) | |
| 164 @end group | |
| 165 @end example | |
| 166 | |
| 167 @noindent | |
| 168 Using @code{save-excursion}, as shown below, handles quitting, errors, | |
| 169 and @code{throw}, as well as ordinary evaluation. | |
| 170 | |
| 171 @example | |
| 172 @group | |
| 173 (let (buffer-read-only) | |
| 174 (save-excursion | |
| 175 (set-buffer @dots{}) | |
| 176 @dots{})) | |
| 177 @end group | |
| 178 @end example | |
| 179 | |
| 180 @defun current-buffer | |
| 181 This function returns the current buffer. | |
| 182 | |
| 183 @example | |
| 184 @group | |
| 185 (current-buffer) | |
| 186 @result{} #<buffer buffers.texi> | |
| 187 @end group | |
| 188 @end example | |
| 189 @end defun | |
| 190 | |
| 191 @defun set-buffer buffer-or-name | |
| 192 This function makes @var{buffer-or-name} the current buffer. It does | |
| 193 not display the buffer in the currently selected window or in any other | |
| 194 window, so the user cannot necessarily see the buffer. But Lisp | |
| 195 programs can in any case work on it. | |
| 196 | |
| 444 | 197 @var{buffer-or-name} must be a buffer or the name of an existing |
| 198 buffer--else an error is signaled. This function returns the buffer | |
| 199 identified by @var{buffer-or-name}. | |
| 428 | 200 @end defun |
| 201 | |
| 202 @node Buffer Names | |
| 203 @section Buffer Names | |
| 204 @cindex buffer names | |
| 205 | |
| 206 Each buffer has a unique name, which is a string. Many of the | |
| 207 functions that work on buffers accept either a buffer or a buffer name | |
| 208 as an argument. Any argument called @var{buffer-or-name} is of this | |
| 209 sort, and an error is signaled if it is neither a string nor a buffer. | |
| 210 Any argument called @var{buffer} must be an actual buffer | |
| 211 object, not a name. | |
| 212 | |
| 213 Buffers that are ephemeral and generally uninteresting to the user | |
| 214 have names starting with a space, so that the @code{list-buffers} and | |
| 215 @code{buffer-menu} commands don't mention them. A name starting with | |
| 216 space also initially disables recording undo information; see | |
| 217 @ref{Undo}. | |
| 218 | |
| 219 @defun buffer-name &optional buffer | |
| 220 This function returns the name of @var{buffer} as a string. If | |
| 221 @var{buffer} is not supplied, it defaults to the current buffer. | |
| 222 | |
| 223 If @code{buffer-name} returns @code{nil}, it means that @var{buffer} | |
| 224 has been killed. @xref{Killing Buffers}. | |
| 225 | |
| 226 @example | |
| 227 @group | |
| 228 (buffer-name) | |
| 229 @result{} "buffers.texi" | |
| 230 @end group | |
| 231 | |
| 232 @group | |
| 233 (setq foo (get-buffer "temp")) | |
| 234 @result{} #<buffer temp> | |
| 235 @end group | |
| 236 @group | |
| 237 (kill-buffer foo) | |
| 238 @result{} nil | |
| 239 @end group | |
| 240 @group | |
| 241 (buffer-name foo) | |
| 242 @result{} nil | |
| 243 @end group | |
| 244 @group | |
| 245 foo | |
| 246 @result{} #<killed buffer> | |
| 247 @end group | |
| 248 @end example | |
| 249 @end defun | |
| 250 | |
| 251 @deffn Command rename-buffer newname &optional unique | |
| 252 This function renames the current buffer to @var{newname}. An error | |
| 253 is signaled if @var{newname} is not a string, or if there is already a | |
| 254 buffer with that name. The function returns @code{nil}. | |
| 255 | |
| 256 @c Emacs 19 feature | |
| 257 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | |
| 258 already in use. However, if @var{unique} is non-@code{nil}, it modifies | |
| 259 @var{newname} to make a name that is not in use. Interactively, you can | |
| 260 make @var{unique} non-@code{nil} with a numeric prefix argument. | |
| 261 | |
| 262 One application of this command is to rename the @samp{*shell*} buffer | |
| 263 to some other name, thus making it possible to create a second shell | |
| 264 buffer under the name @samp{*shell*}. | |
| 265 @end deffn | |
| 266 | |
| 267 @defun get-buffer buffer-or-name | |
| 444 | 268 This function returns the buffer named @var{buffer-or-name}. If |
| 269 @var{buffer-or-name} is a string and there is no buffer with that name, | |
| 270 the value is @code{nil}. If @var{buffer-or-name} is actually a buffer, | |
| 271 it is returned as given. (That is not very useful, so the argument is | |
| 272 usually a name.) For example: | |
| 428 | 273 |
| 274 @example | |
| 275 @group | |
| 276 (setq b (get-buffer "lewis")) | |
| 277 @result{} #<buffer lewis> | |
| 278 @end group | |
| 279 @group | |
| 280 (get-buffer b) | |
| 281 @result{} #<buffer lewis> | |
| 282 @end group | |
| 283 @group | |
| 284 (get-buffer "Frazzle-nots") | |
| 285 @result{} nil | |
| 286 @end group | |
| 287 @end example | |
| 288 | |
| 289 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | |
| 290 @end defun | |
| 291 | |
| 292 @defun generate-new-buffer-name starting-name &optional ignore | |
| 293 This function returns a name that would be unique for a new buffer---but | |
| 294 does not create the buffer. It starts with @var{starting-name}, and | |
| 295 produces a name not currently in use for any buffer by appending a | |
| 296 number inside of @samp{<@dots{}>}. | |
| 297 | |
| 298 If @var{ignore} is given, it specifies a name that is okay to use (if it | |
| 299 is in the sequence to be tried), even if a buffer with that name exists. | |
| 300 | |
| 301 See the related function @code{generate-new-buffer} in @ref{Creating | |
| 302 Buffers}. | |
| 303 @end defun | |
| 304 | |
| 305 @node Buffer File Name | |
| 306 @section Buffer File Name | |
| 307 @cindex visited file | |
| 308 @cindex buffer file name | |
| 309 @cindex file name of buffer | |
| 310 | |
| 311 The @dfn{buffer file name} is the name of the file that is visited in | |
| 312 that buffer. When a buffer is not visiting a file, its buffer file name | |
| 313 is @code{nil}. Most of the time, the buffer name is the same as the | |
| 314 nondirectory part of the buffer file name, but the buffer file name and | |
| 315 the buffer name are distinct and can be set independently. | |
| 316 @xref{Visiting Files}. | |
| 317 | |
| 318 @defun buffer-file-name &optional buffer | |
| 319 This function returns the absolute file name of the file that | |
| 320 @var{buffer} is visiting. If @var{buffer} is not visiting any file, | |
| 321 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not | |
| 322 supplied, it defaults to the current buffer. | |
| 323 | |
| 324 @example | |
| 325 @group | |
| 326 (buffer-file-name (other-buffer)) | |
| 327 @result{} "/usr/user/lewis/manual/files.texi" | |
| 328 @end group | |
| 329 @end example | |
| 330 @end defun | |
| 331 | |
| 332 @defvar buffer-file-name | |
| 333 This buffer-local variable contains the name of the file being visited | |
| 334 in the current buffer, or @code{nil} if it is not visiting a file. It | |
| 335 is a permanent local, unaffected by @code{kill-local-variables}. | |
| 336 | |
| 337 @example | |
| 338 @group | |
| 339 buffer-file-name | |
| 340 @result{} "/usr/user/lewis/manual/buffers.texi" | |
| 341 @end group | |
| 342 @end example | |
| 343 | |
| 344 It is risky to change this variable's value without doing various other | |
| 345 things. See the definition of @code{set-visited-file-name} in | |
| 346 @file{files.el}; some of the things done there, such as changing the | |
| 347 buffer name, are not strictly necessary, but others are essential to | |
| 348 avoid confusing XEmacs. | |
| 349 @end defvar | |
| 350 | |
| 351 @defvar buffer-file-truename | |
| 352 This buffer-local variable holds the truename of the file visited in the | |
| 353 current buffer, or @code{nil} if no file is visited. It is a permanent | |
| 354 local, unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
| 355 @end defvar | |
| 356 | |
| 357 @defvar buffer-file-number | |
| 358 This buffer-local variable holds the file number and directory device | |
| 359 number of the file visited in the current buffer, or @code{nil} if no | |
| 360 file or a nonexistent file is visited. It is a permanent local, | |
| 361 unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
| 362 | |
| 363 The value is normally a list of the form @code{(@var{filenum} | |
| 364 @var{devnum})}. This pair of numbers uniquely identifies the file among | |
| 365 all files accessible on the system. See the function | |
| 366 @code{file-attributes}, in @ref{File Attributes}, for more information | |
| 367 about them. | |
| 368 @end defvar | |
| 369 | |
| 370 @defun get-file-buffer filename | |
| 371 This function returns the buffer visiting file @var{filename}. If | |
| 372 there is no such buffer, it returns @code{nil}. The argument | |
| 373 @var{filename}, which must be a string, is expanded (@pxref{File Name | |
| 374 Expansion}), then compared against the visited file names of all live | |
| 375 buffers. | |
| 376 | |
| 377 @example | |
| 378 @group | |
| 379 (get-file-buffer "buffers.texi") | |
| 380 @result{} #<buffer buffers.texi> | |
| 381 @end group | |
| 382 @end example | |
| 383 | |
| 384 In unusual circumstances, there can be more than one buffer visiting | |
| 385 the same file name. In such cases, this function returns the first | |
| 386 such buffer in the buffer list. | |
| 387 @end defun | |
| 388 | |
| 389 @deffn Command set-visited-file-name filename | |
| 390 If @var{filename} is a non-empty string, this function changes the | |
| 391 name of the file visited in current buffer to @var{filename}. (If the | |
| 392 buffer had no visited file, this gives it one.) The @emph{next time} | |
| 393 the buffer is saved it will go in the newly-specified file. This | |
| 394 command marks the buffer as modified, since it does not (as far as XEmacs | |
| 395 knows) match the contents of @var{filename}, even if it matched the | |
| 396 former visited file. | |
| 397 | |
| 398 If @var{filename} is @code{nil} or the empty string, that stands for | |
| 399 ``no visited file''. In this case, @code{set-visited-file-name} marks | |
| 400 the buffer as having no visited file. | |
| 401 | |
| 402 @c Wordy to avoid overfull hbox. --rjc 16mar92 | |
| 403 When the function @code{set-visited-file-name} is called interactively, it | |
| 404 prompts for @var{filename} in the minibuffer. | |
| 405 | |
| 406 See also @code{clear-visited-file-modtime} and | |
| 407 @code{verify-visited-file-modtime} in @ref{Buffer Modification}. | |
| 408 @end deffn | |
| 409 | |
| 410 @defvar list-buffers-directory | |
| 411 This buffer-local variable records a string to display in a buffer | |
| 412 listing in place of the visited file name, for buffers that don't have a | |
| 413 visited file name. Dired buffers use this variable. | |
| 414 @end defvar | |
| 415 | |
| 416 @node Buffer Modification | |
| 417 @section Buffer Modification | |
| 418 @cindex buffer modification | |
| 419 @cindex modification flag (of buffer) | |
| 420 | |
| 421 XEmacs keeps a flag called the @dfn{modified flag} for each buffer, to | |
| 422 record whether you have changed the text of the buffer. This flag is | |
| 423 set to @code{t} whenever you alter the contents of the buffer, and | |
| 424 cleared to @code{nil} when you save it. Thus, the flag shows whether | |
| 425 there are unsaved changes. The flag value is normally shown in the | |
| 426 modeline (@pxref{Modeline Variables}), and controls saving | |
| 427 (@pxref{Saving Buffers}) and auto-saving (@pxref{Auto-Saving}). | |
| 428 | |
| 429 Some Lisp programs set the flag explicitly. For example, the function | |
| 430 @code{set-visited-file-name} sets the flag to @code{t}, because the text | |
| 431 does not match the newly-visited file, even if it is unchanged from the | |
| 432 file formerly visited. | |
| 433 | |
| 434 The functions that modify the contents of buffers are described in | |
| 435 @ref{Text}. | |
| 436 | |
| 437 @defun buffer-modified-p &optional buffer | |
| 438 This function returns @code{t} if the buffer @var{buffer} has been modified | |
| 439 since it was last read in from a file or saved, or @code{nil} | |
| 440 otherwise. If @var{buffer} is not supplied, the current buffer | |
| 441 is tested. | |
| 442 @end defun | |
| 443 | |
| 444 | 444 @defun set-buffer-modified-p flag &optional buffer |
| 445 This function marks @var{buffer} as modified if @var{flag} is | |
| 428 | 446 non-@code{nil}, or as unmodified if the flag is @code{nil}. |
| 444 | 447 @var{buffer} defaults to the current buffer. |
| 428 | 448 |
| 449 Another effect of calling this function is to cause unconditional | |
| 450 redisplay of the modeline for the current buffer. In fact, the | |
| 451 function @code{redraw-modeline} works by doing this: | |
| 452 | |
| 453 @example | |
| 454 @group | |
| 455 (set-buffer-modified-p (buffer-modified-p)) | |
| 456 @end group | |
| 457 @end example | |
| 458 @end defun | |
| 459 | |
| 460 @c ARG is only in XEmacs | |
| 461 @deffn Command not-modified &optional arg | |
| 462 This command marks the current buffer as unmodified, and not needing | |
| 463 to be saved. (If @var{arg} is non-@code{nil}, the buffer is instead | |
| 464 marked as modified.) Don't use this function in programs, since it | |
| 465 prints a message in the echo area; use @code{set-buffer-modified-p} | |
| 466 (above) instead. | |
| 467 @end deffn | |
| 468 | |
| 469 @c Emacs 19 feature | |
| 470 @defun buffer-modified-tick &optional buffer | |
| 471 This function returns @var{buffer}`s modification-count. This is a | |
| 472 counter that increments every time the buffer is modified. If | |
| 473 @var{buffer} is @code{nil} (or omitted), the current buffer is used. | |
| 474 @end defun | |
| 475 | |
| 476 @node Modification Time | |
| 477 @section Comparison of Modification Time | |
| 478 @cindex comparison of modification time | |
| 444 | 479 @cindex modification time, comparison of |
| 428 | 480 |
| 481 Suppose that you visit a file and make changes in its buffer, and | |
| 482 meanwhile the file itself is changed on disk. At this point, saving the | |
| 483 buffer would overwrite the changes in the file. Occasionally this may | |
| 484 be what you want, but usually it would lose valuable information. XEmacs | |
| 485 therefore checks the file's modification time using the functions | |
| 486 described below before saving the file. | |
| 487 | |
| 488 @defun verify-visited-file-modtime buffer | |
| 489 This function compares what @var{buffer} has recorded for the | |
| 490 modification time of its visited file against the actual modification | |
| 491 time of the file as recorded by the operating system. The two should be | |
| 492 the same unless some other process has written the file since XEmacs | |
| 493 visited or saved it. | |
| 494 | |
| 495 The function returns @code{t} if the last actual modification time and | |
| 496 XEmacs's recorded modification time are the same, @code{nil} otherwise. | |
| 497 @end defun | |
| 498 | |
| 499 @defun clear-visited-file-modtime | |
| 500 This function clears out the record of the last modification time of | |
| 501 the file being visited by the current buffer. As a result, the next | |
| 502 attempt to save this buffer will not complain of a discrepancy in | |
| 503 file modification times. | |
| 504 | |
| 505 This function is called in @code{set-visited-file-name} and other | |
| 506 exceptional places where the usual test to avoid overwriting a changed | |
| 507 file should not be done. | |
| 508 @end defun | |
| 509 | |
| 510 @c Emacs 19 feature | |
| 511 @defun visited-file-modtime | |
| 512 This function returns the buffer's recorded last file modification time, | |
| 513 as a list of the form @code{(@var{high} . @var{low})}. (This is the | |
| 514 same format that @code{file-attributes} uses to return time values; see | |
| 515 @ref{File Attributes}.) | |
| 516 @end defun | |
| 517 | |
| 518 @c Emacs 19 feature | |
| 519 @defun set-visited-file-modtime &optional time | |
| 520 This function updates the buffer's record of the last modification time | |
| 521 of the visited file, to the value specified by @var{time} if @var{time} | |
| 522 is not @code{nil}, and otherwise to the last modification time of the | |
| 523 visited file. | |
| 524 | |
| 525 If @var{time} is not @code{nil}, it should have the form | |
| 526 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
527 either case containing two fixnums, each of which holds 16 bits of the |
| 428 | 528 time. |
| 529 | |
| 530 This function is useful if the buffer was not read from the file | |
| 531 normally, or if the file itself has been changed for some known benign | |
| 532 reason. | |
| 533 @end defun | |
| 534 | |
| 535 @defun ask-user-about-supersession-threat filename | |
| 536 @cindex obsolete buffer | |
| 537 This function is used to ask a user how to proceed after an attempt to | |
| 538 modify an obsolete buffer visiting file @var{filename}. An | |
| 539 @dfn{obsolete buffer} is an unmodified buffer for which the associated | |
| 540 file on disk is newer than the last save-time of the buffer. This means | |
| 541 some other program has probably altered the file. | |
| 542 | |
| 543 @kindex file-supersession | |
| 544 Depending on the user's answer, the function may return normally, in | |
| 545 which case the modification of the buffer proceeds, or it may signal a | |
| 546 @code{file-supersession} error with data @code{(@var{filename})}, in which | |
| 444 | 547 case the proposed buffer modification is not allowed. |
| 428 | 548 |
| 549 This function is called automatically by XEmacs on the proper | |
| 550 occasions. It exists so you can customize XEmacs by redefining it. | |
| 551 See the file @file{userlock.el} for the standard definition. | |
| 552 | |
| 553 See also the file locking mechanism in @ref{File Locks}. | |
| 554 @end defun | |
| 555 | |
| 556 @node Read Only Buffers | |
| 557 @section Read-Only Buffers | |
| 558 @cindex read-only buffer | |
| 559 @cindex buffer, read-only | |
| 560 | |
| 561 If a buffer is @dfn{read-only}, then you cannot change its contents, | |
| 444 | 562 although you may change your view of the contents by scrolling and |
| 428 | 563 narrowing. |
| 564 | |
| 565 Read-only buffers are used in two kinds of situations: | |
| 566 | |
| 567 @itemize @bullet | |
| 568 @item | |
| 569 A buffer visiting a write-protected file is normally read-only. | |
| 570 | |
| 571 Here, the purpose is to show the user that editing the buffer with the | |
| 572 aim of saving it in the file may be futile or undesirable. The user who | |
| 573 wants to change the buffer text despite this can do so after clearing | |
| 574 the read-only flag with @kbd{C-x C-q}. | |
| 575 | |
| 576 @item | |
| 577 Modes such as Dired and Rmail make buffers read-only when altering the | |
| 578 contents with the usual editing commands is probably a mistake. | |
| 579 | |
| 580 The special commands of these modes bind @code{buffer-read-only} to | |
| 581 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to | |
| 582 @code{t} around the places where they change the text. | |
| 583 @end itemize | |
| 584 | |
| 585 @defvar buffer-read-only | |
| 586 This buffer-local variable specifies whether the buffer is read-only. | |
| 587 The buffer is read-only if this variable is non-@code{nil}. | |
| 588 @end defvar | |
| 589 | |
| 590 @defvar inhibit-read-only | |
| 591 If this variable is non-@code{nil}, then read-only buffers and read-only | |
| 592 characters may be modified. Read-only characters in a buffer are those | |
| 593 that have non-@code{nil} @code{read-only} properties (either text | |
| 594 properties or extent properties). @xref{Extent Properties}, for more | |
| 595 information about text properties and extent properties. | |
| 596 | |
| 597 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character | |
| 598 properties have no effect. If @code{inhibit-read-only} is a list, then | |
| 599 @code{read-only} character properties have no effect if they are members | |
| 600 of the list (comparison is done with @code{eq}). | |
| 601 @end defvar | |
| 602 | |
| 444 | 603 @deffn Command toggle-read-only &optional arg |
| 604 This command changes whether the current buffer is read-only. | |
| 605 Interactively, if a prefix arg @var{arg} is supplied, set the current | |
| 606 buffer read only if and only if @var{arg} is positive. | |
| 607 | |
| 608 This command is intended for interactive use only; don't use it in | |
| 609 programs. At any given point in a program, you should know whether you | |
| 610 want the read-only flag on or off; so you can set | |
| 611 @code{buffer-read-only} explicitly to the proper value, @code{t} or | |
| 612 @code{nil}. | |
| 428 | 613 @end deffn |
| 614 | |
| 444 | 615 @defun barf-if-buffer-read-only &optional buffer start end |
| 616 This function signals a @code{buffer-read-only} error if @var{buffer} is | |
| 617 read-only. @var{buffer} defaults to the current buffer. | |
| 618 @xref{Interactive Call}, for another way to signal an error if the | |
| 619 current buffer is read-only. | |
| 620 | |
| 621 If optional argument @var{start} is non-@code{nil}, all extents in the | |
| 622 buffer which overlap that part of the buffer are checked to ensure none | |
| 623 has a @code{read-only} property. (Extents that lie completely within the | |
| 624 range, however, are not checked.) @var{end} defaults to the value of | |
| 625 @var{start}. | |
| 626 | |
| 627 If @var{start} and @var{end} are equal, the range checked is | |
| 628 [@var{start}, @var{end}] (i.e. closed on both ends); otherwise, the | |
| 629 range checked is (@var{start}, @var{end}) \(open on both ends), except | |
| 630 that extents that lie completely within [@var{start}, @var{end}] are not | |
| 631 checked. See @code{extent-in-region-p} for a fuller discussion. | |
| 428 | 632 @end defun |
| 633 | |
| 634 @node The Buffer List | |
| 635 @section The Buffer List | |
| 636 @cindex buffer list | |
| 637 | |
| 638 The @dfn{buffer list} is a list of all live buffers. Creating a | |
| 639 buffer adds it to this list, and killing a buffer deletes it. The order | |
| 640 of the buffers in the list is based primarily on how recently each | |
| 641 buffer has been displayed in the selected window. Buffers move to the | |
| 642 front of the list when they are selected and to the end when they are | |
| 643 buried. Several functions, notably @code{other-buffer}, use this | |
| 644 ordering. A buffer list displayed for the user also follows this order. | |
| 645 | |
| 646 @c XEmacs feature | |
| 647 Every frame has its own order for the buffer list. Switching to a | |
| 648 new buffer inside of a particular frame changes the buffer list order | |
| 649 for that frame, but does not affect the buffer list order of any other | |
| 650 frames. In addition, there is a global, non-frame buffer list order | |
| 651 that is independent of the buffer list orders for any particular frame. | |
| 652 | |
| 653 Note that the different buffer lists all contain the same elements. It | |
| 654 is only the order of those elements that is different. | |
| 655 | |
| 656 @defun buffer-list &optional frame | |
| 657 This function returns a list of all buffers, including those whose | |
| 658 names begin with a space. The elements are actual buffers, not their | |
| 659 names. The order of the list is specific to @var{frame}, which | |
| 660 defaults to the current frame. If @var{frame} is @code{t}, the | |
| 661 global, non-frame ordering is returned instead. | |
| 662 | |
| 663 @example | |
| 664 @group | |
| 665 (buffer-list) | |
| 666 @result{} (#<buffer buffers.texi> | |
| 667 #<buffer *Minibuf-1*> #<buffer buffer.c> | |
| 668 #<buffer *Help*> #<buffer TAGS>) | |
| 669 @end group | |
| 670 | |
| 671 @group | |
| 672 ;; @r{Note that the name of the minibuffer} | |
| 673 ;; @r{begins with a space!} | |
| 674 (mapcar (function buffer-name) (buffer-list)) | |
| 444 | 675 @result{} ("buffers.texi" " *Minibuf-1*" |
| 428 | 676 "buffer.c" "*Help*" "TAGS") |
| 677 @end group | |
| 678 @end example | |
| 679 | |
| 680 Buffers appear earlier in the list if they were current more recently. | |
| 681 | |
| 682 This list is a copy of a list used inside XEmacs; modifying it has no | |
| 683 effect on the buffers. | |
| 684 @end defun | |
| 685 | |
| 686 @defun other-buffer &optional buffer-or-name frame visible-ok | |
| 687 This function returns the first buffer in the buffer list other than | |
| 688 @var{buffer-or-name}, in @var{frame}'s ordering for the buffer list. | |
| 689 (@var{frame} defaults to the current frame. If @var{frame} is | |
| 690 @code{t}, then the global, non-frame ordering is used.) Usually this is | |
| 691 the buffer most recently shown in the selected window, aside from | |
| 692 @var{buffer-or-name}. Buffers are moved to the front of the list when | |
| 693 they are selected and to the end when they are buried. Buffers whose | |
| 694 names start with a space are not considered. | |
| 695 | |
| 696 If @var{buffer-or-name} is not supplied (or if it is not a buffer), | |
| 697 then @code{other-buffer} returns the first buffer on the buffer list | |
| 698 that is not visible in any window in a visible frame. | |
| 699 | |
| 700 If the selected frame has a non-@code{nil} @code{buffer-predicate} | |
| 701 property, then @code{other-buffer} uses that predicate to decide which | |
| 702 buffers to consider. It calls the predicate once for each buffer, and | |
| 703 if the value is @code{nil}, that buffer is ignored. @xref{X Frame | |
| 704 Properties}. | |
| 705 | |
| 706 @c Emacs 19 feature | |
| 707 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | |
| 708 a buffer visible in any window on any visible frame, except as a last | |
| 709 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter | |
| 710 whether a buffer is displayed somewhere or not. | |
| 711 | |
| 712 If no suitable buffer exists, the buffer @samp{*scratch*} is returned | |
| 713 (and created, if necessary). | |
| 714 | |
| 715 Note that in FSF Emacs 19, there is no @var{frame} argument, and | |
| 716 @var{visible-ok} is the second argument instead of the third. | |
| 717 @end defun | |
| 718 | |
| 719 @deffn Command list-buffers &optional files-only | |
| 720 This function displays a listing of the names of existing buffers. It | |
| 721 clears the buffer @samp{*Buffer List*}, then inserts the listing into | |
| 722 that buffer and displays it in a window. @code{list-buffers} is | |
| 723 intended for interactive use, and is described fully in @cite{The XEmacs | |
| 724 Reference Manual}. It returns @code{nil}. | |
| 725 @end deffn | |
| 726 | |
| 444 | 727 @deffn Command bury-buffer &optional buffer-or-name before |
| 428 | 728 This function puts @var{buffer-or-name} at the end of the buffer list |
| 729 without changing the order of any of the other buffers on the list. | |
| 730 This buffer therefore becomes the least desirable candidate for | |
| 731 @code{other-buffer} to return. | |
| 732 | |
| 733 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the | |
| 734 current buffer. In addition, if the buffer is displayed in the selected | |
| 735 window, this switches to some other buffer (obtained using | |
| 736 @code{other-buffer}) in the selected window. But if the buffer is | |
| 737 displayed in some other window, it remains displayed there. | |
| 738 | |
| 739 If you wish to replace a buffer in all the windows that display it, use | |
| 740 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. | |
| 741 @end deffn | |
| 742 | |
| 743 @node Creating Buffers | |
| 744 @section Creating Buffers | |
| 745 @cindex creating buffers | |
| 746 @cindex buffers, creating | |
| 747 | |
| 748 This section describes the two primitives for creating buffers. | |
| 749 @code{get-buffer-create} creates a buffer if it finds no existing buffer | |
| 750 with the specified name; @code{generate-new-buffer} always creates a new | |
| 751 buffer and gives it a unique name. | |
| 752 | |
| 753 Other functions you can use to create buffers include | |
| 754 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | |
| 755 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | |
| 756 subprocess can also create a buffer (@pxref{Processes}). | |
| 757 | |
| 758 @defun get-buffer-create name | |
| 759 This function returns a buffer named @var{name}. It returns an existing | |
| 760 buffer with that name, if one exists; otherwise, it creates a new | |
| 761 buffer. The buffer does not become the current buffer---this function | |
| 762 does not change which buffer is current. | |
| 763 | |
| 764 An error is signaled if @var{name} is not a string. | |
| 765 | |
| 766 @example | |
| 767 @group | |
| 768 (get-buffer-create "foo") | |
| 769 @result{} #<buffer foo> | |
| 770 @end group | |
| 771 @end example | |
| 772 | |
| 773 The major mode for the new buffer is set to Fundamental mode. The | |
| 774 variable @code{default-major-mode} is handled at a higher level. | |
| 775 @xref{Auto Major Mode}. | |
| 776 @end defun | |
| 777 | |
| 778 @defun generate-new-buffer name | |
| 779 This function returns a newly created, empty buffer, but does not make | |
| 780 it current. If there is no buffer named @var{name}, then that is the | |
| 781 name of the new buffer. If that name is in use, this function adds | |
| 782 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an | |
| 783 integer. It tries successive integers starting with 2 until it finds an | |
| 784 available name. | |
| 785 | |
| 786 An error is signaled if @var{name} is not a string. | |
| 787 | |
| 788 @example | |
| 789 @group | |
| 790 (generate-new-buffer "bar") | |
| 791 @result{} #<buffer bar> | |
| 792 @end group | |
| 793 @group | |
| 794 (generate-new-buffer "bar") | |
| 795 @result{} #<buffer bar<2>> | |
| 796 @end group | |
| 797 @group | |
| 798 (generate-new-buffer "bar") | |
| 799 @result{} #<buffer bar<3>> | |
| 800 @end group | |
| 801 @end example | |
| 802 | |
| 803 The major mode for the new buffer is set to Fundamental mode. The | |
| 804 variable @code{default-major-mode} is handled at a higher level. | |
| 805 @xref{Auto Major Mode}. | |
| 806 | |
| 807 See the related function @code{generate-new-buffer-name} in @ref{Buffer | |
| 808 Names}. | |
| 809 @end defun | |
| 810 | |
| 811 @node Killing Buffers | |
| 812 @section Killing Buffers | |
| 813 @cindex killing buffers | |
| 814 @cindex buffers, killing | |
| 815 | |
| 816 @dfn{Killing a buffer} makes its name unknown to XEmacs and makes its | |
| 817 text space available for other use. | |
| 818 | |
| 819 The buffer object for the buffer that has been killed remains in | |
| 820 existence as long as anything refers to it, but it is specially marked | |
| 821 so that you cannot make it current or display it. Killed buffers retain | |
| 822 their identity, however; two distinct buffers, when killed, remain | |
| 823 distinct according to @code{eq}. | |
| 824 | |
| 825 If you kill a buffer that is current or displayed in a window, XEmacs | |
| 826 automatically selects or displays some other buffer instead. This means | |
| 827 that killing a buffer can in general change the current buffer. | |
| 828 Therefore, when you kill a buffer, you should also take the precautions | |
| 829 associated with changing the current buffer (unless you happen to know | |
| 830 that the buffer being killed isn't current). @xref{Current Buffer}. | |
| 831 | |
| 832 If you kill a buffer that is the base buffer of one or more indirect | |
| 833 buffers, the indirect buffers are automatically killed as well. | |
| 834 | |
| 835 The @code{buffer-name} of a killed buffer is @code{nil}. To test | |
| 836 whether a buffer has been killed, you can either use this feature | |
| 837 or the function @code{buffer-live-p}. | |
| 838 | |
| 444 | 839 @defun buffer-live-p object |
| 840 This function returns @code{t} if @var{object} is an editor buffer that | |
| 841 has not been deleted, @code{nil} otherwise. | |
| 428 | 842 @end defun |
| 843 | |
| 844 @deffn Command kill-buffer buffer-or-name | |
| 845 This function kills the buffer @var{buffer-or-name}, freeing all its | |
| 846 memory for use as space for other buffers. (Emacs version 18 and older | |
| 847 was unable to return the memory to the operating system.) It returns | |
| 444 | 848 @code{nil}. The argument @var{buffer-or-name} may be a buffer or the |
| 849 name of one. | |
| 428 | 850 |
| 851 Any processes that have this buffer as the @code{process-buffer} are | |
| 852 sent the @code{SIGHUP} signal, which normally causes them to terminate. | |
| 853 (The basic meaning of @code{SIGHUP} is that a dialup line has been | |
| 854 disconnected.) @xref{Deleting Processes}. | |
| 855 | |
| 856 If the buffer is visiting a file and contains unsaved changes, | |
| 857 @code{kill-buffer} asks the user to confirm before the buffer is killed. | |
| 858 It does this even if not called interactively. To prevent the request | |
| 859 for confirmation, clear the modified flag before calling | |
| 860 @code{kill-buffer}. @xref{Buffer Modification}. | |
| 861 | |
| 862 Killing a buffer that is already dead has no effect. | |
| 863 | |
| 864 @smallexample | |
| 865 (kill-buffer "foo.unchanged") | |
| 866 @result{} nil | |
| 867 (kill-buffer "foo.changed") | |
| 868 | |
| 869 ---------- Buffer: Minibuffer ---------- | |
| 870 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | |
| 871 ---------- Buffer: Minibuffer ---------- | |
| 872 | |
| 873 @result{} nil | |
| 874 @end smallexample | |
| 875 @end deffn | |
| 876 | |
| 877 @defvar kill-buffer-query-functions | |
| 878 After confirming unsaved changes, @code{kill-buffer} calls the functions | |
| 879 in the list @code{kill-buffer-query-functions}, in order of appearance, | |
| 880 with no arguments. The buffer being killed is the current buffer when | |
| 881 they are called. The idea is that these functions ask for confirmation | |
| 882 from the user for various nonstandard reasons. If any of them returns | |
| 883 @code{nil}, @code{kill-buffer} spares the buffer's life. | |
| 884 @end defvar | |
| 885 | |
| 886 @defvar kill-buffer-hook | |
| 887 This is a normal hook run by @code{kill-buffer} after asking all the | |
| 888 questions it is going to ask, just before actually killing the buffer. | |
| 889 The buffer to be killed is current when the hook functions run. | |
| 890 @xref{Hooks}. | |
| 891 @end defvar | |
| 892 | |
| 893 @defvar buffer-offer-save | |
| 894 This variable, if non-@code{nil} in a particular buffer, tells | |
| 895 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to | |
| 896 save that buffer, just as they offer to save file-visiting buffers. The | |
| 897 variable @code{buffer-offer-save} automatically becomes buffer-local | |
| 898 when set for any reason. @xref{Buffer-Local Variables}. | |
| 899 @end defvar | |
| 900 | |
| 901 @node Indirect Buffers | |
| 902 @section Indirect Buffers | |
| 903 @cindex indirect buffers | |
| 904 @cindex base buffer | |
| 905 | |
| 906 An @dfn{indirect buffer} shares the text of some other buffer, which | |
| 907 is called the @dfn{base buffer} of the indirect buffer. In some ways it | |
| 908 is the analogue, for buffers, of a symbolic link among files. The base | |
| 909 buffer may not itself be an indirect buffer. One base buffer may have | |
| 910 several @dfn{indirect children}. | |
| 911 | |
| 912 The text of the indirect buffer is always identical to the text of its | |
| 913 base buffer; changes made by editing either one are visible immediately | |
| 914 in the other. | |
| 915 | |
| 916 But in all other respects, the indirect buffer and its base buffer are | |
| 917 completely separate. They have different names, different values of | |
| 918 point and mark, different narrowing, different markers and extents | |
| 919 (though inserting or deleting text in either buffer relocates the | |
| 920 markers and extents for both), different major modes, and different | |
| 921 local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not | |
| 922 automatically share text properties among themselves and their base | |
| 923 buffer. | |
| 924 | |
| 925 An indirect buffer cannot visit a file, but its base buffer can. If | |
| 926 you try to save the indirect buffer, that actually works by saving the | |
| 927 base buffer. | |
| 928 | |
| 929 Killing an indirect buffer has no effect on its base buffer. Killing | |
| 930 the base buffer kills all its indirect children. | |
| 931 | |
| 932 @deffn Command make-indirect-buffer base-buffer name | |
| 933 This creates an indirect buffer named @var{name} whose base buffer | |
| 934 is @var{base-buffer}. The argument @var{base-buffer} may be a buffer | |
| 935 or a string. | |
| 444 | 936 |
| 428 | 937 If @var{base-buffer} is an indirect buffer, its base buffer is used as |
| 938 the base for the new buffer. | |
| 939 | |
| 940 @example | |
| 941 @group | |
| 942 (make-indirect-buffer "*scratch*" "indirect") | |
| 943 @result{} #<buffer "indirect"> | |
| 944 @end group | |
| 945 @end example | |
| 946 @end deffn | |
| 947 | |
| 948 @defun buffer-base-buffer &optional buffer | |
| 949 This function returns the base buffer of @var{buffer}. If @var{buffer} | |
| 950 is not indirect, the value is @code{nil}. Otherwise, the value is | |
| 951 another buffer, which is never an indirect buffer. If @var{buffer} is | |
| 952 not supplied, it defaults to the current buffer. | |
| 953 | |
| 954 @example | |
| 955 @group | |
| 956 (buffer-base-buffer (get-buffer "indirect")) | |
| 957 @result{} #<buffer "*scratch*"> | |
| 958 @end group | |
| 959 @end example | |
| 960 @end defun | |
| 961 | |
| 962 @defun buffer-indirect-children &optional buffer | |
| 963 This function returns a list of all indirect buffers whose base buffer | |
| 964 is @var{buffer}. If @var{buffer} is indirect, the return value will | |
| 444 | 965 always be @code{nil}; see @code{make-indirect-buffer}. If @var{buffer} is not |
| 428 | 966 supplied, it defaults to the current buffer. |
| 967 | |
| 968 @example | |
| 969 @group | |
| 970 (buffer-indirect-children (get-buffer "*scratch*")) | |
| 971 @result{} (#<buffer "indirect">) | |
| 972 @end group | |
| 973 @end example | |
| 974 @end defun |