GNU Info

(elisp)Reading File Names

---

Next: Programmed Completion Prev: High-Level Completion Up: Completion

---

Enter node , (file) or (file)node

Reading File Names
------------------

   Here is another high-level completion function, designed for reading
a file name.  It provides special features including automatic insertion
of the default directory.

 - Function: read-file-name prompt &optional directory default existing
          initial
     This function reads a file name in the minibuffer, prompting with
     PROMPT and providing completion.  If DEFAULT is non-`nil', then
     the function returns DEFAULT if the user just types <RET>.
     DEFAULT is not checked for validity; it is returned, whatever it
     is, if the user exits with the minibuffer empty.

     If EXISTING is non-`nil', then the user must specify the name of
     an existing file; <RET> performs completion to make the name valid
     if possible, and then refuses to exit if it is not valid.  If the
     value of EXISTING is neither `nil' nor `t', then <RET> also
     requires confirmation after completion.  If EXISTING is `nil',
     then the name of a nonexistent file is acceptable.

     The argument DIRECTORY specifies the directory to use for
     completion of relative file names.  If `insert-default-directory'
     is non-`nil', DIRECTORY is also inserted in the minibuffer as
     initial input.  It defaults to the current buffer's value of
     `default-directory'.

     If you specify INITIAL, that is an initial file name to insert in
     the buffer (after DIRECTORY, if that is inserted).  In this case,
     point goes at the beginning of INITIAL.  The default for INITIAL
     is `nil'--don't insert any file name.  To see what INITIAL does,
     try the command `C-x C-v'.  *Note:* we recommend using DEFAULT
     rather than INITIAL in most cases.

     Here is an example:

          (read-file-name "The file is ")
          
          ;; After evaluation of the preceding expression,
          ;;   the following appears in the minibuffer:
          
          ---------- Buffer: Minibuffer ----------
          The file is /gp/gnu/elisp/-!-
          ---------- Buffer: Minibuffer ----------

     Typing `manual <TAB>' results in the following:

          ---------- Buffer: Minibuffer ----------
          The file is /gp/gnu/elisp/manual.texi-!-
          ---------- Buffer: Minibuffer ----------

     If the user types <RET>, `read-file-name' returns the file name as
     the string `"/gp/gnu/elisp/manual.texi"'.

 - User Option: insert-default-directory
     This variable is used by `read-file-name'.  Its value controls
     whether `read-file-name' starts by placing the name of the default
     directory in the minibuffer, plus the initial file name if any.
     If the value of this variable is `nil', then `read-file-name' does
     not place any initial input in the minibuffer (unless you specify
     initial input with the INITIAL argument).  In that case, the
     default directory is still used for completion of relative file
     names, but is not displayed.

     For example:

          ;; Here the minibuffer starts out with the default directory.
          (let ((insert-default-directory t))
            (read-file-name "The file is "))
          
          ---------- Buffer: Minibuffer ----------
          The file is ~lewis/manual/-!-
          ---------- Buffer: Minibuffer ----------
          
          ;; Here the minibuffer is empty and only the prompt
          ;;   appears on its line.
          (let ((insert-default-directory nil))
            (read-file-name "The file is "))
          
          ---------- Buffer: Minibuffer ----------
          The file is -!-
          ---------- Buffer: Minibuffer ----------