GNU Info

(elisp)Directory Names

---

Next: Relative File Names Prev: File Name Components Up: File Names

---

Enter node , (file) or (file)node

Directory Names
---------------

   A "directory name" is the name of a directory.  A directory is a
kind of file, and it has a file name, which is related to the directory
name but not identical to it.  (This is not quite the same as the usual
Unix terminology.)  These two different names for the same entity are
related by a syntactic transformation.  On most systems, this is simple:
a directory name ends in a slash (or backslash), whereas the directory's
name as a file lacks that slash.  On VMS, the relationship is more
complicated.

   The difference between a directory name and its name as a file is
subtle but crucial.  When an Emacs variable or function argument is
described as being a directory name, a file name of a directory is not
acceptable.

   The following two functions convert between directory names and file
names.  They do nothing special with environment variable substitutions
such as `$HOME', and the constructs `~', and `..'.

 - Function: file-name-as-directory filename
     This function returns a string representing FILENAME in a form
     that the operating system will interpret as the name of a
     directory.  On most systems, this means appending a slash to the
     string (if it does not already end in one).  On VMS, the function
     converts a string of the form `[X]Y.DIR.1' to the form `[X.Y]'.

          (file-name-as-directory "~rms/lewis")
               => "~rms/lewis/"

 - Function: directory-file-name dirname
     This function returns a string representing DIRNAME in a form that
     the operating system will interpret as the name of a file.  On most
     systems, this means removing the final slash (or backslash) from
     the string.  On VMS, the function converts a string of the form
     `[X.Y]' to `[X]Y.DIR.1'.

          (directory-file-name "~lewis/")
               => "~lewis"

   Directory name abbreviations are useful for directories that are
normally accessed through symbolic links.  Sometimes the users recognize
primarily the link's name as "the name" of the directory, and find it
annoying to see the directory's "real" name.  If you define the link
name as an abbreviation for the "real" name, Emacs shows users the
abbreviation instead.

 - Variable: directory-abbrev-alist
     The variable `directory-abbrev-alist' contains an alist of
     abbreviations to use for file directories.  Each element has the
     form `(FROM . TO)', and says to replace FROM with TO when it
     appears in a directory name.  The FROM string is actually a
     regular expression; it should always start with `^'.  The function
     `abbreviate-file-name' performs these substitutions.

     You can set this variable in `site-init.el' to describe the
     abbreviations appropriate for your site.

     Here's an example, from a system on which file system `/home/fsf'
     and so on are normally accessed through symbolic links named `/fsf'
     and so on.

          (("^/home/fsf" . "/fsf")
           ("^/home/gp" . "/gp")
           ("^/home/gd" . "/gd"))

   To convert a directory name to its abbreviation, use this function:

 - Function: abbreviate-file-name dirname
     This function applies abbreviations from `directory-abbrev-alist'
     to its argument, and substitutes `~' for the user's home directory.