Mercurial > emacs
annotate lispref/buffers.texi @ 71879:d236eeffa8f7
*** empty log message ***
author | Kim F. Storm <storm@cua.dk> |
---|---|
date | Thu, 13 Jul 2006 22:52:49 +0000 |
parents | 61a3f8c2718c |
children | 61cb5aae3bc3 a5812696f7bf |
rev | line source |
---|---|
6564 | 1 @c -*-texinfo-*- |
2 @c This is part of the GNU Emacs Lisp Reference Manual. | |
64889
e836425ee789
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
64880
diff
changeset
|
3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2003, |
68648
067115a6e738
Update years in copyright notice; nfc.
Thien-Thi Nguyen <ttn@gnuvola.org>
parents:
66139
diff
changeset
|
4 @c 2004, 2005, 2006 Free Software Foundation, Inc. |
6564 | 5 @c See the file elisp.texi for copying conditions. |
6 @setfilename ../info/buffers | |
7 @node Buffers, Windows, Backups and Auto-Saving, Top | |
8 @chapter Buffers | |
9 @cindex buffer | |
10 | |
11 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
12 are used to hold the contents of files that are being visited; there may | |
7677 | 13 also be buffers that are not visiting files. While several buffers may |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
14 exist at one time, only one buffer is designated the @dfn{current |
6564 | 15 buffer} at any time. Most editing commands act on the contents of the |
16 current buffer. Each buffer, including the current buffer, may or may | |
17 not be displayed in any windows. | |
18 | |
19 @menu | |
20 * Buffer Basics:: What is a buffer? | |
12067 | 21 * Current Buffer:: Designating a buffer as current |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
22 so that primitives will access its contents. |
6564 | 23 * Buffer Names:: Accessing and changing buffer names. |
24 * Buffer File Name:: The buffer file name indicates which file is visited. | |
25 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. | |
26 * Modification Time:: Determining whether the visited file was changed | |
27 ``behind Emacs's back''. | |
28 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. | |
29 * The Buffer List:: How to look at all the existing buffers. | |
30 * Creating Buffers:: Functions that create buffers. | |
31 * Killing Buffers:: Buffers exist until explicitly killed. | |
12067 | 32 * Indirect Buffers:: An indirect buffer shares text with some other buffer. |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
33 * Buffer Gap:: The gap in the buffer. |
6564 | 34 @end menu |
35 | |
36 @node Buffer Basics | |
37 @comment node-name, next, previous, up | |
38 @section Buffer Basics | |
39 | |
27193 | 40 @ifnottex |
6564 | 41 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers |
42 are used to hold the contents of files that are being visited; there may | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
43 also be buffers that are not visiting files. Although several buffers |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
44 normally exist, only one buffer is designated the @dfn{current |
6564 | 45 buffer} at any time. Most editing commands act on the contents of the |
46 current buffer. Each buffer, including the current buffer, may or may | |
47 not be displayed in any windows. | |
27193 | 48 @end ifnottex |
6564 | 49 |
12098 | 50 Buffers in Emacs editing are objects that have distinct names and hold |
51 text that can be edited. Buffers appear to Lisp programs as a special | |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
52 data type. You can think of the contents of a buffer as a string that |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
53 you can extend; insertions and deletions may occur in any part of the |
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
54 buffer. @xref{Text}. |
6564 | 55 |
56 A Lisp buffer object contains numerous pieces of information. Some of | |
57 this information is directly accessible to the programmer through | |
7677 | 58 variables, while other information is accessible only through |
6564 | 59 special-purpose functions. For example, the visited file name is |
60 directly accessible through a variable, while the value of point is | |
61 accessible only through a primitive function. | |
62 | |
63 Buffer-specific information that is directly accessible is stored in | |
64 @dfn{buffer-local} variable bindings, which are variable values that are | |
65 effective only in a particular buffer. This feature allows each buffer | |
66 to override the values of certain variables. Most major modes override | |
67 variables such as @code{fill-column} or @code{comment-column} in this | |
68 way. For more information about buffer-local variables and functions | |
69 related to them, see @ref{Buffer-Local Variables}. | |
70 | |
71 For functions and variables related to visiting files in buffers, see | |
72 @ref{Visiting Files} and @ref{Saving Buffers}. For functions and | |
73 variables related to the display of buffers in windows, see | |
74 @ref{Buffers and Windows}. | |
75 | |
76 @defun bufferp object | |
77 This function returns @code{t} if @var{object} is a buffer, | |
78 @code{nil} otherwise. | |
79 @end defun | |
80 | |
12067 | 81 @node Current Buffer |
82 @section The Current Buffer | |
83 @cindex selecting a buffer | |
84 @cindex changing to another buffer | |
85 @cindex current buffer | |
86 | |
87 There are, in general, many buffers in an Emacs session. At any time, | |
88 one of them is designated as the @dfn{current buffer}. This is the | |
89 buffer in which most editing takes place, because most of the primitives | |
90 for examining or changing text in a buffer operate implicitly on the | |
91 current buffer (@pxref{Text}). Normally the buffer that is displayed on | |
92 the screen in the selected window is the current buffer, but this is not | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
93 always so: a Lisp program can temporarily designate any buffer as |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
94 current in order to operate on its contents, without changing what is |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
95 displayed on the screen. |
12067 | 96 |
97 The way to designate a current buffer in a Lisp program is by calling | |
98 @code{set-buffer}. The specified buffer remains current until a new one | |
99 is designated. | |
100 | |
101 When an editing command returns to the editor command loop, the | |
102 command loop designates the buffer displayed in the selected window as | |
103 current, to prevent confusion: the buffer that the cursor is in when | |
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 | |
106 switch visibly to a different buffer so that the user can edit it. For | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
107 that, you must use the functions described in @ref{Displaying Buffers}. |
12067 | 108 |
52626 | 109 @strong{Warning:} Lisp functions that change to a different current buffer |
12067 | 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 | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
112 as well as from the command loop; it is convenient for the caller if |
12067 | 113 the subroutine does not change which buffer is current (unless, of |
114 course, that is the subroutine's purpose). Therefore, you should | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
115 normally use @code{set-buffer} within a @code{save-current-buffer} or |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
116 @code{save-excursion} (@pxref{Excursions}) form that will restore the |
22138
d4ac295a98b3
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21682
diff
changeset
|
117 current buffer when your function is done. Here is an example, the |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
118 code for the command @code{append-to-buffer} (with the documentation |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
119 string abridged): |
12067 | 120 |
121 @example | |
122 @group | |
123 (defun append-to-buffer (buffer start end) | |
124 "Append to specified buffer the text of the region. | |
125 @dots{}" | |
126 (interactive "BAppend to buffer: \nr") | |
127 (let ((oldbuf (current-buffer))) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
128 (save-current-buffer |
12067 | 129 (set-buffer (get-buffer-create buffer)) |
130 (insert-buffer-substring oldbuf start end)))) | |
131 @end group | |
132 @end example | |
133 | |
134 @noindent | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
135 This function binds a local variable to record the current buffer, and |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
136 then @code{save-current-buffer} arranges to make it current again. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
137 Next, @code{set-buffer} makes the specified buffer current. Finally, |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
138 @code{insert-buffer-substring} copies the string from the original |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
139 current buffer to the specified (and now current) buffer. |
12067 | 140 |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
141 If the buffer appended to happens to be displayed in some window, |
12067 | 142 the next redisplay will show how its text has changed. Otherwise, you |
143 will not see the change immediately on the screen. The buffer becomes | |
144 current temporarily during the execution of the command, but this does | |
145 not cause it to be displayed. | |
146 | |
147 If you make local bindings (with @code{let} or function arguments) for | |
148 a variable that may also have buffer-local bindings, make sure that the | |
149 same buffer is current at the beginning and at the end of the local | |
150 binding's scope. Otherwise you might bind it in one buffer and unbind | |
151 it in another! There are two ways to do this. In simple cases, you may | |
152 see that nothing ever changes the current buffer within the scope of the | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
153 binding. Otherwise, use @code{save-current-buffer} or |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
154 @code{save-excursion} to make sure that the buffer current at the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
155 beginning is current again whenever the variable is unbound. |
12067 | 156 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
157 Do not rely on using @code{set-buffer} to change the current buffer |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
158 back, because that won't do the job if a quit happens while the wrong |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
159 buffer is current. Here is what @emph{not} to do: |
12067 | 160 |
161 @example | |
162 @group | |
163 (let (buffer-read-only | |
164 (obuf (current-buffer))) | |
165 (set-buffer @dots{}) | |
166 @dots{} | |
167 (set-buffer obuf)) | |
168 @end group | |
169 @end example | |
170 | |
171 @noindent | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
172 Using @code{save-current-buffer}, as shown here, handles quitting, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
173 errors, and @code{throw}, as well as ordinary evaluation. |
12067 | 174 |
175 @example | |
176 @group | |
177 (let (buffer-read-only) | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
178 (save-current-buffer |
12067 | 179 (set-buffer @dots{}) |
180 @dots{})) | |
181 @end group | |
182 @end example | |
183 | |
184 @defun current-buffer | |
185 This function returns the current buffer. | |
186 | |
187 @example | |
188 @group | |
189 (current-buffer) | |
190 @result{} #<buffer buffers.texi> | |
191 @end group | |
192 @end example | |
193 @end defun | |
194 | |
195 @defun set-buffer buffer-or-name | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
196 This function makes @var{buffer-or-name} the current buffer. This does |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
197 not display the buffer in any window, so the user cannot necessarily see |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
198 the buffer. But Lisp programs will now operate on it. |
12067 | 199 |
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 | |
202 existing buffer. | |
203 @end defun | |
204 | |
66139
50ae7c160214
(Current Buffer): Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
Juri Linkov <juri@jurta.org>
parents:
65051
diff
changeset
|
205 @defspec save-current-buffer body@dots{} |
49676
5d28b76b587c
(Current Buffer): Describe `save-current-buffer' as a special form, not a macro.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
206 The @code{save-current-buffer} special form saves the identity of the |
5d28b76b587c
(Current Buffer): Describe `save-current-buffer' as a special form, not a macro.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
207 current buffer, evaluates the @var{body} forms, and finally restores |
5d28b76b587c
(Current Buffer): Describe `save-current-buffer' as a special form, not a macro.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
208 that buffer as current. The return value is the value of the last |
5d28b76b587c
(Current Buffer): Describe `save-current-buffer' as a special form, not a macro.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
209 form in @var{body}. The current buffer is restored even in case of an |
5d28b76b587c
(Current Buffer): Describe `save-current-buffer' as a special form, not a macro.
Juanma Barranquero <lekktu@gmail.com>
parents:
49600
diff
changeset
|
210 abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
211 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
212 If the buffer that used to be current has been killed by the time of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
213 exit from @code{save-current-buffer}, then it is not made current again, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
214 of course. Instead, whichever buffer was current just before exit |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
215 remains current. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
216 @end defspec |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
217 |
66139
50ae7c160214
(Current Buffer): Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
Juri Linkov <juri@jurta.org>
parents:
65051
diff
changeset
|
218 @defmac with-current-buffer buffer-or-name body@dots{} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
219 The @code{with-current-buffer} macro saves the identity of the current |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
220 buffer, makes @var{buffer-or-name} current, evaluates the @var{body} |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
221 forms, and finally restores the buffer. The return value is the value |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
222 of the last form in @var{body}. The current buffer is restored even |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
223 in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
224 Exits}). |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
225 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
226 An error is signaled if @var{buffer-or-name} does not identify an |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
227 existing buffer. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
228 @end defmac |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
229 |
66139
50ae7c160214
(Current Buffer): Replace `...' with `@dots{}' in `@defmac' and `@defspec'.
Juri Linkov <juri@jurta.org>
parents:
65051
diff
changeset
|
230 @defmac with-temp-buffer body@dots{} |
53452 | 231 @anchor{Definition of with-temp-buffer} |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
232 The @code{with-temp-buffer} macro evaluates the @var{body} forms |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
233 with a temporary buffer as the current buffer. It saves the identity of |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
234 the current buffer, creates a temporary buffer and makes it current, |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
235 evaluates the @var{body} forms, and finally restores the previous |
70642
3204a9fa48e4
(Current Buffer): Document that with-temp-buffer disables undo.
Eli Zaretskii <eliz@gnu.org>
parents:
70627
diff
changeset
|
236 current buffer while killing the temporary buffer. By default, undo |
3204a9fa48e4
(Current Buffer): Document that with-temp-buffer disables undo.
Eli Zaretskii <eliz@gnu.org>
parents:
70627
diff
changeset
|
237 information (@pxref{Undo}) is not recorded in the buffer created by |
3204a9fa48e4
(Current Buffer): Document that with-temp-buffer disables undo.
Eli Zaretskii <eliz@gnu.org>
parents:
70627
diff
changeset
|
238 this macro (but @var{body} can enable that, if needed). |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
239 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
240 The return value is the value of the last form in @var{body}. You can |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
241 return the contents of the temporary buffer by using |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
242 @code{(buffer-string)} as the last form. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
243 |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
244 The current buffer is restored even in case of an abnormal exit via |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
245 @code{throw} or error (@pxref{Nonlocal Exits}). |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
246 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
247 See also @code{with-temp-file} in @ref{Definition of with-temp-file,, |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
248 Writing to Files}. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
249 @end defmac |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
250 |
6564 | 251 @node Buffer Names |
252 @section Buffer Names | |
253 @cindex buffer names | |
254 | |
255 Each buffer has a unique name, which is a string. Many of the | |
256 functions that work on buffers accept either a buffer or a buffer name | |
257 as an argument. Any argument called @var{buffer-or-name} is of this | |
258 sort, and an error is signaled if it is neither a string nor a buffer. | |
259 Any argument called @var{buffer} must be an actual buffer | |
260 object, not a name. | |
261 | |
70627
61cffb1025d1
(Buffer Names): Add index entries for buffers whose names begin with a space.
Eli Zaretskii <eliz@gnu.org>
parents:
68648
diff
changeset
|
262 @cindex hidden buffers |
61cffb1025d1
(Buffer Names): Add index entries for buffers whose names begin with a space.
Eli Zaretskii <eliz@gnu.org>
parents:
68648
diff
changeset
|
263 @cindex buffers without undo information |
6564 | 264 Buffers that are ephemeral and generally uninteresting to the user |
12098 | 265 have names starting with a space, so that the @code{list-buffers} and |
40492
93b1df487abe
(Buffer Names): Buffers whose names start with a space, but which visit
Eli Zaretskii <eliz@gnu.org>
parents:
39403
diff
changeset
|
266 @code{buffer-menu} commands don't mention them (but if such a buffer |
93b1df487abe
(Buffer Names): Buffers whose names start with a space, but which visit
Eli Zaretskii <eliz@gnu.org>
parents:
39403
diff
changeset
|
267 visits a file, it @strong{is} mentioned). A name starting with |
6564 | 268 space also initially disables recording undo information; see |
269 @ref{Undo}. | |
270 | |
271 @defun buffer-name &optional buffer | |
272 This function returns the name of @var{buffer} as a string. If | |
273 @var{buffer} is not supplied, it defaults to the current buffer. | |
274 | |
275 If @code{buffer-name} returns @code{nil}, it means that @var{buffer} | |
276 has been killed. @xref{Killing Buffers}. | |
277 | |
278 @example | |
279 @group | |
280 (buffer-name) | |
281 @result{} "buffers.texi" | |
282 @end group | |
283 | |
284 @group | |
285 (setq foo (get-buffer "temp")) | |
286 @result{} #<buffer temp> | |
287 @end group | |
288 @group | |
289 (kill-buffer foo) | |
290 @result{} nil | |
291 @end group | |
292 @group | |
293 (buffer-name foo) | |
294 @result{} nil | |
295 @end group | |
296 @group | |
297 foo | |
298 @result{} #<killed buffer> | |
299 @end group | |
300 @end example | |
301 @end defun | |
302 | |
303 @deffn Command rename-buffer newname &optional unique | |
304 This function renames the current buffer to @var{newname}. An error | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
305 is signaled if @var{newname} is not a string. |
6564 | 306 |
307 @c Emacs 19 feature | |
308 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | |
309 already in use. However, if @var{unique} is non-@code{nil}, it modifies | |
310 @var{newname} to make a name that is not in use. Interactively, you can | |
311 make @var{unique} non-@code{nil} with a numeric prefix argument. | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
312 (This is how the command @code{rename-uniquely} is implemented.) |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
313 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
314 This function returns the name actually given to the buffer. |
6564 | 315 @end deffn |
316 | |
317 @defun get-buffer buffer-or-name | |
318 This function returns the buffer specified by @var{buffer-or-name}. | |
319 If @var{buffer-or-name} is a string and there is no buffer with that | |
320 name, the value is @code{nil}. If @var{buffer-or-name} is a buffer, it | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
321 is returned as given; that is not very useful, so the argument is usually |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
322 a name. For example: |
6564 | 323 |
324 @example | |
325 @group | |
326 (setq b (get-buffer "lewis")) | |
327 @result{} #<buffer lewis> | |
328 @end group | |
329 @group | |
330 (get-buffer b) | |
331 @result{} #<buffer lewis> | |
332 @end group | |
333 @group | |
334 (get-buffer "Frazzle-nots") | |
335 @result{} nil | |
336 @end group | |
337 @end example | |
338 | |
339 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | |
340 @end defun | |
341 | |
342 @c Emacs 19 feature | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
343 @defun generate-new-buffer-name starting-name &optional ignore |
6564 | 344 This function returns a name that would be unique for a new buffer---but |
345 does not create the buffer. It starts with @var{starting-name}, and | |
346 produces a name not currently in use for any buffer by appending a | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
347 number inside of @samp{<@dots{}>}. It starts at 2 and keeps |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
348 incrementing the number until it is not the name of an existing buffer. |
6564 | 349 |
26239 | 350 If the optional second argument @var{ignore} is non-@code{nil}, it |
59874
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
351 should be a string, a potential buffer name. It means to consider |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
352 that potential buffer acceptable, if it is tried, even it is the name |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
353 of an existing buffer (which would normally be rejected). Thus, if |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
354 buffers named @samp{foo}, @samp{foo<2>}, @samp{foo<3>} and |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
355 @samp{foo<4>} exist, |
27301
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
356 |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
357 @example |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
358 (generate-new-buffer-name "foo") |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
359 @result{} "foo<5>" |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
360 (generate-new-buffer-name "foo" "foo<3>") |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
361 @result{} "foo<3>" |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
362 (generate-new-buffer-name "foo" "foo<6>") |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
363 @result{} "foo<5>" |
8c79b30d8475
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
27193
diff
changeset
|
364 @end example |
26239 | 365 |
6564 | 366 See the related function @code{generate-new-buffer} in @ref{Creating |
367 Buffers}. | |
368 @end defun | |
369 | |
370 @node Buffer File Name | |
371 @section Buffer File Name | |
372 @cindex visited file | |
373 @cindex buffer file name | |
374 @cindex file name of buffer | |
375 | |
376 The @dfn{buffer file name} is the name of the file that is visited in | |
377 that buffer. When a buffer is not visiting a file, its buffer file name | |
378 is @code{nil}. Most of the time, the buffer name is the same as the | |
379 nondirectory part of the buffer file name, but the buffer file name and | |
380 the buffer name are distinct and can be set independently. | |
381 @xref{Visiting Files}. | |
382 | |
383 @defun buffer-file-name &optional buffer | |
384 This function returns the absolute file name of the file that | |
385 @var{buffer} is visiting. If @var{buffer} is not visiting any file, | |
386 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not | |
387 supplied, it defaults to the current buffer. | |
388 | |
389 @example | |
390 @group | |
391 (buffer-file-name (other-buffer)) | |
392 @result{} "/usr/user/lewis/manual/files.texi" | |
393 @end group | |
394 @end example | |
395 @end defun | |
396 | |
397 @defvar buffer-file-name | |
398 This buffer-local variable contains the name of the file being visited | |
399 in the current buffer, or @code{nil} if it is not visiting a file. It | |
25950
7996385fc601
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
400 is a permanent local variable, unaffected by |
7996385fc601
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
401 @code{kill-all-local-variables}. |
6564 | 402 |
403 @example | |
404 @group | |
405 buffer-file-name | |
406 @result{} "/usr/user/lewis/manual/buffers.texi" | |
407 @end group | |
408 @end example | |
409 | |
410 It is risky to change this variable's value without doing various other | |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
411 things. Normally it is better to use @code{set-visited-file-name} (see |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
412 below); some of the things done there, such as changing the buffer name, |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
413 are not strictly necessary, but others are essential to avoid confusing |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
414 Emacs. |
6564 | 415 @end defvar |
416 | |
417 @defvar buffer-file-truename | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
418 This buffer-local variable holds the abbreviated truename of the file |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
419 visited in the current buffer, or @code{nil} if no file is visited. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
420 It is a permanent local, unaffected by |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
421 @code{kill-all-local-variables}. @xref{Truenames}, and |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
422 @ref{Definition of abbreviate-file-name}. |
6564 | 423 @end defvar |
424 | |
425 @defvar buffer-file-number | |
426 This buffer-local variable holds the file number and directory device | |
427 number of the file visited in the current buffer, or @code{nil} if no | |
428 file or a nonexistent file is visited. It is a permanent local, | |
25950
7996385fc601
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
25751
diff
changeset
|
429 unaffected by @code{kill-all-local-variables}. |
6564 | 430 |
431 The value is normally a list of the form @code{(@var{filenum} | |
432 @var{devnum})}. This pair of numbers uniquely identifies the file among | |
433 all files accessible on the system. See the function | |
434 @code{file-attributes}, in @ref{File Attributes}, for more information | |
435 about them. | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
436 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
437 If @code{buffer-file-name} is the name of a symbolic link, then both |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
438 numbers refer to the recursive target. |
6564 | 439 @end defvar |
440 | |
441 @defun get-file-buffer filename | |
442 This function returns the buffer visiting file @var{filename}. If | |
443 there is no such buffer, it returns @code{nil}. The argument | |
444 @var{filename}, which must be a string, is expanded (@pxref{File Name | |
445 Expansion}), then compared against the visited file names of all live | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
446 buffers. Note that the buffer's @code{buffer-file-name} must match |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
447 the expansion of @var{filename} exactly. This function will not |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
448 recognize other names for the same file. |
6564 | 449 |
450 @example | |
451 @group | |
452 (get-file-buffer "buffers.texi") | |
453 @result{} #<buffer buffers.texi> | |
454 @end group | |
455 @end example | |
456 | |
457 In unusual circumstances, there can be more than one buffer visiting | |
458 the same file name. In such cases, this function returns the first | |
459 such buffer in the buffer list. | |
460 @end defun | |
461 | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
462 @defun find-buffer-visiting filename &optional predicate |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
463 This is like @code{get-file-buffer}, except that it can return any |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
464 buffer visiting the file @emph{possibly under a different name}. That |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
465 is, the buffer's @code{buffer-file-name} does not need to match the |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
466 expansion of @var{filename} exactly, it only needs to refer to the |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
467 same file. If @var{predicate} is non-@code{nil}, it should be a |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
468 function of one argument, a buffer visiting @var{filename}. The |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
469 buffer is only considered a suitable return value if @var{predicate} |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
470 returns non-@code{nil}. If it can not find a suitable buffer to |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
471 return, @code{find-buffer-visiting} returns @code{nil}. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
472 @end defun |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
473 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
474 @deffn Command set-visited-file-name filename &optional no-query along-with-file |
6564 | 475 If @var{filename} is a non-empty string, this function changes the |
26239 | 476 name of the file visited in the current buffer to @var{filename}. (If the |
6564 | 477 buffer had no visited file, this gives it one.) The @emph{next time} |
52137
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
478 the buffer is saved it will go in the newly-specified file. |
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
479 |
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
480 This command marks the buffer as modified, since it does not (as far |
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
481 as Emacs knows) match the contents of @var{filename}, even if it |
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
482 matched the former visited file. It also renames the buffer to |
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
483 correspond to the new file name, unless the new name is already in |
3c3abdef580e
(Buffer File Name): set-visited-file-name renames the buffer too.
Richard M. Stallman <rms@gnu.org>
parents:
51925
diff
changeset
|
484 use. |
6564 | 485 |
486 If @var{filename} is @code{nil} or the empty string, that stands for | |
487 ``no visited file''. In this case, @code{set-visited-file-name} marks | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
488 the buffer as having no visited file, without changing the buffer's |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
489 modified flag. |
6564 | 490 |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
491 Normally, this function asks the user for confirmation if there |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
492 already is a buffer visiting @var{filename}. If @var{no-query} is |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
493 non-@code{nil}, that prevents asking this question. If there already |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
494 is a buffer visiting @var{filename}, and the user confirms or |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
495 @var{query} is non-@code{nil}, this function makes the new buffer name |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
496 unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
497 |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
498 If @var{along-with-file} is non-@code{nil}, that means to assume that |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
499 the former visited file has been renamed to @var{filename}. In this |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
500 case, the command does not change the buffer's modified flag, nor the |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
501 buffer's recorded last file modification time as reported by |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
502 @code{visited-file-modtime} (@pxref{Modification Time}). If |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
503 @var{along-with-file} is @code{nil}, this function clears the recorded |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
504 last file modification time, after which @code{visited-file-modtime} |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
505 returns zero. |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
506 |
6564 | 507 @c Wordy to avoid overfull hbox. --rjc 16mar92 |
508 When the function @code{set-visited-file-name} is called interactively, it | |
509 prompts for @var{filename} in the minibuffer. | |
510 @end deffn | |
511 | |
512 @defvar list-buffers-directory | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
513 This buffer-local variable specifies a string to display in a buffer |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
514 listing where the visited file name would go, for buffers that don't |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
515 have a visited file name. Dired buffers use this variable. |
6564 | 516 @end defvar |
517 | |
518 @node Buffer Modification | |
519 @section Buffer Modification | |
520 @cindex buffer modification | |
521 @cindex modification flag (of buffer) | |
522 | |
523 Emacs keeps a flag called the @dfn{modified flag} for each buffer, to | |
524 record whether you have changed the text of the buffer. This flag is | |
525 set to @code{t} whenever you alter the contents of the buffer, and | |
526 cleared to @code{nil} when you save it. Thus, the flag shows whether | |
527 there are unsaved changes. The flag value is normally shown in the mode | |
528 line (@pxref{Mode Line Variables}), and controls saving (@pxref{Saving | |
529 Buffers}) and auto-saving (@pxref{Auto-Saving}). | |
530 | |
531 Some Lisp programs set the flag explicitly. For example, the function | |
532 @code{set-visited-file-name} sets the flag to @code{t}, because the text | |
533 does not match the newly-visited file, even if it is unchanged from the | |
534 file formerly visited. | |
535 | |
536 The functions that modify the contents of buffers are described in | |
537 @ref{Text}. | |
538 | |
539 @defun buffer-modified-p &optional buffer | |
540 This function returns @code{t} if the buffer @var{buffer} has been modified | |
541 since it was last read in from a file or saved, or @code{nil} | |
542 otherwise. If @var{buffer} is not supplied, the current buffer | |
543 is tested. | |
544 @end defun | |
545 | |
546 @defun set-buffer-modified-p flag | |
547 This function marks the current buffer as modified if @var{flag} is | |
548 non-@code{nil}, or as unmodified if the flag is @code{nil}. | |
549 | |
550 Another effect of calling this function is to cause unconditional | |
551 redisplay of the mode line for the current buffer. In fact, the | |
552 function @code{force-mode-line-update} works by doing this: | |
553 | |
554 @example | |
555 @group | |
556 (set-buffer-modified-p (buffer-modified-p)) | |
557 @end group | |
558 @end example | |
559 @end defun | |
560 | |
53421
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
561 @defun restore-buffer-modified-p flag |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
562 Like @code{set-buffer-modified-p}, but does not force redisplay |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
563 of mode lines. |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
564 @end defun |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
565 |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
566 @deffn Command not-modified &optional arg |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
567 This command marks the current buffer as unmodified, and not needing |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
568 to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
569 modified, so that it will be saved at the next suitable occasion. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
570 Interactively, @var{arg} is the prefix argument. |
13229 | 571 |
572 Don't use this function in programs, since it prints a message in the | |
573 echo area; use @code{set-buffer-modified-p} (above) instead. | |
6564 | 574 @end deffn |
575 | |
576 @c Emacs 19 feature | |
577 @defun buffer-modified-tick &optional buffer | |
13229 | 578 This function returns @var{buffer}'s modification-count. This is a |
6564 | 579 counter that increments every time the buffer is modified. If |
580 @var{buffer} is @code{nil} (or omitted), the current buffer is used. | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
581 The counter can wrap around occasionally. |
6564 | 582 @end defun |
583 | |
584 @node Modification Time | |
585 @comment node-name, next, previous, up | |
586 @section Comparison of Modification Time | |
587 @cindex comparison of modification time | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
588 @cindex modification time, comparison of |
6564 | 589 |
590 Suppose that you visit a file and make changes in its buffer, and | |
591 meanwhile the file itself is changed on disk. At this point, saving the | |
592 buffer would overwrite the changes in the file. Occasionally this may | |
593 be what you want, but usually it would lose valuable information. Emacs | |
594 therefore checks the file's modification time using the functions | |
595 described below before saving the file. | |
596 | |
597 @defun verify-visited-file-modtime buffer | |
598 This function compares what @var{buffer} has recorded for the | |
599 modification time of its visited file against the actual modification | |
600 time of the file as recorded by the operating system. The two should be | |
601 the same unless some other process has written the file since Emacs | |
602 visited or saved it. | |
603 | |
604 The function returns @code{t} if the last actual modification time and | |
605 Emacs's recorded modification time are the same, @code{nil} otherwise. | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
606 It also returns @code{t} if the buffer has no recorded last |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
607 modification time, that is if @code{visited-file-modtime} would return |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
608 zero. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
609 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
610 It always returns @code{t} for buffers that are not visiting a file, |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
611 even if @code{visited-file-modtime} returns a non-zero value. For |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
612 instance, it always returns @code{t} for dired buffers. It returns |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
613 @code{t} for buffers that are visiting a file that does not exist and |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
614 never existed, but @code{nil} for file-visiting buffers whose file has |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
615 been deleted. |
6564 | 616 @end defun |
617 | |
618 @defun clear-visited-file-modtime | |
619 This function clears out the record of the last modification time of | |
620 the file being visited by the current buffer. As a result, the next | |
621 attempt to save this buffer will not complain of a discrepancy in | |
622 file modification times. | |
623 | |
624 This function is called in @code{set-visited-file-name} and other | |
625 exceptional places where the usual test to avoid overwriting a changed | |
626 file should not be done. | |
627 @end defun | |
628 | |
629 @c Emacs 19 feature | |
630 @defun visited-file-modtime | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
631 This function returns the current buffer's recorded last file |
56427
55836d23d2c9
(Modification Time): `visited-file-modtime' now
Luc Teirlinck <teirllm@auburn.edu>
parents:
56215
diff
changeset
|
632 modification time, as a list of the form @code{(@var{high} @var{low})}. |
55836d23d2c9
(Modification Time): `visited-file-modtime' now
Luc Teirlinck <teirllm@auburn.edu>
parents:
56215
diff
changeset
|
633 (This is the same format that @code{file-attributes} uses to return |
55836d23d2c9
(Modification Time): `visited-file-modtime' now
Luc Teirlinck <teirllm@auburn.edu>
parents:
56215
diff
changeset
|
634 time values; see @ref{File Attributes}.) |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
635 |
59874
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
636 If the buffer has no recorded last modification time, this function |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
637 returns zero. This case occurs, for instance, if the buffer is not |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
638 visiting a file or if the time has been explicitly cleared by |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
639 @code{clear-visited-file-modtime}. Note, however, that |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
640 @code{visited-file-modtime} returns a list for some non-file buffers |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
641 too. For instance, in a Dired buffer listing a directory, it returns |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
642 the last modification time of that directory, as recorded by Dired. |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
643 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
644 For a new buffer visiting a not yet existing file, @var{high} is |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
645 @minus{}1 and @var{low} is 65535, that is, |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
646 @ifnottex |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
647 @w{2**16 - 1.} |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
648 @end ifnottex |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
649 @tex |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
650 @math{2^{16}-1}. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
651 @end tex |
6564 | 652 @end defun |
653 | |
654 @c Emacs 19 feature | |
655 @defun set-visited-file-modtime &optional time | |
656 This function updates the buffer's record of the last modification time | |
657 of the visited file, to the value specified by @var{time} if @var{time} | |
658 is not @code{nil}, and otherwise to the last modification time of the | |
659 visited file. | |
660 | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
661 If @var{time} is neither @code{nil} nor zero, it should have the form |
6564 | 662 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in |
663 either case containing two integers, each of which holds 16 bits of the | |
664 time. | |
665 | |
666 This function is useful if the buffer was not read from the file | |
667 normally, or if the file itself has been changed for some known benign | |
668 reason. | |
669 @end defun | |
670 | |
7677 | 671 @defun ask-user-about-supersession-threat filename |
6564 | 672 @cindex obsolete buffer |
673 This function is used to ask a user how to proceed after an attempt to | |
7677 | 674 modify an obsolete buffer visiting file @var{filename}. An |
675 @dfn{obsolete buffer} is an unmodified buffer for which the associated | |
676 file on disk is newer than the last save-time of the buffer. This means | |
677 some other program has probably altered the file. | |
678 | |
679 @kindex file-supersession | |
680 Depending on the user's answer, the function may return normally, in | |
681 which case the modification of the buffer proceeds, or it may signal a | |
682 @code{file-supersession} error with data @code{(@var{filename})}, in which | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
683 case the proposed buffer modification is not allowed. |
6564 | 684 |
685 This function is called automatically by Emacs on the proper | |
686 occasions. It exists so you can customize Emacs by redefining it. | |
687 See the file @file{userlock.el} for the standard definition. | |
688 | |
689 See also the file locking mechanism in @ref{File Locks}. | |
690 @end defun | |
691 | |
692 @node Read Only Buffers | |
693 @section Read-Only Buffers | |
694 @cindex read-only buffer | |
695 @cindex buffer, read-only | |
696 | |
697 If a buffer is @dfn{read-only}, then you cannot change its contents, | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
698 although you may change your view of the contents by scrolling and |
6564 | 699 narrowing. |
700 | |
701 Read-only buffers are used in two kinds of situations: | |
702 | |
703 @itemize @bullet | |
704 @item | |
705 A buffer visiting a write-protected file is normally read-only. | |
706 | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
707 Here, the purpose is to inform the user that editing the buffer with the |
6564 | 708 aim of saving it in the file may be futile or undesirable. The user who |
709 wants to change the buffer text despite this can do so after clearing | |
12098 | 710 the read-only flag with @kbd{C-x C-q}. |
6564 | 711 |
712 @item | |
713 Modes such as Dired and Rmail make buffers read-only when altering the | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
714 contents with the usual editing commands would probably be a mistake. |
6564 | 715 |
716 The special commands of these modes bind @code{buffer-read-only} to | |
717 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
718 @code{t} around the places where they themselves change the text. |
6564 | 719 @end itemize |
720 | |
721 @defvar buffer-read-only | |
722 This buffer-local variable specifies whether the buffer is read-only. | |
723 The buffer is read-only if this variable is non-@code{nil}. | |
724 @end defvar | |
725 | |
726 @defvar inhibit-read-only | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
727 If this variable is non-@code{nil}, then read-only buffers and, |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
728 depending on the actual value, some or all read-only characters may be |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
729 modified. Read-only characters in a buffer are those that have |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
730 non-@code{nil} @code{read-only} properties (either text properties or |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
731 overlay properties). @xref{Special Properties}, for more information |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
732 about text properties. @xref{Overlays}, for more information about |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
733 overlays and their properties. |
6564 | 734 |
7677 | 735 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character |
736 properties have no effect. If @code{inhibit-read-only} is a list, then | |
737 @code{read-only} character properties have no effect if they are members | |
738 of the list (comparison is done with @code{eq}). | |
6564 | 739 @end defvar |
740 | |
54893
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
741 @deffn Command toggle-read-only &optional arg |
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
742 This command toggles whether the current buffer is read-only. It is |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
743 intended for interactive use; do not use it in programs. At any given |
6564 | 744 point in a program, you should know whether you want the read-only flag |
745 on or off; so you can set @code{buffer-read-only} explicitly to the | |
746 proper value, @code{t} or @code{nil}. | |
54893
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
747 |
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
748 If @var{arg} is non-@code{nil}, it should be a raw prefix argument. |
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
749 @code{toggle-read-only} sets @code{buffer-read-only} to @code{t} if |
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
750 the numeric value of that prefix argument is positive and to |
07ceecd3e471
(Read Only Buffers): Mention optional ARG to `toggle-read-only'.
Luc Teirlinck <teirllm@auburn.edu>
parents:
54862
diff
changeset
|
751 @code{nil} otherwise. @xref{Prefix Command Arguments}. |
6564 | 752 @end deffn |
753 | |
754 @defun barf-if-buffer-read-only | |
755 This function signals a @code{buffer-read-only} error if the current | |
54019 | 756 buffer is read-only. @xref{Using Interactive}, for another way to |
6564 | 757 signal an error if the current buffer is read-only. |
758 @end defun | |
759 | |
760 @node The Buffer List | |
761 @section The Buffer List | |
762 @cindex buffer list | |
763 | |
65051
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
764 The @dfn{buffer list} is a list of all live buffers. The order of |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
765 the buffers in the list is based primarily on how recently each buffer |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
766 has been displayed in a window. Several functions, notably |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
767 @code{other-buffer}, use this ordering. A buffer list displayed for |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
768 the user also follows this order. |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
769 |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
770 Creating a buffer adds it to the end of the buffer list, and killing |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
771 a buffer removes it. Buffers move to the front of the list when they |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
772 are selected for display in a window (@pxref{Displaying Buffers}), and |
50466
e4180f608731
Clarify when buffer list is reordered.
Richard M. Stallman <rms@gnu.org>
parents:
49676
diff
changeset
|
773 to the end when they are buried (see @code{bury-buffer}, below). |
65051
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
774 There are no functions available to the Lisp programmer which directly |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
775 manipulate the buffer list. |
a1cc73fd8161
(The Buffer List): Clarify the manipulation of the buffer list.
Eli Zaretskii <eliz@gnu.org>
parents:
64889
diff
changeset
|
776 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
777 In addition to the fundamental Emacs buffer list, each frame has its |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
778 own version of the buffer list, in which the buffers that have been |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
779 selected in that frame come first, starting with the buffers most |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
780 recently selected @emph{in that frame}. (This order is recorded in |
64880
5953197750ce
(The Buffer List): Fix xrefs.
Richard M. Stallman <rms@gnu.org>
parents:
61596
diff
changeset
|
781 @var{frame}'s @code{buffer-list} frame parameter; see @ref{Buffer |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
782 Parameters}.) The buffers that were never selected in @var{frame} come |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
783 afterward, ordered according to the fundamental Emacs buffer list. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
784 |
21682
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
785 @defun buffer-list &optional frame |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
786 This function returns the buffer list, including all buffers, even those |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
787 whose names begin with a space. The elements are actual buffers, not |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
788 their names. |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
789 |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
790 If @var{frame} is a frame, this returns @var{frame}'s buffer list. If |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
791 @var{frame} is @code{nil}, the fundamental Emacs buffer list is used: |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
792 all the buffers appear in order of most recent selection, regardless of |
90da2489c498
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
21007
diff
changeset
|
793 which frames they were selected in. |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
794 |
6564 | 795 @example |
796 @group | |
797 (buffer-list) | |
798 @result{} (#<buffer buffers.texi> | |
799 #<buffer *Minibuf-1*> #<buffer buffer.c> | |
800 #<buffer *Help*> #<buffer TAGS>) | |
801 @end group | |
802 | |
803 @group | |
804 ;; @r{Note that the name of the minibuffer} | |
805 ;; @r{begins with a space!} | |
806 (mapcar (function buffer-name) (buffer-list)) | |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
807 @result{} ("buffers.texi" " *Minibuf-1*" |
6564 | 808 "buffer.c" "*Help*" "TAGS") |
809 @end group | |
810 @end example | |
15862
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
811 @end defun |
6564 | 812 |
15862
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
813 The list that @code{buffer-list} returns is constructed specifically |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
814 by @code{buffer-list}; it is not an internal Emacs data structure, and |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
815 modifying it has no effect on the order of buffers. If you want to |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
816 change the order of buffers in the frame-independent buffer list, here |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
817 is an easy way: |
15862
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
818 |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
819 @example |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
820 (defun reorder-buffer-list (new-list) |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
821 (while new-list |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
822 (bury-buffer (car new-list)) |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
823 (setq new-list (cdr new-list)))) |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
824 @end example |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
825 |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
826 With this method, you can specify any order for the list, but there is |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
827 no danger of losing a buffer or adding something that is not a valid |
d0a061b594a1
Show how to reorder buffers.
Richard M. Stallman <rms@gnu.org>
parents:
13247
diff
changeset
|
828 live buffer. |
6564 | 829 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
830 To change the order or value of a frame's buffer list, set the frame's |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
831 @code{buffer-list} frame parameter with @code{modify-frame-parameters} |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
832 (@pxref{Parameter Access}). |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
833 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
834 @defun other-buffer &optional buffer visible-ok frame |
6564 | 835 This function returns the first buffer in the buffer list other than |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
836 @var{buffer}. Usually this is the buffer selected most recently (in |
39403
f242022750ee
(The Buffer List): Add cross-references to the definition of selected frame.
Eli Zaretskii <eliz@gnu.org>
parents:
27301
diff
changeset
|
837 frame @var{frame} or else the currently selected frame, @pxref{Input |
f242022750ee
(The Buffer List): Add cross-references to the definition of selected frame.
Eli Zaretskii <eliz@gnu.org>
parents:
27301
diff
changeset
|
838 Focus}), aside from @var{buffer}. Buffers whose names start with a |
f242022750ee
(The Buffer List): Add cross-references to the definition of selected frame.
Eli Zaretskii <eliz@gnu.org>
parents:
27301
diff
changeset
|
839 space are not considered at all. |
6564 | 840 |
13247
750f4d22537f
Arg of other-buffer can't be a buffer name.
Richard M. Stallman <rms@gnu.org>
parents:
13229
diff
changeset
|
841 If @var{buffer} is not supplied (or if it is not a buffer), then |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
842 @code{other-buffer} returns the first buffer in the selected frame's |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
843 buffer list that is not now visible in any window in a visible frame. |
6564 | 844 |
22252
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
845 If @var{frame} has a non-@code{nil} @code{buffer-predicate} parameter, |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
846 then @code{other-buffer} uses that predicate to decide which buffers to |
40089afa2b1d
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22138
diff
changeset
|
847 consider. It calls the predicate once for each buffer, and if the value |
64880
5953197750ce
(The Buffer List): Fix xrefs.
Richard M. Stallman <rms@gnu.org>
parents:
61596
diff
changeset
|
848 is @code{nil}, that buffer is ignored. @xref{Buffer Parameters}. |
12067 | 849 |
6564 | 850 @c Emacs 19 feature |
851 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | |
852 a buffer visible in any window on any visible frame, except as a last | |
853 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter | |
854 whether a buffer is displayed somewhere or not. | |
855 | |
856 If no suitable buffer exists, the buffer @samp{*scratch*} is returned | |
857 (and created, if necessary). | |
858 @end defun | |
859 | |
860 @deffn Command bury-buffer &optional buffer-or-name | |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
861 This function puts @var{buffer-or-name} at the end of the buffer list, |
6564 | 862 without changing the order of any of the other buffers on the list. |
863 This buffer therefore becomes the least desirable candidate for | |
59874
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
864 @code{other-buffer} to return. The argument can be either a buffer |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
865 itself or the name of one. |
6564 | 866 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
867 @code{bury-buffer} operates on each frame's @code{buffer-list} parameter |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
868 as well as the frame-independent Emacs buffer list; therefore, the |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
869 buffer that you bury will come last in the value of @code{(buffer-list |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
870 @var{frame})} and in the value of @code{(buffer-list nil)}. |
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
871 |
7677 | 872 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the |
873 current buffer. In addition, if the buffer is displayed in the selected | |
874 window, this switches to some other buffer (obtained using | |
875 @code{other-buffer}) in the selected window. But if the buffer is | |
876 displayed in some other window, it remains displayed there. | |
6564 | 877 |
21007
66d807bdc5b4
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
15862
diff
changeset
|
878 To replace a buffer in all the windows that display it, use |
6564 | 879 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. |
880 @end deffn | |
881 | |
882 @node Creating Buffers | |
883 @section Creating Buffers | |
884 @cindex creating buffers | |
885 @cindex buffers, creating | |
886 | |
887 This section describes the two primitives for creating buffers. | |
7677 | 888 @code{get-buffer-create} creates a buffer if it finds no existing buffer |
889 with the specified name; @code{generate-new-buffer} always creates a new | |
890 buffer and gives it a unique name. | |
6564 | 891 |
892 Other functions you can use to create buffers include | |
893 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | |
894 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | |
895 subprocess can also create a buffer (@pxref{Processes}). | |
896 | |
897 @defun get-buffer-create name | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
898 This function returns a buffer named @var{name}. It returns a live |
6564 | 899 buffer with that name, if one exists; otherwise, it creates a new |
900 buffer. The buffer does not become the current buffer---this function | |
901 does not change which buffer is current. | |
902 | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
903 If @var{name} is a buffer instead of a string, it is returned, even if |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
904 it is dead. An error is signaled if @var{name} is neither a string |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
905 nor a buffer. |
6564 | 906 |
907 @example | |
908 @group | |
909 (get-buffer-create "foo") | |
910 @result{} #<buffer foo> | |
911 @end group | |
912 @end example | |
913 | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
914 The major mode for a newly created buffer is set to Fundamental mode. |
70659
61a3f8c2718c
(Creating Buffers): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
70642
diff
changeset
|
915 (The variable @code{default-major-mode} is handled at a higher level; |
61a3f8c2718c
(Creating Buffers): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
70642
diff
changeset
|
916 see @ref{Auto Major Mode}.) If the name begins with a space, the |
61a3f8c2718c
(Creating Buffers): Cleanup.
Richard M. Stallman <rms@gnu.org>
parents:
70642
diff
changeset
|
917 buffer initially disables undo information recording (@pxref{Undo}). |
6564 | 918 @end defun |
919 | |
920 @defun generate-new-buffer name | |
921 This function returns a newly created, empty buffer, but does not make | |
922 it current. If there is no buffer named @var{name}, then that is the | |
923 name of the new buffer. If that name is in use, this function adds | |
7677 | 924 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an |
925 integer. It tries successive integers starting with 2 until it finds an | |
926 available name. | |
6564 | 927 |
928 An error is signaled if @var{name} is not a string. | |
929 | |
930 @example | |
931 @group | |
932 (generate-new-buffer "bar") | |
933 @result{} #<buffer bar> | |
934 @end group | |
935 @group | |
936 (generate-new-buffer "bar") | |
937 @result{} #<buffer bar<2>> | |
938 @end group | |
939 @group | |
940 (generate-new-buffer "bar") | |
941 @result{} #<buffer bar<3>> | |
942 @end group | |
943 @end example | |
944 | |
12067 | 945 The major mode for the new buffer is set to Fundamental mode. The |
946 variable @code{default-major-mode} is handled at a higher level. | |
947 @xref{Auto Major Mode}. | |
6564 | 948 |
949 See the related function @code{generate-new-buffer-name} in @ref{Buffer | |
950 Names}. | |
951 @end defun | |
952 | |
953 @node Killing Buffers | |
954 @section Killing Buffers | |
955 @cindex killing buffers | |
956 @cindex buffers, killing | |
957 | |
59874
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
958 @dfn{Killing a buffer} makes its name unknown to Emacs and makes the |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
959 memory space it occupied available for other use. |
6564 | 960 |
7677 | 961 The buffer object for the buffer that has been killed remains in |
6564 | 962 existence as long as anything refers to it, but it is specially marked |
963 so that you cannot make it current or display it. Killed buffers retain | |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
964 their identity, however; if you kill two distinct buffers, they remain |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
965 distinct according to @code{eq} although both are dead. |
6564 | 966 |
967 If you kill a buffer that is current or displayed in a window, Emacs | |
968 automatically selects or displays some other buffer instead. This means | |
969 that killing a buffer can in general change the current buffer. | |
970 Therefore, when you kill a buffer, you should also take the precautions | |
971 associated with changing the current buffer (unless you happen to know | |
972 that the buffer being killed isn't current). @xref{Current Buffer}. | |
973 | |
12098 | 974 If you kill a buffer that is the base buffer of one or more indirect |
975 buffers, the indirect buffers are automatically killed as well. | |
976 | |
6564 | 977 The @code{buffer-name} of a killed buffer is @code{nil}. You can use |
978 this feature to test whether a buffer has been killed: | |
979 | |
980 @example | |
981 @group | |
982 (defun buffer-killed-p (buffer) | |
983 "Return t if BUFFER is killed." | |
984 (not (buffer-name buffer))) | |
985 @end group | |
986 @end example | |
987 | |
988 @deffn Command kill-buffer buffer-or-name | |
989 This function kills the buffer @var{buffer-or-name}, freeing all its | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
990 memory for other uses or to be returned to the operating system. If |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
991 @var{buffer-or-name} is @code{nil}, it kills the current buffer. |
6564 | 992 |
993 Any processes that have this buffer as the @code{process-buffer} are | |
994 sent the @code{SIGHUP} signal, which normally causes them to terminate. | |
995 (The basic meaning of @code{SIGHUP} is that a dialup line has been | |
44346
43dc1031ba62
Fix the xref for sending SIGHUP.
Richard M. Stallman <rms@gnu.org>
parents:
40492
diff
changeset
|
996 disconnected.) @xref{Signals to Processes}. |
6564 | 997 |
998 If the buffer is visiting a file and contains unsaved changes, | |
999 @code{kill-buffer} asks the user to confirm before the buffer is killed. | |
1000 It does this even if not called interactively. To prevent the request | |
1001 for confirmation, clear the modified flag before calling | |
1002 @code{kill-buffer}. @xref{Buffer Modification}. | |
1003 | |
1004 Killing a buffer that is already dead has no effect. | |
1005 | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1006 This function returns @code{t} if it actually killed the buffer. It |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1007 returns @code{nil} if the user refuses to confirm or if |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1008 @var{buffer-or-name} was already dead. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1009 |
6564 | 1010 @smallexample |
1011 (kill-buffer "foo.unchanged") | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1012 @result{} t |
6564 | 1013 (kill-buffer "foo.changed") |
1014 | |
1015 ---------- Buffer: Minibuffer ---------- | |
1016 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | |
1017 ---------- Buffer: Minibuffer ---------- | |
1018 | |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1019 @result{} t |
6564 | 1020 @end smallexample |
1021 @end deffn | |
1022 | |
7542
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1023 @defvar kill-buffer-query-functions |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1024 After confirming unsaved changes, @code{kill-buffer} calls the functions |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1025 in the list @code{kill-buffer-query-functions}, in order of appearance, |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1026 with no arguments. The buffer being killed is the current buffer when |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1027 they are called. The idea of this feature is that these functions will |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1028 ask for confirmation from the user. If any of them returns @code{nil}, |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1029 @code{kill-buffer} spares the buffer's life. |
7542
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1030 @end defvar |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1031 |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1032 @defvar kill-buffer-hook |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1033 This is a normal hook run by @code{kill-buffer} after asking all the |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1034 questions it is going to ask, just before actually killing the buffer. |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1035 The buffer to be killed is current when the hook functions run. |
51925
803b9aa5604e
(Killing Buffers): kill-buffer-hook is perm local.
Richard M. Stallman <rms@gnu.org>
parents:
50466
diff
changeset
|
1036 @xref{Hooks}. This variable is a permanent local, so its local binding |
803b9aa5604e
(Killing Buffers): kill-buffer-hook is perm local.
Richard M. Stallman <rms@gnu.org>
parents:
50466
diff
changeset
|
1037 is not cleared by changing major modes. |
7542
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1038 @end defvar |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1039 |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1040 @defvar buffer-offer-save |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1041 This variable, if non-@code{nil} in a particular buffer, tells |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1042 @code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1043 second optional argument to that function is @code{t}) to offer to |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1044 save that buffer, just as they offer to save file-visiting buffers. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1045 @xref{Definition of save-some-buffers}. The variable |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1046 @code{buffer-offer-save} automatically becomes buffer-local when set |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1047 for any reason. @xref{Buffer-Local Variables}. |
7542
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1048 @end defvar |
b93516a5dcda
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
6564
diff
changeset
|
1049 |
59148
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1050 @defvar buffer-save-without-query |
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1051 This variable, if non-@code{nil} in a particular buffer, tells |
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1052 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to save |
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1053 this buffer (if it's modified) without asking the user. The variable |
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1054 automatically becomes buffer-local when set for any reason. |
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1055 @end defvar |
6b3838433689
(Killing Buffers): Add buffer-save-without-query.
Richard M. Stallman <rms@gnu.org>
parents:
56427
diff
changeset
|
1056 |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1057 @defun buffer-live-p object |
53421
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
1058 This function returns @code{t} if @var{object} is a buffer which has |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
1059 not been killed, @code{nil} otherwise. |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
1060 @end defun |
36960c89c04c
(Buffer Modification): Add restore-buffer-modified-p.
Richard M. Stallman <rms@gnu.org>
parents:
52626
diff
changeset
|
1061 |
12067 | 1062 @node Indirect Buffers |
1063 @section Indirect Buffers | |
1064 @cindex indirect buffers | |
1065 @cindex base buffer | |
6564 | 1066 |
12067 | 1067 An @dfn{indirect buffer} shares the text of some other buffer, which |
1068 is called the @dfn{base buffer} of the indirect buffer. In some ways it | |
12098 | 1069 is the analogue, for buffers, of a symbolic link among files. The base |
12067 | 1070 buffer may not itself be an indirect buffer. |
6564 | 1071 |
12067 | 1072 The text of the indirect buffer is always identical to the text of its |
1073 base buffer; changes made by editing either one are visible immediately | |
1074 in the other. This includes the text properties as well as the characters | |
1075 themselves. | |
6564 | 1076 |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1077 In all other respects, the indirect buffer and its base buffer are |
61596
164ca32df6ab
(Indirect Buffers): Clarify.
Richard M. Stallman <rms@gnu.org>
parents:
59874
diff
changeset
|
1078 completely separate. They have different names, independent values of |
164ca32df6ab
(Indirect Buffers): Clarify.
Richard M. Stallman <rms@gnu.org>
parents:
59874
diff
changeset
|
1079 point, independent narrowing, independent markers and overlays (though |
12067 | 1080 inserting or deleting text in either buffer relocates the markers and |
61596
164ca32df6ab
(Indirect Buffers): Clarify.
Richard M. Stallman <rms@gnu.org>
parents:
59874
diff
changeset
|
1081 overlays for both), independent major modes, and independent |
164ca32df6ab
(Indirect Buffers): Clarify.
Richard M. Stallman <rms@gnu.org>
parents:
59874
diff
changeset
|
1082 buffer-local variable bindings. |
6564 | 1083 |
12067 | 1084 An indirect buffer cannot visit a file, but its base buffer can. If |
25751
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1085 you try to save the indirect buffer, that actually saves the base |
467b88fab665
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
24951
diff
changeset
|
1086 buffer. |
6564 | 1087 |
12067 | 1088 Killing an indirect buffer has no effect on its base buffer. Killing |
1089 the base buffer effectively kills the indirect buffer in that it cannot | |
1090 ever again be the current buffer. | |
6564 | 1091 |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1092 @deffn Command make-indirect-buffer base-buffer name &optional clone |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1093 This creates and returns an indirect buffer named @var{name} whose |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1094 base buffer is @var{base-buffer}. The argument @var{base-buffer} may |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1095 be a live buffer or the name (a string) of an existing buffer. If |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1096 @var{name} is the name of an existing buffer, an error is signaled. |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1097 |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1098 If @var{clone} is non-@code{nil}, then the indirect buffer originally |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1099 shares the ``state'' of @var{base-buffer} such as major mode, minor |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1100 modes, buffer local variables and so on. If @var{clone} is omitted |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1101 or @code{nil} the indirect buffer's state is set to the default state |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1102 for new buffers. |
49600
23a1cea22d13
Trailing whitespace deleted.
Juanma Barranquero <lekktu@gmail.com>
parents:
44346
diff
changeset
|
1103 |
12067 | 1104 If @var{base-buffer} is an indirect buffer, its base buffer is used as |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1105 the base for the new buffer. If, in addition, @var{clone} is |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1106 non-@code{nil}, the initial state is copied from the actual base |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1107 buffer, not from @var{base-buffer}. |
12067 | 1108 @end deffn |
6564 | 1109 |
59874
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1110 @defun clone-indirect-buffer newname display-flag &optional norecord |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1111 This function creates and returns a new indirect buffer that shares |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1112 the current buffer's base buffer and copies the rest of the current |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1113 buffer's attributes. (If the current buffer is not indirect, it is |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1114 used as the base buffer.) |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1115 |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1116 If @var{display-flag} is non-@code{nil}, that means to display the new |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1117 buffer by calling @code{pop-to-buffer}. If @var{norecord} is |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1118 non-@code{nil}, that means not to put the new buffer to the front of |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1119 the buffer list. |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1120 @end defun |
134cd8afb3e7
(Buffer Names): Clarify generate-new-buffer-name.
Richard M. Stallman <rms@gnu.org>
parents:
59148
diff
changeset
|
1121 |
54862
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1122 @defun buffer-base-buffer &optional buffer |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1123 This function returns the base buffer of @var{buffer}, which defaults |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1124 to the current buffer. If @var{buffer} is not indirect, the value is |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1125 @code{nil}. Otherwise, the value is another buffer, which is never an |
8de44f69312c
Various changes in addition to:
Luc Teirlinck <teirllm@auburn.edu>
parents:
54019
diff
changeset
|
1126 indirect buffer. |
6564 | 1127 @end defun |
1128 | |
24951
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1129 @node Buffer Gap |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1130 @section The Buffer Gap |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1131 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1132 Emacs buffers are implemented using an invisible @dfn{gap} to make |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1133 insertion and deletion faster. Insertion works by filling in part of |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1134 the gap, and deletion adds to the gap. Of course, this means that the |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1135 gap must first be moved to the locus of the insertion or deletion. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1136 Emacs moves the gap only when you try to insert or delete. This is why |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1137 your first editing command in one part of a large buffer, after |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1138 previously editing in another far-away part, sometimes involves a |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1139 noticeable delay. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1140 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1141 This mechanism works invisibly, and Lisp code should never be affected |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1142 by the gap's current location, but these functions are available for |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1143 getting information about the gap status. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1144 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1145 @defun gap-position |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1146 This function returns the current gap position in the current buffer. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1147 @end defun |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1148 |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1149 @defun gap-size |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1150 This function returns the current gap size of the current buffer. |
7451b1458af1
*** empty log message ***
Richard M. Stallman <rms@gnu.org>
parents:
22252
diff
changeset
|
1151 @end defun |
52401 | 1152 |
1153 @ignore | |
1154 arch-tag: 2e53cfab-5691-41f6-b5a8-9c6a3462399c | |
1155 @end ignore |