Mercurial > emacs
comparison lispref/buffers.texi @ 88155:d7ddb3e565de
sync with trunk
author | Henrik Enberg <henrik.enberg@telia.com> |
---|---|
date | Mon, 16 Jan 2006 00:03:54 +0000 |
parents | 5d28b76b587c |
children |
comparison
equal
deleted
inserted
replaced
88154:8ce476d3ba36 | 88155:d7ddb3e565de |
---|---|
1 @c -*-texinfo-*- | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | 2 @c This is part of the GNU Emacs Lisp Reference Manual. |
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, |
4 @c Free Software Foundation, Inc. | 4 @c 2004, 2005 Free Software Foundation, Inc. |
5 @c See the file elisp.texi for copying conditions. | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/buffers | 6 @setfilename ../info/buffers |
7 @node Buffers, Windows, Backups and Auto-Saving, Top | 7 @node Buffers, Windows, Backups and Auto-Saving, Top |
8 @chapter Buffers | 8 @chapter Buffers |
9 @cindex buffer | 9 @cindex buffer |
104 Emacs reads a command is the buffer that the command will apply to. | 104 Emacs reads a command is the buffer that the command will apply to. |
105 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to | 105 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to |
106 switch visibly to a different buffer so that the user can edit it. For | 106 switch visibly to a different buffer so that the user can edit it. For |
107 that, you must use the functions described in @ref{Displaying Buffers}. | 107 that, you must use the functions described in @ref{Displaying Buffers}. |
108 | 108 |
109 @strong{Note:} Lisp functions that change to a different current buffer | 109 @strong{Warning:} Lisp functions that change to a different current buffer |
110 should not depend on the command loop to set it back afterwards. | 110 should not depend on the command loop to set it back afterwards. |
111 Editing commands written in Emacs Lisp can be called from other programs | 111 Editing commands written in Emacs Lisp can be called from other programs |
112 as well as from the command loop; it is convenient for the caller if | 112 as well as from the command loop; it is convenient for the caller if |
113 the subroutine does not change which buffer is current (unless, of | 113 the subroutine does not change which buffer is current (unless, of |
114 course, that is the subroutine's purpose). Therefore, you should | 114 course, that is the subroutine's purpose). Therefore, you should |
200 This function returns the buffer identified by @var{buffer-or-name}. | 200 This function returns the buffer identified by @var{buffer-or-name}. |
201 An error is signaled if @var{buffer-or-name} does not identify an | 201 An error is signaled if @var{buffer-or-name} does not identify an |
202 existing buffer. | 202 existing buffer. |
203 @end defun | 203 @end defun |
204 | 204 |
205 @defspec save-current-buffer body... | 205 @defspec save-current-buffer body@dots{} |
206 The @code{save-current-buffer} special form saves the identity of the | 206 The @code{save-current-buffer} special form saves the identity of the |
207 current buffer, evaluates the @var{body} forms, and finally restores | 207 current buffer, evaluates the @var{body} forms, and finally restores |
208 that buffer as current. The return value is the value of the last | 208 that buffer as current. The return value is the value of the last |
209 form in @var{body}. The current buffer is restored even in case of an | 209 form in @var{body}. The current buffer is restored even in case of an |
210 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). | 210 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). |
213 exit from @code{save-current-buffer}, then it is not made current again, | 213 exit from @code{save-current-buffer}, then it is not made current again, |
214 of course. Instead, whichever buffer was current just before exit | 214 of course. Instead, whichever buffer was current just before exit |
215 remains current. | 215 remains current. |
216 @end defspec | 216 @end defspec |
217 | 217 |
218 @defmac with-current-buffer buffer body... | 218 @defmac with-current-buffer buffer-or-name body@dots{} |
219 The @code{with-current-buffer} macro saves the identity of the current | 219 The @code{with-current-buffer} macro saves the identity of the current |
220 buffer, makes @var{buffer} current, evaluates the @var{body} forms, and | 220 buffer, makes @var{buffer-or-name} current, evaluates the @var{body} |
221 finally restores the buffer. The return value is the value of the last | 221 forms, and finally restores the buffer. The return value is the value |
222 form in @var{body}. The current buffer is restored even in case of an | 222 of the last form in @var{body}. The current buffer is restored even |
223 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). | 223 in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal |
224 Exits}). | |
225 | |
226 An error is signaled if @var{buffer-or-name} does not identify an | |
227 existing buffer. | |
224 @end defmac | 228 @end defmac |
225 | 229 |
226 @defmac with-temp-buffer body... | 230 @defmac with-temp-buffer body@dots{} |
231 @anchor{Definition of with-temp-buffer} | |
227 The @code{with-temp-buffer} macro evaluates the @var{body} forms | 232 The @code{with-temp-buffer} macro evaluates the @var{body} forms |
228 with a temporary buffer as the current buffer. It saves the identity of | 233 with a temporary buffer as the current buffer. It saves the identity of |
229 the current buffer, creates a temporary buffer and makes it current, | 234 the current buffer, creates a temporary buffer and makes it current, |
230 evaluates the @var{body} forms, and finally restores the previous | 235 evaluates the @var{body} forms, and finally restores the previous |
231 current buffer while killing the temporary buffer. | 236 current buffer while killing the temporary buffer. |
234 return the contents of the temporary buffer by using | 239 return the contents of the temporary buffer by using |
235 @code{(buffer-string)} as the last form. | 240 @code{(buffer-string)} as the last form. |
236 | 241 |
237 The current buffer is restored even in case of an abnormal exit via | 242 The current buffer is restored even in case of an abnormal exit via |
238 @code{throw} or error (@pxref{Nonlocal Exits}). | 243 @code{throw} or error (@pxref{Nonlocal Exits}). |
244 | |
245 See also @code{with-temp-file} in @ref{Definition of with-temp-file,, | |
246 Writing to Files}. | |
239 @end defmac | 247 @end defmac |
240 | |
241 See also @code{with-temp-file} in @ref{Writing to Files}. | |
242 | 248 |
243 @node Buffer Names | 249 @node Buffer Names |
244 @section Buffer Names | 250 @section Buffer Names |
245 @cindex buffer names | 251 @cindex buffer names |
246 | 252 |
290 @end example | 296 @end example |
291 @end defun | 297 @end defun |
292 | 298 |
293 @deffn Command rename-buffer newname &optional unique | 299 @deffn Command rename-buffer newname &optional unique |
294 This function renames the current buffer to @var{newname}. An error | 300 This function renames the current buffer to @var{newname}. An error |
295 is signaled if @var{newname} is not a string, or if there is already a | 301 is signaled if @var{newname} is not a string. |
296 buffer with that name. The function returns @var{newname}. | |
297 | 302 |
298 @c Emacs 19 feature | 303 @c Emacs 19 feature |
299 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | 304 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is |
300 already in use. However, if @var{unique} is non-@code{nil}, it modifies | 305 already in use. However, if @var{unique} is non-@code{nil}, it modifies |
301 @var{newname} to make a name that is not in use. Interactively, you can | 306 @var{newname} to make a name that is not in use. Interactively, you can |
302 make @var{unique} non-@code{nil} with a numeric prefix argument. | 307 make @var{unique} non-@code{nil} with a numeric prefix argument. |
303 (This is how the command @code{rename-uniquely} is implemented.) | 308 (This is how the command @code{rename-uniquely} is implemented.) |
309 | |
310 This function returns the name actually given to the buffer. | |
304 @end deffn | 311 @end deffn |
305 | 312 |
306 @defun get-buffer buffer-or-name | 313 @defun get-buffer buffer-or-name |
307 This function returns the buffer specified by @var{buffer-or-name}. | 314 This function returns the buffer specified by @var{buffer-or-name}. |
308 If @var{buffer-or-name} is a string and there is no buffer with that | 315 If @var{buffer-or-name} is a string and there is no buffer with that |
327 | 334 |
328 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | 335 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. |
329 @end defun | 336 @end defun |
330 | 337 |
331 @c Emacs 19 feature | 338 @c Emacs 19 feature |
332 @defun generate-new-buffer-name starting-name &rest ignore | 339 @defun generate-new-buffer-name starting-name &optional ignore |
333 This function returns a name that would be unique for a new buffer---but | 340 This function returns a name that would be unique for a new buffer---but |
334 does not create the buffer. It starts with @var{starting-name}, and | 341 does not create the buffer. It starts with @var{starting-name}, and |
335 produces a name not currently in use for any buffer by appending a | 342 produces a name not currently in use for any buffer by appending a |
336 number inside of @samp{<@dots{}>}. | 343 number inside of @samp{<@dots{}>}. It starts at 2 and keeps |
344 incrementing the number until it is not the name of an existing buffer. | |
337 | 345 |
338 If the optional second argument @var{ignore} is non-@code{nil}, it | 346 If the optional second argument @var{ignore} is non-@code{nil}, it |
339 should be a string; it makes a difference if it is a name in the | 347 should be a string, a potential buffer name. It means to consider |
340 sequence of names to be tried. That name will be considered acceptable, | 348 that potential buffer acceptable, if it is tried, even it is the name |
341 if it is tried, even if a buffer with that name exists. Thus, if | 349 of an existing buffer (which would normally be rejected). Thus, if |
342 buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and @samp{foo<4>} | 350 buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and |
343 exist, | 351 @samp{foo<4>} exist, |
344 | 352 |
345 @example | 353 @example |
346 (generate-new-buffer-name "foo") | 354 (generate-new-buffer-name "foo") |
347 @result{} "foo<5>" | 355 @result{} "foo<5>" |
348 (generate-new-buffer-name "foo" "foo<3>") | 356 (generate-new-buffer-name "foo" "foo<3>") |
401 are not strictly necessary, but others are essential to avoid confusing | 409 are not strictly necessary, but others are essential to avoid confusing |
402 Emacs. | 410 Emacs. |
403 @end defvar | 411 @end defvar |
404 | 412 |
405 @defvar buffer-file-truename | 413 @defvar buffer-file-truename |
406 This buffer-local variable holds the truename of the file visited in the | 414 This buffer-local variable holds the abbreviated truename of the file |
407 current buffer, or @code{nil} if no file is visited. It is a permanent | 415 visited in the current buffer, or @code{nil} if no file is visited. |
408 local, unaffected by @code{kill-all-local-variables}. @xref{Truenames}. | 416 It is a permanent local, unaffected by |
417 @code{kill-all-local-variables}. @xref{Truenames}, and | |
418 @ref{Definition of abbreviate-file-name}. | |
409 @end defvar | 419 @end defvar |
410 | 420 |
411 @defvar buffer-file-number | 421 @defvar buffer-file-number |
412 This buffer-local variable holds the file number and directory device | 422 This buffer-local variable holds the file number and directory device |
413 number of the file visited in the current buffer, or @code{nil} if no | 423 number of the file visited in the current buffer, or @code{nil} if no |
417 The value is normally a list of the form @code{(@var{filenum} | 427 The value is normally a list of the form @code{(@var{filenum} |
418 @var{devnum})}. This pair of numbers uniquely identifies the file among | 428 @var{devnum})}. This pair of numbers uniquely identifies the file among |
419 all files accessible on the system. See the function | 429 all files accessible on the system. See the function |
420 @code{file-attributes}, in @ref{File Attributes}, for more information | 430 @code{file-attributes}, in @ref{File Attributes}, for more information |
421 about them. | 431 about them. |
432 | |
433 If @code{buffer-file-name} is the name of a symbolic link, then both | |
434 numbers refer to the recursive target. | |
422 @end defvar | 435 @end defvar |
423 | 436 |
424 @defun get-file-buffer filename | 437 @defun get-file-buffer filename |
425 This function returns the buffer visiting file @var{filename}. If | 438 This function returns the buffer visiting file @var{filename}. If |
426 there is no such buffer, it returns @code{nil}. The argument | 439 there is no such buffer, it returns @code{nil}. The argument |
427 @var{filename}, which must be a string, is expanded (@pxref{File Name | 440 @var{filename}, which must be a string, is expanded (@pxref{File Name |
428 Expansion}), then compared against the visited file names of all live | 441 Expansion}), then compared against the visited file names of all live |
429 buffers. | 442 buffers. Note that the buffer's @code{buffer-file-name} must match |
443 the expansion of @var{filename} exactly. This function will not | |
444 recognize other names for the same file. | |
430 | 445 |
431 @example | 446 @example |
432 @group | 447 @group |
433 (get-file-buffer "buffers.texi") | 448 (get-file-buffer "buffers.texi") |
434 @result{} #<buffer buffers.texi> | 449 @result{} #<buffer buffers.texi> |
436 @end example | 451 @end example |
437 | 452 |
438 In unusual circumstances, there can be more than one buffer visiting | 453 In unusual circumstances, there can be more than one buffer visiting |
439 the same file name. In such cases, this function returns the first | 454 the same file name. In such cases, this function returns the first |
440 such buffer in the buffer list. | 455 such buffer in the buffer list. |
456 @end defun | |
457 | |
458 @defun find-buffer-visiting filename &optional predicate | |
459 This is like @code{get-file-buffer}, except that it can return any | |
460 buffer visiting the file @emph{possibly under a different name}. That | |
461 is, the buffer's @code{buffer-file-name} does not need to match the | |
462 expansion of @var{filename} exactly, it only needs to refer to the | |
463 same file. If @var{predicate} is non-@code{nil}, it should be a | |
464 function of one argument, a buffer visiting @var{filename}. The | |
465 buffer is only considered a suitable return value if @var{predicate} | |
466 returns non-@code{nil}. If it can not find a suitable buffer to | |
467 return, @code{find-buffer-visiting} returns @code{nil}. | |
441 @end defun | 468 @end defun |
442 | 469 |
443 @deffn Command set-visited-file-name filename &optional no-query along-with-file | 470 @deffn Command set-visited-file-name filename &optional no-query along-with-file |
444 If @var{filename} is a non-empty string, this function changes the | 471 If @var{filename} is a non-empty string, this function changes the |
445 name of the file visited in the current buffer to @var{filename}. (If the | 472 name of the file visited in the current buffer to @var{filename}. (If the |
446 buffer had no visited file, this gives it one.) The @emph{next time} | 473 buffer had no visited file, this gives it one.) The @emph{next time} |
447 the buffer is saved it will go in the newly-specified file. This | 474 the buffer is saved it will go in the newly-specified file. |
448 command marks the buffer as modified, since it does not (as far as Emacs | 475 |
449 knows) match the contents of @var{filename}, even if it matched the | 476 This command marks the buffer as modified, since it does not (as far |
450 former visited file. | 477 as Emacs knows) match the contents of @var{filename}, even if it |
478 matched the former visited file. It also renames the buffer to | |
479 correspond to the new file name, unless the new name is already in | |
480 use. | |
451 | 481 |
452 If @var{filename} is @code{nil} or the empty string, that stands for | 482 If @var{filename} is @code{nil} or the empty string, that stands for |
453 ``no visited file''. In this case, @code{set-visited-file-name} marks | 483 ``no visited file''. In this case, @code{set-visited-file-name} marks |
454 the buffer as having no visited file. | 484 the buffer as having no visited file, without changing the buffer's |
455 | 485 modified flag. |
456 Normally, this function asks the user for confirmation if the specified | 486 |
457 file already exists. If @var{no-query} is non-@code{nil}, that prevents | 487 Normally, this function asks the user for confirmation if there |
458 asking this question. | 488 already is a buffer visiting @var{filename}. If @var{no-query} is |
459 | 489 non-@code{nil}, that prevents asking this question. If there already |
460 If @var{along-with-file} is non-@code{nil}, that means to assume that the | 490 is a buffer visiting @var{filename}, and the user confirms or |
461 former visited file has been renamed to @var{filename}. | 491 @var{query} is non-@code{nil}, this function makes the new buffer name |
492 unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. | |
493 | |
494 If @var{along-with-file} is non-@code{nil}, that means to assume that | |
495 the former visited file has been renamed to @var{filename}. In this | |
496 case, the command does not change the buffer's modified flag, nor the | |
497 buffer's recorded last file modification time as reported by | |
498 @code{visited-file-modtime} (@pxref{Modification Time}). If | |
499 @var{along-with-file} is @code{nil}, this function clears the recorded | |
500 last file modification time, after which @code{visited-file-modtime} | |
501 returns zero. | |
462 | 502 |
463 @c Wordy to avoid overfull hbox. --rjc 16mar92 | 503 @c Wordy to avoid overfull hbox. --rjc 16mar92 |
464 When the function @code{set-visited-file-name} is called interactively, it | 504 When the function @code{set-visited-file-name} is called interactively, it |
465 prompts for @var{filename} in the minibuffer. | 505 prompts for @var{filename} in the minibuffer. |
466 @end deffn | 506 @end deffn |
512 (set-buffer-modified-p (buffer-modified-p)) | 552 (set-buffer-modified-p (buffer-modified-p)) |
513 @end group | 553 @end group |
514 @end example | 554 @end example |
515 @end defun | 555 @end defun |
516 | 556 |
517 @deffn Command not-modified | 557 @defun restore-buffer-modified-p flag |
518 This command marks the current buffer as unmodified, and not needing to | 558 Like @code{set-buffer-modified-p}, but does not force redisplay |
519 be saved. With prefix arg, it marks the buffer as modified, so that it | 559 of mode lines. |
520 will be saved at the next suitable occasion. | 560 @end defun |
561 | |
562 @deffn Command not-modified &optional arg | |
563 This command marks the current buffer as unmodified, and not needing | |
564 to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as | |
565 modified, so that it will be saved at the next suitable occasion. | |
566 Interactively, @var{arg} is the prefix argument. | |
521 | 567 |
522 Don't use this function in programs, since it prints a message in the | 568 Don't use this function in programs, since it prints a message in the |
523 echo area; use @code{set-buffer-modified-p} (above) instead. | 569 echo area; use @code{set-buffer-modified-p} (above) instead. |
524 @end deffn | 570 @end deffn |
525 | 571 |
526 @c Emacs 19 feature | 572 @c Emacs 19 feature |
527 @defun buffer-modified-tick &optional buffer | 573 @defun buffer-modified-tick &optional buffer |
528 This function returns @var{buffer}'s modification-count. This is a | 574 This function returns @var{buffer}'s modification-count. This is a |
529 counter that increments every time the buffer is modified. If | 575 counter that increments every time the buffer is modified. If |
530 @var{buffer} is @code{nil} (or omitted), the current buffer is used. | 576 @var{buffer} is @code{nil} (or omitted), the current buffer is used. |
577 The counter can wrap around occasionally. | |
531 @end defun | 578 @end defun |
532 | 579 |
533 @node Modification Time | 580 @node Modification Time |
534 @comment node-name, next, previous, up | 581 @comment node-name, next, previous, up |
535 @section Comparison of Modification Time | 582 @section Comparison of Modification Time |
550 the same unless some other process has written the file since Emacs | 597 the same unless some other process has written the file since Emacs |
551 visited or saved it. | 598 visited or saved it. |
552 | 599 |
553 The function returns @code{t} if the last actual modification time and | 600 The function returns @code{t} if the last actual modification time and |
554 Emacs's recorded modification time are the same, @code{nil} otherwise. | 601 Emacs's recorded modification time are the same, @code{nil} otherwise. |
602 It also returns @code{t} if the buffer has no recorded last | |
603 modification time, that is if @code{visited-file-modtime} would return | |
604 zero. | |
605 | |
606 It always returns @code{t} for buffers that are not visiting a file, | |
607 even if @code{visited-file-modtime} returns a non-zero value. For | |
608 instance, it always returns @code{t} for dired buffers. It returns | |
609 @code{t} for buffers that are visiting a file that does not exist and | |
610 never existed, but @code{nil} for file-visiting buffers whose file has | |
611 been deleted. | |
555 @end defun | 612 @end defun |
556 | 613 |
557 @defun clear-visited-file-modtime | 614 @defun clear-visited-file-modtime |
558 This function clears out the record of the last modification time of | 615 This function clears out the record of the last modification time of |
559 the file being visited by the current buffer. As a result, the next | 616 the file being visited by the current buffer. As a result, the next |
565 file should not be done. | 622 file should not be done. |
566 @end defun | 623 @end defun |
567 | 624 |
568 @c Emacs 19 feature | 625 @c Emacs 19 feature |
569 @defun visited-file-modtime | 626 @defun visited-file-modtime |
570 This function returns the buffer's recorded last file modification time, | 627 This function returns the current buffer's recorded last file |
571 as a list of the form @code{(@var{high} . @var{low})}. (This is the | 628 modification time, as a list of the form @code{(@var{high} @var{low})}. |
572 same format that @code{file-attributes} uses to return time values; see | 629 (This is the same format that @code{file-attributes} uses to return |
573 @ref{File Attributes}.) | 630 time values; see @ref{File Attributes}.) |
631 | |
632 If the buffer has no recorded last modification time, this function | |
633 returns zero. This case occurs, for instance, if the buffer is not | |
634 visiting a file or if the time has been explicitly cleared by | |
635 @code{clear-visited-file-modtime}. Note, however, that | |
636 @code{visited-file-modtime} returns a list for some non-file buffers | |
637 too. For instance, in a Dired buffer listing a directory, it returns | |
638 the last modification time of that directory, as recorded by Dired. | |
639 | |
640 For a new buffer visiting a not yet existing file, @var{high} is | |
641 @minus{}1 and @var{low} is 65535, that is, | |
642 @ifnottex | |
643 @w{2**16 - 1.} | |
644 @end ifnottex | |
645 @tex | |
646 @math{2^{16}-1}. | |
647 @end tex | |
574 @end defun | 648 @end defun |
575 | 649 |
576 @c Emacs 19 feature | 650 @c Emacs 19 feature |
577 @defun set-visited-file-modtime &optional time | 651 @defun set-visited-file-modtime &optional time |
578 This function updates the buffer's record of the last modification time | 652 This function updates the buffer's record of the last modification time |
579 of the visited file, to the value specified by @var{time} if @var{time} | 653 of the visited file, to the value specified by @var{time} if @var{time} |
580 is not @code{nil}, and otherwise to the last modification time of the | 654 is not @code{nil}, and otherwise to the last modification time of the |
581 visited file. | 655 visited file. |
582 | 656 |
583 If @var{time} is not @code{nil}, it should have the form | 657 If @var{time} is neither @code{nil} nor zero, it should have the form |
584 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in | 658 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in |
585 either case containing two integers, each of which holds 16 bits of the | 659 either case containing two integers, each of which holds 16 bits of the |
586 time. | 660 time. |
587 | 661 |
588 This function is useful if the buffer was not read from the file | 662 This function is useful if the buffer was not read from the file |
644 This buffer-local variable specifies whether the buffer is read-only. | 718 This buffer-local variable specifies whether the buffer is read-only. |
645 The buffer is read-only if this variable is non-@code{nil}. | 719 The buffer is read-only if this variable is non-@code{nil}. |
646 @end defvar | 720 @end defvar |
647 | 721 |
648 @defvar inhibit-read-only | 722 @defvar inhibit-read-only |
649 If this variable is non-@code{nil}, then read-only buffers and read-only | 723 If this variable is non-@code{nil}, then read-only buffers and, |
650 characters may be modified. Read-only characters in a buffer are those | 724 depending on the actual value, some or all read-only characters may be |
651 that have non-@code{nil} @code{read-only} properties (either text | 725 modified. Read-only characters in a buffer are those that have |
652 properties or overlay properties). @xref{Special Properties}, for more | 726 non-@code{nil} @code{read-only} properties (either text properties or |
653 information about text properties. @xref{Overlays}, for more | 727 overlay properties). @xref{Special Properties}, for more information |
654 information about overlays and their properties. | 728 about text properties. @xref{Overlays}, for more information about |
729 overlays and their properties. | |
655 | 730 |
656 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character | 731 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character |
657 properties have no effect. If @code{inhibit-read-only} is a list, then | 732 properties have no effect. If @code{inhibit-read-only} is a list, then |
658 @code{read-only} character properties have no effect if they are members | 733 @code{read-only} character properties have no effect if they are members |
659 of the list (comparison is done with @code{eq}). | 734 of the list (comparison is done with @code{eq}). |
660 @end defvar | 735 @end defvar |
661 | 736 |
662 @deffn Command toggle-read-only | 737 @deffn Command toggle-read-only &optional arg |
663 This command changes whether the current buffer is read-only. It is | 738 This command toggles whether the current buffer is read-only. It is |
664 intended for interactive use; do not use it in programs. At any given | 739 intended for interactive use; do not use it in programs. At any given |
665 point in a program, you should know whether you want the read-only flag | 740 point in a program, you should know whether you want the read-only flag |
666 on or off; so you can set @code{buffer-read-only} explicitly to the | 741 on or off; so you can set @code{buffer-read-only} explicitly to the |
667 proper value, @code{t} or @code{nil}. | 742 proper value, @code{t} or @code{nil}. |
743 | |
744 If @var{arg} is non-@code{nil}, it should be a raw prefix argument. | |
745 @code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if | |
746 the numeric value of that prefix argument is positive and to | |
747 @code{nil} otherwise. @xref{Prefix Command Arguments}. | |
668 @end deffn | 748 @end deffn |
669 | 749 |
670 @defun barf-if-buffer-read-only | 750 @defun barf-if-buffer-read-only |
671 This function signals a @code{buffer-read-only} error if the current | 751 This function signals a @code{buffer-read-only} error if the current |
672 buffer is read-only. @xref{Interactive Call}, for another way to | 752 buffer is read-only. @xref{Using Interactive}, for another way to |
673 signal an error if the current buffer is read-only. | 753 signal an error if the current buffer is read-only. |
674 @end defun | 754 @end defun |
675 | 755 |
676 @node The Buffer List | 756 @node The Buffer List |
677 @section The Buffer List | 757 @section The Buffer List |
678 @cindex buffer list | 758 @cindex buffer list |
679 | 759 |
680 The @dfn{buffer list} is a list of all live buffers. Creating a | 760 The @dfn{buffer list} is a list of all live buffers. The order of |
681 buffer adds it to this list, and killing a buffer excises it. The order | 761 the buffers in the list is based primarily on how recently each buffer |
682 of the buffers in the list is based primarily on how recently each | 762 has been displayed in a window. Several functions, notably |
683 buffer has been displayed in the selected window. Buffers move to the | 763 @code{other-buffer}, use this ordering. A buffer list displayed for |
684 front of the list when they are selected and to the end when they are | 764 the user also follows this order. |
685 buried (see @code{bury-buffer}, below). Several functions, notably | 765 |
686 @code{other-buffer}, use this ordering. A buffer list displayed for the | 766 Creating a buffer adds it to the end of the buffer list, and killing |
687 user also follows this order. | 767 a buffer removes it. Buffers move to the front of the list when they |
688 | 768 are selected for display in a window (@pxref{Displaying Buffers}), and |
769 to the end when they are buried (see @code{bury-buffer}, below). | |
770 There are no functions available to the Lisp programmer which directly | |
771 manipulate the buffer list. | |
772 | |
689 In addition to the fundamental Emacs buffer list, each frame has its | 773 In addition to the fundamental Emacs buffer list, each frame has its |
690 own version of the buffer list, in which the buffers that have been | 774 own version of the buffer list, in which the buffers that have been |
691 selected in that frame come first, starting with the buffers most | 775 selected in that frame come first, starting with the buffers most |
692 recently selected @emph{in that frame}. (This order is recorded in | 776 recently selected @emph{in that frame}. (This order is recorded in |
693 @var{frame}'s @code{buffer-list} frame parameter; see @ref{Window Frame | 777 @var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer |
694 Parameters}.) The buffers that were never selected in @var{frame} come | 778 Parameters}.) The buffers that were never selected in @var{frame} come |
695 afterward, ordered according to the fundamental Emacs buffer list. | 779 afterward, ordered according to the fundamental Emacs buffer list. |
696 | 780 |
697 @defun buffer-list &optional frame | 781 @defun buffer-list &optional frame |
698 This function returns the buffer list, including all buffers, even those | 782 This function returns the buffer list, including all buffers, even those |
755 buffer list that is not now visible in any window in a visible frame. | 839 buffer list that is not now visible in any window in a visible frame. |
756 | 840 |
757 If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, | 841 If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, |
758 then @code{other-buffer} uses that predicate to decide which buffers to | 842 then @code{other-buffer} uses that predicate to decide which buffers to |
759 consider. It calls the predicate once for each buffer, and if the value | 843 consider. It calls the predicate once for each buffer, and if the value |
760 is @code{nil}, that buffer is ignored. @xref{Window Frame Parameters}. | 844 is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. |
761 | 845 |
762 @c Emacs 19 feature | 846 @c Emacs 19 feature |
763 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | 847 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning |
764 a buffer visible in any window on any visible frame, except as a last | 848 a buffer visible in any window on any visible frame, except as a last |
765 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter | 849 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter |
771 | 855 |
772 @deffn Command bury-buffer &optional buffer-or-name | 856 @deffn Command bury-buffer &optional buffer-or-name |
773 This function puts @var{buffer-or-name} at the end of the buffer list, | 857 This function puts @var{buffer-or-name} at the end of the buffer list, |
774 without changing the order of any of the other buffers on the list. | 858 without changing the order of any of the other buffers on the list. |
775 This buffer therefore becomes the least desirable candidate for | 859 This buffer therefore becomes the least desirable candidate for |
776 @code{other-buffer} to return. | 860 @code{other-buffer} to return. The argument can be either a buffer |
861 itself or the name of one. | |
777 | 862 |
778 @code{bury-buffer} operates on each frame's @code{buffer-list} parameter | 863 @code{bury-buffer} operates on each frame's @code{buffer-list} parameter |
779 as well as the frame-independent Emacs buffer list; therefore, the | 864 as well as the frame-independent Emacs buffer list; therefore, the |
780 buffer that you bury will come last in the value of @code{(buffer-list | 865 buffer that you bury will come last in the value of @code{(buffer-list |
781 @var{frame})} and in the value of @code{(buffer-list nil)}. | 866 @var{frame})} and in the value of @code{(buffer-list nil)}. |
804 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | 889 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and |
805 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | 890 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a |
806 subprocess can also create a buffer (@pxref{Processes}). | 891 subprocess can also create a buffer (@pxref{Processes}). |
807 | 892 |
808 @defun get-buffer-create name | 893 @defun get-buffer-create name |
809 This function returns a buffer named @var{name}. It returns an existing | 894 This function returns a buffer named @var{name}. It returns a live |
810 buffer with that name, if one exists; otherwise, it creates a new | 895 buffer with that name, if one exists; otherwise, it creates a new |
811 buffer. The buffer does not become the current buffer---this function | 896 buffer. The buffer does not become the current buffer---this function |
812 does not change which buffer is current. | 897 does not change which buffer is current. |
813 | 898 |
814 An error is signaled if @var{name} is not a string. | 899 If @var{name} is a buffer instead of a string, it is returned, even if |
900 it is dead. An error is signaled if @var{name} is neither a string | |
901 nor a buffer. | |
815 | 902 |
816 @example | 903 @example |
817 @group | 904 @group |
818 (get-buffer-create "foo") | 905 (get-buffer-create "foo") |
819 @result{} #<buffer foo> | 906 @result{} #<buffer foo> |
820 @end group | 907 @end group |
821 @end example | 908 @end example |
822 | 909 |
823 The major mode for the new buffer is set to Fundamental mode. The | 910 The major mode for a newly created buffer is set to Fundamental mode. |
824 variable @code{default-major-mode} is handled at a higher level. | 911 The variable @code{default-major-mode} is handled at a higher level. |
825 @xref{Auto Major Mode}. | 912 @xref{Auto Major Mode}. |
826 @end defun | 913 @end defun |
827 | 914 |
828 @defun generate-new-buffer name | 915 @defun generate-new-buffer name |
829 This function returns a newly created, empty buffer, but does not make | 916 This function returns a newly created, empty buffer, but does not make |
861 @node Killing Buffers | 948 @node Killing Buffers |
862 @section Killing Buffers | 949 @section Killing Buffers |
863 @cindex killing buffers | 950 @cindex killing buffers |
864 @cindex buffers, killing | 951 @cindex buffers, killing |
865 | 952 |
866 @dfn{Killing a buffer} makes its name unknown to Emacs and makes its | 953 @dfn{Killing a buffer} makes its name unknown to Emacs and makes the |
867 text space available for other use. | 954 memory space it occupied available for other use. |
868 | 955 |
869 The buffer object for the buffer that has been killed remains in | 956 The buffer object for the buffer that has been killed remains in |
870 existence as long as anything refers to it, but it is specially marked | 957 existence as long as anything refers to it, but it is specially marked |
871 so that you cannot make it current or display it. Killed buffers retain | 958 so that you cannot make it current or display it. Killed buffers retain |
872 their identity, however; if you kill two distinct buffers, they remain | 959 their identity, however; if you kill two distinct buffers, they remain |
893 @end group | 980 @end group |
894 @end example | 981 @end example |
895 | 982 |
896 @deffn Command kill-buffer buffer-or-name | 983 @deffn Command kill-buffer buffer-or-name |
897 This function kills the buffer @var{buffer-or-name}, freeing all its | 984 This function kills the buffer @var{buffer-or-name}, freeing all its |
898 memory for other uses or to be returned to the operating system. It | 985 memory for other uses or to be returned to the operating system. If |
899 returns @code{nil}. | 986 @var{buffer-or-name} is @code{nil}, it kills the current buffer. |
900 | 987 |
901 Any processes that have this buffer as the @code{process-buffer} are | 988 Any processes that have this buffer as the @code{process-buffer} are |
902 sent the @code{SIGHUP} signal, which normally causes them to terminate. | 989 sent the @code{SIGHUP} signal, which normally causes them to terminate. |
903 (The basic meaning of @code{SIGHUP} is that a dialup line has been | 990 (The basic meaning of @code{SIGHUP} is that a dialup line has been |
904 disconnected.) @xref{Signals to Processes}. | 991 disconnected.) @xref{Signals to Processes}. |
909 for confirmation, clear the modified flag before calling | 996 for confirmation, clear the modified flag before calling |
910 @code{kill-buffer}. @xref{Buffer Modification}. | 997 @code{kill-buffer}. @xref{Buffer Modification}. |
911 | 998 |
912 Killing a buffer that is already dead has no effect. | 999 Killing a buffer that is already dead has no effect. |
913 | 1000 |
1001 This function returns @code{t} if it actually killed the buffer. It | |
1002 returns @code{nil} if the user refuses to confirm or if | |
1003 @var{buffer-or-name} was already dead. | |
1004 | |
914 @smallexample | 1005 @smallexample |
915 (kill-buffer "foo.unchanged") | 1006 (kill-buffer "foo.unchanged") |
916 @result{} nil | 1007 @result{} t |
917 (kill-buffer "foo.changed") | 1008 (kill-buffer "foo.changed") |
918 | 1009 |
919 ---------- Buffer: Minibuffer ---------- | 1010 ---------- Buffer: Minibuffer ---------- |
920 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | 1011 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} |
921 ---------- Buffer: Minibuffer ---------- | 1012 ---------- Buffer: Minibuffer ---------- |
922 | 1013 |
923 @result{} nil | 1014 @result{} t |
924 @end smallexample | 1015 @end smallexample |
925 @end deffn | 1016 @end deffn |
926 | 1017 |
927 @defvar kill-buffer-query-functions | 1018 @defvar kill-buffer-query-functions |
928 After confirming unsaved changes, @code{kill-buffer} calls the functions | 1019 After confirming unsaved changes, @code{kill-buffer} calls the functions |
935 | 1026 |
936 @defvar kill-buffer-hook | 1027 @defvar kill-buffer-hook |
937 This is a normal hook run by @code{kill-buffer} after asking all the | 1028 This is a normal hook run by @code{kill-buffer} after asking all the |
938 questions it is going to ask, just before actually killing the buffer. | 1029 questions it is going to ask, just before actually killing the buffer. |
939 The buffer to be killed is current when the hook functions run. | 1030 The buffer to be killed is current when the hook functions run. |
940 @xref{Hooks}. | 1031 @xref{Hooks}. This variable is a permanent local, so its local binding |
1032 is not cleared by changing major modes. | |
941 @end defvar | 1033 @end defvar |
942 | 1034 |
943 @defvar buffer-offer-save | 1035 @defvar buffer-offer-save |
944 This variable, if non-@code{nil} in a particular buffer, tells | 1036 This variable, if non-@code{nil} in a particular buffer, tells |
945 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to | 1037 @code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the |
946 save that buffer, just as they offer to save file-visiting buffers. The | 1038 second optional argument to that function is @code{t}) to offer to |
947 variable @code{buffer-offer-save} automatically becomes buffer-local | 1039 save that buffer, just as they offer to save file-visiting buffers. |
948 when set for any reason. @xref{Buffer-Local Variables}. | 1040 @xref{Definition of save-some-buffers}. The variable |
1041 @code{buffer-offer-save} automatically becomes buffer-local when set | |
1042 for any reason. @xref{Buffer-Local Variables}. | |
949 @end defvar | 1043 @end defvar |
1044 | |
1045 @defvar buffer-save-without-query | |
1046 This variable, if non-@code{nil} in a particular buffer, tells | |
1047 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to save | |
1048 this buffer (if it's modified) without asking the user. The variable | |
1049 automatically becomes buffer-local when set for any reason. | |
1050 @end defvar | |
1051 | |
1052 @defun buffer-live-p object | |
1053 This function returns @code{t} if @var{object} is a buffer which has | |
1054 not been killed, @code{nil} otherwise. | |
1055 @end defun | |
950 | 1056 |
951 @node Indirect Buffers | 1057 @node Indirect Buffers |
952 @section Indirect Buffers | 1058 @section Indirect Buffers |
953 @cindex indirect buffers | 1059 @cindex indirect buffers |
954 @cindex base buffer | 1060 @cindex base buffer |
962 base buffer; changes made by editing either one are visible immediately | 1068 base buffer; changes made by editing either one are visible immediately |
963 in the other. This includes the text properties as well as the characters | 1069 in the other. This includes the text properties as well as the characters |
964 themselves. | 1070 themselves. |
965 | 1071 |
966 In all other respects, the indirect buffer and its base buffer are | 1072 In all other respects, the indirect buffer and its base buffer are |
967 completely separate. They have different names, different values of | 1073 completely separate. They have different names, independent values of |
968 point, different narrowing, different markers and overlays (though | 1074 point, independent narrowing, independent markers and overlays (though |
969 inserting or deleting text in either buffer relocates the markers and | 1075 inserting or deleting text in either buffer relocates the markers and |
970 overlays for both), different major modes, and different buffer-local | 1076 overlays for both), independent major modes, and independent |
971 variables. | 1077 buffer-local variable bindings. |
972 | 1078 |
973 An indirect buffer cannot visit a file, but its base buffer can. If | 1079 An indirect buffer cannot visit a file, but its base buffer can. If |
974 you try to save the indirect buffer, that actually saves the base | 1080 you try to save the indirect buffer, that actually saves the base |
975 buffer. | 1081 buffer. |
976 | 1082 |
977 Killing an indirect buffer has no effect on its base buffer. Killing | 1083 Killing an indirect buffer has no effect on its base buffer. Killing |
978 the base buffer effectively kills the indirect buffer in that it cannot | 1084 the base buffer effectively kills the indirect buffer in that it cannot |
979 ever again be the current buffer. | 1085 ever again be the current buffer. |
980 | 1086 |
981 @deffn Command make-indirect-buffer base-buffer name | 1087 @deffn Command make-indirect-buffer base-buffer name &optional clone |
982 This creates an indirect buffer named @var{name} whose base buffer | 1088 This creates and returns an indirect buffer named @var{name} whose |
983 is @var{base-buffer}. The argument @var{base-buffer} may be a buffer | 1089 base buffer is @var{base-buffer}. The argument @var{base-buffer} may |
984 or a string. | 1090 be a live buffer or the name (a string) of an existing buffer. If |
1091 @var{name} is the name of an existing buffer, an error is signaled. | |
1092 | |
1093 If @var{clone} is non-@code{nil}, then the indirect buffer originally | |
1094 shares the ``state'' of @var{base-buffer} such as major mode, minor | |
1095 modes, buffer local variables and so on. If @var{clone} is omitted | |
1096 or @code{nil} the indirect buffer's state is set to the default state | |
1097 for new buffers. | |
985 | 1098 |
986 If @var{base-buffer} is an indirect buffer, its base buffer is used as | 1099 If @var{base-buffer} is an indirect buffer, its base buffer is used as |
987 the base for the new buffer. | 1100 the base for the new buffer. If, in addition, @var{clone} is |
1101 non-@code{nil}, the initial state is copied from the actual base | |
1102 buffer, not from @var{base-buffer}. | |
988 @end deffn | 1103 @end deffn |
989 | 1104 |
990 @defun buffer-base-buffer buffer | 1105 @defun clone-indirect-buffer newname display-flag &optional norecord |
991 This function returns the base buffer of @var{buffer}. If @var{buffer} | 1106 This function creates and returns a new indirect buffer that shares |
992 is not indirect, the value is @code{nil}. Otherwise, the value is | 1107 the current buffer's base buffer and copies the rest of the current |
993 another buffer, which is never an indirect buffer. | 1108 buffer's attributes. (If the current buffer is not indirect, it is |
1109 used as the base buffer.) | |
1110 | |
1111 If @var{display-flag} is non-@code{nil}, that means to display the new | |
1112 buffer by calling @code{pop-to-buffer}. If @var{norecord} is | |
1113 non-@code{nil}, that means not to put the new buffer to the front of | |
1114 the buffer list. | |
1115 @end defun | |
1116 | |
1117 @defun buffer-base-buffer &optional buffer | |
1118 This function returns the base buffer of @var{buffer}, which defaults | |
1119 to the current buffer. If @var{buffer} is not indirect, the value is | |
1120 @code{nil}. Otherwise, the value is another buffer, which is never an | |
1121 indirect buffer. | |
994 @end defun | 1122 @end defun |
995 | 1123 |
996 @node Buffer Gap | 1124 @node Buffer Gap |
997 @section The Buffer Gap | 1125 @section The Buffer Gap |
998 | 1126 |
1014 @end defun | 1142 @end defun |
1015 | 1143 |
1016 @defun gap-size | 1144 @defun gap-size |
1017 This function returns the current gap size of the current buffer. | 1145 This function returns the current gap size of the current buffer. |
1018 @end defun | 1146 @end defun |
1147 | |
1148 @ignore | |
1149 arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c | |
1150 @end ignore |