From 619fb950d62377bf562f597ff81264d3386cc502 Mon Sep 17 00:00:00 2001 From: Luc Teirlinck Date: Wed, 14 Apr 2004 02:48:08 +0000 Subject: Various changes in addition to: (Buffer File Name): Add `find-buffer-visiting'. (Buffer Modification): Mention optional ARG to `not-modified'. (Indirect Buffers): Mention optional CLONE argument to `make-indirect-buffer'. --- lispref/ChangeLog | 17 +++++ lispref/buffers.texi | 207 ++++++++++++++++++++++++++++++++++++--------------- 2 files changed, 164 insertions(+), 60 deletions(-) diff --git a/lispref/ChangeLog b/lispref/ChangeLog index aa20df1030..47a987fdb7 100644 --- a/lispref/ChangeLog +++ b/lispref/ChangeLog @@ -1,3 +1,20 @@ +2004-04-13 Luc Teirlinck + + * buffers.texi: Various changes in addition to: + (Buffer File Name): Add `find-buffer-visiting'. + (Buffer Modification): Mention optional ARG to `not-modified'. + (Indirect Buffers): Mention optional CLONE argument to + `make-indirect-buffer'. + + * files.texi: Various changes in addition to: + (Visiting Functions): `find-file-hook' is now a normal hook. + (File Name Expansion): Explain difference between the way that + `expand-file-name' and `file-truename' treat `..'. + (Contents of Directories): Mention optional ID-FORMAT argument to + `directory-files-and-attributes'. + (Format Conversion): Mention new optional CONFIRM argument to + `format-write-file'. + 2004-04-12 Miles Bader * macros.texi (Expansion): Add description of `macroexpand-all'. diff --git a/lispref/buffers.texi b/lispref/buffers.texi index 4ca375a5c2..0eee01d980 100644 --- a/lispref/buffers.texi +++ b/lispref/buffers.texi @@ -215,12 +215,16 @@ of course. Instead, whichever buffer was current just before exit remains current. @end defspec -@defmac with-current-buffer buffer body... +@defmac with-current-buffer buffer-or-name body... The @code{with-current-buffer} macro saves the identity of the current -buffer, makes @var{buffer} current, evaluates the @var{body} forms, and -finally restores the buffer. The return value is the value of the last -form in @var{body}. The current buffer is restored even in case of an -abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). +buffer, makes @var{buffer-or-name} current, evaluates the @var{body} +forms, and finally restores the buffer. The return value is the value +of the last form in @var{body}. The current buffer is restored even +in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal +Exits}). + +An error is signaled if @var{buffer-or-name} does not identify an +existing buffer. @end defmac @anchor{Definition of with-temp-buffer} @@ -237,9 +241,10 @@ return the contents of the temporary buffer by using The current buffer is restored even in case of an abnormal exit via @code{throw} or error (@pxref{Nonlocal Exits}). -@end defmac -See also @code{with-temp-file} in @ref{Writing to Files}. +See also @code{with-temp-file} in @ref{Definition of with-temp-file,, +Writing to Files}. +@end defmac @node Buffer Names @section Buffer Names @@ -293,8 +298,7 @@ foo @deffn Command rename-buffer newname &optional unique This function renames the current buffer to @var{newname}. An error -is signaled if @var{newname} is not a string, or if there is already a -buffer with that name. The function returns @var{newname}. +is signaled if @var{newname} is not a string. @c Emacs 19 feature Ordinarily, @code{rename-buffer} signals an error if @var{newname} is @@ -302,6 +306,8 @@ already in use. However, if @var{unique} is non-@code{nil}, it modifies @var{newname} to make a name that is not in use. Interactively, you can make @var{unique} non-@code{nil} with a numeric prefix argument. (This is how the command @code{rename-uniquely} is implemented.) + +This function returns the name actually given to the buffer. @end deffn @defun get-buffer buffer-or-name @@ -330,11 +336,12 @@ See also the function @code{get-buffer-create} in @ref{Creating Buffers}. @end defun @c Emacs 19 feature -@defun generate-new-buffer-name starting-name &rest ignore +@defun generate-new-buffer-name starting-name &optional ignore This function returns a name that would be unique for a new buffer---but does not create the buffer. It starts with @var{starting-name}, and produces a name not currently in use for any buffer by appending a -number inside of @samp{<@dots{}>}. +number inside of @samp{<@dots{}>}. It starts at 2 and keeps +incrementing the number until it is not the name of an existing buffer. If the optional second argument @var{ignore} is non-@code{nil}, it should be a string; it makes a difference if it is a name in the @@ -404,9 +411,11 @@ Emacs. @end defvar @defvar buffer-file-truename -This buffer-local variable holds the truename of the file visited in the -current buffer, or @code{nil} if no file is visited. It is a permanent -local, unaffected by @code{kill-all-local-variables}. @xref{Truenames}. +This buffer-local variable holds the abbreviated truename of the file +visited in the current buffer, or @code{nil} if no file is visited. +It is a permanent local, unaffected by +@code{kill-all-local-variables}. @xref{Truenames}, and +@ref{Definition of abbreviate-file-name}. @end defvar @defvar buffer-file-number @@ -420,6 +429,9 @@ The value is normally a list of the form @code{(@var{filenum} all files accessible on the system. See the function @code{file-attributes}, in @ref{File Attributes}, for more information about them. + +If @code{buffer-file-name} is the name of a symbolic link, then both +numbers refer to the recursive target. @end defvar @defun get-file-buffer filename @@ -427,7 +439,9 @@ This function returns the buffer visiting file @var{filename}. If there is no such buffer, it returns @code{nil}. The argument @var{filename}, which must be a string, is expanded (@pxref{File Name Expansion}), then compared against the visited file names of all live -buffers. +buffers. Note that the buffer's @code{buffer-file-name} must match +the expansion of @var{filename} exactly. This function will not +recognize other names for the same file. @example @group @@ -441,6 +455,18 @@ the same file name. In such cases, this function returns the first such buffer in the buffer list. @end defun +@defun find-buffer-visiting filename &optional predicate +This is like @code{get-file-buffer}, except that it can return any +buffer visiting the file @emph{possibly under a different name}. That +is, the buffer's @code{buffer-file-name} does not need to match the +expansion of @var{filename} exactly, it only needs to refer to the +same file. If @var{predicate} is non-@code{nil}, it should be a +function of one argument, a buffer visiting @var{filename}. The +buffer is only considered a suitable return value if @var{predicate} +returns non-@code{nil}. If it can not find a suitable buffer to +return, @code{find-buffer-visiting} returns @code{nil}. +@end defun + @deffn Command set-visited-file-name filename &optional no-query along-with-file If @var{filename} is a non-empty string, this function changes the name of the file visited in the current buffer to @var{filename}. (If the @@ -455,14 +481,24 @@ use. If @var{filename} is @code{nil} or the empty string, that stands for ``no visited file''. In this case, @code{set-visited-file-name} marks -the buffer as having no visited file. - -Normally, this function asks the user for confirmation if the specified -file already exists. If @var{no-query} is non-@code{nil}, that prevents -asking this question. - -If @var{along-with-file} is non-@code{nil}, that means to assume that the -former visited file has been renamed to @var{filename}. +the buffer as having no visited file, without changing the buffer's +modified flag. + +Normally, this function asks the user for confirmation if there +already is a buffer visiting @var{filename}. If @var{no-query} is +non-@code{nil}, that prevents asking this question. If there already +is a buffer visiting @var{filename}, and the user confirms or +@var{query} is non-@code{nil}, this function makes the new buffer name +unique by appending a number inside of @samp{<@dots{}>} to @var{filename}. + +If @var{along-with-file} is non-@code{nil}, that means to assume that +the former visited file has been renamed to @var{filename}. In this +case, the command does not change the buffer's modified flag, nor the +buffer's recorded last file modification time as reported by +@code{visited-file-modtime} (@pxref{Modification Time}). If +@var{along-with-file} is @code{nil}, this function clears the recorded +last file modification time, after which @code{visited-file-modtime} +returns zero. @c Wordy to avoid overfull hbox. --rjc 16mar92 When the function @code{set-visited-file-name} is called interactively, it @@ -523,10 +559,11 @@ Like @code{set-buffer-modified-p}, but does not force redisplay of mode lines. @end defun -@deffn Command not-modified -This command marks the current buffer as unmodified, and not needing to -be saved. With prefix arg, it marks the buffer as modified, so that it -will be saved at the next suitable occasion. +@deffn Command not-modified &optional arg +This command marks the current buffer as unmodified, and not needing +to be saved. If @var{arg} is non-@code{nil}, it marks the buffer as +modified, so that it will be saved at the next suitable occasion. +Interactively, @var{arg} is the prefix argument. Don't use this function in programs, since it prints a message in the echo area; use @code{set-buffer-modified-p} (above) instead. @@ -537,6 +574,7 @@ echo area; use @code{set-buffer-modified-p} (above) instead. This function returns @var{buffer}'s modification-count. This is a counter that increments every time the buffer is modified. If @var{buffer} is @code{nil} (or omitted), the current buffer is used. +The counter can wrap around occasionally. @end defun @node Modification Time @@ -561,6 +599,16 @@ visited or saved it. The function returns @code{t} if the last actual modification time and Emacs's recorded modification time are the same, @code{nil} otherwise. +It also returns @code{t} if the buffer has no recorded last +modification time, that is if @code{visited-file-modtime} would return +zero. + +It always returns @code{t} for buffers that are not visiting a file, +even if @code{visited-file-modtime} returns a non-zero value. For +instance, it always returns @code{t} for dired buffers. It returns +@code{t} for buffers that are visiting a file that does not exist and +never existed, but @code{nil} for file-visiting buffers whose file has +been deleted. @end defun @defun clear-visited-file-modtime @@ -576,10 +624,30 @@ file should not be done. @c Emacs 19 feature @defun visited-file-modtime -This function returns the buffer's recorded last file modification time, -as a list of the form @code{(@var{high} . @var{low})}. (This is the -same format that @code{file-attributes} uses to return time values; see -@ref{File Attributes}.) +This function returns the current buffer's recorded last file +modification time, as a list of the form @code{(@var{high} . +@var{low})}. (This is the same format that @code{file-attributes} +uses to return time values; see @ref{File Attributes}.) + +The function returns zero if the buffer has no recorded last +modification time, which can happen, for instance, if the record has +been explicitly cleared by @code{clear-visited-file-modtime} or if the +buffer is not visiting a file. Note, however, that +@code{visited-file-modtime} can return a non-zero value for some +buffers that are not visiting files, but are nevertheless closely +associated with a file. This happens, for instance, with dired +buffers listing a directory. For such buffers, +@code{visited-file-modtime} returns the last modification time of that +directory, as recorded by dired. + +For a new buffer visiting a not yet existing file, @var{high} is +@minus{}1 and @var{low} is 65535, that is, +@ifnottex +@w{2**16 - 1.} +@end ifnottex +@tex +@math{2^{16}-1}. +@end tex @end defun @c Emacs 19 feature @@ -589,7 +657,7 @@ of the visited file, to the value specified by @var{time} if @var{time} is not @code{nil}, and otherwise to the last modification time of the visited file. -If @var{time} is not @code{nil}, it should have the form +If @var{time} is neither @code{nil} nor zero, it should have the form @code{(@var{high} . @var{low})} or @code{(@var{high} @var{low})}, in either case containing two integers, each of which holds 16 bits of the time. @@ -655,12 +723,13 @@ The buffer is read-only if this variable is non-@code{nil}. @end defvar @defvar inhibit-read-only -If this variable is non-@code{nil}, then read-only buffers and read-only -characters may be modified. Read-only characters in a buffer are those -that have non-@code{nil} @code{read-only} properties (either text -properties or overlay properties). @xref{Special Properties}, for more -information about text properties. @xref{Overlays}, for more -information about overlays and their properties. +If this variable is non-@code{nil}, then read-only buffers and, +depending on the actual value, some or all read-only characters may be +modified. Read-only characters in a buffer are those that have +non-@code{nil} @code{read-only} properties (either text properties or +overlay properties). @xref{Special Properties}, for more information +about text properties. @xref{Overlays}, for more information about +overlays and their properties. If @code{inhibit-read-only} is @code{t}, all @code{read-only} character properties have no effect. If @code{inhibit-read-only} is a list, then @@ -816,12 +885,14 @@ buffer and gives it a unique name. subprocess can also create a buffer (@pxref{Processes}). @defun get-buffer-create name -This function returns a buffer named @var{name}. It returns an existing +This function returns a buffer named @var{name}. It returns a live buffer with that name, if one exists; otherwise, it creates a new buffer. The buffer does not become the current buffer---this function does not change which buffer is current. -An error is signaled if @var{name} is not a string. +If @var{name} is a buffer instead of a string, it is returned, even if +it is dead. An error is signaled if @var{name} is neither a string +nor a buffer. @example @group @@ -830,8 +901,8 @@ An error is signaled if @var{name} is not a string. @end group @end example -The major mode for the new buffer is set to Fundamental mode. The -variable @code{default-major-mode} is handled at a higher level. +The major mode for a newly created buffer is set to Fundamental mode. +The variable @code{default-major-mode} is handled at a higher level. @xref{Auto Major Mode}. @end defun @@ -905,8 +976,8 @@ this feature to test whether a buffer has been killed: @deffn Command kill-buffer buffer-or-name This function kills the buffer @var{buffer-or-name}, freeing all its -memory for other uses or to be returned to the operating system. It -returns @code{nil}. +memory for other uses or to be returned to the operating system. If +@var{buffer-or-name} is @code{nil}, it kills the current buffer. Any processes that have this buffer as the @code{process-buffer} are sent the @code{SIGHUP} signal, which normally causes them to terminate. @@ -921,16 +992,20 @@ for confirmation, clear the modified flag before calling Killing a buffer that is already dead has no effect. +This function returns @code{t} if it actually killed the buffer. It +returns @code{nil} if the user refuses to confirm or if +@var{buffer-or-name} was already dead. + @smallexample (kill-buffer "foo.unchanged") - @result{} nil + @result{} t (kill-buffer "foo.changed") ---------- Buffer: Minibuffer ---------- Buffer foo.changed modified; kill anyway? (yes or no) @kbd{yes} ---------- Buffer: Minibuffer ---------- - @result{} nil + @result{} t @end smallexample @end deffn @@ -953,13 +1028,15 @@ is not cleared by changing major modes. @defvar buffer-offer-save This variable, if non-@code{nil} in a particular buffer, tells -@code{save-buffers-kill-emacs} and @code{save-some-buffers} to offer to -save that buffer, just as they offer to save file-visiting buffers. The -variable @code{buffer-offer-save} automatically becomes buffer-local -when set for any reason. @xref{Buffer-Local Variables}. +@code{save-buffers-kill-emacs} and @code{save-some-buffers} (if the +second optional argument to that function is @code{t}) to offer to +save that buffer, just as they offer to save file-visiting buffers. +@xref{Definition of save-some-buffers}. The variable +@code{buffer-offer-save} automatically becomes buffer-local when set +for any reason. @xref{Buffer-Local Variables}. @end defvar -@defun buffer-live-p buffer +@defun buffer-live-p object This function returns @code{t} if @var{object} is a buffer which has not been killed, @code{nil} otherwise. @end defun @@ -994,19 +1071,29 @@ buffer. the base buffer effectively kills the indirect buffer in that it cannot ever again be the current buffer. -@deffn Command make-indirect-buffer base-buffer name -This creates an indirect buffer named @var{name} whose base buffer -is @var{base-buffer}. The argument @var{base-buffer} may be a buffer -or a string. +@deffn Command make-indirect-buffer base-buffer name &optional clone +This creates and returns an indirect buffer named @var{name} whose +base buffer is @var{base-buffer}. The argument @var{base-buffer} may +be a live buffer or the name (a string) of an existing buffer. If +@var{name} is the name of an existing buffer, an error is signaled. + +If @var{clone} is non-@code{nil}, then the indirect buffer originally +shares the ``state'' of @var{base-buffer} such as major mode, minor +modes, buffer local variables and so on. If @var{clone} is omitted +or @code{nil} the indirect buffer's state is set to the default state +for new buffers. If @var{base-buffer} is an indirect buffer, its base buffer is used as -the base for the new buffer. +the base for the new buffer. If, in addition, @var{clone} is +non-@code{nil}, the initial state is copied from the actual base +buffer, not from @var{base-buffer}. @end deffn -@defun buffer-base-buffer buffer -This function returns the base buffer of @var{buffer}. If @var{buffer} -is not indirect, the value is @code{nil}. Otherwise, the value is -another buffer, which is never an indirect buffer. +@defun buffer-base-buffer &optional buffer +This function returns the base buffer of @var{buffer}, which defaults +to the current buffer. If @var{buffer} is not indirect, the value is +@code{nil}. Otherwise, the value is another buffer, which is never an +indirect buffer. @end defun @node Buffer Gap -- cgit v1.2.3