comparison lispref/files.texi @ 46956:2c01ee3e5305

Move the node Relative Files before Directory Names. Show what file-name-nondirectory returns when given a directory name. Explain that abbreviate-file-name works on file names too. Explain how to combine a directory name with a relative file name with concat, and the pitfalls. Update some details.

46955:2a1651fdb0b5

syntax.  This enables Lisp programs to specify file names in Unix syntax
and work properly on all systems without change.

@menu
* File Name Components::  The directory part of a file name, and the rest.
* Directory Names::       A directory's name as a directory
                            is different from its name as a file.
* Relative File Names::   Some file names are relative to a current directory.
* File Name Expansion::   Converting relative file names to absolute ones.
* Unique File Names::     Generating names for temporary files.
* File Name Completion::  Finding the completions for a given file name.
* Standard File Names::   If your package uses a fixed file name,
                            how to handle various operating systems simply.

has a version number, but most of the time the file name actually used
in Emacs omits the version number, so that version numbers in Emacs are
found mostly in directory lists.

@defun file-name-directory filename
This function returns the directory part of @var{filename} (or
@code{nil} if @var{filename} does not include a directory part).  On
most systems, the function returns a string ending in a slash.  On VMS,
it returns a string ending in one of the three characters @samp{:},
@samp{]}, or @samp{>}.

@example
@group
(file-name-directory "lewis/foo")  ; @r{Unix example}

     @result{} "foo"
@end group
@group
(file-name-nondirectory "foo")
     @result{} "foo"
@end group
@group
;; @r{The following example is accurate only on VMS.}
(file-name-nondirectory "[X]FOO.TMP")
     @result{} "FOO.TMP"
@end group
@end example
@end defun

@defun file-name-sans-versions filename &optional keep-backup-version
This function returns @var{filename} with any file version numbers,
backup version numbers, or trailing tildes discarded.

If @var{keep-backup-version} is non-@code{nil}, then true file version
numbers understood as such by the file system are discarded from the
return value, but backup version numbers are kept.

@example
@group
(file-name-sans-versions "~rms/foo.~1~")
     @result{} "~rms/foo"
@end group
@group
(file-name-sans-versions "~rms/foo~")
     @result{} "~rms/foo"
@end group
@group
(file-name-sans-versions "~rms/foo")
     @result{} "~rms/foo"
@end group
@group
;; @r{The following example applies to VMS only.}
(file-name-sans-versions "foo;23")
     @result{} "foo"
@end group
@end example
@end defun

@defun file-name-sans-extension filename
This function returns @var{filename} minus its ``extension,'' if any.
The extension, in a file name, is the part that starts with the last
@samp{.} in the last name component, except if that @samp{.} is the
first character of the file name's last component.  For example,

@example
(file-name-sans-extension "foo.lose.c")
     @result{} "foo.lose"
(file-name-sans-extension "big.hack/foo")
     @result{} "big.hack/foo"
(file-name-sans-extension "/my/home/.emacs")
     @result{} "/my/home.emacs"
(file-name-sans-extension "/my/home/.emacs.el")
     @result{} "/my/home/.emacs"
@end example
@end defun

@ignore
Andrew Innes says that this 

@c @defvar directory-sep-char
@c @tindex directory-sep-char
This variable holds the character that Emacs normally uses to separate
file name components.  The default value is @code{?/}, but on MS-Windows
you can set it to @code{?\\}; then the functions that transform file names
use backslashes in their output.

File names using backslashes work as input to Lisp primitives even on
MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
value of @code{?/}.
@end defvar
@end ignore

@defun file-name-extension filename &optional period
This function returns @var{filename}'s final ``extension,'' if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part.  It returns @code{nil} for extensionless file

component of a file name begins with a @samp{.}, that @samp{.} doesn't
count as the beginning of an extension, so, for example,
@file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}.
@end defun

@node Directory Names
@comment  node-name,  next,  previous,  up
@subsection Directory Names
@cindex directory name
@cindex file name of directory

  A @dfn{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 @samp{$HOME}, and the constructs @samp{~}, and @samp{..}.

@defun file-name-as-directory filename
This function returns a string representing @var{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
@file{[X]Y.DIR.1} to the form @file{[X.Y]}.

@example
@group
(file-name-as-directory "~rms/lewis")
     @result{} "~rms/lewis/"
@end group
@end example
@end defun

@defun directory-file-name dirname
This function returns a string representing @var{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 @file{[X.Y]}
to @file{[X]Y.DIR.1}.

@example
@group
(directory-file-name "~lewis/")
     @result{} "~lewis"
@end group
@end example
@end defun

@cindex directory name abbreviation
  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.

@defvar directory-abbrev-alist
The variable @code{directory-abbrev-alist} contains an alist of
abbreviations to use for file directories.  Each element has the form
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
@var{to} when it appears in a directory name.  The @var{from} string is
actually a regular expression; it should always start with @samp{^}.
The function @code{abbreviate-file-name} performs these substitutions.

You can set this variable in @file{site-init.el} to describe the
abbreviations appropriate for your site.

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

@example
(("^/home/fsf" . "/fsf")
 ("^/home/gp" . "/gp")
 ("^/home/gd" . "/gd"))
@end example
@end defvar

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

@defun abbreviate-file-name dirname
This function applies abbreviations from @code{directory-abbrev-alist}
to its argument, and substitutes @samp{~} for the user's home
directory.
@end defun

@node Relative File Names
@subsection Absolute and Relative File Names
@cindex absolute file name
@cindex relative file name

@group
(file-name-absolute-p "/user/rms/foo")
     @result{} t
@end group
@end example
@end defun

@node File Name Expansion
@subsection Functions that Expand Filenames
@cindex expansion of file names

46956:2c01ee3e5305

syntax.  This enables Lisp programs to specify file names in Unix syntax
and work properly on all systems without change.

@menu
* File Name Components::  The directory part of a file name, and the rest.
* Relative File Names::   Some file names are relative to a current directory.
* Directory Names::       A directory's name as a directory
                            is different from its name as a file.
* File Name Expansion::   Converting relative file names to absolute ones.
* Unique File Names::     Generating names for temporary files.
* File Name Completion::  Finding the completions for a given file name.
* Standard File Names::   If your package uses a fixed file name,
                            how to handle various operating systems simply.

has a version number, but most of the time the file name actually used
in Emacs omits the version number, so that version numbers in Emacs are
found mostly in directory lists.

@defun file-name-directory filename
This function returns the directory part of @var{filename}, as a
directory name (@pxref{Directory Names}), or @code{nil} if
@var{filename} does not include a directory part.

On GNU and Unix systems, a string returned by this function always
ends in a slash.  On MSDOS it can also end in a colon.  On VMS, it
returns a string ending in one of the three characters @samp{:},
@samp{]}, or @samp{>}.

@example
@group
(file-name-directory "lewis/foo")  ; @r{Unix example}

     @result{} "foo"
@end group
@group
(file-name-nondirectory "foo")
     @result{} "foo"
@end group
@group
(file-name-nondirectory "lewis/")
     @result{} ""
@end group
@group
;; @r{The following example is accurate only on VMS.}
(file-name-nondirectory "[X]FOO.TMP")
     @result{} "FOO.TMP"
@end group
@end example
@end defun

@defun file-name-extension filename &optional period
This function returns @var{filename}'s final ``extension,'' if any,
after applying @code{file-name-sans-versions} to remove any
version/backup part.  It returns @code{nil} for extensionless file

component of a file name begins with a @samp{.}, that @samp{.} doesn't
count as the beginning of an extension, so, for example,
@file{.emacs}'s ``extension'' is @code{nil}, not @samp{.emacs}.
@end defun

@defun file-name-sans-versions filename &optional keep-backup-version
This function returns @var{filename} with any file version numbers,
backup version numbers, or trailing tildes discarded.

If @var{keep-backup-version} is non-@code{nil}, then true file version
numbers understood as such by the file system are discarded from the
return value, but backup version numbers are kept.

@example
@group
(file-name-sans-versions "~rms/foo.~1~")
     @result{} "~rms/foo"
@end group
@group
(file-name-sans-versions "~rms/foo~")
     @result{} "~rms/foo"
@end group
@group
(file-name-sans-versions "~rms/foo")
     @result{} "~rms/foo"
@end group
@group
;; @r{The following example applies to VMS only.}
(file-name-sans-versions "foo;23")
     @result{} "foo"
@end group
@end example
@end defun

@defun file-name-sans-extension filename
This function returns @var{filename} minus its ``extension,'' if any.
The extension, in a file name, is the part that starts with the last
@samp{.} in the last name component, except if that @samp{.} is the
first character of the file name's last component.  For example,

@example
(file-name-sans-extension "foo.lose.c")
     @result{} "foo.lose"
(file-name-sans-extension "big.hack/foo")
     @result{} "big.hack/foo"
(file-name-sans-extension "/my/home/.emacs")
     @result{} "/my/home.emacs"
(file-name-sans-extension "/my/home/.emacs.el")
     @result{} "/my/home/.emacs"
@end example
@end defun

@ignore
Andrew Innes says that this 

@c @defvar directory-sep-char
@c @tindex directory-sep-char
This variable holds the character that Emacs normally uses to separate
file name components.  The default value is @code{?/}, but on MS-Windows
you can set it to @code{?\\}; then the functions that transform file names
use backslashes in their output.

File names using backslashes work as input to Lisp primitives even on
MS-DOS and MS-Windows, even if @code{directory-sep-char} has its default
value of @code{?/}.
@end defvar
@end ignore

@node Relative File Names
@subsection Absolute and Relative File Names
@cindex absolute file name
@cindex relative file name

@group
(file-name-absolute-p "/user/rms/foo")
     @result{} t
@end group
@end example
@end defun

@node Directory Names
@comment  node-name,  next,  previous,  up
@subsection Directory Names
@cindex directory name
@cindex file name of directory

  A @dfn{directory name} is the name of a directory.  A directory is
actually a kind of file, so 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 GNU and
Unix 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 MSDOS and 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.  When @code{file-name-directory} returns a string, that is
always a directory name.

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

@defun file-name-as-directory filename
This function returns a string representing @var{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
@file{[X]Y.DIR.1} to the form @file{[X.Y]}.

@example
@group
(file-name-as-directory "~rms/lewis")
     @result{} "~rms/lewis/"
@end group
@end example
@end defun

@defun directory-file-name dirname
This function returns a string representing @var{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 @file{[X.Y]}
to @file{[X]Y.DIR.1}.

@example
@group
(directory-file-name "~lewis/")
     @result{} "~lewis"
@end group
@end example
@end defun

  Given a directory name, you can combine it with a relative file name
using @code{concat}:

@example
(concat @var{dirname} @var{relfile})
@end example

@noindent
Be sure to verify that the file name is relative before doing that.
If you use an absolute file name, the results could be syntactically
invalid or refer to the wrong file.

  If you want to use a directory file name in making such a
combination, you must first convert it to a directory name using
@code{file-name-as-directory}:

@example
(concat (file-name-as-directory @var{dirfile}) @var{relfile})
@end example

@noindent
Don't try concatenating a slash by hand, as in

@example
;;; @r{Wrong!}
(concat @var{dirfile} "/" @var{relfile})
@end example

@noindent
because this is not portable.  Always use
@code{file-name-as-directory}.

@cindex directory name abbreviation
  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.

@defvar directory-abbrev-alist
The variable @code{directory-abbrev-alist} contains an alist of
abbreviations to use for file directories.  Each element has the form
@code{(@var{from} . @var{to})}, and says to replace @var{from} with
@var{to} when it appears in a directory name.  The @var{from} string is
actually a regular expression; it should always start with @samp{^}.
The function @code{abbreviate-file-name} performs these substitutions.

You can set this variable in @file{site-init.el} to describe the
abbreviations appropriate for your site.

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

@example
(("^/home/fsf" . "/fsf")
 ("^/home/gp" . "/gp")
 ("^/home/gd" . "/gd"))
@end example
@end defvar

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

@defun abbreviate-file-name filename
This function applies abbreviations from @code{directory-abbrev-alist}
to its argument, and substitutes @samp{~} for the user's home
directory.  You can use it for directory names and for file names,
because it recognizes abbreviations even as part of the name.
@end defun

@node File Name Expansion
@subsection Functions that Expand Filenames
@cindex expansion of file names