(lispref.info)Reading File Names


Next: Lisp Symbol Completion Prev: High-Level Completion Up: Completion

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.

     If EXISTING is non-`nil', then the name must refer to an existing
     file; then 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.

     The argument DIRECTORY specifies the directory to use for
     completion of relative file names.  Usually it is inserted in the
     minibuffer as initial input as well.  It defaults to the current
     buffer's default directory.

     If you specify INITIAL, that is an initial file name to insert in
     the buffer along with DIRECTORY.  In this case, point goes after
     DIRECTORY, before 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'.

     Here is an example:

          (read-file-name "The file is ")
          
          ;; After evaluating 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 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.  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 containing 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 ----------


automatically generated by info2www