Mercurial > hg > xemacs-beta
annotate man/lispref/buffers.texi @ 5353:38e24b8be4ea
Improve the lexical scoping in #'block, #'return-from.
lisp/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el:
* bytecomp.el (byte-compile-initial-macro-environment):
Shadow `block', `return-from' here, we implement them differently
when byte-compiling.
* bytecomp.el (byte-compile-active-blocks): New.
* bytecomp.el (byte-compile-block-1): New.
* bytecomp.el (byte-compile-return-from-1): New.
* bytecomp.el (return-from-1): New.
* bytecomp.el (block-1): New.
These are two aliases that exist to have their own associated
byte-compile functions, which functions implement `block' and
`return-from'.
* cl-extra.el (cl-macroexpand-all):
Fix a bug here when macros in the environment have been compiled.
* cl-macs.el (block):
* cl-macs.el (return):
* cl-macs.el (return-from):
Be more careful about lexical scope in these macros.
* cl.el:
* cl.el ('cl-block-wrapper): Removed.
* cl.el ('cl-block-throw): Removed.
These aren't needed in code generated by this XEmacs. They
shouldn't be needed in code generated by XEmacs 21.4, but if it
turns out the packages do need them, we can put them back.
2011-01-30 Mike Sperber <mike@xemacs.org>
* font-lock.el (font-lock-fontify-pending-extents): Don't fail if
`font-lock-mode' is unset, which can happen in the middle of
`revert-buffer'.
2011-01-23 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete):
* cl-macs.el (delq):
* cl-macs.el (remove):
* cl-macs.el (remq):
Don't use the compiler macro if these functions were given the
wrong number of arguments, as happens in lisp-tests.el.
* cl-seq.el (remove, remq): Removed.
I added these to subr.el, and forgot to remove them from here.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-setq, byte-compile-set):
Remove kludge allowing keywords' values to be set, all the code
that does that is gone.
* cl-compat.el (elt-satisfies-test-p):
* faces.el (set-face-parent):
* faces.el (face-doc-string):
* gtk-font-menu.el:
* gtk-font-menu.el (gtk-reset-device-font-menus):
* msw-font-menu.el:
* msw-font-menu.el (mswindows-reset-device-font-menus):
* package-get.el (package-get-installedp):
* select.el (select-convert-from-image-data):
* sound.el:
* sound.el (load-sound-file):
* x-font-menu.el (x-reset-device-font-menus-core):
Don't quote keywords, they're self-quoting, and the
win from backward-compatibility is sufficiently small now that the
style problem overrides it.
2011-01-22 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (block, return-from): Require that NAME be a symbol
in these macros, as always documented in the #'block docstring and
as required by Common Lisp.
* descr-text.el (unidata-initialize-unihan-database):
Correct the use of non-symbols in #'block and #'return-from in
this function.
2011-01-15 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (concatenate): Accept more complicated TYPEs in this
function, handing the sequences over to #'coerce if we don't
understand them here.
* cl-macs.el (inline): Don't proclaim #'concatenate as inline, its
compiler macro is more useful than doing that.
2011-01-11 Aidan Kehoe <kehoea@parhasard.net>
* subr.el (delete, delq, remove, remq): Move #'remove, #'remq
here, they don't belong in cl-seq.el; move #'delete, #'delq here
from fns.c, implement them in terms of #'delete*, allowing support
for sequences generally.
* update-elc.el (do-autoload-commands): Use #'delete*, not #'delq
here, now the latter's no longer dumped.
* cl-macs.el (delete, delq): Add compiler macros transforming
#'delete and #'delq to #'delete* calls.
2011-01-10 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box): Correct a misplaced parenthesis
here, thank you Mats Lidell in 87zkr9gqrh.fsf@mail.contactor.se !
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* dialog.el (make-dialog-box):
* list-mode.el (display-completion-list):
These functions used to use cl-parsing-keywords; change them to
use defun* instead, fixing the build. (Not sure what led to me
not including this change in d1b17a33450b!)
2011-01-02 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (define-star-compiler-macros):
Make sure the form has ITEM and LIST specified before attempting
to change to calls with explicit tests; necessary for some tests
in lisp-tests.el to compile correctly.
(stable-union, stable-intersection): Add compiler macros for these
functions, in the same way we do for most of the other functions
in cl-seq.el.
2011-01-01 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (dolist, dotimes, do-symbols, macrolet)
(symbol-macrolet):
Define these macros with defmacro* instead of parsing the argument
list by hand, for the sake of style and readability; use backquote
where appropriate, instead of calling #'list and and friends, for
the same reason.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* x-misc.el (device-x-display):
Provide this function, documented in the Lispref for years, but
not existing previously. Thank you Julian Bradfield, thank you
Jeff Mincy.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl-seq.el:
Move the heavy lifting from this file to C. Dump the
cl-parsing-keywords macro, but don't use defun* for the functions
we define that do take keywords, dynamic scope lossage makes that
not practical.
* subr.el (sort, fillarray): Move these aliases here.
(map-plist): #'nsublis is now built-in, but at this point #'eql
isn't necessarily available as a test; use #'eq.
* obsolete.el (cl-delete-duplicates): Make this available for old
compiler macros and old code.
(memql): Document that this is equivalent to #'member*, and worse.
* cl.el (adjoin, subst): Removed. These are in C.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* simple.el (assoc-ignore-case): Remove a duplicate definition of
this function (it's already in subr.el).
* iso8859-1.el (char-width):
On non-Mule, make this function equivalent to that produced by
(constantly 1), but preserve its docstring.
* subr.el (subst-char-in-string): Define this in terms of
#'substitute, #'nsubstitute.
(string-width): Define this using #'reduce and #'char-width.
(char-width): Give this a simpler definition, it makes far more
sense to check for mule at load time and redefine, as we do in
iso8859-1.el.
(store-substring): Implement this in terms of #'replace, now
#'replace is cheap.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* update-elc.el (lisp-files-needed-for-byte-compilation)
(lisp-files-needing-early-byte-compilation):
cl-macs belongs in the former, not the latter, it is as
fundamental as bytecomp.el.
2010-12-30 Aidan Kehoe <kehoea@parhasard.net>
* cl.el:
Provde the Common Lisp program-error, type-error as error
symbols. This doesn't nearly go far enough for anyone using the
Common Lisp errors.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (delete-duplicates):
If the form has an incorrect number of arguments, don't attempt a
compiler macroexpansion.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (cl-safe-expr-p):
Forms that start with the symbol lambda are also safe.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
For these functions' compiler macros, the optimisation is safe
even if the first and the last arguments have side effects, since
they're only used the once.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (inline-side-effect-free-compiler-macros):
Unroll a loop here at macro-expansion time, so these compiler
macros are compiled. Use #'eql instead of #'eq in a couple of
places for better style.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (notany, notevery): Avoid some dynamic scope
stupidity with local variable names in these functions, when they
weren't prefixed with cl-; go into some more detail in the doc
strings.
2010-12-29 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns): #'remove, #'remq are
free of side-effects.
(side-effect-and-error-free-fns):
Drop dot, dot-marker from the list.
2010-11-17 Aidan Kehoe <kehoea@parhasard.net>
* cl-extra.el (coerce):
In the argument list, name the first argument OBJECT, not X; the
former name was always used in the doc string and is clearer.
Handle vector type specifications which include the length of the
target sequence, error if there's a mismatch.
* cl-macs.el (cl-make-type-test): Handle type specifications
starting with the symbol 'eql.
2010-11-14 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (eql): Don't remove the byte-compile property of this
symbol. That was necessary to override a bug in bytecomp.el where
#'eql was confused with #'eq, which bug we no longer have.
If neither expression is constant, don't attempt to handle the
expression in this compiler macro, leave it to byte-compile-eql,
which produces better code anyway.
* bytecomp.el (eq): #'eql is not the function associated with the
byte-eq byte code.
(byte-compile-eql): Add an explicit compile method for this
function, for cases where the cl-macs compiler macro hasn't
reduced it to #'eq or #'equal.
2010-10-25 Aidan Kehoe <kehoea@parhasard.net>
Add compiler macros and compilation sanity-checking for various
functions that take keywords.
* byte-optimize.el (side-effect-free-fns): #'symbol-value is
side-effect free and not error free.
* bytecomp.el (byte-compile-normal-call): Check keyword argument
lists for sanity; store information about the positions where
keyword arguments start using the new byte-compile-keyword-start
property.
* cl-macs.el (cl-const-expr-val): Take a new optional argument,
cl-not-constant, defaulting to nil, in this function; return it if
the expression is not constant.
(cl-non-fixnum-number-p): Make this into a separate function, we
want to pass it to #'every.
(eql): Use it.
(define-star-compiler-macros): Use the same code to generate the
member*, assoc* and rassoc* compiler macros; special-case some
code in #'add-to-list in subr.el.
(remove, remq): Add compiler macros for these two functions, in
preparation for #'remove being in C.
(define-foo-if-compiler-macros): Transform (remove-if-not ...) calls to
(remove ... :if-not) at compile time, which will be a real win
once the latter is in C.
(define-substitute-if-compiler-macros)
(define-subst-if-compiler-macros): Similarly for these functions.
(delete-duplicates): Change this compiler macro to use
#'plists-equal; if we don't have information about the type of
SEQUENCE at compile time, don't bother attempting to inline the
call, the function will be in C soon enough.
(equalp): Remove an old commented-out compiler macro for this, if
we want to see it it's in version control.
(subst-char-in-string): Transform this to a call to nsubstitute or
nsubstitute, if that is appropriate.
* cl.el (ldiff): Don't call setf here, this makes for a load-time
dependency problem in cl-macs.el
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* term/vt100.el:
Refer to XEmacs, not GNU Emacs, in permissions.
* term/bg-mouse.el:
* term/sup-mouse.el:
Put copyright notice in canonical "Copyright DATE AUTHOR" form.
Refer to XEmacs, not GNU Emacs, in permissions.
* site-load.el:
Add permission boilerplate.
* mule/canna-leim.el:
* alist.el:
Refer to XEmacs, not APEL/this program, in permissions.
* mule/canna-leim.el:
Remove my copyright, I've assigned it to the FSF.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* gtk.el:
* gtk-widget-accessors.el:
* gtk-package.el:
* gtk-marshal.el:
* gtk-compose.el:
* gnome.el:
Add copyright notice based on internal evidence.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* easymenu.el: Add reference to COPYING to permission notice.
* gutter.el:
* gutter-items.el:
* menubar-items.el:
Fix typo "Xmacs" in permissions notice.
2010-06-14 Stephen J. Turnbull <stephen@xemacs.org>
* auto-save.el:
* font.el:
* fontconfig.el:
* mule/kinsoku.el:
Add "part of XEmacs" text to permission notice.
2010-10-14 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (side-effect-free-fns):
* cl-macs.el (remf, getf):
* cl-extra.el (tailp, cl-set-getf, cl-do-remf):
* cl.el (ldiff, endp):
Tighten up Common Lisp compatibility for #'ldiff, #'endp, #'tailp;
add circularity checking for the first two.
#'cl-set-getf and #'cl-do-remf were Lisp implementations of
#'plist-put and #'plist-remprop; change the names to aliases,
changes the macros that use them to using #'plist-put and
#'plist-remprop directly.
2010-10-12 Aidan Kehoe <kehoea@parhasard.net>
* abbrev.el (fundamental-mode-abbrev-table, global-abbrev-table):
Create both these abbrev tables using the usual
#'define-abbrev-table calls, rather than attempting to
special-case them.
* cl-extra.el: Force cl-macs to be loaded here, if cl-extra.el is
being loaded interpreted. Previously other, later files would
redundantly call (load "cl-macs") when interpreted, it's more
reasonable to do it here, once.
* cmdloop.el (read-quoted-char-radix): Use defcustom here, we
don't have any dump-order dependencies that would prevent that.
* custom.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling, rely on cl-extra.el in the
former case and the appropriate entry in bytecomp-load-hook in the
latter. Get rid of custom-declare-variable-list, we have no
dump-time dependencies that would require it.
* faces.el (eval-when-compile): Don't load cl-macs when
interpreted or when byte-compiling.
* packages.el: Remove some inaccurate comments.
* post-gc.el (cleanup-simple-finalizers): Use #'delete-if-not
here, now the order of preloaded-file-list has been changed to
make it available.
* subr.el (custom-declare-variable-list): Remove. No need for it.
Also remove a stub define-abbrev-table from this file, given the
current order of preloaded-file-list there's no need for it.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-constp) Forms quoted with FUNCTION are
also constant.
(byte-compile-initial-macro-environment): In #'the, if FORM is
constant and does not match TYPE, warn at byte-compile time.
2010-10-10 Aidan Kehoe <kehoea@parhasard.net>
* backquote.el (bq-vector-contents, bq-list*): Remove; the former
is equivalent to (append VECTOR nil), the latter to (list* ...).
(bq-process-2): Use (append VECTOR nil) instead of using
#'bq-vector-contents to convert to a list.
(bq-process-1): Now we use list* instead of bq-list
* subr.el (list*): Moved from cl.el, since it is now required to
be available the first time a backquoted form is encountered.
* cl.el (list*): Move to subr.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* test-harness.el (Check-Message):
Add an omitted comma here, thank you the buildbot.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* hash-table.el (hash-table-key-list, hash-table-value-list)
(hash-table-key-value-alist, hash-table-key-value-plist):
Remove some useless #'nreverse calls in these files; our hash
tables have no order, it's not helpful to pretend they do.
* behavior.el (read-behavior):
Do the same in this file, in some code evidently copied from
hash-table.el.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* info.el (Info-insert-dir):
* format.el (format-deannotate-region):
* files.el (cd, save-buffers-kill-emacs):
Use #'some, #'every and related functions for applying boolean
operations to lists, instead of rolling our own ones that cons and
don't short-circuit.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-initial-macro-environment):
* cl-macs.el (the):
Rephrase the docstring, make its implementation when compiling
files a little nicer.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* descr-text.el (unidata-initialize-unicodedata-database)
(unidata-initialize-unihan-database, describe-char-unicode-data)
(describe-char-unicode-data):
Wrap calls to the database functions with (with-fboundp ...),
avoiding byte compile warnings on builds without support for the
database functions.
(describe-char): (reduce #'max ...), not (apply #'max ...), no
need to cons needlessly.
(describe-char): Remove a redundant lambda wrapping
#'extent-properties.
(describe-char-unicode-data): Call #'nsubst when replacing "" with
nil in the result of #'split-string, instead of consing inside
mapcar.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* x-faces.el (x-available-font-sizes):
* specifier.el (let-specifier):
* package-ui.el (pui-add-required-packages):
* msw-faces.el (mswindows-available-font-sizes):
* modeline.el (modeline-minor-mode-menu):
* minibuf.el (minibuf-directory-files):
Replace the O2N (delq nil (mapcar (lambda (W) (and X Y)) Z)) with
the ON (mapcan (lambda (W) (and X (list Y))) Z) in these files.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* cl-macs.el (= < > <= >=):
When these functions are handed more than two arguments, and those
arguments have no side effects, transform to a series of two
argument calls, avoiding funcall in the byte-compiled code.
* mule/mule-cmds.el (finish-set-language-environment):
Take advantage of this change in a function called 256 times at
startup.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* bytecomp.el (byte-compile-function-form, byte-compile-quote)
(byte-compile-quote-form):
Warn at compile time, and error at runtime, if a (quote ...) or a
(function ...) form attempts to quote more than one object.
2010-09-16 Aidan Kehoe <kehoea@parhasard.net>
* byte-optimize.el (byte-optimize-apply): Transform (apply 'nconc
(mapcar ...)) to (mapcan ...); warn about use of the first idiom.
* update-elc.el (do-autoload-commands):
* packages.el (packages-find-package-library-path):
* frame.el (frame-list):
* extents.el (extent-descendants):
* etags.el (buffer-tag-table-files):
* dumped-lisp.el (preloaded-file-list):
* device.el (device-list):
* bytecomp-runtime.el (proclaim-inline, proclaim-notinline)
Use #'mapcan, not (apply #'nconc (mapcar ...) in all these files.
* bytecomp-runtime.el (eval-when-compile, eval-and-compile):
In passing, mention that these macros also evaluate the body when
interpreted.
tests/ChangeLog addition:
2011-02-07 Aidan Kehoe <kehoea@parhasard.net>
* automated/lisp-tests.el:
Test lexical scope for `block', `return-from'; add a
Known-Bug-Expect-Failure for a contorted example that fails when
byte-compiled.
| author | Aidan Kehoe <kehoea@parhasard.net> |
|---|---|
| date | Mon, 07 Feb 2011 12:01:24 +0000 |
| parents | 6772ce4d982b |
| children | 9fae6227ede5 |
| rev | line source |
|---|---|
| 428 | 1 @c -*-texinfo-*- |
| 2 @c This is part of the XEmacs Lisp Reference Manual. | |
| 444 | 3 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc. |
| 428 | 4 @c See the file lispref.texi for copying conditions. |
| 5 @setfilename ../../info/buffers.info | |
| 6 @node Buffers, Windows, Backups and Auto-Saving, Top | |
| 7 @chapter Buffers | |
| 8 @cindex buffer | |
| 9 | |
| 10 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
| 11 are used to hold the contents of files that are being visited; there may | |
| 12 also be buffers that are not visiting files. While several buffers may | |
| 13 exist at one time, exactly one buffer is designated the @dfn{current | |
| 14 buffer} at any time. Most editing commands act on the contents of the | |
| 15 current buffer. Each buffer, including the current buffer, may or may | |
| 444 | 16 not be displayed in any window. |
| 428 | 17 |
| 18 @menu | |
| 19 * Buffer Basics:: What is a buffer? | |
| 20 * Current Buffer:: Designating a buffer as current | |
| 21 so primitives will access its contents. | |
| 22 * Buffer Names:: Accessing and changing buffer names. | |
| 23 * Buffer File Name:: The buffer file name indicates which file is visited. | |
| 24 * Buffer Modification:: A buffer is @dfn{modified} if it needs to be saved. | |
| 25 * Modification Time:: Determining whether the visited file was changed | |
| 26 ``behind XEmacs's back''. | |
| 27 * Read Only Buffers:: Modifying text is not allowed in a read-only buffer. | |
| 28 * The Buffer List:: How to look at all the existing buffers. | |
| 29 * Creating Buffers:: Functions that create buffers. | |
| 30 * Killing Buffers:: Buffers exist until explicitly killed. | |
| 31 * Indirect Buffers:: An indirect buffer shares text with some other buffer. | |
| 32 @end menu | |
| 33 | |
| 34 @node Buffer Basics | |
| 35 @section Buffer Basics | |
| 36 | |
| 37 @ifinfo | |
| 38 A @dfn{buffer} is a Lisp object containing text to be edited. Buffers | |
| 39 are used to hold the contents of files that are being visited; there may | |
| 40 also be buffers that are not visiting files. While several buffers may | |
| 41 exist at one time, exactly one buffer is designated the @dfn{current | |
| 42 buffer} at any time. Most editing commands act on the contents of the | |
| 43 current buffer. Each buffer, including the current buffer, may or may | |
| 44 not be displayed in any windows. | |
| 45 @end ifinfo | |
| 46 | |
| 47 Buffers in Emacs editing are objects that have distinct names and hold | |
| 48 text that can be edited. Buffers appear to Lisp programs as a special | |
| 442 | 49 data type. You can think of the contents of a buffer as an extendible |
| 428 | 50 string; insertions and deletions may occur in any part of the buffer. |
| 51 @xref{Text}. | |
| 52 | |
| 53 A Lisp buffer object contains numerous pieces of information. Some of | |
| 54 this information is directly accessible to the programmer through | |
| 55 variables, while other information is accessible only through | |
| 56 special-purpose functions. For example, the visited file name is | |
| 57 directly accessible through a variable, while the value of point is | |
| 58 accessible only through a primitive function. | |
| 59 | |
| 60 Buffer-specific information that is directly accessible is stored in | |
| 61 @dfn{buffer-local} variable bindings, which are variable values that are | |
| 62 effective only in a particular buffer. This feature allows each buffer | |
| 63 to override the values of certain variables. Most major modes override | |
| 64 variables such as @code{fill-column} or @code{comment-column} in this | |
| 65 way. For more information about buffer-local variables and functions | |
| 66 related to them, see @ref{Buffer-Local Variables}. | |
| 67 | |
| 68 For functions and variables related to visiting files in buffers, see | |
| 69 @ref{Visiting Files} and @ref{Saving Buffers}. For functions and | |
| 70 variables related to the display of buffers in windows, see | |
| 71 @ref{Buffers and Windows}. | |
| 72 | |
| 73 @defun bufferp object | |
| 74 This function returns @code{t} if @var{object} is a buffer, | |
| 75 @code{nil} otherwise. | |
| 76 @end defun | |
| 77 | |
| 78 @node Current Buffer | |
| 79 @section The Current Buffer | |
| 80 @cindex selecting a buffer | |
| 81 @cindex changing to another buffer | |
| 82 @cindex current buffer | |
| 83 | |
| 84 There are, in general, many buffers in an Emacs session. At any time, | |
| 85 one of them is designated as the @dfn{current buffer}. This is the | |
| 86 buffer in which most editing takes place, because most of the primitives | |
| 87 for examining or changing text in a buffer operate implicitly on the | |
| 88 current buffer (@pxref{Text}). Normally the buffer that is displayed on | |
| 89 the screen in the selected window is the current buffer, but this is not | |
| 90 always so: a Lisp program can designate any buffer as current | |
| 91 temporarily in order to operate on its contents, without changing what | |
| 92 is displayed on the screen. | |
| 93 | |
| 94 The way to designate a current buffer in a Lisp program is by calling | |
| 95 @code{set-buffer}. The specified buffer remains current until a new one | |
| 96 is designated. | |
| 97 | |
| 98 When an editing command returns to the editor command loop, the | |
| 99 command loop designates the buffer displayed in the selected window as | |
| 100 current, to prevent confusion: the buffer that the cursor is in when | |
| 101 Emacs reads a command is the buffer that the command will apply to. | |
| 102 (@xref{Command Loop}.) Therefore, @code{set-buffer} is not the way to | |
| 103 switch visibly to a different buffer so that the user can edit it. For | |
| 104 this, you must use the functions described in @ref{Displaying Buffers}. | |
| 105 | |
| 106 However, Lisp functions that change to a different current buffer | |
| 107 should not depend on the command loop to set it back afterwards. | |
| 108 Editing commands written in XEmacs Lisp can be called from other programs | |
| 109 as well as from the command loop. It is convenient for the caller if | |
| 110 the subroutine does not change which buffer is current (unless, of | |
| 111 course, that is the subroutine's purpose). Therefore, you should | |
| 112 normally use @code{set-buffer} within a @code{save-excursion} that will | |
| 113 restore the current buffer when your function is done | |
| 114 (@pxref{Excursions}). Here is an example, the code for the command | |
| 115 @code{append-to-buffer} (with the documentation string abridged): | |
| 116 | |
| 117 @example | |
| 118 @group | |
| 119 (defun append-to-buffer (buffer start end) | |
| 120 "Append to specified buffer the text of the region. | |
| 121 @dots{}" | |
| 122 (interactive "BAppend to buffer: \nr") | |
| 123 (let ((oldbuf (current-buffer))) | |
| 124 (save-excursion | |
| 125 (set-buffer (get-buffer-create buffer)) | |
| 126 (insert-buffer-substring oldbuf start end)))) | |
| 127 @end group | |
| 128 @end example | |
| 129 | |
| 130 @noindent | |
| 131 This function binds a local variable to the current buffer, and then | |
| 132 @code{save-excursion} records the values of point, the mark, and the | |
| 133 original buffer. Next, @code{set-buffer} makes another buffer current. | |
| 134 Finally, @code{insert-buffer-substring} copies the string from the | |
| 135 original current buffer to the new current buffer. | |
| 136 | |
| 444 | 137 If the buffer appended to happens to be displayed in some window, |
| 428 | 138 the next redisplay will show how its text has changed. Otherwise, you |
| 139 will not see the change immediately on the screen. The buffer becomes | |
| 140 current temporarily during the execution of the command, but this does | |
| 141 not cause it to be displayed. | |
| 142 | |
| 143 If you make local bindings (with @code{let} or function arguments) for | |
| 144 a variable that may also have buffer-local bindings, make sure that the | |
| 145 same buffer is current at the beginning and at the end of the local | |
| 146 binding's scope. Otherwise you might bind it in one buffer and unbind | |
| 147 it in another! There are two ways to do this. In simple cases, you may | |
| 148 see that nothing ever changes the current buffer within the scope of the | |
| 149 binding. Otherwise, use @code{save-excursion} to make sure that the | |
| 150 buffer current at the beginning is current again whenever the variable | |
| 151 is unbound. | |
| 152 | |
| 153 It is not reliable to change the current buffer back with | |
| 154 @code{set-buffer}, because that won't do the job if a quit happens while | |
| 155 the wrong buffer is current. Here is what @emph{not} to do: | |
| 156 | |
| 157 @example | |
| 158 @group | |
| 159 (let (buffer-read-only | |
| 160 (obuf (current-buffer))) | |
| 161 (set-buffer @dots{}) | |
| 162 @dots{} | |
| 163 (set-buffer obuf)) | |
| 164 @end group | |
| 165 @end example | |
| 166 | |
| 167 @noindent | |
| 168 Using @code{save-excursion}, as shown below, handles quitting, errors, | |
| 169 and @code{throw}, as well as ordinary evaluation. | |
| 170 | |
| 171 @example | |
| 172 @group | |
| 173 (let (buffer-read-only) | |
| 174 (save-excursion | |
| 175 (set-buffer @dots{}) | |
| 176 @dots{})) | |
| 177 @end group | |
| 178 @end example | |
| 179 | |
| 180 @defun current-buffer | |
| 181 This function returns the current buffer. | |
| 182 | |
| 183 @example | |
| 184 @group | |
| 185 (current-buffer) | |
| 186 @result{} #<buffer buffers.texi> | |
| 187 @end group | |
| 188 @end example | |
| 189 @end defun | |
| 190 | |
| 191 @defun set-buffer buffer-or-name | |
| 192 This function makes @var{buffer-or-name} the current buffer. It does | |
| 193 not display the buffer in the currently selected window or in any other | |
| 194 window, so the user cannot necessarily see the buffer. But Lisp | |
| 195 programs can in any case work on it. | |
| 196 | |
| 444 | 197 @var{buffer-or-name} must be a buffer or the name of an existing |
| 198 buffer--else an error is signaled. This function returns the buffer | |
| 199 identified by @var{buffer-or-name}. | |
| 428 | 200 @end defun |
| 201 | |
| 202 @node Buffer Names | |
| 203 @section Buffer Names | |
| 204 @cindex buffer names | |
| 205 | |
| 206 Each buffer has a unique name, which is a string. Many of the | |
| 207 functions that work on buffers accept either a buffer or a buffer name | |
| 208 as an argument. Any argument called @var{buffer-or-name} is of this | |
| 209 sort, and an error is signaled if it is neither a string nor a buffer. | |
| 210 Any argument called @var{buffer} must be an actual buffer | |
| 211 object, not a name. | |
| 212 | |
| 213 Buffers that are ephemeral and generally uninteresting to the user | |
| 214 have names starting with a space, so that the @code{list-buffers} and | |
| 215 @code{buffer-menu} commands don't mention them. A name starting with | |
| 216 space also initially disables recording undo information; see | |
| 217 @ref{Undo}. | |
| 218 | |
| 219 @defun buffer-name &optional buffer | |
| 220 This function returns the name of @var{buffer} as a string. If | |
| 221 @var{buffer} is not supplied, it defaults to the current buffer. | |
| 222 | |
| 223 If @code{buffer-name} returns @code{nil}, it means that @var{buffer} | |
| 224 has been killed. @xref{Killing Buffers}. | |
| 225 | |
| 226 @example | |
| 227 @group | |
| 228 (buffer-name) | |
| 229 @result{} "buffers.texi" | |
| 230 @end group | |
| 231 | |
| 232 @group | |
| 233 (setq foo (get-buffer "temp")) | |
| 234 @result{} #<buffer temp> | |
| 235 @end group | |
| 236 @group | |
| 237 (kill-buffer foo) | |
| 238 @result{} nil | |
| 239 @end group | |
| 240 @group | |
| 241 (buffer-name foo) | |
| 242 @result{} nil | |
| 243 @end group | |
| 244 @group | |
| 245 foo | |
| 246 @result{} #<killed buffer> | |
| 247 @end group | |
| 248 @end example | |
| 249 @end defun | |
| 250 | |
| 251 @deffn Command rename-buffer newname &optional unique | |
| 252 This function renames the current buffer to @var{newname}. An error | |
| 253 is signaled if @var{newname} is not a string, or if there is already a | |
| 254 buffer with that name. The function returns @code{nil}. | |
| 255 | |
| 256 @c Emacs 19 feature | |
| 257 Ordinarily, @code{rename-buffer} signals an error if @var{newname} is | |
| 258 already in use. However, if @var{unique} is non-@code{nil}, it modifies | |
| 259 @var{newname} to make a name that is not in use. Interactively, you can | |
| 260 make @var{unique} non-@code{nil} with a numeric prefix argument. | |
| 261 | |
| 262 One application of this command is to rename the @samp{*shell*} buffer | |
| 263 to some other name, thus making it possible to create a second shell | |
| 264 buffer under the name @samp{*shell*}. | |
| 265 @end deffn | |
| 266 | |
| 267 @defun get-buffer buffer-or-name | |
| 444 | 268 This function returns the buffer named @var{buffer-or-name}. If |
| 269 @var{buffer-or-name} is a string and there is no buffer with that name, | |
| 270 the value is @code{nil}. If @var{buffer-or-name} is actually a buffer, | |
| 271 it is returned as given. (That is not very useful, so the argument is | |
| 272 usually a name.) For example: | |
| 428 | 273 |
| 274 @example | |
| 275 @group | |
| 276 (setq b (get-buffer "lewis")) | |
| 277 @result{} #<buffer lewis> | |
| 278 @end group | |
| 279 @group | |
| 280 (get-buffer b) | |
| 281 @result{} #<buffer lewis> | |
| 282 @end group | |
| 283 @group | |
| 284 (get-buffer "Frazzle-nots") | |
| 285 @result{} nil | |
| 286 @end group | |
| 287 @end example | |
| 288 | |
| 289 See also the function @code{get-buffer-create} in @ref{Creating Buffers}. | |
| 290 @end defun | |
| 291 | |
| 292 @defun generate-new-buffer-name starting-name &optional ignore | |
| 293 This function returns a name that would be unique for a new buffer---but | |
| 294 does not create the buffer. It starts with @var{starting-name}, and | |
| 295 produces a name not currently in use for any buffer by appending a | |
| 296 number inside of @samp{<@dots{}>}. | |
| 297 | |
| 298 If @var{ignore} is given, it specifies a name that is okay to use (if it | |
| 299 is in the sequence to be tried), even if a buffer with that name exists. | |
| 300 | |
| 301 See the related function @code{generate-new-buffer} in @ref{Creating | |
| 302 Buffers}. | |
| 303 @end defun | |
| 304 | |
| 305 @node Buffer File Name | |
| 306 @section Buffer File Name | |
| 307 @cindex visited file | |
| 308 @cindex buffer file name | |
| 309 @cindex file name of buffer | |
| 310 | |
| 311 The @dfn{buffer file name} is the name of the file that is visited in | |
| 312 that buffer. When a buffer is not visiting a file, its buffer file name | |
| 313 is @code{nil}. Most of the time, the buffer name is the same as the | |
| 314 nondirectory part of the buffer file name, but the buffer file name and | |
| 315 the buffer name are distinct and can be set independently. | |
| 316 @xref{Visiting Files}. | |
| 317 | |
| 318 @defun buffer-file-name &optional buffer | |
| 319 This function returns the absolute file name of the file that | |
| 320 @var{buffer} is visiting. If @var{buffer} is not visiting any file, | |
| 321 @code{buffer-file-name} returns @code{nil}. If @var{buffer} is not | |
| 322 supplied, it defaults to the current buffer. | |
| 323 | |
| 324 @example | |
| 325 @group | |
| 326 (buffer-file-name (other-buffer)) | |
| 327 @result{} "/usr/user/lewis/manual/files.texi" | |
| 328 @end group | |
| 329 @end example | |
| 330 @end defun | |
| 331 | |
| 332 @defvar buffer-file-name | |
| 333 This buffer-local variable contains the name of the file being visited | |
| 334 in the current buffer, or @code{nil} if it is not visiting a file. It | |
| 335 is a permanent local, unaffected by @code{kill-local-variables}. | |
| 336 | |
| 337 @example | |
| 338 @group | |
| 339 buffer-file-name | |
| 340 @result{} "/usr/user/lewis/manual/buffers.texi" | |
| 341 @end group | |
| 342 @end example | |
| 343 | |
| 344 It is risky to change this variable's value without doing various other | |
| 345 things. See the definition of @code{set-visited-file-name} in | |
| 346 @file{files.el}; some of the things done there, such as changing the | |
| 347 buffer name, are not strictly necessary, but others are essential to | |
| 348 avoid confusing XEmacs. | |
| 349 @end defvar | |
| 350 | |
| 351 @defvar buffer-file-truename | |
| 352 This buffer-local variable holds the truename of the file visited in the | |
| 353 current buffer, or @code{nil} if no file is visited. It is a permanent | |
| 354 local, unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
| 355 @end defvar | |
| 356 | |
| 357 @defvar buffer-file-number | |
| 358 This buffer-local variable holds the file number and directory device | |
| 359 number of the file visited in the current buffer, or @code{nil} if no | |
| 360 file or a nonexistent file is visited. It is a permanent local, | |
| 361 unaffected by @code{kill-local-variables}. @xref{Truenames}. | |
| 362 | |
| 363 The value is normally a list of the form @code{(@var{filenum} | |
| 364 @var{devnum})}. This pair of numbers uniquely identifies the file among | |
| 365 all files accessible on the system. See the function | |
| 366 @code{file-attributes}, in @ref{File Attributes}, for more information | |
| 367 about them. | |
| 368 @end defvar | |
| 369 | |
| 370 @defun get-file-buffer filename | |
| 371 This function returns the buffer visiting file @var{filename}. If | |
| 372 there is no such buffer, it returns @code{nil}. The argument | |
| 373 @var{filename}, which must be a string, is expanded (@pxref{File Name | |
| 374 Expansion}), then compared against the visited file names of all live | |
| 375 buffers. | |
| 376 | |
| 377 @example | |
| 378 @group | |
| 379 (get-file-buffer "buffers.texi") | |
| 380 @result{} #<buffer buffers.texi> | |
| 381 @end group | |
| 382 @end example | |
| 383 | |
| 384 In unusual circumstances, there can be more than one buffer visiting | |
| 385 the same file name. In such cases, this function returns the first | |
| 386 such buffer in the buffer list. | |
| 387 @end defun | |
| 388 | |
| 389 @deffn Command set-visited-file-name filename | |
| 390 If @var{filename} is a non-empty string, this function changes the | |
| 391 name of the file visited in current buffer to @var{filename}. (If the | |
| 392 buffer had no visited file, this gives it one.) The @emph{next time} | |
| 393 the buffer is saved it will go in the newly-specified file. This | |
| 394 command marks the buffer as modified, since it does not (as far as XEmacs | |
| 395 knows) match the contents of @var{filename}, even if it matched the | |
| 396 former visited file. | |
| 397 | |
| 398 If @var{filename} is @code{nil} or the empty string, that stands for | |
| 399 ``no visited file''. In this case, @code{set-visited-file-name} marks | |
| 400 the buffer as having no visited file. | |
| 401 | |
| 402 @c Wordy to avoid overfull hbox. --rjc 16mar92 | |
| 403 When the function @code{set-visited-file-name} is called interactively, it | |
| 404 prompts for @var{filename} in the minibuffer. | |
| 405 | |
| 406 See also @code{clear-visited-file-modtime} and | |
| 407 @code{verify-visited-file-modtime} in @ref{Buffer Modification}. | |
| 408 @end deffn | |
| 409 | |
| 410 @defvar list-buffers-directory | |
| 411 This buffer-local variable records a string to display in a buffer | |
| 412 listing in place of the visited file name, for buffers that don't have a | |
| 413 visited file name. Dired buffers use this variable. | |
| 414 @end defvar | |
| 415 | |
| 416 @node Buffer Modification | |
| 417 @section Buffer Modification | |
| 418 @cindex buffer modification | |
| 419 @cindex modification flag (of buffer) | |
| 420 | |
| 421 XEmacs keeps a flag called the @dfn{modified flag} for each buffer, to | |
| 422 record whether you have changed the text of the buffer. This flag is | |
| 423 set to @code{t} whenever you alter the contents of the buffer, and | |
| 424 cleared to @code{nil} when you save it. Thus, the flag shows whether | |
| 425 there are unsaved changes. The flag value is normally shown in the | |
| 426 modeline (@pxref{Modeline Variables}), and controls saving | |
| 427 (@pxref{Saving Buffers}) and auto-saving (@pxref{Auto-Saving}). | |
| 428 | |
| 429 Some Lisp programs set the flag explicitly. For example, the function | |
| 430 @code{set-visited-file-name} sets the flag to @code{t}, because the text | |
| 431 does not match the newly-visited file, even if it is unchanged from the | |
| 432 file formerly visited. | |
| 433 | |
| 434 The functions that modify the contents of buffers are described in | |
| 435 @ref{Text}. | |
| 436 | |
| 437 @defun buffer-modified-p &optional buffer | |
| 438 This function returns @code{t} if the buffer @var{buffer} has been modified | |
| 439 since it was last read in from a file or saved, or @code{nil} | |
| 440 otherwise. If @var{buffer} is not supplied, the current buffer | |
| 441 is tested. | |
| 442 @end defun | |
| 443 | |
| 444 | 444 @defun set-buffer-modified-p flag &optional buffer |
| 445 This function marks @var{buffer} as modified if @var{flag} is | |
| 428 | 446 non-@code{nil}, or as unmodified if the flag is @code{nil}. |
| 444 | 447 @var{buffer} defaults to the current buffer. |
| 428 | 448 |
| 449 Another effect of calling this function is to cause unconditional | |
| 450 redisplay of the modeline for the current buffer. In fact, the | |
| 451 function @code{redraw-modeline} works by doing this: | |
| 452 | |
| 453 @example | |
| 454 @group | |
| 455 (set-buffer-modified-p (buffer-modified-p)) | |
| 456 @end group | |
| 457 @end example | |
| 458 @end defun | |
| 459 | |
| 460 @c ARG is only in XEmacs | |
| 461 @deffn Command not-modified &optional arg | |
| 462 This command marks the current buffer as unmodified, and not needing | |
| 463 to be saved. (If @var{arg} is non-@code{nil}, the buffer is instead | |
| 464 marked as modified.) Don't use this function in programs, since it | |
| 465 prints a message in the echo area; use @code{set-buffer-modified-p} | |
| 466 (above) instead. | |
| 467 @end deffn | |
| 468 | |
| 469 @c Emacs 19 feature | |
| 470 @defun buffer-modified-tick &optional buffer | |
| 471 This function returns @var{buffer}`s modification-count. This is a | |
| 472 counter that increments every time the buffer is modified. If | |
| 473 @var{buffer} is @code{nil} (or omitted), the current buffer is used. | |
| 474 @end defun | |
| 475 | |
| 476 @node Modification Time | |
| 477 @section Comparison of Modification Time | |
| 478 @cindex comparison of modification time | |
| 444 | 479 @cindex modification time, comparison of |
| 428 | 480 |
| 481 Suppose that you visit a file and make changes in its buffer, and | |
| 482 meanwhile the file itself is changed on disk. At this point, saving the | |
| 483 buffer would overwrite the changes in the file. Occasionally this may | |
| 484 be what you want, but usually it would lose valuable information. XEmacs | |
| 485 therefore checks the file's modification time using the functions | |
| 486 described below before saving the file. | |
| 487 | |
| 488 @defun verify-visited-file-modtime buffer | |
| 489 This function compares what @var{buffer} has recorded for the | |
| 490 modification time of its visited file against the actual modification | |
| 491 time of the file as recorded by the operating system. The two should be | |
| 492 the same unless some other process has written the file since XEmacs | |
| 493 visited or saved it. | |
| 494 | |
| 495 The function returns @code{t} if the last actual modification time and | |
| 496 XEmacs's recorded modification time are the same, @code{nil} otherwise. | |
| 497 @end defun | |
| 498 | |
| 499 @defun clear-visited-file-modtime | |
| 500 This function clears out the record of the last modification time of | |
| 501 the file being visited by the current buffer. As a result, the next | |
| 502 attempt to save this buffer will not complain of a discrepancy in | |
| 503 file modification times. | |
| 504 | |
| 505 This function is called in @code{set-visited-file-name} and other | |
| 506 exceptional places where the usual test to avoid overwriting a changed | |
| 507 file should not be done. | |
| 508 @end defun | |
| 509 | |
| 510 @c Emacs 19 feature | |
| 511 @defun visited-file-modtime | |
| 512 This function returns the buffer's recorded last file modification time, | |
| 513 as a list of the form @code{(@var{high} . @var{low})}. (This is the | |
| 514 same format that @code{file-attributes} uses to return time values; see | |
| 515 @ref{File Attributes}.) | |
| 516 @end defun | |
| 517 | |
| 518 @c Emacs 19 feature | |
| 519 @defun set-visited-file-modtime &optional time | |
| 520 This function updates the buffer's record of the last modification time | |
| 521 of the visited file, to the value specified by @var{time} if @var{time} | |
| 522 is not @code{nil}, and otherwise to the last modification time of the | |
| 523 visited file. | |
| 524 | |
| 525 If @var{time} is not @code{nil}, it should have the form | |
| 526 @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in | |
|
4885
6772ce4d982b
Fix hash tables, #'member*, #'assoc*, #'eql compiler macros if bignums
Aidan Kehoe <kehoea@parhasard.net>
parents:
444
diff
changeset
|
527 either case containing two fixnums, each of which holds 16 bits of the |
| 428 | 528 time. |
| 529 | |
| 530 This function is useful if the buffer was not read from the file | |
| 531 normally, or if the file itself has been changed for some known benign | |
| 532 reason. | |
| 533 @end defun | |
| 534 | |
| 535 @defun ask-user-about-supersession-threat filename | |
| 536 @cindex obsolete buffer | |
| 537 This function is used to ask a user how to proceed after an attempt to | |
| 538 modify an obsolete buffer visiting file @var{filename}. An | |
| 539 @dfn{obsolete buffer} is an unmodified buffer for which the associated | |
| 540 file on disk is newer than the last save-time of the buffer. This means | |
| 541 some other program has probably altered the file. | |
| 542 | |
| 543 @kindex file-supersession | |
| 544 Depending on the user's answer, the function may return normally, in | |
| 545 which case the modification of the buffer proceeds, or it may signal a | |
| 546 @code{file-supersession} error with data @code{(@var{filename})}, in which | |
| 444 | 547 case the proposed buffer modification is not allowed. |
| 428 | 548 |
| 549 This function is called automatically by XEmacs on the proper | |
| 550 occasions. It exists so you can customize XEmacs by redefining it. | |
| 551 See the file @file{userlock.el} for the standard definition. | |
| 552 | |
| 553 See also the file locking mechanism in @ref{File Locks}. | |
| 554 @end defun | |
| 555 | |
| 556 @node Read Only Buffers | |
| 557 @section Read-Only Buffers | |
| 558 @cindex read-only buffer | |
| 559 @cindex buffer, read-only | |
| 560 | |
| 561 If a buffer is @dfn{read-only}, then you cannot change its contents, | |
| 444 | 562 although you may change your view of the contents by scrolling and |
| 428 | 563 narrowing. |
| 564 | |
| 565 Read-only buffers are used in two kinds of situations: | |
| 566 | |
| 567 @itemize @bullet | |
| 568 @item | |
| 569 A buffer visiting a write-protected file is normally read-only. | |
| 570 | |
| 571 Here, the purpose is to show the user that editing the buffer with the | |
| 572 aim of saving it in the file may be futile or undesirable. The user who | |
| 573 wants to change the buffer text despite this can do so after clearing | |
| 574 the read-only flag with @kbd{C-x C-q}. | |
| 575 | |
| 576 @item | |
| 577 Modes such as Dired and Rmail make buffers read-only when altering the | |
| 578 contents with the usual editing commands is probably a mistake. | |
| 579 | |
| 580 The special commands of these modes bind @code{buffer-read-only} to | |
| 581 @code{nil} (with @code{let}) or bind @code{inhibit-read-only} to | |
| 582 @code{t} around the places where they change the text. | |
| 583 @end itemize | |
| 584 | |
| 585 @defvar buffer-read-only | |
| 586 This buffer-local variable specifies whether the buffer is read-only. | |
| 587 The buffer is read-only if this variable is non-@code{nil}. | |
| 588 @end defvar | |
| 589 | |
| 590 @defvar inhibit-read-only | |
| 591 If this variable is non-@code{nil}, then read-only buffers and read-only | |
| 592 characters may be modified. Read-only characters in a buffer are those | |
| 593 that have non-@code{nil} @code{read-only} properties (either text | |
| 594 properties or extent properties). @xref{Extent Properties}, for more | |
| 595 information about text properties and extent properties. | |
| 596 | |
| 597 If @code{inhibit-read-only} is @code{t}, all @code{read-only} character | |
| 598 properties have no effect. If @code{inhibit-read-only} is a list, then | |
| 599 @code{read-only} character properties have no effect if they are members | |
| 600 of the list (comparison is done with @code{eq}). | |
| 601 @end defvar | |
| 602 | |
| 444 | 603 @deffn Command toggle-read-only &optional arg |
| 604 This command changes whether the current buffer is read-only. | |
| 605 Interactively, if a prefix arg @var{arg} is supplied, set the current | |
| 606 buffer read only if and only if @var{arg} is positive. | |
| 607 | |
| 608 This command is intended for interactive use only; don't use it in | |
| 609 programs. At any given point in a program, you should know whether you | |
| 610 want the read-only flag on or off; so you can set | |
| 611 @code{buffer-read-only} explicitly to the proper value, @code{t} or | |
| 612 @code{nil}. | |
| 428 | 613 @end deffn |
| 614 | |
| 444 | 615 @defun barf-if-buffer-read-only &optional buffer start end |
| 616 This function signals a @code{buffer-read-only} error if @var{buffer} is | |
| 617 read-only. @var{buffer} defaults to the current buffer. | |
| 618 @xref{Interactive Call}, for another way to signal an error if the | |
| 619 current buffer is read-only. | |
| 620 | |
| 621 If optional argument @var{start} is non-@code{nil}, all extents in the | |
| 622 buffer which overlap that part of the buffer are checked to ensure none | |
| 623 has a @code{read-only} property. (Extents that lie completely within the | |
| 624 range, however, are not checked.) @var{end} defaults to the value of | |
| 625 @var{start}. | |
| 626 | |
| 627 If @var{start} and @var{end} are equal, the range checked is | |
| 628 [@var{start}, @var{end}] (i.e. closed on both ends); otherwise, the | |
| 629 range checked is (@var{start}, @var{end}) \(open on both ends), except | |
| 630 that extents that lie completely within [@var{start}, @var{end}] are not | |
| 631 checked. See @code{extent-in-region-p} for a fuller discussion. | |
| 428 | 632 @end defun |
| 633 | |
| 634 @node The Buffer List | |
| 635 @section The Buffer List | |
| 636 @cindex buffer list | |
| 637 | |
| 638 The @dfn{buffer list} is a list of all live buffers. Creating a | |
| 639 buffer adds it to this list, and killing a buffer deletes it. The order | |
| 640 of the buffers in the list is based primarily on how recently each | |
| 641 buffer has been displayed in the selected window. Buffers move to the | |
| 642 front of the list when they are selected and to the end when they are | |
| 643 buried. Several functions, notably @code{other-buffer}, use this | |
| 644 ordering. A buffer list displayed for the user also follows this order. | |
| 645 | |
| 646 @c XEmacs feature | |
| 647 Every frame has its own order for the buffer list. Switching to a | |
| 648 new buffer inside of a particular frame changes the buffer list order | |
| 649 for that frame, but does not affect the buffer list order of any other | |
| 650 frames. In addition, there is a global, non-frame buffer list order | |
| 651 that is independent of the buffer list orders for any particular frame. | |
| 652 | |
| 653 Note that the different buffer lists all contain the same elements. It | |
| 654 is only the order of those elements that is different. | |
| 655 | |
| 656 @defun buffer-list &optional frame | |
| 657 This function returns a list of all buffers, including those whose | |
| 658 names begin with a space. The elements are actual buffers, not their | |
| 659 names. The order of the list is specific to @var{frame}, which | |
| 660 defaults to the current frame. If @var{frame} is @code{t}, the | |
| 661 global, non-frame ordering is returned instead. | |
| 662 | |
| 663 @example | |
| 664 @group | |
| 665 (buffer-list) | |
| 666 @result{} (#<buffer buffers.texi> | |
| 667 #<buffer *Minibuf-1*> #<buffer buffer.c> | |
| 668 #<buffer *Help*> #<buffer TAGS>) | |
| 669 @end group | |
| 670 | |
| 671 @group | |
| 672 ;; @r{Note that the name of the minibuffer} | |
| 673 ;; @r{begins with a space!} | |
| 674 (mapcar (function buffer-name) (buffer-list)) | |
| 444 | 675 @result{} ("buffers.texi" " *Minibuf-1*" |
| 428 | 676 "buffer.c" "*Help*" "TAGS") |
| 677 @end group | |
| 678 @end example | |
| 679 | |
| 680 Buffers appear earlier in the list if they were current more recently. | |
| 681 | |
| 682 This list is a copy of a list used inside XEmacs; modifying it has no | |
| 683 effect on the buffers. | |
| 684 @end defun | |
| 685 | |
| 686 @defun other-buffer &optional buffer-or-name frame visible-ok | |
| 687 This function returns the first buffer in the buffer list other than | |
| 688 @var{buffer-or-name}, in @var{frame}'s ordering for the buffer list. | |
| 689 (@var{frame} defaults to the current frame. If @var{frame} is | |
| 690 @code{t}, then the global, non-frame ordering is used.) Usually this is | |
| 691 the buffer most recently shown in the selected window, aside from | |
| 692 @var{buffer-or-name}. Buffers are moved to the front of the list when | |
| 693 they are selected and to the end when they are buried. Buffers whose | |
| 694 names start with a space are not considered. | |
| 695 | |
| 696 If @var{buffer-or-name} is not supplied (or if it is not a buffer), | |
| 697 then @code{other-buffer} returns the first buffer on the buffer list | |
| 698 that is not visible in any window in a visible frame. | |
| 699 | |
| 700 If the selected frame has a non-@code{nil} @code{buffer-predicate} | |
| 701 property, then @code{other-buffer} uses that predicate to decide which | |
| 702 buffers to consider. It calls the predicate once for each buffer, and | |
| 703 if the value is @code{nil}, that buffer is ignored. @xref{X Frame | |
| 704 Properties}. | |
| 705 | |
| 706 @c Emacs 19 feature | |
| 707 If @var{visible-ok} is @code{nil}, @code{other-buffer} avoids returning | |
| 708 a buffer visible in any window on any visible frame, except as a last | |
| 709 resort. If @var{visible-ok} is non-@code{nil}, then it does not matter | |
| 710 whether a buffer is displayed somewhere or not. | |
| 711 | |
| 712 If no suitable buffer exists, the buffer @samp{*scratch*} is returned | |
| 713 (and created, if necessary). | |
| 714 | |
| 715 Note that in FSF Emacs 19, there is no @var{frame} argument, and | |
| 716 @var{visible-ok} is the second argument instead of the third. | |
| 717 @end defun | |
| 718 | |
| 719 @deffn Command list-buffers &optional files-only | |
| 720 This function displays a listing of the names of existing buffers. It | |
| 721 clears the buffer @samp{*Buffer List*}, then inserts the listing into | |
| 722 that buffer and displays it in a window. @code{list-buffers} is | |
| 723 intended for interactive use, and is described fully in @cite{The XEmacs | |
| 724 Reference Manual}. It returns @code{nil}. | |
| 725 @end deffn | |
| 726 | |
| 444 | 727 @deffn Command bury-buffer &optional buffer-or-name before |
| 428 | 728 This function puts @var{buffer-or-name} at the end of the buffer list |
| 729 without changing the order of any of the other buffers on the list. | |
| 730 This buffer therefore becomes the least desirable candidate for | |
| 731 @code{other-buffer} to return. | |
| 732 | |
| 733 If @var{buffer-or-name} is @code{nil} or omitted, this means to bury the | |
| 734 current buffer. In addition, if the buffer is displayed in the selected | |
| 735 window, this switches to some other buffer (obtained using | |
| 736 @code{other-buffer}) in the selected window. But if the buffer is | |
| 737 displayed in some other window, it remains displayed there. | |
| 738 | |
| 739 If you wish to replace a buffer in all the windows that display it, use | |
| 740 @code{replace-buffer-in-windows}. @xref{Buffers and Windows}. | |
| 741 @end deffn | |
| 742 | |
| 743 @node Creating Buffers | |
| 744 @section Creating Buffers | |
| 745 @cindex creating buffers | |
| 746 @cindex buffers, creating | |
| 747 | |
| 748 This section describes the two primitives for creating buffers. | |
| 749 @code{get-buffer-create} creates a buffer if it finds no existing buffer | |
| 750 with the specified name; @code{generate-new-buffer} always creates a new | |
| 751 buffer and gives it a unique name. | |
| 752 | |
| 753 Other functions you can use to create buffers include | |
| 754 @code{with-output-to-temp-buffer} (@pxref{Temporary Displays}) and | |
| 755 @code{create-file-buffer} (@pxref{Visiting Files}). Starting a | |
| 756 subprocess can also create a buffer (@pxref{Processes}). | |
| 757 | |
| 758 @defun get-buffer-create name | |
| 759 This function returns a buffer named @var{name}. It returns an existing | |
| 760 buffer with that name, if one exists; otherwise, it creates a new | |
| 761 buffer. The buffer does not become the current buffer---this function | |
| 762 does not change which buffer is current. | |
| 763 | |
| 764 An error is signaled if @var{name} is not a string. | |
| 765 | |
| 766 @example | |
| 767 @group | |
| 768 (get-buffer-create "foo") | |
| 769 @result{} #<buffer foo> | |
| 770 @end group | |
| 771 @end example | |
| 772 | |
| 773 The major mode for the new buffer is set to Fundamental mode. The | |
| 774 variable @code{default-major-mode} is handled at a higher level. | |
| 775 @xref{Auto Major Mode}. | |
| 776 @end defun | |
| 777 | |
| 778 @defun generate-new-buffer name | |
| 779 This function returns a newly created, empty buffer, but does not make | |
| 780 it current. If there is no buffer named @var{name}, then that is the | |
| 781 name of the new buffer. If that name is in use, this function adds | |
| 782 suffixes of the form @samp{<@var{n}>} to @var{name}, where @var{n} is an | |
| 783 integer. It tries successive integers starting with 2 until it finds an | |
| 784 available name. | |
| 785 | |
| 786 An error is signaled if @var{name} is not a string. | |
| 787 | |
| 788 @example | |
| 789 @group | |
| 790 (generate-new-buffer "bar") | |
| 791 @result{} #<buffer bar> | |
| 792 @end group | |
| 793 @group | |
| 794 (generate-new-buffer "bar") | |
| 795 @result{} #<buffer bar<2>> | |
| 796 @end group | |
| 797 @group | |
| 798 (generate-new-buffer "bar") | |
| 799 @result{} #<buffer bar<3>> | |
| 800 @end group | |
| 801 @end example | |
| 802 | |
| 803 The major mode for the new buffer is set to Fundamental mode. The | |
| 804 variable @code{default-major-mode} is handled at a higher level. | |
| 805 @xref{Auto Major Mode}. | |
| 806 | |
| 807 See the related function @code{generate-new-buffer-name} in @ref{Buffer | |
| 808 Names}. | |
| 809 @end defun | |
| 810 | |
| 811 @node Killing Buffers | |
| 812 @section Killing Buffers | |
| 813 @cindex killing buffers | |
| 814 @cindex buffers, killing | |
| 815 | |
| 816 @dfn{Killing a buffer} makes its name unknown to XEmacs and makes its | |
| 817 text space available for other use. | |
| 818 | |
| 819 The buffer object for the buffer that has been killed remains in | |
| 820 existence as long as anything refers to it, but it is specially marked | |
| 821 so that you cannot make it current or display it. Killed buffers retain | |
| 822 their identity, however; two distinct buffers, when killed, remain | |
| 823 distinct according to @code{eq}. | |
| 824 | |
| 825 If you kill a buffer that is current or displayed in a window, XEmacs | |
| 826 automatically selects or displays some other buffer instead. This means | |
| 827 that killing a buffer can in general change the current buffer. | |
| 828 Therefore, when you kill a buffer, you should also take the precautions | |
| 829 associated with changing the current buffer (unless you happen to know | |
| 830 that the buffer being killed isn't current). @xref{Current Buffer}. | |
| 831 | |
| 832 If you kill a buffer that is the base buffer of one or more indirect | |
| 833 buffers, the indirect buffers are automatically killed as well. | |
| 834 | |
| 835 The @code{buffer-name} of a killed buffer is @code{nil}. To test | |
| 836 whether a buffer has been killed, you can either use this feature | |
| 837 or the function @code{buffer-live-p}. | |
| 838 | |
| 444 | 839 @defun buffer-live-p object |
| 840 This function returns @code{t} if @var{object} is an editor buffer that | |
| 841 has not been deleted, @code{nil} otherwise. | |
| 428 | 842 @end defun |
| 843 | |
| 844 @deffn Command kill-buffer buffer-or-name | |
| 845 This function kills the buffer @var{buffer-or-name}, freeing all its | |
| 846 memory for use as space for other buffers. (Emacs version 18 and older | |
| 847 was unable to return the memory to the operating system.) It returns | |
| 444 | 848 @code{nil}. The argument @var{buffer-or-name} may be a buffer or the |
| 849 name of one. | |
| 428 | 850 |
| 851 Any processes that have this buffer as the @code{process-buffer} are | |
| 852 sent the @code{SIGHUP} signal, which normally causes them to terminate. | |
| 853 (The basic meaning of @code{SIGHUP} is that a dialup line has been | |
| 854 disconnected.) @xref{Deleting Processes}. | |
| 855 | |
| 856 If the buffer is visiting a file and contains unsaved changes, | |
| 857 @code{kill-buffer} asks the user to confirm before the buffer is killed. | |
| 858 It does this even if not called interactively. To prevent the request | |
| 859 for confirmation, clear the modified flag before calling | |
| 860 @code{kill-buffer}. @xref{Buffer Modification}. | |
| 861 | |
| 862 Killing a buffer that is already dead has no effect. | |
| 863 | |
| 864 @smallexample | |
| 865 (kill-buffer "foo.unchanged") | |
| 866 @result{} nil | |
| 867 (kill-buffer "foo.changed") | |
| 868 | |
| 869 ---------- Buffer: Minibuffer ---------- | |
| 870 Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} | |
| 871 ---------- Buffer: Minibuffer ---------- | |
| 872 | |
| 873 @result{} nil | |
| 874 @end smallexample | |
| 875 @end deffn | |
| 876 | |
| 877 @defvar kill-buffer-query-functions | |
| 878 After confirming unsaved changes, @code{kill-buffer} calls the functions | |
| 879 in the list @code{kill-buffer-query-functions}, in order of appearance, | |
| 880 with no arguments. The buffer being killed is the current buffer when | |
| 881 they are called. The idea is that these functions ask for confirmation | |
| 882 from the user for various nonstandard reasons. If any of them returns | |
| 883 @code{nil}, @code{kill-buffer} spares the buffer's life. | |
| 884 @end defvar | |
| 885 | |
| 886 @defvar kill-buffer-hook | |
| 887 This is a normal hook run by @code{kill-buffer} after asking all the | |
| 888 questions it is going to ask, just before actually killing the buffer. | |
| 889 The buffer to be killed is current when the hook functions run. | |
| 890 @xref{Hooks}. | |
| 891 @end defvar | |
| 892 | |
| 893 @defvar buffer-offer-save | |
| 894 This variable, if non-@code{nil} in a particular buffer, tells | |
| 895 @code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to | |
| 896 save that buffer, just as they offer to save file-visiting buffers. The | |
| 897 variable @code{buffer-offer-save} automatically becomes buffer-local | |
| 898 when set for any reason. @xref{Buffer-Local Variables}. | |
| 899 @end defvar | |
| 900 | |
| 901 @node Indirect Buffers | |
| 902 @section Indirect Buffers | |
| 903 @cindex indirect buffers | |
| 904 @cindex base buffer | |
| 905 | |
| 906 An @dfn{indirect buffer} shares the text of some other buffer, which | |
| 907 is called the @dfn{base buffer} of the indirect buffer. In some ways it | |
| 908 is the analogue, for buffers, of a symbolic link among files. The base | |
| 909 buffer may not itself be an indirect buffer. One base buffer may have | |
| 910 several @dfn{indirect children}. | |
| 911 | |
| 912 The text of the indirect buffer is always identical to the text of its | |
| 913 base buffer; changes made by editing either one are visible immediately | |
| 914 in the other. | |
| 915 | |
| 916 But in all other respects, the indirect buffer and its base buffer are | |
| 917 completely separate. They have different names, different values of | |
| 918 point and mark, different narrowing, different markers and extents | |
| 919 (though inserting or deleting text in either buffer relocates the | |
| 920 markers and extents for both), different major modes, and different | |
| 921 local variables. Unlike in FSF Emacs, XEmacs indirect buffers do not | |
| 922 automatically share text properties among themselves and their base | |
| 923 buffer. | |
| 924 | |
| 925 An indirect buffer cannot visit a file, but its base buffer can. If | |
| 926 you try to save the indirect buffer, that actually works by saving the | |
| 927 base buffer. | |
| 928 | |
| 929 Killing an indirect buffer has no effect on its base buffer. Killing | |
| 930 the base buffer kills all its indirect children. | |
| 931 | |
| 932 @deffn Command make-indirect-buffer base-buffer name | |
| 933 This creates an indirect buffer named @var{name} whose base buffer | |
| 934 is @var{base-buffer}. The argument @var{base-buffer} may be a buffer | |
| 935 or a string. | |
| 444 | 936 |
| 428 | 937 If @var{base-buffer} is an indirect buffer, its base buffer is used as |
| 938 the base for the new buffer. | |
| 939 | |
| 940 @example | |
| 941 @group | |
| 942 (make-indirect-buffer "*scratch*" "indirect") | |
| 943 @result{} #<buffer "indirect"> | |
| 944 @end group | |
| 945 @end example | |
| 946 @end deffn | |
| 947 | |
| 948 @defun buffer-base-buffer &optional buffer | |
| 949 This function returns the base buffer of @var{buffer}. If @var{buffer} | |
| 950 is not indirect, the value is @code{nil}. Otherwise, the value is | |
| 951 another buffer, which is never an indirect buffer. If @var{buffer} is | |
| 952 not supplied, it defaults to the current buffer. | |
| 953 | |
| 954 @example | |
| 955 @group | |
| 956 (buffer-base-buffer (get-buffer "indirect")) | |
| 957 @result{} #<buffer "*scratch*"> | |
| 958 @end group | |
| 959 @end example | |
| 960 @end defun | |
| 961 | |
| 962 @defun buffer-indirect-children &optional buffer | |
| 963 This function returns a list of all indirect buffers whose base buffer | |
| 964 is @var{buffer}. If @var{buffer} is indirect, the return value will | |
| 444 | 965 always be @code{nil}; see @code{make-indirect-buffer}. If @var{buffer} is not |
| 428 | 966 supplied, it defaults to the current buffer. |
| 967 | |
| 968 @example | |
| 969 @group | |
| 970 (buffer-indirect-children (get-buffer "*scratch*")) | |
| 971 @result{} (#<buffer "indirect">) | |
| 972 @end group | |
| 973 @end example | |
| 974 @end defun |