Function: read-file-name
read-file-name is a byte-compiled function defined in
minibuffer.el.gz.
Signature
(read-file-name PROMPT &optional DIR DEFAULT-FILENAME MUSTMATCH INITIAL PREDICATE)
Documentation
Read file name, prompting with PROMPT and completing in directory DIR.
The return value is not expanded---you must call expand-file-name yourself.
DIR is the directory to use for completing relative file names.
It should be an absolute directory name, or nil (which means the
current buffer's value of default-directory).
DEFAULT-FILENAME specifies the default file name to return if the user exits the minibuffer with the same non-empty string inserted by this function. If DEFAULT-FILENAME is a string, that serves as the default. If DEFAULT-FILENAME is a list of strings, the first string is the default. If DEFAULT-FILENAME is omitted or nil, then if INITIAL is non-nil, the default is DIR combined with INITIAL; otherwise, if the current buffer is visiting a file, that file serves as the default; otherwise, the default is simply the string inserted into the minibuffer.
If the user exits with an empty minibuffer, return an empty
string. (This happens only if the user erases the pre-inserted
contents, or if insert-default-directory is nil.)
Fourth arg MUSTMATCH can take the following values:
- nil means that the user can exit with any input.
- t means that the user is not allowed to exit unless
the input is (or completes to) an existing file.
- confirm means that the user can exit with any input, but she needs
to confirm her choice if the input is not an existing file.
- confirm-after-completion means that the user can exit with any
input, but she needs to confirm her choice if she called
minibuffer-complete right before minibuffer-complete-and-exit
and the input is not an existing file.
- a function, which will be called with a single argument, the
input unquoted by substitute-in-file-name, which see. If the
function returns a non-nil value, the minibuffer is exited with
that argument as the value.
- anything else behaves like t except that typing RET does not exit if it
does non-null completion.
Fifth arg INITIAL specifies text to start with. It will be interpreted as the trailing part of DEFAULT-FILENAME, so using a full file name for INITIAL will usually lead to surprising results.
Sixth arg PREDICATE, if non-nil, should be a function of one argument; then a file name is considered an acceptable completion alternative only if PREDICATE returns non-nil with the file name as its argument.
If this command was invoked with the mouse, use a graphical file
dialog if use-dialog-box is non-nil, and the window system or X
toolkit in use provides a file dialog box, and DIR is not a
remote file. For graphical file dialogs, any of the special values
of MUSTMATCH confirm and confirm-after-completion are
treated as equivalent to nil. Some graphical file dialogs respect
a MUSTMATCH value of t, and some do not (or it only has a cosmetic
effect, and does not actually prevent the user from entering a
non-existent file).
See also read-file-name-completion-ignore-case
and read-file-name-function.
Probably introduced at or before Emacs version 1.6.
Aliases
org-iread-file-name (obsolete since 9.0)
Source Code
;; Defined in /usr/src/emacs/lisp/minibuffer.el.gz
(defun read-file-name (prompt &optional dir default-filename mustmatch initial predicate)
"Read file name, prompting with PROMPT and completing in directory DIR.
The return value is not expanded---you must call `expand-file-name' yourself.
DIR is the directory to use for completing relative file names.
It should be an absolute directory name, or nil (which means the
current buffer's value of `default-directory').
DEFAULT-FILENAME specifies the default file name to return if the
user exits the minibuffer with the same non-empty string inserted
by this function. If DEFAULT-FILENAME is a string, that serves
as the default. If DEFAULT-FILENAME is a list of strings, the
first string is the default. If DEFAULT-FILENAME is omitted or
nil, then if INITIAL is non-nil, the default is DIR combined with
INITIAL; otherwise, if the current buffer is visiting a file,
that file serves as the default; otherwise, the default is simply
the string inserted into the minibuffer.
If the user exits with an empty minibuffer, return an empty
string. (This happens only if the user erases the pre-inserted
contents, or if `insert-default-directory' is nil.)
Fourth arg MUSTMATCH can take the following values:
- nil means that the user can exit with any input.
- t means that the user is not allowed to exit unless
the input is (or completes to) an existing file.
- `confirm' means that the user can exit with any input, but she needs
to confirm her choice if the input is not an existing file.
- `confirm-after-completion' means that the user can exit with any
input, but she needs to confirm her choice if she called
`minibuffer-complete' right before `minibuffer-complete-and-exit'
and the input is not an existing file.
- a function, which will be called with a single argument, the
input unquoted by `substitute-in-file-name', which see. If the
function returns a non-nil value, the minibuffer is exited with
that argument as the value.
- anything else behaves like t except that typing RET does not exit if it
does non-null completion.
Fifth arg INITIAL specifies text to start with. It will be
interpreted as the trailing part of DEFAULT-FILENAME, so using a
full file name for INITIAL will usually lead to surprising
results.
Sixth arg PREDICATE, if non-nil, should be a function of one
argument; then a file name is considered an acceptable completion
alternative only if PREDICATE returns non-nil with the file name
as its argument.
If this command was invoked with the mouse, use a graphical file
dialog if `use-dialog-box' is non-nil, and the window system or X
toolkit in use provides a file dialog box, and DIR is not a
remote file. For graphical file dialogs, any of the special values
of MUSTMATCH `confirm' and `confirm-after-completion' are
treated as equivalent to nil. Some graphical file dialogs respect
a MUSTMATCH value of t, and some do not (or it only has a cosmetic
effect, and does not actually prevent the user from entering a
non-existent file).
See also `read-file-name-completion-ignore-case'
and `read-file-name-function'."
;; If x-gtk-use-old-file-dialog = t (xg_get_file_with_selection),
;; then MUSTMATCH is enforced. But with newer Gtk
;; (xg_get_file_with_chooser), it only has a cosmetic effect.
;; The user can still type a non-existent file name.
(funcall (or read-file-name-function #'read-file-name-default)
prompt dir default-filename mustmatch initial predicate))