forked from Github/emacs
Document visiting files asynchronously
* doc/emacs/files.texi (Visiting): * doc/lispref/files.texi (Visiting Functions): Document visiting files asynchronously. * etc/NEWS: Rework entry about asynchronous file visiting. * lisp/files.el (find-file, find-file-other-window) (find-file-other-frame, find-file-existing) (find-alternate-file-other-window, find-alternate-file) (find-file-literally): Adapt docstring.
This commit is contained in:
Michael Albinus
parent
d7314b35ff
commit
4615b9148c
4 changed files with 78 additions and 26 deletions
|
|
@ -228,6 +228,34 @@ File Names}, for information on how to visit a file whose name
|
|||
actually contains wildcard characters. You can disable the wildcard
|
||||
feature by customizing @code{find-file-wildcards}.
|
||||
|
||||
@cindex visiting files asynchronously
|
||||
@vindex find-file-asynchronously
|
||||
Sometimes, it is handy to visit a file asynchronously. This means,
|
||||
while loading the file into its buffer Emacs keeps responsive, and you
|
||||
can continue to edit other files, or call commands. This is
|
||||
controlled by the user option @code{find-file-asynchronously}. If
|
||||
this option is @code{nil} (the default), visiting a file is performed
|
||||
synchronously. A regexp value let files, which name matches the
|
||||
regexp, being visited asynchronously, and synchronously otherwise.
|
||||
The value @code{t} forces asynchronous visiting of files
|
||||
unconditionally.
|
||||
|
||||
If you want to visit all remote files asynchronously, you should set
|
||||
|
||||
@example
|
||||
@group
|
||||
(customize-set-variable
|
||||
'find-file-asynchronously tramp-file-name-regexp
|
||||
"Visit remote files asynchronously")
|
||||
@end group
|
||||
@end example
|
||||
|
||||
With a prefix argument @kbd{C-u}, the meaning of
|
||||
@code{find-file-asynchronously} will be reverted. If this user option
|
||||
is @code{nil}, visiting a file is performed asynchronously. Contrary,
|
||||
if this user option is non-@code{nil}, visiting a file is performed
|
||||
synchronously.
|
||||
|
||||
@kindex C-x C-v
|
||||
@findex find-alternate-file
|
||||
If you visit the wrong file unintentionally by typing its name
|
||||
|
|
|
|||
|
|
@ -96,7 +96,7 @@ not alter it, the fastest way is to use @code{insert-file-contents} in a
|
|||
temporary buffer. Visiting the file is not necessary and takes longer.
|
||||
@xref{Reading from Files}.
|
||||
|
||||
@deffn Command find-file filename &optional wildcards
|
||||
@deffn Command find-file filename &optional wildcards async
|
||||
This command selects a buffer visiting the file @var{filename},
|
||||
using an existing buffer if there is one, and otherwise creating a
|
||||
new buffer and reading the file into it. It also returns that buffer.
|
||||
|
|
@ -105,7 +105,8 @@ Aside from some technical details, the body of the @code{find-file}
|
|||
function is basically equivalent to:
|
||||
|
||||
@smallexample
|
||||
(switch-to-buffer (find-file-noselect filename nil nil wildcards))
|
||||
(switch-to-buffer
|
||||
(find-file-noselect filename nil nil wildcards async))
|
||||
@end smallexample
|
||||
|
||||
@noindent
|
||||
|
|
@ -115,21 +116,27 @@ If @var{wildcards} is non-@code{nil}, which is always true in an
|
|||
interactive call, then @code{find-file} expands wildcard characters in
|
||||
@var{filename} and visits all the matching files.
|
||||
|
||||
If @var{async} is non-@code{nil}, the file will be loaded into the
|
||||
buffer asynchronously. Interactively, this is indicated by either
|
||||
setting user option @code{find-file-asynchronously} to non-@code{nil},
|
||||
or by a prefix argument.
|
||||
|
||||
When @code{find-file} is called interactively, it prompts for
|
||||
@var{filename} in the minibuffer.
|
||||
@end deffn
|
||||
|
||||
@deffn Command find-file-literally filename
|
||||
@deffn Command find-file-literally filename &optional async
|
||||
This command visits @var{filename}, like @code{find-file} does, but it
|
||||
does not perform any format conversions (@pxref{Format Conversion}),
|
||||
character code conversions (@pxref{Coding Systems}), or end-of-line
|
||||
conversions (@pxref{Coding System Basics, End of line conversion}).
|
||||
The buffer visiting the file is made unibyte, and its major mode is
|
||||
Fundamental mode, regardless of the file name. File local variable
|
||||
specifications in the file (@pxref{File Local Variables}) are
|
||||
ignored, and automatic decompression and adding a newline at the end
|
||||
of the file due to @code{require-final-newline} (@pxref{Saving
|
||||
Buffers, require-final-newline}) are also disabled.
|
||||
If called interactively, the argument @var{async} is determined like
|
||||
in @code{find-file}. The buffer visiting the file is made unibyte,
|
||||
and its major mode is Fundamental mode, regardless of the file name.
|
||||
File local variable specifications in the file (@pxref{File Local
|
||||
Variables}) are ignored, and automatic decompression and adding a
|
||||
newline at the end of the file due to @code{require-final-newline}
|
||||
(@pxref{Saving Buffers, require-final-newline}) are also disabled.
|
||||
|
||||
Note that if Emacs already has a buffer visiting the same file
|
||||
non-literally, it will not visit the same file literally, but instead
|
||||
|
|
@ -139,7 +146,7 @@ buffer and then read the file contents into it using
|
|||
@code{insert-file-contents-literally} (@pxref{Reading from Files}).
|
||||
@end deffn
|
||||
|
||||
@defun find-file-noselect filename &optional nowarn rawfile wildcards
|
||||
@defun find-file-noselect filename &optional nowarn rawfile wildcards async
|
||||
This function is the guts of all the file-visiting functions. It
|
||||
returns a buffer visiting the file @var{filename}. You may make the
|
||||
buffer current or display it in a window if you wish, but this
|
||||
|
|
@ -157,7 +164,9 @@ Reading the file involves decoding the file's contents (@pxref{Coding
|
|||
Systems}), including end-of-line conversion, and format conversion
|
||||
(@pxref{Format Conversion}). If @var{wildcards} is non-@code{nil},
|
||||
then @code{find-file-noselect} expands wildcard characters in
|
||||
@var{filename} and visits all the matching files.
|
||||
@var{filename} and visits all the matching files. If @var{async} is
|
||||
non-@code{nil} and there are several matching files due to expansion
|
||||
of wildcard characters, every file will be loaded in an own thread.
|
||||
|
||||
This function displays warning or advisory messages in various peculiar
|
||||
cases, unless the optional argument @var{nowarn} is non-@code{nil}. For
|
||||
|
|
@ -191,7 +200,7 @@ various files.
|
|||
@end example
|
||||
@end defun
|
||||
|
||||
@deffn Command find-file-other-window filename &optional wildcards
|
||||
@deffn Command find-file-other-window filename &optional wildcards async
|
||||
This command selects a buffer visiting the file @var{filename}, but
|
||||
does so in a window other than the selected window. It may use
|
||||
another existing window or split a window; see @ref{Switching
|
||||
|
|
@ -201,7 +210,7 @@ When this command is called interactively, it prompts for
|
|||
@var{filename}.
|
||||
@end deffn
|
||||
|
||||
@deffn Command find-file-read-only filename &optional wildcards
|
||||
@deffn Command find-file-read-only filename &optional wildcards async
|
||||
This command selects a buffer visiting the file @var{filename}, like
|
||||
@code{find-file}, but it marks the buffer as read-only. @xref{Read Only
|
||||
Buffers}, for related functions and variables.
|
||||
|
|
@ -219,6 +228,14 @@ the @code{find-file} commands ignore their @var{wildcards} argument
|
|||
and never treat wildcard characters specially.
|
||||
@end defopt
|
||||
|
||||
@defopt find-file-asynchronously
|
||||
If this variable is non-@code{nil}, a file will be visited
|
||||
asynchronously when called interactively. If it is a regular
|
||||
expression, it must match the file name to be visited. This behavior
|
||||
is toggled by a prefix argument to the interactive call of the file
|
||||
visiting command.
|
||||
@end defopt
|
||||
|
||||
@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
|
||||
|
|
|
|||
13
etc/NEWS
13
etc/NEWS
|
|
@ -209,13 +209,14 @@ large files. Now it also offers a third alternative: to visit the
|
|||
file literally, as in 'find-file-literally', which speeds up
|
||||
navigation and editing of large files.
|
||||
|
||||
--- (Documentation to be added)
|
||||
+++
|
||||
** Files can be visited asynchronously.
|
||||
If the file visiting commands are prefixed like 'C-u C-x C-f ...', the
|
||||
files are loaded asynchronously into the respective buffers. I.e.,
|
||||
Emacs is still responsive while loading the files, which is useful
|
||||
especially for remote files. See the node "(emacs) Visiting" in the
|
||||
user manual for the supported commands..
|
||||
If the new user option 'find-file-asynchronously' has a proper non-nil
|
||||
value, interactive file visiting commands load the file asynchronously
|
||||
into the respective buffer. I.e., Emacs is still responsive while
|
||||
loading the files, which is useful especially for remote files. See
|
||||
the node "(emacs) Visiting" in the user manual for the supported
|
||||
commands.
|
||||
|
||||
|
||||
* Changes in Specialized Modes and Packages in Emacs 27.1
|
||||
|
|
|
|||
|
|
@ -1629,7 +1629,7 @@ suppress wildcard expansion by setting `find-file-wildcards' to nil.
|
|||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to nil, or by a prefix
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument.
|
||||
|
||||
To visit a file without any kind of conversion and without
|
||||
|
|
@ -1665,7 +1665,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp,
|
|||
expand wildcards (if any) and visit multiple files.
|
||||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by a prefix
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument."
|
||||
(interactive
|
||||
(find-file-read-args "Find file in other window: "
|
||||
|
|
@ -1702,7 +1703,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp,
|
|||
expand wildcards (if any) and visit multiple files.
|
||||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by a prefix
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument."
|
||||
(interactive
|
||||
(find-file-read-args "Find file in other frame: "
|
||||
|
|
@ -1723,7 +1725,8 @@ Like \\[find-file], but only allow a file that exists, and do not allow
|
|||
file names with wildcards.
|
||||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by a prefix
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument."
|
||||
(interactive
|
||||
(find-file-read-args "Find existing file: " t))
|
||||
|
|
@ -1781,7 +1784,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp,
|
|||
expand wildcards (if any) and replace the file with multiple files.
|
||||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by a prefix
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument."
|
||||
(interactive
|
||||
(save-selected-window
|
||||
|
|
@ -1823,7 +1827,8 @@ Interactively, or if WILDCARDS is non-nil in a call from Lisp,
|
|||
expand wildcards (if any) and replace the file with multiple files.
|
||||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by a prefix
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument.
|
||||
|
||||
If the current buffer is an indirect buffer, or the base buffer
|
||||
|
|
@ -2493,7 +2498,8 @@ If Emacs already has a buffer which is visiting the file,
|
|||
this command asks you whether to visit it literally instead.
|
||||
|
||||
If ASYNC is non-nil, the file will be loaded into the buffer
|
||||
asynchronously. Interactively, this is indicated by a prefix
|
||||
asynchronously. Interactively, this is indicated by either
|
||||
setting `find-file-asynchronously' to non-nil, or by a prefix
|
||||
argument.
|
||||
|
||||
In non-interactive use, the value is the buffer where the file is
|
||||
|
|
|
|||
Loading…
Reference in a new issue