-This is ../info/lispref.info, produced by makeinfo version 3.12s from
+This is ../info/lispref.info, produced by makeinfo version 4.0 from
lispref/lispref.texi.
INFO-DIR-SECTION XEmacs Editor
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
(*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.
* 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.
-
projects / chise / xemacs-chise.git / blobdiff