@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.
+@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/files
@node Files, Backups and Auto-Saving, Documentation, Top
and never treat wildcard characters specially.
@end defopt
-@defvar find-file-hook
+@defopt find-file-hook
The value of this variable is a list of functions to be called after a
file is visited. The file's local-variables specification (if any) will
have been processed before the hooks are run. The buffer visiting the
file is current when the hook functions are run.
This variable is a normal hook. @xref{Hooks}.
-@end defvar
+@end defopt
@defvar find-file-not-found-functions
The value of this variable is a list of functions to be called when
Normally, one of the functions in the
@code{after-insert-file-functions} list determines the coding system
(@pxref{Coding Systems}) used for decoding the file's contents,
-including end-of-line conversion.
+including end-of-line conversion. However, if the file contains null
+bytes, it is by default visited without any code conversions; see
+@ref{Lisp and Coding Systems, inhibit-null-byte-detection}, for how to
+control this behavior.
If @var{visit} is non-@code{nil}, this function additionally marks the
buffer as unmodified and sets up various fields in the buffer so that it
@end table
@end defun
+@cindex MS-DOS and file modes
+@cindex file modes and MS-DOS
+ On MS-DOS, there is no such thing as an ``executable'' file mode bit.
+So Emacs considers a file executable if its name ends in one of the
+standard executable extensions, such as @file{.com}, @file{.bat},
+@file{.exe}, and some others. Files that begin with the Unix-standard
+@samp{#!} signature, such as shell and Perl scripts, are also considered
+as executable files. This is reflected in the values returned by
+@code{file-modes} and @code{file-attributes}. Directories are also
+reported with executable bit set, for compatibility with Unix.
+
@node Locating Files
@subsection How to Locate Files in Standard Places
@cindex locate file in path
in @code{"u=rwx"}, the function converts it to the equivalent numeric
value using @code{file-modes-symbolic-to-number} and returns the
result. If the specification is relative, as in @code{"o+g"}, then
-the permissions on which the specification is based is taken from the
+the permissions on which the specification is based are taken from the
mode bits of @var{base-file}. If @var{base-file} is omitted or
@code{nil}, the function uses @code{0} as the base mode bits. The
complete and relative specifications can be combined, as in
symbolic mode bits specifications.
@end defun
-@deffn Subroutine file-modes-symbolic-to-number modes &optional base-modes
+@defun file-modes-symbolic-to-number modes &optional base-modes
This subroutine converts a symbolic specification of file mode bits in
@var{modes} into the equivalent numeric value. If the symbolic
specification is based on an existing file, that file's mode bits are
taken from the optional argument @var{base-modes}; if that argument is
-omitted or nil, it defaults to zero, i.e.@: no access rights at all.
-@end deffn
+omitted or @code{nil}, it defaults to zero, i.e.@: no access rights at
+all.
+@end defun
@defun set-file-times filename &optional time
This function sets the access and modification times of @var{filename}
(@pxref{Time of Day}).
@end defun
-@cindex MS-DOS and file modes
-@cindex file modes and MS-DOS
- On MS-DOS, there is no such thing as an ``executable'' file mode bit.
-So Emacs considers a file executable if its name ends in one of the
-standard executable extensions, such as @file{.com}, @file{.bat},
-@file{.exe}, and some others. Files that begin with the Unix-standard
-@samp{#!} signature, such as shell and Perl scripts, are also considered
-as executable files. This is reflected in the values returned by
-@code{file-modes} and @code{file-attributes}. Directories are also
-reported with executable bit set, for compatibility with Unix.
-
@node File Names
@section File Names
@cindex file names
This function returns @var{filename}'s final ``extension,'' if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part. The extension, in a file name, is the part that
-starts with the last @samp{.} in the last name component (minus
-any version/backup part).
+follows the last @samp{.} in the last name component (minus any
+version/backup part).
This function returns @code{nil} for extensionless file names such as
@file{foo}. It returns @code{""} for null extensions, as in
name as an abbreviation for the ``real'' name, Emacs shows users the
abbreviation instead.
-@defvar directory-abbrev-alist
+@defopt directory-abbrev-alist
The variable @code{directory-abbrev-alist} contains an alist of
abbreviations to use for file directories. Each element has the form
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
("^/home/gp" . "/gp")
("^/home/gd" . "/gd"))
@end example
-@end defvar
+@end defopt
To convert a directory name to its abbreviation, use this
function:
truncate the @var{string} prefix to fit into the 8+3 file-name limits.
@end defun
-@defvar temporary-file-directory
+@defopt temporary-file-directory
@cindex @code{TMPDIR} environment variable
@cindex @code{TMP} environment variable
@cindex @code{TEMP} environment variable
put the file in. However, if you expect the file to be small, you
should use @code{small-temporary-file-directory} first if that is
non-@code{nil}.
-@end defvar
+@end defopt
-@defvar small-temporary-file-directory
+@defopt small-temporary-file-directory
This variable specifies the directory name for
creating certain temporary files, which are likely to be small.
(or small-temporary-file-directory
temporary-file-directory)))
@end example
-@end defvar
+@end defopt
@node File Name Completion
@subsection File Name Completion
with @code{delete-file}. These special functions exist to create and
delete directories.
-@defun make-directory dirname &optional parents
-This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, as is always the case in an
+@findex mkdir
+@deffn Command make-directory dirname &optional parents
+This command creates a directory named @var{dirname}. If
+@var{parents} is non-@code{nil}, as is always the case in an
interactive call, that means to create the parent directories first,
if they don't already exist.
-@end defun
-@defun delete-directory dirname
-This function deletes the directory named @var{dirname}. The function
+@code{mkdir} is an alias for this.
+@end deffn
+
+@deffn Command delete-directory dirname
+This command deletes the directory named @var{dirname}. The function
@code{delete-file} does not work for files that are directories; you
must use @code{delete-directory} for them. If the directory contains
any files, @code{delete-directory} signals an error.
-This function only follows symbolic links at the level of parent
-directories.
-@end defun
+@code{delete-directory} only follows symbolic links at the level of
+parent directories.
+@end deffn
@node Magic File Names
@section Making Certain File Names ``Magic''
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
-@code{find-file-noselect},@*
+@c Not sure why it was here: @code{find-file-noselect},@*
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},@*
@code{file-readable-p}, @code{file-regular-p}, @code{file-symlink-p},
@code{file-truename}, @code{file-writable-p},
@code{find-backup-file-name},
-@code{find-file-noselect},
+@c Not sure why it was here: @code{find-file-noselect},
@code{get-file-buffer},
@code{insert-directory},
@code{insert-file-contents},
@end defun
@defun unhandled-file-name-directory filename
-This function returns the name of a directory that is not magic.
-It uses the directory part of @var{filename} if that is not magic.
-For a magic file name, it invokes the file name handler, which
-therefore decides what value to return. If @var{filename} is not
-accessible from a local process, then the file name handler should
-indicate it by returning nil.
+This function returns the name of a directory that is not magic. It
+uses the directory part of @var{filename} if that is not magic. For a
+magic file name, it invokes the file name handler, which therefore
+decides what value to return. If @var{filename} is not accessible
+from a local process, then the file name handler should indicate it by
+returning @code{nil}.
This is useful for running a subprocess; every subprocess must have a
non-magic directory to serve as its current directory, and this function
Each format definition is a list of this form:
@example
-(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn})
+(@var{name} @var{doc-string} @var{regexp} @var{from-fn} @var{to-fn} @var{modify} @var{mode-fn} @var{preserve})
@end example
@end defvar
A minor-mode function to call after visiting a file converted from this
format. The function is called with one argument, the integer 1;
that tells a minor-mode function to enable the mode.
+
+@item preserve
+A flag, @code{t} if @code{format-write-file} should not remove this format
+from @code{buffer-file-format}.
@end table
The function @code{insert-file-contents} automatically recognizes file
in the order of appearance in the list.
@deffn Command format-write-file file format &optional confirm
-This command writes the current buffer contents into the file
-@var{file} in format @var{format}, and makes that format the default
-for future saves of the buffer. The argument @var{format} is a list
-of format names. Except for the @var{format} argument, this command
-is similar to @code{write-file}. In particular, @var{confirm} has the
-same meaning and interactive treatment as the corresponding argument
-to @code{write-file}. @xref{Definition of write-file}.
+This command writes the current buffer contents into the file @var{file}
+in a format based on @var{format}, which is a list of format names. It
+constructs the actual format starting from @var{format}, then appending
+any elements from the value of @code{buffer-file-format} with a non-nil
+@var{preserve} flag (see above), if they are not already present in
+@var{format}. It then updates @code{buffer-file-format} with this
+format, making it the default for future saves. Except for the
+@var{format} argument, this command is similar to @code{write-file}. In
+particular, @var{confirm} has the same meaning and interactive treatment
+as the corresponding argument to @code{write-file}. @xref{Definition of
+write-file}.
@end deffn
@deffn Command format-find-file file format
@c ??? for `write-region-annotate-functions', below? --ttn
In contrast, when reading, the annotations intermixed with the text
-are handled immediately. @code{insert-file-contents} sets point to the
-beginning of some text to be converted, then calls the conversion
+are handled immediately. @code{insert-file-contents} sets point to
+the beginning of some text to be converted, then calls the conversion
functions with the length of that text. These functions should always
-return with point at the beginning of the inserted text. This approach
-makes sense for reading because annotations removed by the first
-converter can't be mistakenly processed by a later converter.
-
- Each conversion function should scan for the annotations it
-recognizes, remove the annotation, modify the buffer text (to set a text
-property, for example), and return the updated length of the text, as it
-stands after those changes. The value returned by one function becomes
-the argument to the next function.
+return with point at the beginning of the inserted text. This
+approach makes sense for reading because annotations removed by the
+first converter can't be mistakenly processed by a later converter.
+Each conversion function should scan for the annotations it
+recognizes, remove the annotation, modify the buffer text (to set a
+text property, for example), and return the updated length of the
+text, as it stands after those changes. The value returned by one
+function becomes the argument to the next function.
@defvar write-region-annotate-functions
A list of functions for @code{write-region} to call. Each function in
to be written. These functions should not alter the contents of the
buffer. Instead, they should return annotations.
-@c ??? Following adapted from comment in `build_annotations' (fileio.c).
-@c ??? Perhaps this is intended for internal use only?
-@c ??? Someone who understands this, please reword it. --ttn
-As a special case, if a function returns with a different buffer
-current, Emacs takes it to mean the current buffer contains altered text
-to be output, and discards all previous annotations because they should
-have been dealt with by this function.
+As a special case, a function may return with a different buffer
+current. Emacs takes this to mean that the current buffer contains
+altered text to be output. It therefore changes the @var{start} and
+@var{end} arguments of the @code{write-region} call, giving them the
+values of @code{point-min} and @code{point-max} in the new buffer,
+respectively. It also discards all previous annotations, because they
+should have been dealt with by this function.
+@end defvar
+
+@defvar write-region-post-annotation-function
+The value of this variable, if non-@code{nil}, should be a function.
+This function is called, with no arguments, after @code{write-region}
+has completed.
+
+If any function in @code{write-region-annotate-functions} returns with
+a different buffer current, Emacs calls
+@code{write-region-post-annotation-function} more than once. Emacs
+calls it with the last buffer that was current, and again with the
+buffer before that, and so on back to the original buffer.
+
+Thus, a function in @code{write-region-annotate-functions} can create
+a buffer, give this variable the local value of @code{kill-buffer} in
+that buffer, set up the buffer with altered text, and make the buffer
+current. The buffer will be killed after @code{write-region} is done.
@end defvar
@defvar after-insert-file-functions
HCoop / bpt / emacs.git / blobdiff