-This is Info file ../../info/lispref.info, produced by Makeinfo version
-1.68 from the input file lispref.texi.
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
+lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
START-INFO-DIR-ENTRY
Foundation instead of in the original English.
\1f
+File: lispref.info, Node: User Name Completion, Prev: File Name Completion, Up: File Names
+
+User Name Completion
+--------------------
+
+ This section describes low-level subroutines for completing a user
+name. For other completion functions, see *Note Completion::.
+
+ - Function: user-name-all-completions partial-username
+ This function returns a list of all possible completions for a user
+ whose name starts with PARTIAL-USERNAME. The order of the
+ completions is unpredictable and conveys no useful information.
+
+ The argument PARTIAL-USERNAME must be a partial user name
+ containing no tilde character and no slash.
+
+ - Function: user-name-completion username
+ This function completes the user name USERNAME. It returns the
+ longest prefix common to all user names that start with USERNAME.
+
+ If only one match exists and USERNAME matches it exactly, the
+ function returns `t'. The function returns `nil' if no user name
+ starting with USERNAME exists.
+
+ - Function: user-name-completion-1 username
+ This function completes the user name USERNAME, like
+ `user-name-completion', differing only in the return value. This
+ function returns the cons of the completion returned by
+ `user-name-completion', and a boolean indicating whether that
+ completion was unique.
+
+\1f
+File: lispref.info, Node: Contents of Directories, Next: Create/Delete Dirs, Prev: File Names, Up: Files
+
+Contents of Directories
+=======================
+
+ A directory is a kind of file that contains other files entered under
+various names. Directories are a feature of the file system.
+
+ XEmacs can list the names of the files in a directory as a Lisp list,
+or display the names in a buffer using the `ls' shell command. In the
+latter case, it can optionally display information about each file,
+depending on the value of switches passed to the `ls' command.
+
+ - Function: directory-files directory &optional full-name match-regexp
+ nosort files-only
+ This function returns a list of the names of the files in the
+ directory DIRECTORY. By default, the list is in alphabetical
+ order.
+
+ If FULL-NAME is non-`nil', the function returns the files'
+ absolute file names. Otherwise, it returns just the names
+ relative to the specified directory.
+
+ If MATCH-REGEXP is non-`nil', this function returns only those
+ file names that contain that regular expression--the other file
+ names are discarded from the list.
+
+ If NOSORT is non-`nil', `directory-files' does not sort the list,
+ so you get the file names in no particular order. Use this if you
+ want the utmost possible speed and don't care what order the files
+ are processed in. If the order of processing is visible to the
+ user, then the user will probably be happier if you do sort the
+ names.
+
+ If FILES-ONLY is the symbol `t', then only the "files" in the
+ directory will be returned; subdirectories will be excluded. If
+ FILES-ONLY is not `nil' and not `t', then only the subdirectories
+ will be returned. Otherwise, if FILES-ONLY is `nil' (the default)
+ then both files and subdirectories will be returned.
+
+ (directory-files "~lewis")
+ => ("#foo#" "#foo.el#" "." ".."
+ "dired-mods.el" "files.texi"
+ "files.texi.~1~")
+
+ An error is signaled if DIRECTORY is not the name of a directory
+ that can be read.
+
+ - Function: insert-directory file switches &optional wildcard
+ full-directory-p
+ This function inserts (in the current buffer) a directory listing
+ for directory FILE, formatted with `ls' according to SWITCHES. It
+ leaves point after the inserted text.
+
+ The argument FILE may be either a directory name or a file
+ specification including wildcard characters. If WILDCARD is
+ non-`nil', that means treat FILE as a file specification with
+ wildcards.
+
+ If FULL-DIRECTORY-P is non-`nil', that means FILE is a directory
+ and switches do not contain `-d', so that the listing should show
+ the full contents of the directory. (The `-d' option to `ls' says
+ to describe a directory itself rather than its contents.)
+
+ This function works by running a directory listing program whose
+ name is in the variable `insert-directory-program'. If WILDCARD is
+ non-`nil', it also runs the shell specified by `shell-file-name',
+ to expand the wildcards.
+
+ - Variable: insert-directory-program
+ This variable's value is the program to run to generate a
+ directory listing for the function `insert-directory'.
+
+\1f
+File: lispref.info, Node: Create/Delete Dirs, Next: Magic File Names, Prev: Contents of Directories, Up: Files
+
+Creating and Deleting Directories
+=================================
+
+ Most XEmacs Lisp file-manipulation functions get errors when used on
+files that are directories. For example, you cannot delete a directory
+with `delete-file'. These special functions exist to create and delete
+directories.
+
+ - Command: make-directory dirname &optional parents
+ This function creates a directory named DIRNAME. Interactively,
+ the default choice of directory to create is the current default
+ directory for file names. That is useful when you have visited a
+ file in a nonexistent directory.
+
+ Non-interactively, optional argument PARENTS says whether to
+ create parent directories if they don't exist. (Interactively, this
+ always happens.)
+
+ - Command: delete-directory dirname
+ This function deletes the directory named DIRNAME. The function
+ `delete-file' does not work for files that are directories; you
+ must use `delete-directory' in that case.
+
+\1f
+File: lispref.info, Node: Magic File Names, Next: Partial Files, Prev: Create/Delete Dirs, Up: Files
+
+Making Certain File Names "Magic"
+=================================
+
+ You can implement special handling for certain file names. This is
+called making those names "magic". You must supply a regular
+expression to define the class of names (all those that match the
+regular expression), plus a handler that implements all the primitive
+XEmacs file operations for file names that do match.
+
+ The variable `file-name-handler-alist' holds a list of handlers,
+together with regular expressions that determine when to apply each
+handler. Each element has this form:
+
+ (REGEXP . HANDLER)
+
+All the XEmacs primitives for file access and file name transformation
+check the given file name against `file-name-handler-alist'. If the
+file name matches REGEXP, the primitives handle that file by calling
+HANDLER.
+
+ The first argument given to HANDLER is the name of the primitive;
+the remaining arguments are the arguments that were passed to that
+operation. (The first of these arguments is typically the file name
+itself.) For example, if you do this:
+
+ (file-exists-p FILENAME)
+
+and FILENAME has handler HANDLER, then HANDLER is called like this:
+
+ (funcall HANDLER 'file-exists-p FILENAME)
+
+ Here are the operations that a magic file name handler gets to
+handle:
+
+`add-name-to-file', `copy-file', `delete-directory', `delete-file',
+`diff-latest-backup-file', `directory-file-name', `directory-files',
+`dired-compress-file', `dired-uncache', `expand-file-name',
+`file-accessible-directory-p', `file-attributes', `file-directory-p',
+`file-executable-p', `file-exists-p', `file-local-copy', `file-modes',
+`file-name-all-completions', `file-name-as-directory',
+`file-name-completion', `file-name-directory', `file-name-nondirectory',
+`file-name-sans-versions', `file-newer-than-file-p', `file-readable-p',
+`file-regular-p', `file-symlink-p', `file-truename', `file-writable-p',
+`get-file-buffer', `insert-directory', `insert-file-contents', `load',
+`make-directory', `make-symbolic-link', `rename-file', `set-file-modes',
+`set-visited-file-modtime', `unhandled-file-name-directory',
+`verify-visited-file-modtime', `write-region'.
+
+ Handlers for `insert-file-contents' typically need to clear the
+buffer's modified flag, with `(set-buffer-modified-p nil)', if the
+VISIT argument is non-`nil'. This also has the effect of unlocking the
+buffer if it is locked.
+
+ The handler function must handle all of the above operations, and
+possibly others to be added in the future. It need not implement all
+these operations itself--when it has nothing special to do for a
+certain operation, it can reinvoke the primitive, to handle the
+operation "in the usual way". It should always reinvoke the primitive
+for an operation it does not recognize. Here's one way to do this:
+
+ (defun my-file-handler (operation &rest args)
+ ;; First check for the specific operations
+ ;; that we have special handling for.
+ (cond ((eq operation 'insert-file-contents) ...)
+ ((eq operation 'write-region) ...)
+ ...
+ ;; Handle any operation we don't know about.
+ (t (let ((inhibit-file-name-handlers
+ (cons 'my-file-handler
+ (and (eq inhibit-file-name-operation operation)
+ inhibit-file-name-handlers)))
+ (inhibit-file-name-operation operation))
+ (apply operation args)))))
+
+ When a handler function decides to call the ordinary Emacs primitive
+for the operation at hand, it needs to prevent the primitive from
+calling the same handler once again, thus leading to an infinite
+recursion. The example above shows how to do this, with the variables
+`inhibit-file-name-handlers' and `inhibit-file-name-operation'. Be
+careful to use them exactly as shown above; the details are crucial for
+proper behavior in the case of multiple handlers, and for operations
+that have two file names that may each have handlers.
+
+ - Variable: inhibit-file-name-handlers
+ This variable holds a list of handlers whose use is presently
+ inhibited for a certain operation.
+
+ - Variable: inhibit-file-name-operation
+ The operation for which certain handlers are presently inhibited.
+
+ - Function: find-file-name-handler file operation
+ This function returns the handler function for file name FILE, or
+ `nil' if there is none. The argument OPERATION should be the
+ operation to be performed on the file--the value you will pass to
+ the handler as its first argument when you call it. The operation
+ is needed for comparison with `inhibit-file-name-operation'.
+
+ - Function: file-local-copy filename
+ This function copies file FILENAME to an ordinary non-magic file,
+ if it isn't one already.
+
+ If FILENAME specifies a "magic" file name, which programs outside
+ Emacs cannot directly read or write, this copies the contents to
+ an ordinary file and returns that file's name.
+
+ If FILENAME is an ordinary file name, not magic, then this function
+ does nothing and returns `nil'.
+
+ - Function: unhandled-file-name-directory filename
+ This function returns the name of a directory that is not magic.
+ It uses the directory part of FILENAME if that is not magic.
+ Otherwise, it asks the handler what to do.
+
+ This is useful for running a subprocess; every subprocess must
+ have a non-magic directory to serve as its current directory, and
+ this function is a good way to come up with one.
+
+\1f
+File: lispref.info, Node: Partial Files, Next: Format Conversion, Prev: Magic File Names, Up: Files
+
+Partial Files
+=============
+
+* Menu:
+
+* Intro to Partial Files::
+* Creating a Partial File::
+* Detached Partial Files::
+
+\1f
+File: lispref.info, Node: Intro to Partial Files, Next: Creating a Partial File, Up: Partial Files
+
+Intro to Partial Files
+----------------------
+
+ A "partial file" is a section of a buffer (called the "master
+buffer") that is placed in its own buffer and treated as its own file.
+Changes made to the partial file are not reflected in the master buffer
+until the partial file is "saved" using the standard buffer save
+commands. Partial files can be "reverted" (from the master buffer)
+just like normal files. When a file part is active on a master buffer,
+that section of the master buffer is marked as read-only. Two file
+parts on the same master buffer are not allowed to overlap. Partial
+file buffers are indicated by the words `File Part' in the modeline.
+
+ The master buffer knows about all the partial files that are active
+on it, and thus killing or reverting the master buffer will be handled
+properly. When the master buffer is saved, if there are any unsaved
+partial files active on it then the user will be given the opportunity
+to first save these files.
+
+ When a partial file buffer is first modified, the master buffer is
+automatically marked as modified so that saving the master buffer will
+work correctly.
+
+\1f
+File: lispref.info, Node: Creating a Partial File, Next: Detached Partial Files, Prev: Intro to Partial Files, Up: Partial Files
+
+Creating a Partial File
+-----------------------
+
+ - Function: make-file-part &optional start end name buffer
+ Make a file part on buffer BUFFER out of the region. Call it
+ NAME. This command creates a new buffer containing the contents
+ of the region and marks the buffer as referring to the specified
+ buffer, called the "master buffer". When the file-part buffer is
+ saved, its changes are integrated back into the master buffer.
+ When the master buffer is deleted, all file parts are deleted with
+ it.
+
+ When called from a function, expects four arguments, START, END,
+ NAME, and BUFFER, all of which are optional and default to the
+ beginning of BUFFER, the end of BUFFER, a name generated from
+ BUFFER name, and the current buffer, respectively.
+
+\1f
+File: lispref.info, Node: Detached Partial Files, Prev: Creating a Partial File, Up: Partial Files
+
+Detached Partial Files
+----------------------
+
+ Every partial file has an extent in the master buffer associated
+with it (called the "master extent"), marking where in the master
+buffer the partial file begins and ends. If the text in master buffer
+that is contained by the extent is deleted, then the extent becomes
+"detached", meaning that it no longer refers to a specific region of
+the master buffer. This can happen either when the text is deleted
+directly or when the master buffer is reverted. Neither of these should
+happen in normal usage because the master buffer should generally not be
+edited directly.
+
+ Before doing any operation that references a partial file's master
+extent, XEmacs checks to make sure that the extent is not detached. If
+this is the case, XEmacs warns the user of this and the master extent is
+deleted out of the master buffer, disconnecting the file part. The file
+part's filename is cleared and thus must be explicitly specified if the
+detached file part is to be saved.
+
+\1f
+File: lispref.info, Node: Format Conversion, Next: Files and MS-DOS, Prev: Partial Files, Up: Files
+
+File Format Conversion
+======================
+
+ The variable `format-alist' defines a list of "file formats", which
+describe textual representations used in files for the data (text,
+text-properties, and possibly other information) in an Emacs buffer.
+Emacs performs format conversion if appropriate when reading and writing
+files.
+
+ - Variable: format-alist
+ This list contains one format definition for each defined file
+ format.
+
+ Each format definition is a list of this form:
+
+ (NAME DOC-STRING REGEXP FROM-FN TO-FN MODIFY MODE-FN)
+
+ Here is what the elements in a format definition mean:
+
+NAME
+ The name of this format.
+
+DOC-STRING
+ A documentation string for the format.
+
+REGEXP
+ A regular expression which is used to recognize files represented
+ in this format.
+
+FROM-FN
+ A function to call to decode data in this format (to convert file
+ data into the usual Emacs data representation).
+
+ The FROM-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. It should convert the
+ text by editing it in place. Since this can change the length of
+ the text, FROM-FN should return the modified end position.
+
+ One responsibility of FROM-FN is to make sure that the beginning
+ of the file no longer matches REGEXP. Otherwise it is likely to
+ get called again.
+
+TO-FN
+ A function to call to encode data in this format (to convert the
+ usual Emacs data representation into this format).
+
+ The TO-FN is called with two args, BEGIN and END, which specify
+ the part of the buffer it should convert. There are two ways it
+ can do the conversion:
+
+ * By editing the buffer in place. In this case, TO-FN should
+ return the end-position of the range of text, as modified.
+
+ * By returning a list of annotations. This is a list of
+ elements of the form `(POSITION . STRING)', where POSITION is
+ an integer specifying the relative position in the text to be
+ written, and STRING is the annotation to add there. The list
+ must be sorted in order of position when TO-FN returns it.
+
+ When `write-region' actually writes the text from the buffer
+ to the file, it intermixes the specified annotations at the
+ corresponding positions. All this takes place without
+ modifying the buffer.
+
+MODIFY
+ A flag, `t' if the encoding function modifies the buffer, and
+ `nil' if it works by returning a list of annotations.
+
+MODE
+ A mode function to call after visiting a file converted from this
+ format.
+
+ The function `insert-file-contents' automatically recognizes file
+formats when it reads the specified file. It checks the text of the
+beginning of the file against the regular expressions of the format
+definitions, and if it finds a match, it calls the decoding function for
+that format. Then it checks all the known formats over again. It
+keeps checking them until none of them is applicable.
+
+ Visiting a file, with `find-file-noselect' or the commands that use
+it, performs conversion likewise (because it calls
+`insert-file-contents'); it also calls the mode function for each
+format that it decodes. It stores a list of the format names in the
+buffer-local variable `buffer-file-format'.
+
+ - Variable: buffer-file-format
+ This variable states the format of the visited file. More
+ precisely, this is a list of the file format names that were
+ decoded in the course of visiting the current buffer's file. It
+ is always local in all buffers.
+
+ When `write-region' writes data into a file, it first calls the
+encoding functions for the formats listed in `buffer-file-format', in
+the order of appearance in the list.
+
+ - Function: format-write-file file format
+ This command writes the current buffer contents into the file FILE
+ in format FORMAT, and makes that format the default for future
+ saves of the buffer. The argument FORMAT is a list of format
+ names.
+
+ - Function: format-find-file file format
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-insert-file file format &optional beg end
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If BEG and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-find-file file format
+ This command finds the file FILE, converting it according to
+ format FORMAT. It also makes FORMAT the default if the buffer is
+ saved later.
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Function: format-insert-file file format &optional beg end
+ This command inserts the contents of file FILE, converting it
+ according to format FORMAT. If BEG and END are non-`nil', they
+ specify which part of the file to read, as in
+ `insert-file-contents' (*note Reading from Files::).
+
+ The return value is like what `insert-file-contents' returns: a
+ list of the absolute file name and the length of the data inserted
+ (after conversion).
+
+ The argument FORMAT is a list of format names. If FORMAT is
+ `nil', no conversion takes place. Interactively, typing just
+ <RET> for FORMAT specifies `nil'.
+
+ - Variable: auto-save-file-format
+ This variable specifies the format to use for auto-saving. Its
+ value is a list of format names, just like the value of
+ `buffer-file-format'; but it is used instead of
+ `buffer-file-format' for writing auto-save files. This variable
+ is always local in all buffers.
+
+\1f
File: lispref.info, Node: Files and MS-DOS, Prev: Format Conversion, Up: Files
Files and MS-DOS
file type of the buffer's visited file. The value is `nil' for
text, `t' for binary.
- - Function: find-buffer-file-type FILENAME
+ - Function: find-buffer-file-type filename
This function determines whether file FILENAME is a text file or a
binary file. It returns `nil' for text, `t' for binary.
don't indicate anything in particular. Its value should be `nil'
for text, or `t' for binary.
- - Command: find-file-text FILENAME
+ - Command: find-file-text filename
Like `find-file', but treat the file as text regardless of its
name.
- - Command: find-file-binary FILENAME
+ - Command: find-file-binary filename
Like `find-file', but treat the file as binary regardless of its
name.
variables have the value 2, then the backups numbered 1 and 2 are kept
as old versions and those numbered 5 and 7 are kept as new versions;
backup version 3 is excess. The function `find-backup-file-name'
-(*note Backup Names::.) is responsible for determining which backup
+(*note Backup Names::) is responsible for determining which backup
versions to delete, but does not delete them itself.
- - User Option: trim-versions-without-asking
+ - User Option: delete-old-versions
If this variable is non-`nil', then saving a file deletes excess
backup versions silently. Otherwise, it asks the user whether to
delete them.
customize the naming conventions for backup files by redefining them.
If you change one, you probably need to change the rest.
- - Function: backup-file-name-p FILENAME
+ - Function: backup-file-name-p filename
This function returns a non-`nil' value if FILENAME is a possible
name for a backup file. A file with the name FILENAME need not
exist; the function just checks the name.
(backup-file-name-p "foo")
=> nil
-
(backup-file-name-p "foo~")
=> 3
This simple expression is placed in a separate function to make it
easy to redefine for customization.
- - Function: make-backup-file-name FILENAME
+ - Function: make-backup-file-name filename
This function returns a string that is the name to use for a
non-numbered backup file for file FILENAME. On Unix, this is just
FILENAME with a tilde appended.
(defun make-backup-file-name (filename)
(concat "." filename "~"))
-
+
(make-backup-file-name "backups.texi")
=> ".backups.texi~"
- - Function: find-backup-file-name FILENAME
+ - Function: find-backup-file-name filename
This function computes the file name for a new backup file for
FILENAME. It may also propose certain existing backup files for
deletion. `find-backup-file-name' returns a list whose CAR is the
(find-backup-file-name "~rms/foo")
=> ("~rms/foo.~5~" "~rms/foo.~3~")
- - Function: file-newest-backup FILENAME
+ - Function: file-newest-backup filename
This function returns the name of the most recent backup file for
FILENAME, or `nil' if that file has no backup files.
buffer-auto-save-file-name
=> "/xcssun/users/rms/lewis/#files.texi#"
- - Command: auto-save-mode ARG
+ - Command: auto-save-mode arg
When used interactively without an argument, this command is a
toggle switch: it turns on auto-saving of the current buffer if it
is off, and vice-versa. With an argument ARG, the command turns
auto-saving on if the value of ARG is `t', a nonempty list, or a
positive integer. Otherwise, it turns auto-saving off.
- - Function: auto-save-file-name-p FILENAME
+ - Function: auto-save-file-name-p filename
This function returns a non-`nil' value if FILENAME is a string
that could be the name of an auto-save file. It works based on
knowledge of the naming convention for auto-save files: a name that
If this variable is non-`nil', buffers that are visiting files
have auto-saving enabled by default. Otherwise, they do not.
- - Command: do-auto-save &optional NO-MESSAGE CURRENT-ONLY
+ - Command: do-auto-save &optional no-message current-only
This function auto-saves all buffers that need to be auto-saved.
It saves all buffers for which auto-saving is enabled and that
have been changed since the previous auto-save.
version of the file with the `revert-buffer' command. *Note Reverting
a Buffer: (emacs)Reverting.
- - Command: revert-buffer &optional CHECK-AUTO-SAVE NOCONFIRM
+ - Command: revert-buffer &optional check-auto-save noconfirm
This command replaces the buffer text with the text of the visited
file on disk. This action undoes all changes since the file was
visited or saved.
* Buffer File Name:: The buffer file name indicates which file is visited.
* Buffer Modification:: A buffer is "modified" if it needs to be saved.
* Modification Time:: Determining whether the visited file was changed
- "behind XEmacs's back".
+ ``behind XEmacs's back''.
* Read Only Buffers:: Modifying text is not allowed in a read-only buffer.
* The Buffer List:: How to look at all the existing buffers.
* Creating Buffers:: Functions that create buffers.
* Killing Buffers:: Buffers exist until explicitly killed.
* Indirect Buffers:: An indirect buffer shares text with some other buffer.
-\1f
-File: lispref.info, Node: Buffer Basics, Next: Current Buffer, Up: Buffers
-
-Buffer Basics
-=============
-
- A "buffer" is a Lisp object containing text to be edited. Buffers
-are used to hold the contents of files that are being visited; there may
-also be buffers that are not visiting files. While several buffers may
-exist at one time, exactly one buffer is designated the "current
-buffer" at any time. Most editing commands act on the contents of the
-current buffer. Each buffer, including the current buffer, may or may
-not be displayed in any windows.
-
- Buffers in Emacs editing are objects that have distinct names and
-hold text that can be edited. Buffers appear to Lisp programs as a
-special data type. You can think of the contents of a buffer as an
-extendable string; insertions and deletions may occur in any part of
-the buffer. *Note Text::.
-
- A Lisp buffer object contains numerous pieces of information. Some
-of this information is directly accessible to the programmer through
-variables, while other information is accessible only through
-special-purpose functions. For example, the visited file name is
-directly accessible through a variable, while the value of point is
-accessible only through a primitive function.
-
- Buffer-specific information that is directly accessible is stored in
-"buffer-local" variable bindings, which are variable values that are
-effective only in a particular buffer. This feature allows each buffer
-to override the values of certain variables. Most major modes override
-variables such as `fill-column' or `comment-column' in this way. For
-more information about buffer-local variables and functions related to
-them, see *Note Buffer-Local Variables::.
-
- For functions and variables related to visiting files in buffers, see
-*Note Visiting Files:: and *Note Saving Buffers::. For functions and
-variables related to the display of buffers in windows, see *Note
-Buffers and Windows::.
-
- - Function: bufferp OBJECT
- This function returns `t' if OBJECT is a buffer, `nil' otherwise.
-
-\1f
-File: lispref.info, Node: Current Buffer, Next: Buffer Names, Prev: Buffer Basics, Up: Buffers
-
-The Current Buffer
-==================
-
- There are, in general, many buffers in an Emacs session. At any
-time, one of them is designated as the "current buffer". This is the
-buffer in which most editing takes place, because most of the primitives
-for examining or changing text in a buffer operate implicitly on the
-current buffer (*note Text::.). Normally the buffer that is displayed
-on the screen in the selected window is the current buffer, but this is
-not always so: a Lisp program can designate any buffer as current
-temporarily in order to operate on its contents, without changing what
-is displayed on the screen.
-
- The way to designate a current buffer in a Lisp program is by calling
-`set-buffer'. The specified buffer remains current until a new one is
-designated.
-
- When an editing command returns to the editor command loop, the
-command loop designates the buffer displayed in the selected window as
-current, to prevent confusion: the buffer that the cursor is in when
-Emacs reads a command is the buffer that the command will apply to.
-(*Note Command Loop::.) Therefore, `set-buffer' is not the way to
-switch visibly to a different buffer so that the user can edit it. For
-this, you must use the functions described in *Note Displaying
-Buffers::.
-
- However, Lisp functions that change to a different current buffer
-should not depend on the command loop to set it back afterwards.
-Editing commands written in XEmacs Lisp can be called from other
-programs as well as from the command loop. It is convenient for the
-caller if the subroutine does not change which buffer is current
-(unless, of course, that is the subroutine's purpose). Therefore, you
-should normally use `set-buffer' within a `save-excursion' that will
-restore the current buffer when your function is done (*note
-Excursions::.). Here is an example, the code for the command
-`append-to-buffer' (with the documentation string abridged):
-
- (defun append-to-buffer (buffer start end)
- "Append to specified buffer the text of the region.
- ..."
- (interactive "BAppend to buffer: \nr")
- (let ((oldbuf (current-buffer)))
- (save-excursion
- (set-buffer (get-buffer-create buffer))
- (insert-buffer-substring oldbuf start end))))
-
-This function binds a local variable to the current buffer, and then
-`save-excursion' records the values of point, the mark, and the
-original buffer. Next, `set-buffer' makes another buffer current.
-Finally, `insert-buffer-substring' copies the string from the original
-current buffer to the new current buffer.
-
- If the buffer appended to happens to be displayed in some window,
-the next redisplay will show how its text has changed. Otherwise, you
-will not see the change immediately on the screen. The buffer becomes
-current temporarily during the execution of the command, but this does
-not cause it to be displayed.
-
- If you make local bindings (with `let' or function arguments) for a
-variable that may also have buffer-local bindings, make sure that the
-same buffer is current at the beginning and at the end of the local
-binding's scope. Otherwise you might bind it in one buffer and unbind
-it in another! There are two ways to do this. In simple cases, you may
-see that nothing ever changes the current buffer within the scope of the
-binding. Otherwise, use `save-excursion' to make sure that the buffer
-current at the beginning is current again whenever the variable is
-unbound.
-
- It is not reliable to change the current buffer back with
-`set-buffer', because that won't do the job if a quit happens while the
-wrong buffer is current. Here is what *not* to do:
-
- (let (buffer-read-only
- (obuf (current-buffer)))
- (set-buffer ...)
- ...
- (set-buffer obuf))
-
-Using `save-excursion', as shown below, handles quitting, errors, and
-`throw', as well as ordinary evaluation.
-
- (let (buffer-read-only)
- (save-excursion
- (set-buffer ...)
- ...))
-
- - Function: current-buffer
- This function returns the current buffer.
-
- (current-buffer)
- => #<buffer buffers.texi>
-
- - Function: set-buffer BUFFER-OR-NAME
- This function makes BUFFER-OR-NAME the current buffer. It does
- not display the buffer in the currently selected window or in any
- other window, so the user cannot necessarily see the buffer. But
- Lisp programs can in any case work on it.
-
- This function returns the buffer identified by BUFFER-OR-NAME. An
- error is signaled if BUFFER-OR-NAME does not identify an existing
- buffer.
-
-\1f
-File: lispref.info, Node: Buffer Names, Next: Buffer File Name, Prev: Current Buffer, Up: Buffers
-
-Buffer Names
-============
-
- Each buffer has a unique name, which is a string. Many of the
-functions that work on buffers accept either a buffer or a buffer name
-as an argument. Any argument called BUFFER-OR-NAME is of this sort,
-and an error is signaled if it is neither a string nor a buffer. Any
-argument called BUFFER must be an actual buffer object, not a name.
-
- Buffers that are ephemeral and generally uninteresting to the user
-have names starting with a space, so that the `list-buffers' and
-`buffer-menu' commands don't mention them. A name starting with space
-also initially disables recording undo information; see *Note Undo::.
-
- - Function: buffer-name &optional BUFFER
- This function returns the name of BUFFER as a string. If BUFFER
- is not supplied, it defaults to the current buffer.
-
- If `buffer-name' returns `nil', it means that BUFFER has been
- killed. *Note Killing Buffers::.
-
- (buffer-name)
- => "buffers.texi"
-
- (setq foo (get-buffer "temp"))
- => #<buffer temp>
- (kill-buffer foo)
- => nil
- (buffer-name foo)
- => nil
- foo
- => #<killed buffer>
-
- - Command: rename-buffer NEWNAME &optional UNIQUE
- This function renames the current buffer to NEWNAME. An error is
- signaled if NEWNAME is not a string, or if there is already a
- buffer with that name. The function returns `nil'.
-
- Ordinarily, `rename-buffer' signals an error if NEWNAME is already
- in use. However, if UNIQUE is non-`nil', it modifies NEWNAME to
- make a name that is not in use. Interactively, you can make
- UNIQUE non-`nil' with a numeric prefix argument.
-
- One application of this command is to rename the `*shell*' buffer
- to some other name, thus making it possible to create a second
- shell buffer under the name `*shell*'.
-
- - Function: get-buffer BUFFER-OR-NAME
- This function returns the buffer specified by BUFFER-OR-NAME. If
- BUFFER-OR-NAME is a string and there is no buffer with that name,
- the value is `nil'. If BUFFER-OR-NAME is a buffer, it is returned
- as given. (That is not very useful, so the argument is usually a
- name.) For example:
-
- (setq b (get-buffer "lewis"))
- => #<buffer lewis>
- (get-buffer b)
- => #<buffer lewis>
- (get-buffer "Frazzle-nots")
- => nil
-
- See also the function `get-buffer-create' in *Note Creating
- Buffers::.
-
- - Function: 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
- STARTING-NAME, and produces a name not currently in use for any
- buffer by appending a number inside of `<...>'.
-
- If IGNORE is given, it specifies a name that is okay to use (if it
- is in the sequence to be tried), even if a buffer with that name
- exists.
-
- See the related function `generate-new-buffer' in *Note Creating
- Buffers::.
-
-\1f
-File: lispref.info, Node: Buffer File Name, Next: Buffer Modification, Prev: Buffer Names, Up: Buffers
-
-Buffer File Name
-================
-
- The "buffer file name" is the name of the file that is visited in
-that buffer. When a buffer is not visiting a file, its buffer file name
-is `nil'. Most of the time, the buffer name is the same as the
-nondirectory part of the buffer file name, but the buffer file name and
-the buffer name are distinct and can be set independently. *Note
-Visiting Files::.
-
- - Function: buffer-file-name &optional BUFFER
- This function returns the absolute file name of the file that
- BUFFER is visiting. If BUFFER is not visiting any file,
- `buffer-file-name' returns `nil'. If BUFFER is not supplied, it
- defaults to the current buffer.
-
- (buffer-file-name (other-buffer))
- => "/usr/user/lewis/manual/files.texi"
-
- - Variable: buffer-file-name
- This buffer-local variable contains the name of the file being
- visited in the current buffer, or `nil' if it is not visiting a
- file. It is a permanent local, unaffected by
- `kill-local-variables'.
-
- buffer-file-name
- => "/usr/user/lewis/manual/buffers.texi"
-
- It is risky to change this variable's value without doing various
- other things. See the definition of `set-visited-file-name' in
- `files.el'; some of the things done there, such as changing the
- buffer name, are not strictly necessary, but others are essential
- to avoid confusing XEmacs.
-
- - Variable: buffer-file-truename
- This buffer-local variable holds the truename of the file visited
- in the current buffer, or `nil' if no file is visited. It is a
- permanent local, unaffected by `kill-local-variables'. *Note
- Truenames::.
-
- - Variable: buffer-file-number
- This buffer-local variable holds the file number and directory
- device number of the file visited in the current buffer, or `nil'
- if no file or a nonexistent file is visited. It is a permanent
- local, unaffected by `kill-local-variables'. *Note Truenames::.
-
- The value is normally a list of the form `(FILENUM DEVNUM)'. This
- pair of numbers uniquely identifies the file among all files
- accessible on the system. See the function `file-attributes', in
- *Note File Attributes::, for more information about them.
-
- - Function: get-file-buffer FILENAME
- This function returns the buffer visiting file FILENAME. If there
- is no such buffer, it returns `nil'. The argument FILENAME, which
- must be a string, is expanded (*note File Name Expansion::.), then
- compared against the visited file names of all live buffers.
-
- (get-file-buffer "buffers.texi")
- => #<buffer buffers.texi>
-
- In unusual circumstances, there can be more than one buffer
- visiting the same file name. In such cases, this function returns
- the first such buffer in the buffer list.
-
- - Command: set-visited-file-name FILENAME
- If FILENAME is a non-empty string, this function changes the name
- of the file visited in current buffer to FILENAME. (If the buffer
- had no visited file, this gives it one.) The *next time* the
- buffer is saved it will go in the newly-specified file. This
- command marks the buffer as modified, since it does not (as far as
- XEmacs knows) match the contents of FILENAME, even if it matched
- the former visited file.
-
- If FILENAME is `nil' or the empty string, that stands for "no
- visited file". In this case, `set-visited-file-name' marks the
- buffer as having no visited file.
-
- When the function `set-visited-file-name' is called interactively,
- it prompts for FILENAME in the minibuffer.
-
- See also `clear-visited-file-modtime' and
- `verify-visited-file-modtime' in *Note Buffer Modification::.
-
- - Variable: list-buffers-directory
- This buffer-local variable records a string to display in a buffer
- listing in place of the visited file name, for buffers that don't
- have a visited file name. Dired buffers use this variable.
-
-\1f
-File: lispref.info, Node: Buffer Modification, Next: Modification Time, Prev: Buffer File Name, Up: Buffers
-
-Buffer Modification
-===================
-
- XEmacs keeps a flag called the "modified flag" for each buffer, to
-record whether you have changed the text of the buffer. This flag is
-set to `t' whenever you alter the contents of the buffer, and cleared
-to `nil' when you save it. Thus, the flag shows whether there are
-unsaved changes. The flag value is normally shown in the modeline
-(*note Modeline Variables::.), and controls saving (*note Saving
-Buffers::.) and auto-saving (*note Auto-Saving::.).
-
- Some Lisp programs set the flag explicitly. For example, the
-function `set-visited-file-name' sets the flag to `t', because the text
-does not match the newly-visited file, even if it is unchanged from the
-file formerly visited.
-
- The functions that modify the contents of buffers are described in
-*Note Text::.
-
- - Function: buffer-modified-p &optional BUFFER
- This function returns `t' if the buffer BUFFER has been modified
- since it was last read in from a file or saved, or `nil'
- otherwise. If BUFFER is not supplied, the current buffer is
- tested.
-
- - Function: set-buffer-modified-p FLAG
- This function marks the current buffer as modified if FLAG is
- non-`nil', or as unmodified if the flag is `nil'.
-
- Another effect of calling this function is to cause unconditional
- redisplay of the modeline for the current buffer. In fact, the
- function `redraw-modeline' works by doing this:
-
- (set-buffer-modified-p (buffer-modified-p))
-
- - Command: not-modified &optional ARG
- This command marks the current buffer as unmodified, and not
- needing to be saved. (If ARG is non-`nil', the buffer is instead
- marked as modified.) Don't use this function in programs, since it
- prints a message in the echo area; use `set-buffer-modified-p'
- (above) instead.
-
- - Function: buffer-modified-tick &optional BUFFER
- This function returns BUFFER`s modification-count. This is a
- counter that increments every time the buffer is modified. If
- BUFFER is `nil' (or omitted), the current buffer is used.
-
-\1f
-File: lispref.info, Node: Modification Time, Next: Read Only Buffers, Prev: Buffer Modification, Up: Buffers
-
-Comparison of Modification Time
-===============================
-
- Suppose that you visit a file and make changes in its buffer, and
-meanwhile the file itself is changed on disk. At this point, saving the
-buffer would overwrite the changes in the file. Occasionally this may
-be what you want, but usually it would lose valuable information.
-XEmacs therefore checks the file's modification time using the functions
-described below before saving the file.
-
- - Function: verify-visited-file-modtime BUFFER
- This function compares what BUFFER has recorded for the
- modification time of its visited file against the actual
- modification time of the file as recorded by the operating system.
- The two should be the same unless some other process has written
- the file since XEmacs visited or saved it.
-
- The function returns `t' if the last actual modification time and
- XEmacs's recorded modification time are the same, `nil' otherwise.
-
- - Function: clear-visited-file-modtime
- This function clears out the record of the last modification time
- of the file being visited by the current buffer. As a result, the
- next attempt to save this buffer will not complain of a
- discrepancy in file modification times.
-
- This function is called in `set-visited-file-name' and other
- exceptional places where the usual test to avoid overwriting a
- changed file should not be done.
-
- - Function: visited-file-modtime
- This function returns the buffer's recorded last file modification
- time, as a list of the form `(HIGH . LOW)'. (This is the same
- format that `file-attributes' uses to return time values; see
- *Note File Attributes::.)
-
- - Function: set-visited-file-modtime &optional TIME
- This function updates the buffer's record of the last modification
- time of the visited file, to the value specified by TIME if TIME
- is not `nil', and otherwise to the last modification time of the
- visited file.
-
- If TIME is not `nil', it should have the form `(HIGH . LOW)' or
- `(HIGH LOW)', in either case containing two integers, each of
- which holds 16 bits of the time.
-
- This function is useful if the buffer was not read from the file
- normally, or if the file itself has been changed for some known
- benign reason.
-
- - Function: ask-user-about-supersession-threat FILENAME
- This function is used to ask a user how to proceed after an
- attempt to modify an obsolete buffer visiting file FILENAME. An
- "obsolete buffer" is an unmodified buffer for which the associated
- file on disk is newer than the last save-time of the buffer. This
- means some other program has probably altered the file.
-
- Depending on the user's answer, the function may return normally,
- in which case the modification of the buffer proceeds, or it may
- signal a `file-supersession' error with data `(FILENAME)', in which
- case the proposed buffer modification is not allowed.
-
- This function is called automatically by XEmacs on the proper
- occasions. It exists so you can customize XEmacs by redefining it.
- See the file `userlock.el' for the standard definition.
-
- See also the file locking mechanism in *Note File Locks::.
-
-\1f
-File: lispref.info, Node: Read Only Buffers, Next: The Buffer List, Prev: Modification Time, Up: Buffers
-
-Read-Only Buffers
-=================
-
- If a buffer is "read-only", then you cannot change its contents,
-although you may change your view of the contents by scrolling and
-narrowing.
-
- Read-only buffers are used in two kinds of situations:
-
- * A buffer visiting a write-protected file is normally read-only.
-
- Here, the purpose is to show the user that editing the buffer with
- the aim of saving it in the file may be futile or undesirable.
- The user who wants to change the buffer text despite this can do
- so after clearing the read-only flag with `C-x C-q'.
-
- * Modes such as Dired and Rmail make buffers read-only when altering
- the contents with the usual editing commands is probably a mistake.
-
- The special commands of these modes bind `buffer-read-only' to
- `nil' (with `let') or bind `inhibit-read-only' to `t' around the
- places where they change the text.
-
- - Variable: buffer-read-only
- This buffer-local variable specifies whether the buffer is
- read-only. The buffer is read-only if this variable is non-`nil'.
-
- - Variable: inhibit-read-only
- If this variable is non-`nil', then read-only buffers and read-only
- characters may be modified. Read-only characters in a buffer are
- those that have non-`nil' `read-only' properties (either text
- properties or extent properties). *Note Extent Properties::, for
- more information about text properties and extent properties.
-
- If `inhibit-read-only' is `t', all `read-only' character
- properties have no effect. If `inhibit-read-only' is a list, then
- `read-only' character properties have no effect if they are members
- of the list (comparison is done with `eq').
-
- - Command: toggle-read-only
- This command changes whether the current buffer is read-only. It
- is intended for interactive use; don't use it in programs. At any
- given point in a program, you should know whether you want the
- read-only flag on or off; so you can set `buffer-read-only'
- explicitly to the proper value, `t' or `nil'.
-
- - Function: barf-if-buffer-read-only
- This function signals a `buffer-read-only' error if the current
- buffer is read-only. *Note Interactive Call::, for another way to
- signal an error if the current buffer is read-only.
-