Mercurial > emacs
comparison lispref/buffers.texi @ 7677:431b1a011c29
entered into RCS
author | Richard M. Stallman <rms@gnu.org> |
---|---|
date | Wed, 25 May 1994 06:00:06 +0000 |
parents | b93516a5dcda |
children | a91fcb58e8d2 |
comparison
equal
deleted
inserted
replaced
7676:5b8a573e9f69 | 7677:431b1a011c29 |
---|---|
7 @chapter Buffers | 7 @chapter Buffers |
8 @cindex buffer | 8 @cindex buffer |
9 | 9 |
10 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | 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 | 11 are used to hold the contents of files that are being visited; there may |
12 also be buffers which are not visiting files. While several buffers 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 | 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 | 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 | 15 current buffer. Each buffer, including the current buffer, may or may |
16 not be displayed in any windows. | 16 not be displayed in any windows. |
17 | 17 |
35 @section Buffer Basics | 35 @section Buffer Basics |
36 | 36 |
37 @ifinfo | 37 @ifinfo |
38 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | 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 | 39 are used to hold the contents of files that are being visited; there may |
40 also be buffers which are not visiting files. While several buffers 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 | 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 | 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 | 43 current buffer. Each buffer, including the current buffer, may or may |
44 not be displayed in any windows. | 44 not be displayed in any windows. |
45 @end ifinfo | 45 @end ifinfo |
46 | 46 |
47 Buffers in Emacs editing are objects which have distinct names and | 47 Buffers in Emacs editing are objects that have distinct names and |
48 hold text that can be edited. Buffers appear to Lisp programs as a | 48 hold text that can be edited. Buffers appear to Lisp programs as a |
49 special data type. The contents of a buffer may be viewed as an | 49 special data type. The contents of a buffer may be viewed as an |
50 extendable string; insertions and deletions may occur in any part of the | 50 extendable string; insertions and deletions may occur in any part of the |
51 buffer. @xref{Text}. | 51 buffer. @xref{Text}. |
52 | 52 |
53 A Lisp buffer object contains numerous pieces of information. Some of | 53 A Lisp buffer object contains numerous pieces of information. Some of |
54 this information is directly accessible to the programmer through | 54 this information is directly accessible to the programmer through |
55 variables, while other information is only accessible through | 55 variables, while other information is accessible only through |
56 special-purpose functions. For example, the visited file name is | 56 special-purpose functions. For example, the visited file name is |
57 directly accessible through a variable, while the value of point is | 57 directly accessible through a variable, while the value of point is |
58 accessible only through a primitive function. | 58 accessible only through a primitive function. |
59 | 59 |
60 Buffer-specific information that is directly accessible is stored in | 60 Buffer-specific information that is directly accessible is stored in |
401 This function is useful if the buffer was not read from the file | 401 This function is useful if the buffer was not read from the file |
402 normally, or if the file itself has been changed for some known benign | 402 normally, or if the file itself has been changed for some known benign |
403 reason. | 403 reason. |
404 @end defun | 404 @end defun |
405 | 405 |
406 @defun ask-user-about-supersession-threat fn | 406 @defun ask-user-about-supersession-threat filename |
407 @cindex obsolete buffer | 407 @cindex obsolete buffer |
408 This function is used to ask a user how to proceed after an attempt to | 408 This function is used to ask a user how to proceed after an attempt to |
409 modify an obsolete buffer. An @dfn{obsolete buffer} is an unmodified | 409 modify an obsolete buffer visiting file @var{filename}. An |
410 buffer for which the associated file on disk is newer than the last | 410 @dfn{obsolete buffer} is an unmodified buffer for which the associated |
411 save-time of the buffer. This means some other program has probably | 411 file on disk is newer than the last save-time of the buffer. This means |
412 altered the file. | 412 some other program has probably altered the file. |
413 | |
414 @kindex file-supersession | |
415 Depending on the user's answer, the function may return normally, in | |
416 which case the modification of the buffer proceeds, or it may signal a | |
417 @code{file-supersession} error with data @code{(@var{filename})}, in which | |
418 case the proposed buffer modification is not allowed. | |
413 | 419 |
414 This function is called automatically by Emacs on the proper | 420 This function is called automatically by Emacs on the proper |
415 occasions. It exists so you can customize Emacs by redefining it. | 421 occasions. It exists so you can customize Emacs by redefining it. |
416 See the file @file{userlock.el} for the standard definition. | 422 See the file @file{userlock.el} for the standard definition. |
417 | |
418 @kindex file-supersession | |
419 Depending on the user's answer, the function may return normally, in | |
420 which case the modification of the buffer proceeds, or it may signal a | |
421 @code{file-supersession} error with data @code{(@var{fn})}, in which | |
422 case the proposed buffer modification is not allowed. | |
423 | 423 |
424 See also the file locking mechanism in @ref{File Locks}. | 424 See also the file locking mechanism in @ref{File Locks}. |
425 @end defun | 425 @end defun |
426 | 426 |
427 @node Read Only Buffers | 427 @node Read Only Buffers |
458 The buffer is read-only if this variable is non-@code{nil}. | 458 The buffer is read-only if this variable is non-@code{nil}. |
459 @end defvar | 459 @end defvar |
460 | 460 |
461 @defvar inhibit-read-only | 461 @defvar inhibit-read-only |
462 If this variable is non-@code{nil}, then read-only buffers and read-only | 462 If this variable is non-@code{nil}, then read-only buffers and read-only |
463 characters may be modified. The value of @code{buffer-read-only} does | 463 characters may be modified. Read-only characters in a buffer are those |
464 not matter when @code{inhibit-read-only} is non-@code{nil}. | 464 that have non-@code{nil} @code{read-only} properties (either text |
465 | 465 properties or overlay properties). @xref{Special Properties}, for more |
466 If @code{inhibit-read-only} is @code{t}, all @code{read-only} text | 466 information about text properties. @xref{Overlays}, for more |
467 properties have no effect (@pxref{Special Properties}). If | 467 information about overlays and their properties. |
468 @code{inhibit-read-only} is a list, then @code{read-only} text | 468 |
469 properties are ignored if they are members of the list (comparison is | 469 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character |
470 done with @code{eq}). | 470 properties have no effect. If @code{inhibit-read-only} is a list, then |
471 @code{read-only} character properties have no effect if they are members | |
472 of the list (comparison is done with @code{eq}). | |
471 @end defvar | 473 @end defvar |
472 | 474 |
473 @deffn Command toggle-read-only | 475 @deffn Command toggle-read-only |
474 This command changes whether the current buffer is read-only. It is | 476 This command changes whether the current buffer is read-only. It is |
475 intended for interactive use; don't use it in programs. At any given | 477 intended for interactive use; don't use it in programs. At any given |
545 This function puts @var{buffer-or-name} at the end of the buffer list | 547 This function puts @var{buffer-or-name} at the end of the buffer list |
546 without changing the order of any of the other buffers on the list. | 548 without changing the order of any of the other buffers on the list. |
547 This buffer therefore becomes the least desirable candidate for | 549 This buffer therefore becomes the least desirable candidate for |
548 @code{other-buffer} to return. | 550 @code{other-buffer} to return. |
549 | 551 |
550 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury | 552 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the |
551 the current buffer. In addition, this switches to some other buffer | 553 current buffer. In addition, if the buffer is displayed in the selected |
552 (obtained using @code{other-buffer}) in the selected window. If the | 554 window, this switches to some other buffer (obtained using |
553 buffer is displayed in a window other than the selected one, it remains | 555 @code{other-buffer}) in the selected window. But if the buffer is |
554 there. | 556 displayed in some other window, it remains displayed there. |
555 | 557 |
556 If you wish to replace a buffer in all the windows that display it, use | 558 If you wish to replace a buffer in all the windows that display it, use |
557 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. | 559 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. |
558 @end deffn | 560 @end deffn |
559 | 561 |
561 @section Creating Buffers | 563 @section Creating Buffers |
562 @cindex creating buffers | 564 @cindex creating buffers |
563 @cindex buffers, creating | 565 @cindex buffers, creating |
564 | 566 |
565 This section describes the two primitives for creating buffers. | 567 This section describes the two primitives for creating buffers. |
566 @code{get-buffer-create} creates a buffer if it finds no existing | 568 @code{get-buffer-create} creates a buffer if it finds no existing buffer |
567 buffer; @code{generate-new-buffer} always creates a new buffer, and | 569 with the specified name; @code{generate-new-buffer} always creates a new |
568 gives it a unique name. | 570 buffer and gives it a unique name. |
569 | 571 |
570 Other functions you can use to create buffers include | 572 Other functions you can use to create buffers include |
571 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | 573 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and |
572 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | 574 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a |
573 subprocess can also create a buffer (@pxref{Processes}). | 575 subprocess can also create a buffer (@pxref{Processes}). |
593 | 595 |
594 @defun generate-new-buffer name | 596 @defun generate-new-buffer name |
595 This function returns a newly created, empty buffer, but does not make | 597 This function returns a newly created, empty buffer, but does not make |
596 it current. If there is no buffer named @var{name}, then that is the | 598 it current. If there is no buffer named @var{name}, then that is the |
597 name of the new buffer. If that name is in use, this function adds | 599 name of the new buffer. If that name is in use, this function adds |
598 suffixes of the form @samp{<@var{n}>} are added to @var{name}, where | 600 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an |
599 @var{n} is an integer. It tries successive integers starting with 2 | 601 integer. It tries successive integers starting with 2 until it finds an |
600 until it finds an available name. | 602 available name. |
601 | 603 |
602 An error is signaled if @var{name} is not a string. | 604 An error is signaled if @var{name} is not a string. |
603 | 605 |
604 @example | 606 @example |
605 @group | 607 @group |
627 @section Killing Buffers | 629 @section Killing Buffers |
628 @cindex killing buffers | 630 @cindex killing buffers |
629 @cindex buffers, killing | 631 @cindex buffers, killing |
630 | 632 |
631 @dfn{Killing a buffer} makes its name unknown to Emacs and makes its | 633 @dfn{Killing a buffer} makes its name unknown to Emacs and makes its |
632 space available for other use. | 634 text space available for other use. |
633 | 635 |
634 The buffer object for the buffer which has been killed remains in | 636 The buffer object for the buffer that has been killed remains in |
635 existence as long as anything refers to it, but it is specially marked | 637 existence as long as anything refers to it, but it is specially marked |
636 so that you cannot make it current or display it. Killed buffers retain | 638 so that you cannot make it current or display it. Killed buffers retain |
637 their identity, however; two distinct buffers, when killed, remain | 639 their identity, however; two distinct buffers, when killed, remain |
638 distinct according to @code{eq}. | 640 distinct according to @code{eq}. |
639 | 641 |
731 @code{set-buffer}. The specified buffer remains current until a new one | 733 @code{set-buffer}. The specified buffer remains current until a new one |
732 is designated. | 734 is designated. |
733 | 735 |
734 When an editing command returns to the editor command loop, the | 736 When an editing command returns to the editor command loop, the |
735 command loop designates the buffer displayed in the selected window as | 737 command loop designates the buffer displayed in the selected window as |
736 current, to prevent confusion: the buffer that the cursor is in, when | 738 current, to prevent confusion: the buffer that the cursor is in when |
737 Emacs reads a command, is the one to which the command will apply. | 739 Emacs reads a command is the buffer that the command will apply to. |
738 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to | 740 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to |
739 switch visibly to a different buffer so that the user can edit it. For | 741 switch visibly to a different buffer so that the user can edit it. For |
740 this, you must use the functions described in @ref{Displaying Buffers}. | 742 this, you must use the functions described in @ref{Displaying Buffers}. |
741 | 743 |
742 However, Lisp functions that change to a different current buffer | 744 However, Lisp functions that change to a different current buffer |
786 buffer current at the beginning is current again whenever the variable | 788 buffer current at the beginning is current again whenever the variable |
787 is unbound. | 789 is unbound. |
788 | 790 |
789 It is not reliable to change the current buffer back with | 791 It is not reliable to change the current buffer back with |
790 @code{set-buffer}, because that won't do the job if a quit happens while | 792 @code{set-buffer}, because that won't do the job if a quit happens while |
791 the wrong buffer is current. Here is what not to do: | 793 the wrong buffer is current. Here is what @emph{not} to do: |
792 | 794 |
793 @example | 795 @example |
794 @group | 796 @group |
795 (let (buffer-read-only | 797 (let (buffer-read-only |
796 (obuf (current-buffer))) | 798 (obuf (current-buffer))) |
799 (set-buffer obuf)) | 801 (set-buffer obuf)) |
800 @end group | 802 @end group |
801 @end example | 803 @end example |
802 | 804 |
803 @noindent | 805 @noindent |
804 Using @code{save-excursion}, as shown below, handles quitting, errors | 806 Using @code{save-excursion}, as shown below, handles quitting, errors, |
805 and @code{throw} as well as ordinary evaluation. | 807 and @code{throw}, as well as ordinary evaluation. |
806 | 808 |
807 @example | 809 @example |
808 @group | 810 @group |
809 (let (buffer-read-only) | 811 (let (buffer-read-only) |
810 (save-excursion | 812 (save-excursion |