Mercurial > hg > xemacs-beta
annotate man/lispref/buffers.texi @ 5384:3889ef128488
Fix misspelled words, and some grammar, across the entire source tree.
See xemacs-patches message with ID
<AANLkTi=edkEKtK3pZ60ytsG5pTJQy2TjAEVCZCLOa-oA@mail.gmail.com>.
| author | Jerry James <james@xemacs.org> |
|---|---|
| date | Thu, 24 Mar 2011 11:00:11 -0600 |
| parents | 6772ce4d982b |
| 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 |