files.tex

%Part{Files, Root = "CLM.MSS"}
%%%Chapter of Common Lisp Manual.  Copyright 1984, 1988, 1989 Guy L. Steele Jr.

\clearpage\def\pagestatus{FINAL PROOF}

\chapter{File System Interface}
\label{FILES}

%\chapter{Работа с файловой системой}
%\label{FILES}

A frequent use of streams is to communicate with a \emph{file system}
to which groups of data (files) can be written and from which files
can be retrieved.

Потоки чаще всего используются для работы с \emph{файловой системой}, в которую
могут быть записаны данные (файлы) и из которой после эти файлы могут быть
прочитаны.

Common Lisp defines a standard interface for dealing with such a file system.
This interface is designed to be simple and general enough to
accommodate the facilities provided by ``typical'' operating system
environments within which Common Lisp is likely to be implemented.
The goal is to make Common Lisp programs that perform only simple operations
on files reasonably portable.

Common Lisp определяет стандартный интерфейс для работы с файловой системой.
Данные интерфейс спроектирован простым и достаточно обобщённым для того, чтобы
предоставлять функционал <<типичной>> операционной системы, в которой работает
реализация Common Lisp'а. Целью является переносимость Common Lisp'овых программ
в случае, если они используют простые операции над файлами.

To this end, Common Lisp assumes that files are named, that given a name one
can construct a stream connected to a file of that name, and that the
names can be fit into a certain canonical, implementation-independent
form called a \emph{pathname}.

И наконец, Common Lisp предполагает, что файлы имеют имена, которые используются
при создании файлового потока. Эти имена абстрагируются в системонезависимую
форму - \emph{pathname}.

Facilities are provided for manipulating pathnames, for creating
streams connected to files, and for manipulating the file system
through pathnames and streams.

Интерфейс предоставляет функционал для управления именами-файлов, для создания
файловых потоков, и для управления файловой системой с помощью имён-файлов и
потоков.

\section{File Names}
%\section{Имена файлов}

Common Lisp programs need to use names to designate files.
The main difficulty in dealing with names of files is that different
file systems have different naming formats for files.
For example, here is a table of several file systems (actually,
operating systems that provide file systems) and what equivalent
file names might look like for each one:
\begin{flushleft}
\begin{tabular}{@{}l@{\hskip 2pc}l@{}}
System&File Name \\
\hlinesp
{TOPS-20}&\cd{<LISPIO>FORMAT.FASL.13} \\
{TOPS-10}&\cd{FORMAT.FAS{\Xlbracket}1,4{\Xrbracket}} \\
{ITS}&\cd{LISPIO;FORMAT FASL} \\
{MULTICS}&\cd{>udd>LispIO>format.fasl} \\
{TENEX}&\cd{<LISPIO>FORMAT.FASL;13} \\
{VAX}/{VMS}&\cd{{\Xlbracket}LISPIO{\Xrbracket}FORMAT.FAS;13} \\
{UNIX}&\cd{/usr/lispio/format.fasl} \\
\hline
\end{tabular}
\end{flushleft}
It would be impossible for each program that deals with file names to
know about each different file name format that exists; a new Common Lisp
implementation might use a format different from any of its predecessors.
Therefore, Common Lisp provides \emph{two} ways to represent file names:
\emph{namestrings}, which are strings in the implementation-dependent form
customary for the file system, and \emph{pathnames}, which are special abstract
data objects that represent file names in an implementation-independent
way.  Functions are provided to convert between these two representations,
and all manipulations of files can be expressed in machine-independent
terms by using pathnames.

In order to allow Common Lisp programs to operate in a network environment
that may have more than one kind of file system, the pathname facility
allows a file name to specify which file system is to be used.
In this context, each file system is called a \emph{host}, in keeping
with the usual networking terminology.

\begin{newer}
Different hosts may use different notations for file names.
Common Lisp allows customary notation to be used for each host, but
also supports
a system of logical pathnames that provides a standard framework for naming
files in a portable manner (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}

\subsection{Pathnames}
\label{PATHNAME}
All file systems dealt with by Common Lisp are forced into a common framework,
in which files are named by a Lisp data object of type \cdf{pathname}.

A pathname always has six components, described below.  These components
are the common interface that allows programs to work the same way with
different file systems; the mapping of the pathname components into the
concepts peculiar to each file system is taken care of by the Common Lisp
implementation.


\begin{flushdesc}
\item[\emph{host}]
The name of the file system on which the file resides.

\item[\emph{device}]
Corresponds to the ``device'' or ``file structure'' concept in many
host file systems: the name of a (logical or physical) device containing files.

\item[\emph{directory}]
Corresponds to the ``directory'' concept in many host file systems:
the name of a group of related files
(typically those belonging to a single
user or project).

\item[\emph{name}]
The name of a group of files that can be thought of as
the ``same'' file.

\item[\emph{type}]
Corresponds to the ``filetype'' or ``extension'' concept in many host
file systems; identifies the type of file.  Files with the same names
but different types are usually related in some specific way, for instance,
one being a source file, another the compiled form of that source,
and a third the listing of error messages from the compiler.

\item[\emph{version}]
Corresponds to the ``version number'' concept in many host file systems.
Typically this is a number that is incremented every time the file is modified.
\end{flushdesc}

Note that a pathname is not necessarily the name of a specific file.
Rather, it is a specification (possibly only a partial specification) of
how to access a file.  A pathname need not correspond to any file that
actually exists, and more than one pathname can refer to the same file.
For example, the pathname with a version of ``newest'' may refer to the
same file as a pathname with the same components except a certain number
as the version.  Indeed, a pathname with version ``newest'' may refer to
different files as time passes, because the meaning of such a pathname
depends on the state of the file system.  In file systems with such
facilities as ``links,'' multiple file names, logical devices, and so on,
two pathnames that look quite different may turn out to address the same
file.  To access a file given a pathname, one must do a file system
operation such as
\cdf{open}.

Two important operations involving pathnames are \emph{parsing} and
\emph{merging}.  Parsing is the conversion of a namestring (which might be
something supplied interactively by the user when asked to supply the
name of a file) into a pathname object.  This operation is
implementation-dependent, because the format of namestrings
is implementation-dependent.
Merging takes a pathname with missing components
and supplies values for those components from a source of defaults.

Not all of the components of a pathname need to be specified.  If a
component of a pathname is missing, its value is {\nil}.  Before the file
system interface can do anything interesting with a file, such as opening the
file, all the missing components of a pathname must be filled in
(typically from a set of defaults).  Pathnames with missing components
may be used internally for various purposes;
in particular, parsing a namestring
that does not specify certain components will result in a pathname with
missing components.

\begin{newer}
X3J13 voted in January 1989 \issue{PATHNAME-UNSPECIFIC-COMPONENT}
to permit any component of a pathname to have the value \cd{:unspecific},
meaning that the component simply does not exist,
for file systems in which such a value makes sense.
(For example, a UNIX file system usually does not support version numbers,
so the version component of a pathname for a UNIX host might be
\cd{:unspecific}.  Similarly,
the file type is usually regarded in a UNIX file system as the part
of a name after a period, but some file names contain no periods and therefore have
no file types.)

  When a pathname is converted to a namestring, the values \cdf{nil} and \cd{:unspecific}
  have the same effect: they
  are treated as if the component were empty (that is, they each cause the
  component not to appear in the namestring).
  When merging, however, only a \cdf{nil} value for a component will be
  replaced with the default for that component; the value \cd{:unspecific}
  will be left alone as if the field were filled.

  The results are undefined if \cd{:unspecific} is supplied
  to a file system in a component for which
  \cd{:unspecific} does not make sense for that file system.

  Programming hint:
  portable programs should be prepared to handle the value \cd{:unspecific} in the device,
  directory, type, or version field in some implementations.
  Portable programs should not explicitly place \cd{:unspecific} in any
  field because it might not be permitted in some situations,
  but portable programs may sometimes do so implicitly (by copying
  such a value from another pathname, for example).
\end{newer}

What values are allowed for components of a pathname depends, in general,
on the pathname's host.  However, in order for pathnames to be usable
in a system-independent way, certain global conventions are adhered to.
These conventions are stronger for the type and version than for the
other components, since the type and version are explicitly manipulated by
many programs, while the other components are usually treated as something
supplied by the user that just needs to be remembered and copied
from place to place.

The type is always a string or {\nil} or \cd{:wild}.
It is expected that most
programs that deal with files will supply a default type for each file.

The version is either a positive integer or a special symbol.  The
meanings of {\nil} and \cd{:wild} have been explained
above.  The keyword \cd{:newest} refers to the largest version number
that already exists in the file system when reading a file, or to
a version number
greater than any already existing in the file system
when writing a new file.  Some Common Lisp implementors
may choose to define other special version symbols.
Some semi-standard names, suggested but not required to be supported
by every Common Lisp implementation, are
\cd{:oldest}, to refer to the smallest version number that exists
in the file system;
\cd{:previous}, to refer to the version previous to the newest version;
and \cd{:installed}, to refer to a version that is officially installed
for users (as opposed to a working or development version).
Some Common Lisp implementors may also choose to attach a meaning to
non-positive version numbers (a typical convention is that \cd{0}
is synonymous with \cd{:newest} and \cd{-1} with \cd{:previous}),
but such interpretations are implementation-dependent.

The host may be a string, indicating a file system, or a list
of strings, of which the first names the file system and the rest
may be used for such a purpose as inter-network routing.

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-VALUE}
to approve the following clarifications and specifications
of precisely what are valid values for the various components
of a pathname.

\makeatletter
\def\@listi{\leftmargin\leftmargini \labelsep\leftmargin
   \parsep 3pt\relax
   \topsep 2pt plus 5pt\relax
   \itemsep\topsep}
\makeatother

  Pathname component value strings never contain the punctuation
  characters that are used to separate fields in a namestring (for example,
  slashes and
  periods as used in UNIX file systems).  Punctuation characters appear only in namestrings.
  Characters used as punctuation can appear in pathname component values
  with a non-punctuation meaning if the file system allows it (for example,
  UNIX file systems allow a file name to begin with a period).

  When examining pathname components, conforming programs must be prepared
  to encounter any of the following siutations:
  \begin{itemize}
    \item Any component can be \cdf{nil}, which means the component has not
    been specified.
  
   \item  Any component can be \cd{:unspecific}, which means the component has
    no meaning in this particular pathname.
  
   \item  The device, directory, name, and type can be strings.
  
   \item  The host can be any object, at the discretion of the implementation.
  
  \item  The directory can be a list of strings and symbols as described in
    section~\ref{STRUCTURED-DIRECTORY-SECTION}.
  
  \item  The version can be any symbol or any integer.  The symbol \cd{:newest}
    refers to the largest version number that already exists in the file
    system when reading, overwriting, appending, superseding, or
    directory-listing an existing file; it refers to the smallest version number
    greater than any existing version number when creating a new file.
    Other symbols and integers have implementation-defined meaning.
    It is suggested, but not required, that implementations use positive
    integers starting at 1 as version numbers, recognize the symbol \cd{:oldest}
    to designate the smallest existing version number, and use keyword
    symbols for other special versions.
  \end{itemize}

  When examining wildcard components of a wildcard pathname, conforming programs
  must be prepared to encounter any of the following additional values
  in any component or any element of a list that is the directory component:
  \begin{itemize}
    \item The symbol \cd{:wild}, which matches anything.

   \item  A string containing implementation-dependent special wildcard
    characters.

    \item  Any object, representing an implementation-dependent wildcard pattern.
  \end{itemize}

  When constructing a pathname from components, conforming programs
  must follow these rules:
  \begin{itemize}
    \item  Any component may be \cdf{nil}.  Specifying \cdf{nil} for the host may,
     in some implementations,
    result in using a default host
    rather than an actual \cdf{nil} value.
    
    \item  The host, device, directory, name, and type may be strings.  There
    are implementation-dependent limits on the number and type of
    characters in these strings.  A plausible assumption is that letters (of a single case)
    and digits are acceptable to most file systems.
  
    \item  The directory may be a list of strings and symbols as described in
    section~\ref{STRUCTURED-DIRECTORY-SECTION}.  There are
    implementation-dependent limits on the length and contents of the list.
  
   \item  The version may be \cd{:newest}.

    \item  Any component may be taken from the corresponding component
    of another pathname.  When the two pathnames are for different
    file systems (in implementations that support multiple file
    systems), an appropriate translation occurs.  If no meaningful
    translation is possible, an error is signaled.  The definitions
    of ``appropriate'' and ``meaningful'' are implementation-dependent.
  
    \item  When constructing a wildcard pathname, the name, type, or version
    may be \cd{:wild}, which matches anything.
  
   \item  An implementation might support other values for some components,
    but a portable program should not use those values.  A conforming program
    can use implementation-dependent values but this can make it
    non-portable; for example, it might work only with UNIX file systems.
   \end{itemize}
\end{newer}

The best way to compare two pathnames for equality is with \cdf{equal},
not \cdf{eql}.
(On pathnames, \cdf{eql} is simply the same as \cdf{eq}.)
Two pathname objects are \cdf{equal} if and only if
all the corresponding components
(host, device, and so on) are equivalent.  (Whether or not
uppercase and lowercase letters are considered equivalent
in strings appearing in components depends on the file
name conventions of the file system.)  Pathnames
that are \cdf{equal} should be functionally equivalent.

\subsection{Case Conventions}
\label{PATHNAME-COMPONENT-CASE-SECTION}

  Issues of alphabetic case in pathnames are a major source of problems.
  In some file systems, the customary case is lowercase, in some uppercase,
  in some mixed.  Some file systems are case-sensitive (that is, they treat
  \cdf{FOO} and \cdf{foo} as different file names) and others are not.

  There are two kinds of pathname case portability problems: moving
  programs from one Common Lisp to another, and moving pathname component
  values from one file system to another.  The solution to the first problem
  is the requirement that all
  Common Lisp implementations that support a particular file system must
  use compatible representations for pathname component values.  The solution to
  the second problem is the use of a common representation for the
  least-common-denominator pathname component values that exist on all
  interesting file systems.

  Requiring a common representation directly conflicts with the
  desire among programmers that use only one file system to work with the
  local conventions and to ignore issues of porting to other file
  systems.  The common representation cannot be the same as local (varying)
  conventions.

X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-CASE} to
add a keyword argument \cd{:case} to each of the functions
  \cdf{make-pathname}, \cdf{pathname-host},
  \cdf{pathname-device}, \cdf{pathname-directory}, \cdf{pathname-name},
  and \cdf{pathname-type}.
  The possible values for the argument are \cd{:common} and \cd{:local}.
  The default is \cd{:local}.

  The value \cd{:local} means that strings given to \cdf{make-pathname}
  or returned by any of the pathname component accessors
  follow the local file system's conventions for alphabetic case.
  Strings given to \cdf{make-pathname} will be used exactly as written if
  the file system supports both cases.  If the file system
  supports only one case, the strings will be translated to that case.

  The value \cd{:common} means that strings given to \cdf{make-pathname}
  or returned by any of the pathname component accessors
  follow this common convention:
\begin{itemize}
\item All uppercase means that a file system's customary case will be used.
\item All lowercase means that the opposite of the customary case will be used.
\item Mixed case represents itself.
\end{itemize}
  Uppercase is used as the common case for no better reason than
  consistency with Lisp symbols.
  The second and third points allow translation from local representation to
  common and back to be information-preserving.  (Note that translation
  from common to local representation and back may or may not be information-preserving,
  depending on the nature of the local representation.)

  Namestrings always use \cd{:local} file system case conventions.

  Finally, \cdf{merge-pathnames} and \cdf{translate-pathname} map customary case in the
  input pathnames into customary case in the output pathname.

  Examples of possible use of this convention:
\begin{itemize}
  \item TOPS-20 is case-sensitive and prefers uppercase,
  translating lowercase to uppercase unless escaped with \cd{{\Xcircumflex}V};
  for a TOPS-20--based
  file system, a Common Lisp implementation
  should use identical
  representations for common and local.

\item UNIX is case-sensitive and prefers lowercase; for a UNIX-based file system,
  a Common Lisp implementation should translate between
  common and local representations by inverting the case of non-mixed-case strings.

\item VAX/VMS is uppercase-only (that is, the file system translates all file
  name arguments to uppercase); for a VAX/VMS-based file system,
  a Common Lisp implementation should
  translate common representation to local by
  converting to uppercase and should translate local representation
  to common with no change.

\item The Macintosh operating system is case-insensitive and prefers lowercase,
  but remembers the cases of letters actually used to name a file;
  for a Macintosh-based file system, a Common Lisp implementation should translate
  between common and local representations by inverting the case of non-mixed-case strings
  and should ignore case when determining whether two pathnames are \cdf{equal}.
\end{itemize}

\newpage%required

Here are some examples of this behavior.  Assume that the host \cdf{T} runs
TOPS-20, \cdf{U} runs UNIX, \cdf{V} runs VAX/VMS, and \cdf{M} runs the Macintosh
operating system.
\begin{lisp}
;;; Returns two values: the PATHNAME-NAME from a namestring \\*
;;; in :COMMON and :LOCAL representations (in that order). \\*
(defun pathname-example (name) \\*
~~(let ((path (parse-namestring name)))) \\*
~~~~(values (pathname-name path :case :common) \\*
~~~~~~~~~~~~(pathname-name path :case :local)))) \\
\\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\EV\ "FOO" \textrm{and} \="FOO" \kill
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~;\textrm{Common}\>\textrm{Local} \\*
(pathname-example "T:<ME>FOO.LISP")~~~~~~~~\EV\ "FOO" \textrm{and} "FOO" \\*
(pathname-example "T:<ME>foo.LISP")~~~~~~~~\EV\ "FOO" \textrm{and} "FOO" \\*
(pathname-example "T:<ME>{\Xcircumflex}Vf{\Xcircumflex}Vo{\Xcircumflex}Vo.LISP")~~\EV\ "foo" \textrm{and} "foo" \\
(pathname-example "T:<ME>TeX.LISP")~~~~~~~~\EV\ "TEX" \textrm{and} "TEX" \\
(pathname-example "T:<ME>T{\Xcircumflex}VeX.LISP")~~~~~~\EV\ "TeX" \textrm{and} "TeX" \\
(pathname-example "U:/me/FOO.lisp")~~~~~~~~\EV\ "foo" \textrm{and} "FOO" \\
(pathname-example "U:/me/foo.lisp")~~~~~~~~\EV\ "FOO" \textrm{and} "foo" \\
(pathname-example "U:/me/TeX.lisp")~~~~~~~~\EV\ "TeX" \textrm{and} "TeX" \\
(pathname-example "V:[me]FOO.LISP")~~~~~~~~\EV\ "FOO" \textrm{and} "FOO" \\
(pathname-example "V:[me]foo.LISP")~~~~~~~~\EV\ "FOO" \textrm{and} "FOO" \\
(pathname-example "V:[me]TeX.LISP")~~~~~~~~\EV\ "TEX" \textrm{and} "TEX" \\
(pathname-example "M:FOO.LISP")~~~~~~~~~~~~\EV\ "foo" \textrm{and} "FOO" \\*
(pathname-example "M:foo.LISP")~~~~~~~~~~~~\EV\ "FOO" \textrm{and} "foo" \\*
(pathname-example "M:TeX.LISP")~~~~~~~~~~~~\EV\ "TeX" \textrm{and} "TeX"
\end{lisp}
The following example illustrates the creation of new pathnames.
The name is converted from common representation to local because
namestrings always use local conventions.
\begin{lisp}
(defun make-pathname-example (h n) \\*
~~(namestring (make-pathname :host h :name n :case :common)) \\
\\
(make-pathname-example "T" "FOO") \EV\ "T:FOO" \\*
(make-pathname-example "T" "foo") \EV\ "T:{\Xcircumflex}Vf{\Xcircumflex}Vo{\Xcircumflex}Vo" \\
(make-pathname-example "T" "TeX") \EV\ "T:T{\Xcircumflex}VeX" \\
(make-pathname-example "U" "FOO") \EV\ "U:foo" \\
(make-pathname-example "U" "foo") \EV\ "U:FOO" \\
(make-pathname-example "U" "TeX") \EV\ "U:TeX" \\
(make-pathname-example "V" "FOO") \EV\ "V:FOO" \\
(make-pathname-example "V" "foo") \EV\ "V:FOO" \\
(make-pathname-example "V" "TeX") \EV\ "V:TeX" \\
(make-pathname-example "M" "FOO") \EV\ "M:foo" \\
(make-pathname-example "M" "foo") \EV\ "M:FOO" \\*
(make-pathname-example "M" "TeX") \EV\ "M:TeX"
\end{lisp}
A big advantage of this set of conventions is that one can, for example,
call \cdf{make-pathname} with \cd{:type~"LISP"} and \cd{:case~:common},
and the result will appear in a namestring as \cd{.LISP} or \cd{.lisp},
whichever is appropriate.

\subsection{Structured Directories}
\label{STRUCTURED-DIRECTORY-SECTION}

X3J13 voted in June 1989 \issue{PATHNAME-SUBDIRECTORY-LIST}
to define a specific pathname component format for structured directories.

The value of a pathname's directory component may be a list.  The
  \emph{car} of the list should be a keyword, either \cd{:absolute} or \cd{:relative}.
  Each remaining element of the list should be a string or a symbol (see below).
  Each string names a single level of directory structure and should consist
  of only the directory name without any punctuation characters.

  A list whose \emph{car} is the symbol \cd{:absolute} represents a directory path
  starting from the root directory.  For example, the list \cd{(:absolute)} represents
  the root directory itself;  the list \cd{(:absolute "foo" "bar" "baz")} represents
  the directory that in a UNIX file system would be called \cd{/foo/bar/baz}.

  A list whose \emph{car} is the symbol \cd{:relative} represents a directory path
  starting from a default directory.  The list \cd{(:relative)} has the same
  meaning as \cdf{nil} and hence normally is not used.  The list \cd{(:relative "foo" "bar")}
  represents the directory named \cdf{bar} in the directory named \cdf{foo} in the
  default directory.

  In place of a string, at any point in the list, a symbol may occur to
  indicate a special file notation. The following symbols have standard
  meanings.
\begin{indentdesc}{}
\item[\cd{:wild}]
Wildcard match of one level of directory structure

\item[\cd{:wild-inferiors}]
  Wildcard match of any number of directory levels

\item[\cd{:up}]
  Go upward in directory structure (semantic)

\item[\cd{:back}]
  Go upward in directory structure (syntactic)
\end{indentdesc}

  (See section~\ref{WILD-PATHNAME-SECTION} for a discussion of wildcard pathnames.)

  Implementations are permitted to add additional objects of any
  non-string type if necessary to represent features of their file systems
  that cannot be represented with the standard strings and symbols.
  Supplying any non-string, including any of the symbols listed below, to a
  file system for which it does not make sense signals an error of type
  \cdf{file-error}.  For example, most implementations of the UNIX file system
  do not support \cd{:wild-inferiors}.  Any directory list in which
  \cd{:absolute} or \cd{:wild-inferiors} is immediately followed by \cd{:up} or \cd{:back}
  is illegal and when  processed causes an error to be signaled.

  The keyword \cd{:back} has a ``syntactic'' meaning that depends only on the pathname
  and not on the contents of the file system.  The keyword \cd{:up} has a ``semantic''
  meaning that depends on the contents of the file system; to resolve
  a pathname containing \cd{:up} to a pathname whose directory component
  contains only \cd{:absolute} and strings requires a search of the file system.
  Note that use of \cd{:up} instead of \cd{:back} can result in designating a different
  actual directory only in file systems that support multiple
  names for directories, perhaps via symbolic links.  For example,
  suppose that there is a directory link such that
\begin{lisp}
(:absolute "X" "Y")~~\textrm{is linked to}~~(:absolute "A" "B")
\end{lisp}
and there also exist directories
\begin{lisp}
(:absolute "A" "Q")~~\textrm{and}~~(:absolute "X" "Q")
\end{lisp}
Then
\begin{lisp}
(:absolute "X" "Y" :up "Q")~~\textrm{designates}~~(:absolute "A" "Q")
\end{lisp}
but
\begin{lisp}
(:absolute "X" "Y" :back "Q")~~\textrm{designates}~~(:absolute "X" "Q")
\end{lisp}

  If a string is used as the value of the \cd{:directory} argument to
  \cdf{make-pathname}, it should be the name of a top-level directory and should
  not contain any punctuation characters.  Specifying a string \emph{s} is
  equivalent to specifying the list \cd{(:absolute \emph{s\/})}.  Specifying the symbol
  \cd{:wild} is equivalent to specifying the list \cd{(:absolute :wild-inferiors)}
  (or \cd{(:absolute :wild)} in a file system that does not support \cd{:wild-inferiors}).

  The function \cdf{pathname-directory}  always returns \cdf{nil}, \cd{:unspecific}, or a
  list---never a string, never \cd{:wild}.
  If a list is returned, it is not guaranteed to be freshly consed; the
  consequences of modifying this list are undefined.
 
  In non-hierarchical file systems, the only valid list values for the
  directory component of a pathname are \cd{(:absolute \emph{s})} (where \emph{s}
  is a string) and
  \cd{(:absolute :wild)}.  The keywords \cd{:relative},
  \cd{:wild-inferiors}, \cd{:up}, and \cd{:back} are not used in non-hierarchical file
  systems.

  Pathname merging treats a relative directory specially.  Let
  \emph{pathname\/} and \emph{defaults\/} be the first two arguments to
  \cdf{merge-pathnames}.  If \cd{(pathname-directory \emph{pathname\/})} is a list whose
  \emph{car} is \cd{:relative}, and \cd{(pathname-directory \emph{defaults\/})} is a list, then
  the merged directory is the value of
\begin{lisp}
(append (pathname-directory \emph{defaults\/}) \\*
~~~~~~~~(cdr~~~~~;\textrm{Remove \cd{:relative} from the front} \\*
~~~~~~~~~~(pathname-directory \emph{pathname\/})))
\end{lisp}
  except that if the resulting list contains a string or \cd{:wild} immediately
  followed by \cd{:back}, both of them are removed.  This removal of redundant
  occurrences of \cd{:back} is repeated as many times as possible.
  If \cd{(pathname-directory \emph{defaults\/})} is not a list or
  \cd{(pathname-directory \emph{pathname\/})} is not a list whose \emph{car} is \cd{:relative}, the
  merged directory is the value of
\begin{lisp}
(or (pathname-directory \emph{pathname\/}) \\
~~~~(pathname-directory \emph{defaults\/}))
\end{lisp}

  A relative directory in the pathname argument to a function such as
  \cdf{open} is merged with the value of \cd{*default-pathname-defaults*} before the
  file system is accessed.

Here are some examples of the use of structured directories.
Suppose that host \cdf{L} supports a Symbolics Lisp Machine file system,
host \cdf{U} supports a UNIX file system, and
host \cdf{V} supports a VAX/VMS file system.
\begin{lisp}
(pathname-directory (parse-namestring "V:[FOO.BAR]BAZ.LSP")) \\*
~~~\EV\ (:ABSOLUTE "FOO" "BAR")
\end{lisp}
\begin{lisp}
(pathname-directory (parse-namestring "U:/foo/bar/baz.lisp")) \\*
~~~\EV\ (:ABSOLUTE "foo" "bar")
\end{lisp}
\begin{lisp}
(pathname-directory (parse-namestring "U:../baz.lisp")) \\*
~~~\EV\ (:RELATIVE :UP)
\end{lisp}
\begin{lisp}
(pathname-directory (parse-namestring "U:/foo/bar/../mum/baz")) \\*
~~~\EV\ (:ABSOLUTE "foo" "bar" :UP "mum")
\end{lisp}
\begin{lisp}
(pathname-directory (parse-namestring "U:bar/../../ztesch/zip")) \\*
~~~\EV\ (:RELATIVE "bar" :UP :UP "ztesch")
\end{lisp}
\begin{lisp}
(pathname-directory (parse-namestring "L:>foo>**>bar>baz.lisp")) \\*
~~~\EV\ (:ABSOLUTE "FOO" :WILD-INFERIORS "BAR")
\end{lisp}
\begin{lisp}
(pathname-directory (parse-namestring "L:>foo>*>bar>baz.lisp")) \\*
~~~\EV\ (:ABSOLUTE "FOO" :WILD "BAR")
\end{lisp}

\subsection{Extended Wildcards}
\label{WILD-PATHNAME-SECTION}

  Some file systems provide more complex conventions for wildcards than
  simple component-wise wildcards representable by \cd{:wild}.
For example, the namestring \cd{"F*O"} might mean a normal three-character
name; a three-character name with the middle character wild;
a name with at least two characters, beginning with \cdf{F} and ending with \cdf{O};
or perhaps a wild match spanning multiple directories.  Similarly, the
namestring \cd{">foo>**>bar>"} might imply that the middle directory is
named \cd{"**"}; the middle directory is \cd{:wild};
there are zero or more middle directories that are \cd{:wild};
or perhaps that the middle directory name matches any two-letter name.
Some file systems support even more complex wildcards, such as
  regular expressions.

X3J13 voted in June 1989 \issue{PATHNAME-WILD} to provide
some facilities for dealing with more general wildcard pathnames
in a fairly portable manner.

\begin{defun}[Function]
wild-pathname-p pathname &optional field-key
  
Tests a pathname for the presence of wildcard components.  If the first argument
is not a pathname, string, or file stream, an error of type \cdf{type-error} is
signaled.
  
If no \emph{field-key} is provided, or the \emph{field-key} is \cdf{nil}, the
result is true if and only if \emph{pathname} has any wildcard components.

If a non-null \emph{field-key} is provided, it must be one of \cd{:host},
\cd{:device}, \cd{:directory}, \cd{:name}, \cd{:type}, or \cd{:version}.  In
this case, the result is true if and only if the indicated component of
\emph{pathname} is a wildcard.

Note that X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-VALUE} to specify
that an implementation need not support wildcards in all fields; the only
requirement is that the name, type, or version may be \cd{:wild}.  However,
portable programs should be prepared to encounter either \cd{:wild} or
implementation-dependent wildcards in any pathname component.  The function
\cdf{wild-pathname-p} provides a portable way for testing the presence of
wildcards.
\end{defun}

\begin{defun}[Function]
pathname-match-p pathname wildname

This predicate is true if and only if the \emph{pathname} matches the
\emph{wildname}.  The matching rules are implementation-defined but should be
consistent with the behavior of the \cdf{directory} function.  Missing
components of \emph{wildname} default to \cd{:wild}.

If either argument is not a pathname, string, or file stream, an error of type
\cdf{type-error} is signaled.  It is valid for \emph{pathname} to be a wild
pathname; a wildcard field in \emph{pathname} will match only a wildcard field
in \emph{wildname}; that is, \cdf{pathname-match-p} is not commutative.  It is
valid for \emph{wildname} to be a non-wild pathname; I believe that in this case
\cdf{pathname-match-p} will have the same behavior as \cdf{equal}, though the
X3J13 specification did not say so.
\end{defun}

\begin{defun}[Function]
translate-pathname source from-wildname to-wildname &key

Translates the pathname \emph{source}, which must match \emph{from-wildname},
into a corresponding pathname (call it \emph{result}), which is constructed so
as to match \emph{to-wildname}, and returns \emph{result}.

The pathname \emph{result} is a copy of \emph{to-wildname} with each missing or
wildcard field replaced by a portion of \emph{source}; for this purpose a
wildcard field is a pathname component with a value of \cd{:wild}, a \cd{:wild}
element of a list-valued directory component, or an implementation-defined
portion of a component, such as the \cdf{*} in the complex wildcard string
\cd{"foo*bar"} that some implementations support.  An implementation that adds
other wildcard features, such as regular expressions, must define how
\cdf{translate-pathname} extends to those features.  A missing field is a
pathname component that is \cdf{nil}.

The portion of \emph{source} that is copied into \emph{result} is
implementation-defined.  Typically it is determined by the user interface
conventions of the file systems involved.  Usually it is the portion of
\emph{source} that matches a wildcard field of \emph{from-wildname} that is in
the same position as the missing or wildcard field of \emph{to-wildname}.  If
there is no wildcard field in \emph{from-wildname} at that position, then
usually it is the entire corresponding pathname component of \emph{source} or,
in the case of a list-valued directory component, the entire corresponding list
element.  For example, if the name components of \emph{source},
\emph{from-wildname}, and \emph{to-wildname} are \cd{"gazonk"}, \cd{"gaz*"}, and
\cd{"h*"} respectively, then in most file systems the wildcard fields of the
name component of \emph{from-wildname} and \emph{to-wildname} are each \cd{"*"},
the matching portion of \emph{source} is \cd{"onk"}, and the name component of
\emph{result} is \cd{"honk"}; however, the exact behavior of
\cdf{translate-pathname} is not dictated by the Common Lisp language and may
vary according to the user interface conventions of the file systems involved.

During the copying of a portion of \emph{source} into \emph{result}, additional
implementation-defined translations of alphabetic case or file naming
conventions may occur, especially when \emph{from-wildname} and
\emph{to-wildname} are for different hosts.

If any of the first three arguments is not a pathname, string, or file stream,
an error of type \cdf{type-error} is signaled.  It is valid for \emph{source} to
be a wild pathname; in general this will produce a wild \emph{result} pathname.
It is valid for \emph{from-wildname} or \emph{to-wildname} or both to be
non-wild.  An error is signaled if the \emph{source} pathname does not match the
\emph{from-wildname}, that is, if \cd{(pathname-match-p \emph{source}
  \emph{from-wildname})} would not be true.
    
There are no specified keyword arguments for \cdf{translate-pathname}, but
implementations are permitted to extend it by adding keyword arguments.  There
is one specified return value from \cdf{translate-pathname}; implementations are
permitted to extend it by returning additional values.

Here is an implementation suggestion.  One file system performs this operation
by examining corresponding pieces of the three pathnames in turn, where a piece
is a pathname component or a list element of a structured component such as a
hierarchical directory.  Hierarchical directory elements in \emph{from-wildname}
and \emph{to-wildname} are matched by whether they are wildcards, not by depth
in the directory hierarchy.  If the piece in \emph{to-wildname} is present and
not wild, it is copied into the result.  If the piece in \emph{to-wildname} is
\cd{:wild} or \cdf{nil}, the corresponding piece in \emph{source} is copied into
the result.  Otherwise, the piece in \emph{to-wildname} might be a complex
wildcard such as \cd{"foo*bar"}; the portion of the piece in \emph{source} that
matches the wildcard portion of the corresponding piece in \emph{from-wildname}
(or the entire \emph{source} piece, if the \emph{from-wildname} piece is not
wild and therefore equals the \emph{source} piece) replaces the wildcard portion
of the piece in \emph{to-wildname} and the value produced is used in the result.

X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-CASE} to
require \cdf{translate-pathname} to map customary case in argument
pathnames to the customary case in returned pathnames
(see section~\ref{PATHNAME-COMPONENT-CASE-SECTION}).

Here are some examples of the use of the new wildcard pathname facilities.
These examples are not portable.  They are written to run
with particular file systems and particular wildcard conventions and are
intended to be illustrative, not prescriptive.
Other implementations may behave differently.
\begin{lisp}
(wild-pathname-p (make-pathname :name :wild)) \EV\ t \\*
(wild-pathname-p (make-pathname :name :wild) :name) \EV\ t \\
(wild-pathname-p (make-pathname :name :wild) :type) \EV\ nil \\
(wild-pathname-p (pathname "S:>foo>**>")) \EV\ t~~~~~~~~~;\textrm{Maybe} \\*
(wild-pathname-p (make-pathname :name "F*O")) \EV\ t~~~~~;\textrm{Probably}
\end{lisp}
One cannot rely on \cdf{rename-file} to handle wild pathnames in a predictable
manner.  However, one can use \cdf{translate-pathname} explicitly to control
the process.
\begin{lisp}
(defun rename-files (from to) \\*
~~"Rename all files that match the first argument by \\*
~~~translating their names to the form of the second \\*
~~~argument.  Both arguments may be wild pathnames." \\
~~(dolist (file (directory from)) \\*
~~~~;; DIRECTORY produces only pathnames that match from-wildname. \\*
~~~~(rename-file file (translate-pathname file from to))))
\end{lisp}
\end{defun}

Assuming one particular set of popular wildcard conventions,
this function might exhibit the following behavior.
Not all file systems will run this example exactly as written.
\begin{lisp}
(rename-files "/usr/me/*.lisp" "/dev/her/*.l") \\*
~~~\textrm{renames}\=~~/usr/me/init.lisp \\
\textrm{to}~~/dev/her/init.l \\
\\
(rename-files "/usr/me/pcl*/*" "/sys/pcl/*/") \\*
~~~\textrm{renames}~~/usr/me/pcl-5-may/low.lisp \\*
\textrm{to}~~/sys/pcl/pcl-5-may/low.lisp \\*
~~~\textrm{(in some file systems the result might be}~/sys/pcl/5-may/low.lisp\textrm{)} \\
\\
(rename-files "/usr/me/pcl*/*" "/sys/library/*/") \\*
~~~\textrm{renames}~~/usr/me/pcl-5-may/low.lisp \\*
\textrm{to}~~/sys/library/pcl-5-may/low.lisp \\*
~~~\textrm{(in some file systems the result might be}~/sys/library/5-may/low.lisp\textrm{)} \\
\\
(rename-files "/usr/me/foo.bar" "/usr/me2/") \\*
~~~\textrm{renames}~~/usr/me/foo.bar \\
\textrm{to}~~/usr/me2/foo.bar \\
\\
(rename-files "/usr/joe/*-recipes.text" \\*
~~~~~~~~~~~~~~"/usr/jim/personal/cookbook/joe's-*-rec.text") \\*
~~~\textrm{renames}~~/usr/joe/lamb-recipes.text \\*
\textrm{to}~~/usr/jim/personal/cookbook/joe's-lamb-rec.text~~~~ \\
~~~\textrm{renames}~~/usr/joe/veg-recipes.text \\*
\textrm{to}~~/usr/jim/personal/cookbook/joe's-veg-rec.text~~~~~ \\
~~~\textrm{renames}~~/usr/joe/cajun-recipes.text \\*
\textrm{to}~~/usr/jim/personal/cookbook/joe's-cajun-rec.text~~~ \\
~~~\textrm{renames}~~/usr/joe/szechuan-recipes.text \\*
\textrm{to}~~/usr/jim/personal/cookbook/joe's-szechuan-rec.text
\end{lisp}

The following examples use UNIX syntax and the wildcard conventions of one
particular version of UNIX.
\begin{lisp}
(namestring \\*
~~(translate-pathname "/usr/dmr/hacks/frob.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"/usr/d*/hacks/*.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"/usr/d*/backup/hacks/backup-*.*")) \\*
~~~\EV\ "/usr/dmr/backup/hacks/backup-frob.l"
\end{lisp}
\goodbreak
\begin{lisp}
(namestring \\*
~~(translate-pathname "/usr/dmr/hacks/frob.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"/usr/d*/hacks/fr*.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"/usr/d*/backup/hacks/backup-*.*")) \\*
~~~\EV\ "/usr/dmr/backup/hacks/backup-ob.l"
\end{lisp}
The following examples are similar to the preceding examples
but use two different hosts; host \cdf{U} supports a UNIX file system
and host \cdf{V} supports a VAX/VMS file system.  Note the translation
of file type (from \cdf{l} to \cdf{LSP}) and the change of alphabetic case conventions.
\begin{lisp}
(namestring \\*
~~(translate-pathname "U:/usr/dmr/hacks/frob.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"U:/usr/d*/hacks/*.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"V:SYS\$DISK:[D*.BACKUP.HACKS]BACKUP-*.*")) \\*
~~~\EV\ "V:SYS\$DISK:[DMR.BACKUP.HACKS]BACKUP-FROB.LSP"
\end{lisp}
\begin{lisp}
(namestring \\*
~~(translate-pathname "U:/usr/dmr/hacks/frob.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"U:/usr/d*/hacks/fr*.l" \\*
~~~~~~~~~~~~~~~~~~~~~~"V:SYS\$DISK:[D*.BACKUP.HACKS]BACKUP-*.*")) \\*
~~~\EV\ "V:SYS\$DISK:[DMR.BACKUP.HACKS]BACKUP-OB.LSP"
\end{lisp}
The next example is a version of the
function \cdf{translate-logical-pathname} (simplified a bit) for a logical host named \cdf{FOO}.
The points of interest are the use of \cdf{pathname-match-p} as
a \cd{:test} argument for \cdf{assoc} and the use of \cdf{translate-pathname}
as a substrate for \cdf{translate-logical-pathname}.
\begin{lisp}
(define-condition logical-translation-error (file-error)) \\
\\
(defun my-translate-logical-pathname (pathname \&key rules) \\*
~~(let ((rule (assoc pathname rules :test \#'pathname-match-p))) \\
~~~~(unless rule \\*
~~~~~~(error 'logical-translation-error :pathname pathname)) \\*
~~~~(translate-pathname pathname (first rule) (second rule)))) \\
\\
(my-translate-logical-pathname \\*
~~"FOO:CODE;BASIC.LISP" \\*
~~:rules '(("FOO:DOCUMENTATION;"~"U:/doc/foo/") \\*
~~~~~~~~~~~("FOO:CODE;"~~~~~~~~~~"U:/lib/foo/") \\*
~~~~~~~~~~~("FOO:PATCHES;*;"~~~~~"U:/lib/foo/patch/*/"))) \\*
~~~\EV\ \#P"U:/lib/foo/basic.l"
\end{lisp}

\newpage%required

\subsection{Logical Pathnames}
\label{LOGICAL-PATHNAMES-SECTION}

Pathname values are not portable, but sometimes they must be mentioned in a
program (for example, the names of files containing the program and the data
used by the program).

X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to provide
some facilities for portable pathname values.  The idea is to provide
a portable framework for pathname values; these logical pathnames
are then mapped to physical (that is, actual) pathnames by a set of implementation-dependent
or site-dependent rules.  The logical pathname facility therefore
separates the concerns of program writing and user software architecture
from the details of how a software system is embedded in a particular
file system or operating environment.

Pathname values are not portable because not all Common Lisp implementations use
the same operating system and file name syntax varies widely among operating
systems.  In addition, corresponding files at two different sites may have
different names even when the operating system is the same; for example, they
may be on different directories or different devices.  The Common Lisp logical
pathname system defines a particular pathname structure and namestring syntax
that must be supported by all implementations.

\begin{defun}[Class]
logical-pathname

This is a subclass of \cdf{pathname}.
\end{defun}

\subsubsection{Syntax of Logical Pathname Namestrings}

The syntax of a logical pathname namestring is as follows:
\begin{tabbing}
\emph{logical-namestring\/} ::= \Mopt{host\/ \cd{:}} \Mopt{\cd{;}} \Mstar{directory\/ \cd{;}}
      \Mopt{name} \Mopt{\cd{.} type\/ \Mopt{\cd{.} version}}
\end{tabbing}
Note that a logical namestring has no \emph{device} portion.

\begin{tabbing}
\emph{host\/} ::= \emph{word\/} \\*
\emph{directory\/} ::= \emph{word\/} {\Mor} \emph{wildcard-word\/} {\Mor} \emph{wildcard-inferiors\/} \\
\emph{name\/} ::= \emph{word\/} {\Mor} \emph{wildcard-word\/} \\
\emph{type\/} ::= \emph{word\/} {\Mor} \emph{wildcard-word\/} \\
\emph{version\/} ::= \emph{word\/} {\Mor} \emph{wildcard-word\/} \\
\emph{word\/} ::= \Mplus{letter\/ {\Mor} digit\/ {\Mor} \cdf{-}} \\
\emph{wildcard-word\/} ::= \Mopt{word} \cdf{*} \Mstar{word\/ \cdf{*}} \Mopt{word} \\*
\emph{wildcard-inferiors\/} ::= \cdf{**}
\end{tabbing}

  A \emph{word} consists of one or more uppercase letters, digits, and hyphens.
  
  A \emph{wildcard word} consists of one or more asterisks, uppercase letters,
  digits, and hyphens, including at least one asterisk, with no two
  asterisks adjacent.
  Each asterisk matches a sequence of zero or more
  characters.  The wildcard word \cdf{*} parses as \cd{:wild}; all others parse
  as strings.

  Lowercase letters may also appear in a word or wildcard word
  occurring in a namestring.  Such letters are converted to uppercase
  when the namestring is converted to a pathname.
  The consequences of using other characters are unspecified.

  The \emph{host} is a word that has been defined as a logical pathname host by
  using \cdf{setf} with the function \cdf{logical-pathname-translations}.

  There is no device, so the device component of a logical pathname is
  always \cd{:unspecific}.  No other component of a logical pathname can be \cd{:unspecific}.

  Each \emph{directory} is a word, a wildcard word, or \cdf{**} (which is parsed as \cd{:wild-inferiors}).
  If a semicolon precedes the directories, the directory component is
  relative; otherwise it is absolute.

  The \emph{name} is a word or a wildcard word.

  The \emph{type} is a word or a wildcard word.

  The \emph{version} is a positive decimal integer or the word \cdf{NEWEST} (which is parsed
  as \cd{:newest}) or \cdf{*} (which is parsed as \cd{:wild}).
  The letters in \cdf{NEWEST} can be in either alphabetic case.

  The consequences of using any value not specified here as a logical
  pathname component are unspecified.
  The null string \cd{""} is not a valid value for any component of a logical pathname,
  since the null string is not a word or a wildcard word.

\subsubsection{Parsing of Logical Pathname Namestrings}

  Logical pathname namestrings are recognized by the functions \cdf{logical-pathname}
  and \cdf{translate-logical-pathname}.  The host portion
  of the logical pathname namestring and its following colon must appear in
  the namestring arguments to these functions.

  The function \cdf{parse-namestring} recognizes a logical pathname
  namestring when the \emph{host} argument is logical or the \emph{defaults} argument is
  a logical pathname.  In this case the host portion of the logical
  pathname namestring and its following colon are optional.  If the host
  portion of the namestring and the \emph{host} argument are both present and do
  not match, an error is signaled.
  The host argument is logical if it is supplied and came from
  \cdf{pathname-host} of a logical pathname.  Whether a host argument is logical
  if it is a string \cdf{equal} to a logical pathname host name is
  implementation-defined.

  The function \cdf{merge-pathnames} recognizes a logical pathname namestring
  when the \emph{defaults} argument is a logical pathname.  In this case the host
  portion of the logical pathname namestring and its following colon are
  optional.

  Whether the other functions that coerce strings to pathnames
  recognize logical pathname namestrings is implementation-defined.
  These functions include \cdf{parse-namestring} in circumstances other than those described above,
  \cd{merge-\discretionary{}{}{}pathnames} in circumstances other than those described above,
  the \cd{:defaults} argument to \cdf{make-pathname}, and the following functions:
  \begin{flushleft}
  \begin{tabular*}{\linewidth}{@{\extracolsep{\fill}}lll@{}}
  \cdf{compile-file} & \cdf{file-write-date} & \cdf{pathname-name} \\
  \cdf{compile-file-pathname} & \cdf{host-namestring} & \cdf{pathname-type} \\
  \cdf{delete-file} & \cdf{load} & \cdf{pathname-version} \\
  \cdf{directory} & \cdf{namestring} & \cdf{probe-file} \\
  \cdf{directory-namestring} & \cdf{open} & \cdf{rename-file} \\
  \cdf{dribble} & \cdf{pathname} & \cdf{translate-pathname} \\
  \cdf{ed} & \cdf{pathname-device} & \cdf{truename} \\
  \cdf{enough-namestring} & \cdf{pathname-directory} & \cdf{wild-pathname-p} \\
  \cdf{file-author} & \cdf{pathname-host} & \cdf{with-open-file} \\
  \cdf{file-namestring} & \cdf{pathname-match-p} &
  \end{tabular*}
  \end{flushleft}
  Note that many of these functions must accept logical pathnames even though
  they do not accept logical pathname namestrings.
  

\subsubsection{Using Logical Pathnames}

  Some real file systems do not have versions.  Logical pathname
  translation to such a file system ignores the version.  This implies that
  a portable program cannot rely on being able to store in a file system
  more than one version of a
  file named by a logical pathname.

  The type of a logical pathname for a Common Lisp source file is \cdf{LISP}.
  This should be translated into whatever implementation-defined
  type is appropriate in a physical pathname.

  The logical pathname host name \cdf{SYS} is reserved for the implementation.
  The existence and meaning of logical pathnames for logical host \cdf{SYS} is
  implementation-defined.

  File manipulation functions must operate with logical pathnames
according to the following requirements:
\begin{itemize}
\item  The following accept logical pathnames
  and translate them into physical pathnames as if by calling the
  function \cdf{translate-logical-pathname}:
  \begin{flushleft}
  \begin{tabular*}{\linewidth}{@{}l@{\extracolsep{\fill}}ll@{}}
  \cdf{compile-file} & \cdf{ed} & \cdf{probe-file} \\
  \cdf{compile-file-pathname} & \cdf{file-author} & \cdf{rename-file} \\
  \cdf{delete-file} & \cdf{file-write-date} & \cdf{truename} \\
  \cdf{directory} & \cdf{load} & \cdf{with-open-file} \\
  \cdf{dribble} & \cdf{open} & 
  \end{tabular*}
  \end{flushleft}

\item Applying the function \cdf{pathname} to a stream created by the function \cdf{open}
  or the macro \cdf{with-open-file} using a logical pathname produces a logical pathname.

\item The functions \cdf{truename}, \cdf{probe-file}, and \cdf{directory}
      never return logical pathnames.

\item Calling \cdf{rename-file} with a logical pathname as the second argument returns a
  logical pathname as the first value.

\item \cdf{make-pathname} returns a logical pathname if and only if the host is
  logical.  If the \cd{:host} argument to \cdf{make-pathname} is supplied, the host is
  logical if it came from the \cdf{pathname-host} of a logical pathname.  Whether a
  \cd{:host} argument is logical if it is a string equal to a logical pathname
  host name is implementation-defined.
\end{itemize}

\begin{defun}[Function]
logical-pathname pathname

    Converts the argument to a logical pathname and returns it.  The
    argument can be a logical pathname, a logical pathname namestring
    containing a host component, or a stream for which the \cdf{pathname}
    function returns a logical pathname.  For any other argument,
    \cdf{logical-pathname} signals an error of type \cdf{type-error}.
\end{defun}

\begin{defun}[Function]
translate-logical-pathname pathname &key

    Translates a logical pathname to the corresponding physical pathname.
    The \emph{pathname} argument is first coerced to a pathname.  If it is not a
    pathname, string, or file stream, an error of type \cdf{type-error} is
    signaled.

    If the coerced argument is a physical pathname, it is returned.

    If the coerced argument is a logical pathname, the first matching
    translation (according to \cdf{pathname-match-p}) of the logical pathname
    host is applied, as if by calling \cdf{translate-pathname}.  If the result is
    a logical pathname, this process is repeated.  When the result is
    finally a physical pathname, it is returned.

    If no translation matches a logical pathname,
    an error of type \cdf{file-error} is signaled.

    \cdf{translate-logical-pathname} may perform additional translations,
    typically to provide translation of file types to local naming
    conventions, to accommodate physical file systems with names of limited length,
    or to deal with special character requirements such as
    translating hyphens to underscores or uppercase letters to lowercase.
    Any such additional translations are implementation-defined.  Some
    implementations do no additional translations.

    There are no specified keyword arguments for
    \cdf{translate-logical-pathname} but implementations are permitted to extend
    it by adding keyword arguments.  There is one specified return value
    from \cdf{translate-logical-pathname}; implementations are permitted to
    extend it by returning additional values.
\end{defun}

\begin{defun}[Function]
logical-pathname-translations host

    If the specified \emph{host} is not the host component of a logical pathname and is not a
    string that has been defined as a logical pathname host name by \cdf{setf} of
    \cdf{logical-pathname-translations}, this function signals an error of type \cdf{type-error};
    otherwise, it returns the list of translations for the specified \emph{host}.  Each translation is
    a list of at least two elements, from-wildname and to-wildname.  Any
    additional elements are implementation-defined.  A from-wildname is a
    logical pathname whose host is the specified \emph{host}.  A to-wildname is any pathname.
    Translations are searched in the order listed, so more specific
    from-wildnames must precede more general ones.

    \cd{(setf (logical-pathname-translations \emph{host\/}) \emph{translations\/})}
    sets the list of translations for the logical
    pathname \emph{host} to \emph{translations}.  If \emph{host} is a string that has
    not previously been used as logical pathname host, a new logical
    pathname host is defined; otherwise an existing host's translations are
    replaced.  Logical pathname host names are compared with \cdf{string-equal}.

    When setting the translations list, each from-wildname can be a logical
    pathname whose host is \emph{host} or a logical pathname namestring \emph{s}
    parseable by \cd{(parse-namestring \emph{s} \emph{host-object})}, where \emph{host-object}
    is an appropriate object for representing the specified \emph{host} to
    \cdf{parse-namestring}.  (This circuitous specification dodges the fact
    that \cdf{parse-namestring} does not necessarily accept as its second argument
    any old string that names a logical host.)
    Each to-wildname can be anything coercible to a pathname by application of
    the function \cdf{pathname}.
    If to-wildname coerces to a logical pathname,
    \cdf{translate-logical-pathname} will retranslate the result, repeatedly if
    necessary.

    Implementations may define additional functions that operate on
    logical pathname hosts (for example, to specify additional translation
    rules or options).
\end{defun}

\begin{defun}[Function]
load-logical-pathname-translations host

    If a logical pathname host named \emph{host} (a string) is already defined,
    this function returns \cdf{nil}.  Otherwise, it searches for a logical pathname host definition
    in an implementation-defined manner.  If none is found, it signals an
    error.  If a definition is found, it installs the definition and returns \cdf{t}.

    The search used by \cdf{load-logical-pathname-translations} should be
    documented, as logical pathname definitions will be created by users as well as
    by Lisp implementors.  A typical search technique is to
    look in an implementation-defined directory for a file whose name is derived from
    the host name in an implementation-defined fashion.
\end{defun}

\begin{defun}[Function]
compile-file-pathname pathname &key :output-file           

    Returns the pathname that \cdf{compile-file} would write into, if given the
    same arguments.  If the pathname argument is a logical pathname and the
    \cd{:output-file} argument is unspecified, the result is a logical pathname.
    If an implementation supports additional keyword arguments to
    \cdf{compile-file}, \cdf{compile-file-pathname} must accept the same arguments.
\end{defun}

\subsubsection{Examples of the Use of Logical Pathnames}

  Here is a very simple example of setting up a logical pathname host named \cdf{FOO}.
  Suppose that no
  translations are necessary to get around file system restrictions, so
  all that is necessary is to specify the root of the physical directory
  tree that contains the logical file system.
 The namestring syntax in the to-wildname is implementation-specific.
\begin{lisp}
(setf (logical-pathname-translations "foo") \\*
~~~~~~'(("**;*.*.*"~~~~~~~~~~"MY-LISPM:>library>foo>**>")))
\end{lisp}
The following is a sample use of that logical pathname.  All return values
are of course implementation-specific; all of the examples in this section
are of course meant to be illustrative and not prescriptive.
\begin{lisp}
(translate-logical-pathname "foo:bar;baz;mum.quux.3") \\*
~~~\EV\ \#P"MY-LISPM:>library>foo>bar>baz>mum.quux.3"
\end{lisp}

  Next we have a more complex example, dividing the files among two file servers
  (\cdf{U}, supporting a UNIX file system, and \cdf{V}, supporting a VAX/VMS file system)
  and several different directories.  This UNIX file system doesn't support
  \cd{:wild-inferiors} in the directory, so each directory level must
  be translated individually.  No file name or type translations
  are required except for \cd{.MAIL} to \cd{.MBX}.
  The namestring syntax used for the to-wildnames is implementation-specific.
\begin{lisp}
(setf (logical-pathname-translations "prog") \\*
~~~~~~'(("RELEASED;*.*.*"~~~~"U:/sys/bin/my-prog/") \\*
~~~~~~~~("RELEASED;*;*.*.*"~~"U:/sys/bin/my-prog/*/") \\
~~~~~~~~("EXPERIMENTAL;*.*.*" \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"U:/usr/Joe/development/prog/") \\
~~~~~~~~("EXPERIMENTAL;DOCUMENTATION;*.*.*" \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"V:SYS\$DISK:[JOE.DOC]") \\
~~~~~~~~("EXPERIMENTAL;*;*.*.*" \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"U:/usr/Joe/development/prog/*/") \\*
~~~~~~~~("MAIL;**;*.MAIL"~~~~"V:SYS\$DISK:[JOE.MAIL.PROG...]*.MBX") \\*
~~~~~~~~))
\end{lisp}
  Here are sample uses of logical host \cdf{PROG}.  All return values
  are of course implementation-specific.
\begin{lisp}
(translate-logical-pathname "prog:mail;save;ideas.mail.3") \\*
~~~\EV\ \#P"V:SYS\$DISK:[JOE.MAIL.PROG.SAVE]IDEAS.MBX.3" \\
\\
(translate-logical-pathname "prog:experimental;spreadsheet.c") \\*
~~~\EV\ \#P"U:/usr/Joe/development/prog/spreadsheet.c"
\end{lisp}

  Suppose now that we have a program that uses three files logically named \cd{MAIN.LISP},
  \cd{AUXILIARY.LISP}, and \cd{DOCUMENTATION.LISP}.  The following translations might be
  provided by a software supplier as examples.

For a UNIX file system with long file names:
\begin{lisp}
(setf (logical-pathname-translations "prog") \\*
~~~~~~'(("CODE;*.*.*"~~~~~~~~"/lib/prog/"))) \\
\\
(translate-logical-pathname "prog:code;documentation.lisp") \\*
~~~\EV\ \#P"/lib/prog/documentation.lisp"
\end{lisp}
For a UNIX file system with 14-character file names, using \cd{.lisp} as the type:
\begin{lisp}
(setf (logical-pathname-translations "prog") \\*
~~~~~~'(("CODE;DOCUMENTATION.*.*" "/lib/prog/docum.*") \\*
~~~~~~~~("CODE;*.*.*"~~~~~~~~~~~~~"/lib/prog/"))) \\
\\
(translate-logical-pathname "prog:code;documentation.lisp") \\*
~~~\EV\ \#P"/lib/prog/docum.lisp"
\end{lisp}
For a UNIX file system with 14-character file names, using \cd{.l} as the type
(the second translation shortens the compiled file type to \cd{.b}):
\begin{lisp}
(setf (logical-pathname-translations "prog") \\*
~~~~~~{\Xbq}(("**;*.LISP.*"~~~~~~,(logical-pathname "PROG:**;*.L.*")) \\*
~~~~~~~~(,(compile-file-pathname \\*
~~~~~~~~~~~~(logical-pathname "PROG:**;*.LISP.*")) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~,(logical-pathname "PROG:**;*.B.*")) \\
~~~~~~~~("CODE;DOCUMENTATION.*.*" "/lib/prog/documentatio.*") \\*
~~~~~~~~("CODE;*.*.*"~~~~~~~~~~~~~"/lib/prog/"))) \\
\\
(translate-logical-pathname "prog:code;documentation.lisp") \\*
~~~\EV\ \#P"/lib/prog/documentatio.l"
\end{lisp}

\subsubsection{Discussion of Logical Pathnames}

  Large programs can be moved between sites without changing any
  pathnames, provided all pathnames used are logical.  A portable system
  construction tool can be created that operates on programs defined as
  sets of files named by logical pathnames.

   Logical pathname syntax was chosen to be easily translated into the formats of most
  popular file systems, while still being powerful enough for storing large
  programs.  Although they have hierarchical directories, extended wildcard
  matching, versions, and no limit on the length of names, logical pathnames can be
  mapped onto a less capable real file system by translating each
  directory that is used into a flat directory name, processing wildcards in
  the Lisp implementation rather than in the file system, treating all versions as \cd{:newest},
  and using translations to shorten long names.

  Logical pathname words are restricted to non-case-sensitive letters,
  digits, and hyphens to avoid creating problems with real file systems
  that support limited character sets for file naming.
  (If logical pathnames were
  case-sensitive, it would be very difficult to map them into a
  file system that is not sensitive to case in its file names.)

  It is not a goal of logical pathnames to be able to represent all
  possible file names.  Their goal is rather to represent just enough file
  names to be useful for storing software.  Real pathnames, in contrast,
  need to provide a uniform interface to all possible file names, including
  names and naming conventions that are not under the control of Common
  Lisp.

  The choice of logical pathname syntax, using colon, semicolon, and
  period, was guided by the goals of being visually distinct from real file
  systems and minimizing the use of special characters.

  The \cdf{logical-pathname} function is separate from the \cdf{pathname} function
  so that the syntax of logical pathname namestrings does not constrain the
  syntax of physical pathname namestrings in any way.  Logical pathname
  syntax must be defined by Common Lisp so that logical pathnames can be
  conveniently exchanged between implementations, but physical pathname
  syntax is dictated by the operating environments.

\vskip 0pt plus 0.3pt

  The \cdf{compile-file-pathname} function and the specification of \cdf{LISP}
  as the type of a logical pathname for a Common Lisp source file together
  provide enough information about compilation to make possible a portable system
  construction tool.  Suppose that it is desirable
  to call \cdf{compile-file} only if the source file is newer than the compiled
  file.  For this to succeed, it must be possible to know the name of the
  compiled file without actually calling \cdf{compile-file}.
  In some implementations the compiler produces one of several file types,
  depending on a variety of implementation-dependent circumstances,
  so it is not sufficient simply to prescribe a standard logical file type
  for compiled files;
  \cdf{compile-file-pathname} provides access to the defaulting that is performed
  by \cdf{compile-file} ``in a manner
  appropriate to the implementation's file system conventions.''

\vskip 0pt plus 0.3pt

  The use of the logical pathname host name \cdf{SYS} for the implementation
  is current practice.  Standardizing on this name helps users choose
  logical pathname host names that avoid conflicting with
  implementation-defined names.

\vskip 0pt plus 0.3pt

  Loading of logical pathname translations from a site-dependent file
  allows software to be distributed using logical pathnames.  The assumed
  model of software distribution is a division of labor between the
  supplier of the software and the user installing it.  The supplier
  chooses logical pathnames to name all the files used or created by the
  software, and supplies examples of logical pathname translations for a
  few popular file systems.  Each example uses an assumed directory and/or
  device name, assumes local file naming conventions, and provides
  translations that will translate all the logical pathnames used or
  generated by the particular software into valid physical pathnames.
  For a powerful file system these translations can be quite simple.  For
  a more restricted file system, it may be necessary to list an explicit
  translation for every logical pathname used (for example, when dealing
  with restrictions on the maximum length of a file name).

\vskip 0pt plus 0.3pt

  The user installing the software decides on which device and directory
  to store the files and edits the example logical pathname translations
  accordingly.  If necessary, the user also adjusts the translations for
  local file naming conventions and any other special aspects of the user's
  local file system policy and local Common Lisp implementation.  For
  example, the files might be divided among several file server hosts to
  share the load.  The process of defining site-customized logical pathname
  translations is quite easy for a user of a popular file system for which
  the software supplier has provided an example.  A user of a more unusual
  file system might have to take more time; the supplier can help by
  providing a list of all the logical pathnames used or generated by the
  software.\strut

  Once the user has created and executed
  a suitable \cdf{setf} form for setting the \cdf{logical-pathname-translations}
  of the relevant logical host, the software can be loaded and run.  It
  may be necessary to use the translations again, or on another workstation
  at the same site, so it is best to save the \cdf{setf} form in the standard
  place where it can be found later by \cdf{load-logical-pathname-translations}.
  Often a software supplier will include a program for restoring software
  from the distribution medium to the file system and a program for loading
  the software from the file system into a Common Lisp; these programs
  will start by calling \cdf{load-logical-pathname-translations} to make sure that
  the logical pathname host is defined.

  Note that the \cdf{setf} of \cdf{logical-pathname-translations} form isn't part of
  the program; it is separate and is written by the user, not by the
  software supplier.  That separation and a uniform convention for
  doing the separation are the key aspects of logical pathnames.  For small
  programs involving only a handful of files, it doesn't matter much.  The
  real benefits come with large programs with hundreds or thousands of
  files and more complicated situations such as program-generated file
  names or porting a program developed on a system with long file names
  onto a system with a very restrictive limit on the length of file names.

\subsection{Pathname Functions}
\label{PATHNAME-FUNCTIONS}

These functions are what programs use to parse and default file names
that have been typed in or otherwise supplied by the user.

\begin{obsolete}
Any argument called \emph{pathname} in this book may actually be a pathname,
a string or symbol, or a stream.  Any argument called \emph{defaults} may
likewise be a pathname, a string or symbol, or a stream.
\end{obsolete}

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-SYMBOL}
to change the language so that a symbol is
\emph{never} allowed as a pathname argument.  More specifically, the
following functions are changed to disallow a symbol as a \emph{pathname}
argument:
\begin{flushleft}
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lll@{}}
\cdf{pathname} & \cdf{pathname-device} & \cdf{namestring} \\
\cdf{truename} & \cdf{pathname-directory} & \cdf{file-namestring} \\
\cdf{parse-namestring} & \cdf{pathname-name} & \cdf{directory-namestring} \\
\cdf{merge-pathnames} & \cdf{pathname-type} & \cdf{host-namestring} \\
\cdf{pathname-host} & \cdf{pathname-version} & \cdf{enough-namestring}
\end{tabular*}
\end{flushleft}
(The function \cdf{require} was
also changed by this vote but was
deleted from the language by a vote in January 1989
\issue{REQUIRE-PATHNAME-DEFAULTS}.)
Furthermore, the vote reaffirmed that the following functions
do not accept symbols as \emph{file}, \emph{filename}, or \emph{pathname} arguments:
\begin{flushleft}
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}lll@{}}
\cdf{open} & \cdf{rename-file} & \cdf{file-write-date} \\
\cdf{with-open-file} & \cdf{delete-file} & \cdf{file-author} \\
\cdf{load} & \cdf{probe-file} & \cdf{directory} \\
\cdf{compile-file}
\end{tabular*}
\end{flushleft}
In older implementations of Lisp that did not have strings, for example
MacLisp, symbols were the only means for specifying pathnames.
This was convenient only because the file systems of the time allowed
only uppercase letters in file names.  Typing \cd{(load 'foo)} caused
the function \cdf{load} to receive the symbol \cdf{FOO} (with uppercase
letters because of the way symbols are parsed) and therefore to
load the file named \cdf{FOO}.
Now that many file systems, most notably {UNIX}, support
case-sensitive file names, the use of symbols is less convenient
and more error-prone.
\end{new}

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify that a stream may be used
as a \cdf{pathname}, \cdf{file}, or \cdf{filename} argument
only if it was created by use of \cdf{open} or \cdf{with-open-file},
or if it is a synonym stream whose symbol is bound to a stream that
may be used as a pathname.

If such a stream is used as a pathname, it is as if the \cdf{pathname} function
were applied to the stream and the resulting pathname used in place of the
stream.  This represents the name used to open the file.
This may be, but is not required to be, the actual name of the file.

It is an error to attempt to obtain a pathname
from a stream created by any of the following:
\begin{flushleft}
\begin{tabular*}{\textwidth}{@{\extracolsep{\fill}}ll@{}}
\cdf{make-two-way-stream} & \cdf{make-string-input-stream} \\
\cdf{make-echo-stream} & \cdf{make-string-output-stream} \\
\cdf{make-broadcast-stream} & \cdf{with-input-from-string} \\
\cdf{make-concatenated-stream} & \cdf{with-output-to-string}
\end{tabular*}
\end{flushleft}
\end{new}

In the examples, it is assumed that the host named \cdf{CMUC} runs
the {TOPS-20} operating system, and therefore uses {TOPS-20}
file system syntax; furthermore, an explicit host name is
indicated by following the host name with a double colon.
Remember, however, that namestring syntax is implementation-dependent,
and this syntax is used here purely for the sake of examples.

\begin{defun}[Function]
pathname pathname

The \cdf{pathname} function converts its argument to be a pathname.
The argument may be a pathname, a string or symbol, or a stream;
the result is always a pathname.

\begin{new}
X3J13 voted in March 1988
not to permit symbols as pathnames
\issue{PATHNAME-SYMBOL} and
to specify exactly which streams may be used as pathnames
\issue{PATHNAME-STREAM}.
\end{new}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that \cdf{pathname} is unaffected
by whether its argument, if a stream, is open or closed.
X3J13 further commented that because some implementations cannot
provide the ``true name'' of a file until the file is closed,
in such an implementation \cdf{pathname} might, in principle,
return a different (perhaps more specific) file name after the stream is closed.
However, such behavior is prohibited; \cdf{pathname} must return the
same pathname after a stream is closed as it would have while the stream
was open.  See \cdf{truename}.
\end{new}
\end{defun}

\begin{defun}[Function]
truename pathname

The \cdf{truename} function
endeavors to discover the ``true name'' of the file
associated with the \emph{pathname} within the file system.
If the \emph{pathname} is an open stream already associated with a file
in the file system, that file is used.
The ``true name'' is returned as a pathname.
An error is signaled if an appropriate file cannot be located
within the file system for the given \emph{pathname}.

The \cdf{truename} function may be used to
account for any file name translations performed by the file system,
for example.

For example, suppose that \cd{DOC:} is a {TOPS-20} logical
device name that is translated by the {TOPS-20} file system
to be \cd{PS:<DOCUMENTATION>}.
\begin{lisp}
(setq file (open "CMUC::DOC:DUMPER.HLP")) \\
(namestring (pathname file)) \EV\ "CMUC::DOC:DUMPER.HLP" \\
(namestring (truename file)) \\
~~~\EV\ "CMUC::PS:<DOCUMENTATION>DUMPER.HLP.13"
\end{lisp}

\begin{new}
X3J13 voted in March 1988
not to permit symbols as pathnames
\issue{PATHNAME-SYMBOL} and
to specify exactly which streams may be used as pathnames
\issue{PATHNAME-STREAM}.
\end{new}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that \cdf{truename} may be
applied to a stream whether the stream is open or closed.
X3J13 further commented that because some implementations cannot
provide the ``true name'' of a file until the file is closed, in principle
it would be possible in such an implementation for \cdf{truename} to
return a different file name after the stream is closed.
Such behavior is permitted; in this respect \cdf{truename}
differs from \cdf{pathname}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that \cdf{truename} accepts only non-wild pathnames;
an error is signaled if \cdf{wild-pathname-p} would be true of
the \emph{pathname} argument.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{truename}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
However, \cdf{truename} never returns a logical pathname.
\end{newer}
\end{defun}

\begin{defun}[Function]
parse-namestring thing &optional host defaults &key :start :end :junk-allowed

\begin{obsolete}\noindent
This turns \emph{thing} into a pathname.  The \emph{thing} is usually a string
(that is, a namestring), but it may be a symbol (in which case the print
name is used) or a pathname or stream
(in which case no parsing is needed, but
an error check may be made for matching hosts).
\end{obsolete}

\begin{new}
X3J13 voted in March 1988
not to permit symbols as pathnames
\issue{PATHNAME-SYMBOL} and
to specify exactly which streams may be used as pathnames
\issue{PATHNAME-STREAM}.  The \emph{thing} argument may not be a symbol.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{parse-namestring}
to accept logical pathname namestrings (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}

This function does \emph{not}, in general, do defaulting of pathname components,
even though it has an argument named \emph{defaults};
it only does parsing.  The
\emph{host} and \emph{defaults} arguments are present because in some implementations
it may be that a namestring can only be parsed with reference to a
particular file name syntax of several available in the implementation.
If \emph{host} is
non-{\nil}, it must be a host name that could appear in the
host component of a pathname, or {\nil};
if \emph{host} is {\nil} then the host 
name is extracted from the default pathname in \emph{defaults}
and used to determine the syntax convention.  The \emph{defaults} argument
defaults to the value of \cd{*default-pathname-defaults*}.

For a string (or symbol) argument, \cdf{parse-namestring}
parses a file name within it in the
range delimited by the \cd{:start} and \cd{:end} arguments
(which are integer indices
into \emph{string}, defaulting to the beginning and end of the string).

\begin{newer}
See chapter~\ref{KSEQUE} for a discussion of \cd{:start} and \cd{:end} arguments.
\end{newer}

If \cd{:junk-allowed} is not {\false}, then the first value
returned is the pathname parsed, or {\false} if no syntactically correct
pathname was seen.

If \cd{:junk-allowed} is {\false} (the default),
then the entire substring is scanned.
The returned value is the pathname parsed.
An error is signaled if the substring does not consist entirely of
the representation of a pathname, possibly surrounded on either side by
whitespace characters if that is appropriate to the cultural conventions
of the implementation.

In either case, the second value is the index into the string of the delimiter
that terminated the parse, or the index beyond the substring if the
parse terminated at the end of the substring (as will always be the case if
\cd{:junk-allowed} is false).

If \emph{thing} is not a string or symbol, then \emph{start} (which defaults
to zero in any case) is always returned as the second value.

Parsing an empty string always succeeds, producing a pathname with
all components (except the host) equal to {\nil}.

Note that if \emph{host} is specified and not {\nil},
and \emph{thing} contains a manifest host name, an
error is signaled if the hosts do not match.

If \emph{thing} contains an explicit host name and no explicit device name,
then it might be appropriate, depending on the
implementation environment, for \cdf{parse-namestring} to supply the
standard default device for that host as the device component
of the resulting pathname.
\end{defun}


\begin{defun}[Function]
merge-pathnames pathname &optional defaults default-version

\begin{new}
X3J13 voted in March 1988
not to permit symbols as pathnames
\issue{PATHNAME-SYMBOL} and
to specify exactly which streams may be used as pathnames
\issue{PATHNAME-STREAM}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{merge-namestrings}
to recognize a logical pathname namestring as its first argument
if its second argument is a logical pathname (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that \cdf{merge-pathname} is unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, \cdf{merge-pathname} behaves as if the function
\cdf{pathname} were applied to the stream and the resulting pathname used instead.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-CASE} to
require \cdf{merge-pathnames} to map customary case in argument
pathnames to the customary case in returned pathnames
(see section~\ref{PATHNAME-COMPONENT-CASE-SECTION}).
\end{newer}

\emph{defaults} defaults to the value of \cd{*default-pathname-defaults*}.

\emph{default-version} defaults to \cd{:newest}.

Here is an example of the use of \cdf{merge-pathnames}:
\begin{lisp}
(merge-pathnames "CMUC::FORMAT" \\
~~~~~~~~~~~~~~~~~"CMUC::PS:<LISPIO>.FASL") \\
~~~\EV\ \textrm{a pathname object that re-expressed as a namestring would be} \\
~~~~~~"CMUC::PS:<LISPIO>FORMAT.FASL.0"
\end{lisp}

Defaulting of pathname components is done by filling in components taken
from another pathname.
This is especially useful for
cases such as a program that has an input file and an output file, and
asks the user for the name of both, letting the unsupplied components of
one name default from the other.  Unspecified components of the output
pathname will come from the input pathname, except that the type should
default not to the type of the input but to the appropriate default type
for output from this program.

The pathname merging operation takes as input a given pathname, a
defaults pathname, and a default version, and returns a
new pathname.  Basically, the missing components in the given pathname
are filled in from the defaults pathname, except that
if no version is specified the
default version is used.
The default version is usually \cd{:newest}; if no version is specified
the newest version in existence should be used.  The default
version can be {\nil}, to preserve the information that it was missing
in the input pathname.

If the
given pathname explicitly specifies a host and does not supply a device, then
if the host component of the defaults matches the host component
of the given pathname, then the device is taken from the defaults;
otherwise
the device will be the default file device for that host.  Next, if
the
given pathname does not specify a host, device, directory, name,
or type, each such
component is copied from the defaults.
The merging rules for the version are more complicated and
depend on whether the pathname specifies a name.  If the pathname
doesn't specify a name, then the version, if not provided, will
come from the defaults, just like the other components.  However, if the
pathname does specify a name, then the version is not affected
by the defaults.  The reason is that the version
``belongs to'' some other file name and is unlikely to have anything to do
with the new one.  Finally, if this process leaves the
version missing, the default version is used.

The net effect is that if the user supplies just a name, then the
host, device, directory, and type will come from the defaults, but the
version will come from the default version
argument to the merging operation.  If the user supplies nothing, or
just a directory, the name, type, and version will come over from
the defaults together.  If the host's file name syntax provides a way
to input a version without a name or type, the user can let the name
and type
default but supply a version different from the one in the defaults.

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-SYNTAX-ERROR-TIME} to agree to disagree:
\cdf{merge-pathname} might or might not perform plausibility checking
on its arguments to ensure that the resulting pathname can be converted
a valid namestring.  User beware: this could cause portability problems.

For example, suppose that host \cdf{LOSER} constrains file types to be three characters
or fewer but host \cdf{CMUC} does not.  Then \cd{"LOSER::FORMAT"} is a valid
namestring and \cd{"CMUC::PS:<LISPIO>.FASL"} is a valid namestring, but
\begin{lisp}
(merge-pathnames "LOSER::FORMAT" "CMUC::PS:<LISPIO>.FASL")
\end{lisp}
might signal an error in some implementations because the hypothetical result would be a pathname
equivalent to the namestring \cd{"LOSER::FORMAT.FASL"} which is illegal
because the file type \cdf{FASL} has more than three characters.
In other implementations \cdf{merge-pathname} might return a pathname but that pathname might
cause \cdf{namestring} to signal an error.
\end{newer}
\end{defun}

\begin{defun}[Variable]
*default-pathname-defaults*

This is the default pathname-defaults pathname; if any pathname primitive
that needs a set of defaults is not given one, it uses this one.
As a general rule, however, each program
should have its own pathname defaults rather than using this one.
\end{defun}

The following example assumes the use of UNIX syntax and conventions.
\begin{lisp}
(make-pathname :host "technodrome" \\
~~~~~~~~~~~~~~~:directory '(:absolute "usr" "krang") \\
~~~~~~~~~~~~~~~:name "shredder") \\
~~\EV\ \#P"technodrome:/usr/krang/shredder"
\end{lisp}
X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-CASE} to add a new keyword
argument \cd{:case} to \cdf{make-pathname}.  The new argument description
is therefore as follows:

\begin{defun}[Function]
make-pathname &key :host :device :directory :name :type :version :defaults :case

See section~\ref{PATHNAME-COMPONENT-CASE-SECTION} for a description
of the \cd{:case} argument.

X3J13 voted in June 1989 \issue{PATHNAME-SYNTAX-ERROR-TIME} to agree to disagree:
\cdf{make-pathname} might or might not check
on its arguments to ensure that the resulting pathname can be converted to
a valid namestring.  If \cdf{make-pathname} does not check its arguments
and signal an error in problematical cases,
\cdf{namestring} yet might or might not signal an error when given the resulting
pathname.  User beware: this could cause portability problems.
\end{defun}

\begin{defun}[Function]
pathnamep object

This predicate is true if \emph{object} is a pathname, and otherwise is false.
\begin{lisp}
(pathnamep x) \EQ\ (typep x 'pathname)
\end{lisp}
\end{defun}

\begin{new}
X3J13 voted in March 1988
not to permit symbols as pathnames
\issue{PATHNAME-SYMBOL} and
to specify exactly which streams may be used as pathnames
\issue{PATHNAME-STREAM}.
\end{new}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that these operations are unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, each operation behaves as if the function \cdf{pathname}
were applied to the stream and the resulting pathname used instead.
\end{new}

X3J13 voted in June 1989 \issue{PATHNAME-COMPONENT-CASE} to add a keyword
argument \cd{:case} to all of the pathname accessor functions except
\cdf{pathname-version}.  The new argument descriptions
are therefore as follows:

\begin{defun}[Function]
pathname-host pathname &key :case \\
pathname-device pathname &key :case \\
pathname-directory pathname &key :case \\
pathname-name pathname &key :case \\
pathname-type pathname &key :case \\
pathname-version pathname

See section~\ref{PATHNAME-COMPONENT-CASE-SECTION} for a description
of the \cd{:case} argument.

X3J13 voted in June 1989 \issue{PATHNAME-SUBDIRECTORY-LIST}
to specify that
  \cdf{pathname-directory}  always returns \cdf{nil}, \cd{:unspecific}, or a
  list---never a string, never \cd{:wild} (see section~\ref{STRUCTURED-DIRECTORY-SECTION}).
  If a list is returned, it is not guaranteed to be freshly consed; the
  consequences of modifying this list are undefined.
\end{defun}

\begin{defun}[Function]
namestring pathname \\
file-namestring pathname \\
directory-namestring pathname \\
host-namestring pathname \\
enough-namestring pathname &optional defaults

The \emph{pathname} argument may be a pathname, a string or symbol,
or a stream that is or was open to a file.
The name represented by \emph{pathname} is returned as a namelist
in canonical form.

If \emph{pathname} is a stream, the name returned represents the
name used to \emph{open} the file, which may not be the \emph{actual}
name of the file (see \cdf{truename}).

\begin{new}
X3J13 voted in March 1988
not to permit symbols as pathnames
\issue{PATHNAME-SYMBOL} and
to specify exactly which streams may be used as pathnames
\issue{PATHNAME-STREAM}.
\end{new}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that these operations are unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, each operation behaves as if the function \cdf{pathname}
were applied to the stream and the resulting pathname used instead.
\end{new}

\cdf{namestring} returns the full form of the \emph{pathname} as a string.
\cdf{file-namestring} returns a string representing just the \emph{name},
\emph{type}, and \emph{version} components of the \emph{pathname};
the result of \cdf{directory-namestring}
represents just the \emph{directory-name} portion; and \cdf{host-namestring}
returns a string for just the \emph{host-name} portion.
Note that a valid namestring cannot necessarily be constructed
simply by concatenating some of the three shorter strings in some order.

\cdf{enough-namestring} takes another argument, \emph{defaults}.
It returns an abbreviated namestring that is just sufficient to
identify the file named by \emph{pathname} when considered relative
to the \emph{defaults} (which defaults to the value of
\cd{*default-pathname-defaults*}).  That is, it is required
that
\begin{lisp}
(merge-pathnames (enough-namestring \emph{pathname} \emph{defaults}) \emph{defaults}) {\EQ} \\
~(merge-pathnames (parse-namestring \emph{pathname} nil \emph{defaults}) \emph{defaults})
\end{lisp}
in all cases; and the result of \cdf{enough-namestring} is, roughly speaking,
the shortest reasonable string that will still satisfy this criterion.
\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-SYNTAX-ERROR-TIME} to agree to disagree:
\cdf{make-pathname} and \cdf{merge-pathnames} might or might not be able to produce pathnames
that cannot be converted to valid namestrings.
User beware: this could cause portability problems.
\end{newer}
\end{defun}

\begin{defun}[Function]
user-homedir-pathname &optional host

Returns a pathname for the user's ``home directory'' on \emph{host}.
The \emph{host} argument
defaults in some appropriate implementation-dependent manner.  The
concept of ``home directory'' is itself somewhat
implementation-dependent, but from the point of view of Common Lisp it is the
directory where the user keeps personal files such as initialization
files and mail.  If it is impossible to determine this information,
then {\nil} is returned instead of a pathname; however,
\cdf{user-homedir-pathname} never returns {\nil} if the \emph{host} argument
is not specified.
This function returns a pathname without any name, type,
or version component (those components are all {\nil}).
\end{defun}


\section{Opening and Closing Files}

When a file is \emph{opened}, a stream object is constructed to serve
as the file system's ambassador to the Lisp environment;
operations on the stream are reflected by operations on the file
in the file system.  The act of \emph{closing} the file (actually,
the stream) ends the association; the transaction with the file
system is terminated, and input/output may no longer be performed
on the stream.  The stream function \cdf{close} may be used
to close a file; the functions described below may be used to open them.
The basic operation is \cdf{open}, but \cdf{with-open-file} is usually
more convenient for most applications.

\begin{defun}[Function]
open filename &key :direction :element-type :if-exists :if-does-not-exist :external-format

\begin{newer}
X3J13 voted in June 1989 \issue{MORE-CHARACTER-PROPOSAL}
to add to the function \cdf{open} a new keyword argument \cd{:external-format}.
This argument did not appear in the preceding argument description in the
first edition.
\end{newer}

This returns a stream that is connected to the file specified by \emph{filename}.
The \emph{filename} is the name of the file to be opened; it may be a string,
a pathname, or a stream.  (If the \emph{filename} is a stream, then it is not
closed first or otherwise affected; it is used merely to provide a file name
for the opening of a new stream.)

\begin{new}
X3J13 voted in January 1989
\issue{STREAM-ACCESS}
to specify that the result of
\cdf{open}, if it is a stream, is always a stream of type \cdf{file-stream}.
\end{new}

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that \cdf{open} is unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, \cdf{open} behaves as if the function \cdf{pathname}
were applied to the stream and the resulting pathname used instead.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that \cdf{open} accepts only non-wild pathnames;
an error is signaled if \cdf{wild-pathname-p} would be true of \emph{filename}.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{open}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}

The keyword arguments specify what kind of stream to produce and how
to handle errors:
\begin{flushdesc}
\item[\cd{:direction}]
This argument specifies whether the stream should handle input, output,
or both.
\begin{quotation}
\begin{flushdesc}
\item[\cd{:input}]
The result will be an input stream.  This is the default.

\item[\cd{:output}]
The result will be an output stream.

\item[\cd{:io}]
The result will be a bidirectional stream.

\item[\cd{:probe}]
The result will be a no-directional stream (in effect, the stream
is created and then closed).  This is useful for determining whether
a file exists without actually setting up a complete stream.
\end{flushdesc}
\end{quotation}

\item[\cd{:element-type}]
This argument specifies the type of the unit of transaction for the stream.
Anything that can be recognized as being a finite subtype of
\cdf{character} or \cdf{integer} is acceptable.  In particular,
the following types are recognized:

\begin{quotation}
\begin{flushdesc}
\item[\cdf{character}]
The unit of transaction is any character, not just a string-character.
The functions \cdf{read-char} and \cdf{write-char} (depending on the value of the
\cd{:direction} argument) may be used on the stream.  This is the default.

\item[\cdf{base-char}]
The unit of transaction is a base character.
The functions \cdf{read-char} and \cdf{write-char} (depending on the value of the
\cd{:direction} argument) may be used on the stream.
\end{flushdesc}
\end{quotation}

\begin{quotation}
\begin{flushdesc}
\item[\cd{(unsigned-byte \emph{n})}]
The unit of transaction is an unsigned byte (a non-negative integer) of size \emph{n}.
The functions \cdf{read-byte} and/or \cdf{write-byte} may be
used on the stream.

\item[\cdf{unsigned-byte}]
The unit of transaction is an unsigned byte (a non-negative integer);
the size of the byte is determined by the file system.
The functions \cdf{read-byte} and/or \cdf{write-byte} may be
used on the stream.

\item[\cd{(signed-byte \emph{n})}]
The unit of transaction is a signed byte of size \emph{n}.
The functions \cdf{read-byte} and/or \cdf{write-byte} may be
used on the stream.

\item[\cdf{signed-byte}]
The unit of transaction is a signed byte;
the size of the byte is determined by the file system.
The functions \cdf{read-byte} and/or \cdf{write-byte} may be
used on the stream.

\item[\cdf{bit}]
The unit of transaction is a bit (values \cd{0} and \cd{1}).
The functions \cdf{read-byte} and/or \cdf{write-byte} may be
used on the stream.

\item[\cd{(mod \emph{n})}]
The unit of transaction is a non-negative integer less than \emph{n}.
The functions \cdf{read-byte} and/or \cdf{write-byte} may be
used on the stream.

\item[\cd{:default}]
The unit of transaction is to be determined by the file system, based
on the file it finds.
The type can be determined by using the function \cdf{stream-element-type}.
\end{flushdesc}
\end{quotation}

\item[\cd{:if-exists}]
This argument specifies the action to be taken if the \cd{:direction} is
\cd{:output} or \cd{:io} and a file of the specified name already exists.
If the direction is \cd{:input} or \cd{:probe}, this argument is ignored.
\begin{quotation}
\begin{flushdesc}
\item[\cd{:error}]
Signals an error.  This is the default when the version component of
the \emph{filename} is not \cd{:newest}.

\item[\cd{:new-version}]
Creates a new file with the same file name but with a larger version number.
This is the default when the version component of the \emph{filename} is \cd{:newest}.

\item[\cd{:rename}]
Renames the existing file to some other name and then creates a new file
with the specified name.

\item[\cd{:rename-and-delete}]
Renames the existing file to some other name and then deletes it (but
does not expunge it, on those systems that distinguish deletion from
expunging).  Then create a new file with the specified name.

\item[\cd{:overwrite}]
Uses the existing file.  Output operations on the stream
will destructively modify the file.
If the \cd{:direction} is \cd{:io},
the file is opened in a bidirectional mode that allows both
reading and writing.  The file pointer is initially positioned
at the beginning of the file; however, the file is not truncated
back to length zero when it is opened.
This mode is most useful when
the \cdf{file-position} function can be used on the stream.

\item[\cd{:append}]
Uses the existing file.  Output operations on the stream
will destructively modify the file.  The file pointer is
initially positioned at the end of the file.
If the \cd{:direction} is \cd{:io},
the file is opened in a bidirectional mode that allows both
reading and writing.

\item[\cd{:supersede}]
Supersedes the existing file.  If possible, the implementation should
arrange not to destroy the old file until the new stream is closed,
against the possibility that the stream will be closed in ``abort'' mode
(see \cdf{close}).
This differs from \cd{:new-version} in that \cd{:supersede} creates
a new file with the same name as the old one, rather than a file
name with a higher version number.

\item[\cd{\false}]
Does not create a file or even a stream, but instead
simply returns {\false} to indicate failure.
\end{flushdesc}
\end{quotation}

If the \cd{:direction} is \cd{:output} or \cd{:io}
and the value of \cd{:if-exists} is \cd{:new-version},
then the version of the (newly created) file that is opened will
be a version greater than that of any other file in the file system
whose other pathname components are the same as those of \emph{filename}.

If the \cd{:direction} is \cd{:input} or \cd{:probe}
or the value of \cd{:if-exists} is not \cd{:new-version},
\emph{and} the version component of the \emph{filename} is \cd{:newest},
then the file opened is that file already existing in the file system
that has a version greater than that of any other file in the file system
whose other pathname components are the same as those of \emph{filename}.

\begin{new}
Some file systems permit yet other actions to be taken when a file
already exists; therefore,
some implementations provide implementation-specific \cd{:if-exist} options.
\end{new}
\end{flushdesc}

\beforenoterule
\begin{implementation}
The various file systems in existence today
have widely differing capabilities.  A given implementation may not
be able to support all of these options in exactly the manner stated.
An implementation is required to recognize all of these option keywords
and to try to do something ``reasonable'' in the context of the host operating
system.  Implementors are encouraged to approximate the semantics specified
here as closely as possible.

As an example, suppose that a file system does not support distinct file
versions and does not distinguish the notions of deletion and expunging
(in some file systems file deletion is reversible until an expunge operation
is performed).  Then \cd{:new-version} might be treated the same as
\cd{:rename} or \cd{:supersede}, and \cd{:rename-and-delete} might
be treated the same as \cd{:supersede}.

If it is utterly impossible for an implementation to handle some option
in a manner close to what is specified here, it may simply signal an error.
The opening of files is an area where complete portability is too much to
hope for; the intent here is simply to make things as portable as possible
by providing specific names for a range of commonly supportable options.
\end{implementation}
\afternoterule

\begin{flushdesc}
\item[\cd{:if-does-not-exist}]
This argument specifies the action to be taken if
a file of the specified name does not already exist.\vadjust{\vskip2pt}
\begin{quotation}
\begin{flushdesc}
\item[\cd{:error}]
Signals an error.  This is the default if the \cd{:direction} is \cd{:input},
or if the \cd{:if-exists} argument is \cd{:overwrite} or \cd{:append}.

\item[\cd{:create}]
Creates an empty file with the specified name and then proceeds as if it
had already existed (but do not perform any processing directed by the
\cd{:if-exists} argument).
This is the default if the \cd{:direction} is \cd{:output}
or \cd{:io}, and the \cd{:if-exists} argument is anything but \cd{:overwrite}
or \cd{:append}.

\item[\cd{\false}]
Does not create a file or even a stream, but
instead simply returns {\false} to indicate failure.
This is the default if the \cd{:direction} is \cd{:probe}.
\end{flushdesc}
\end{quotation}
\end{flushdesc}

\begin{newer}
X3J13 voted in June 1989 \issue{MORE-CHARACTER-PROPOSAL}
to add to the function \cdf{open} a new keyword argument \cd{:external-format}.
\begin{flushdesc}
\item[\cd{:external-format}]
This argument specifies an implementation-recognized scheme for
representing characters in files.  The default value is \cd{:default}
and is implementation-defined but must support the base characters.
An error is signaled if the implementation does recognize the specified format.

This argument may be specified if the \cd{:direction} argument is
\cd{:input}, \cd{:output}, or \cd{:io}.  It is an error to write a character
to the resulting stream that cannot be represented by the specified file format.
(However, the \cd{\#{\Xbackslash}Newline} character cannot produce such an error;
implementations must provide appropriate line division behavior for all character
streams.)

See \cdf{stream-external-format}.
\end{flushdesc}
\end{newer}

When the caller is finished with the stream, it should close the file by
using the \cdf{close} function.  The \cdf{with-open-file}
form does this automatically, and so is preferred for most purposes.
\cdf{open} should be used only when the control structure of the program
necessitates opening and closing of a file in some way more complex than
provided by \cdf{with-open-file}.  It is suggested that any program that uses
\cdf{open} directly should use the special operator \cdf{unwind-protect} to
close the file if an abnormal exit occurs.
\end{defun}

\begin{defmac}
with-open-file (stream filename {options}*)
               {declaration}* {form}*

\cdf{with-open-file}
evaluates the \emph{forms} of the body (an implicit \cdf{progn}) with the variable
\emph{stream} bound to a stream that reads or writes the file named by the
value of \emph{filename}.
The \emph{options} are evaluated and are used as keyword arguments to
the function \cdf{open}.

When control leaves the body, either normally or abnormally (such as by
use of \cdf{throw}), the file is automatically closed.  If a new
output file is being written, and control leaves abnormally, the file is
aborted and the file system is left, so far as possible, as if the file
had never been opened.  Because \cdf{with-open-file} always closes the
file, even when an error exit is taken, it is preferred over \cdf{open} for
most applications.

\emph{filename} is the name of the file to be opened; it may be a string,
a pathname, or a stream.

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that \cdf{with-open-file} accepts only non-wild pathnames;
an error is signaled if \cdf{wild-pathname-p} would be true of
the \emph{filename} argument.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{with-open-file}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}


For example:
\begin{lisp}
(with-open-file (ifile name \\
~~~~~~~~~~~~~~~~~:direction :input) \\
~~(with-open-file (ofile (merge-pathname-defaults ifile \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~nil \\
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~"out") \\
~~~~~~~~~~~~~~~~~~~~~~~~~:direction :output \\
~~~~~~~~~~~~~~~~~~~~~~~~~:if-exists :supersede) \\
~~~~(transduce-file ifile ofile)))
\end{lisp}

\begin{newer}
X3J13 voted in June 1989 \issue{WITH-OPEN-FILE-DOES-NOT-EXIST}
to specify that the variable \emph{stream} is not always bound to
a stream; rather it is bound to whatever would be returned by
a call to \cdf{open}.  For example, if the options include
\cd{:if-does-not-exist~nil}, \emph{stream} will be bound to \cdf{nil}
if the file does not exist.  In this case the value of \emph{stream}
should be tested within the body of the \cdf{with-open-file} form
before it is used as a stream.  For example:
\begin{lisp}
(with-open-file (ifile name \\*
~~~~~~~~~~~~~~~~~:direction :input \\*
~~~~~~~~~~~~~~~~~:if-does-not-exist nil) \\*
~~;; Process the file only if it actually exists. \\*
~~(when (streamp name)\\*
~~~~(compile-cobol-program ifile)))
\end{lisp}
\end{newer}
\end{defmac}

\beforenoterule
\begin{implementation}
While \cdf{with-open-file} tries to automatically close
the stream on exit from the construct, for robustness it is helpful
if the garbage collector can detect discarded streams and automatically
close them.
\end{implementation}
\afternoterule

\section{Renaming, Deleting, and Other File Operations}

These functions provide a standard interface to operations provided
in some form by most file systems.  It may be that some implementations
of Common Lisp cannot support them all completely.

\begin{defun}[Function]
rename-file file new-name

The specified \emph{file} is renamed to \emph{new-name} (which must be a file name).
The \emph{file} may be a string, a pathname, or a stream.  If it is an open stream
associated with a file, then the stream itself and the file associated
with it are affected (if the file system permits).

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\cdf{rename-file} returns three values if successful.  The first value
is the \emph{new-name} with any missing components filled in by performing
a \cdf{merge-pathnames} operation using \emph{file} as the defaults.
The second value is the \cdf{truename} of the file before it was renamed.
The third value is the \cdf{truename} of the file after it was renamed.

If the renaming operation is not successful, an error is signaled.

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{rename-file}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}
\end{defun}

\begin{defun}[Function]
delete-file file

The specified \emph{file} is deleted.  The \emph{file} may be a string, a
pathname, or a stream.  If it is an open stream associated with a file,
then the stream itself and the file associated with it are affected (if
the file system permits), in which case the stream may or may not be
closed immediately, and the deletion may be immediate or delayed until
the stream is explicitly closed, depending on the requirements of the
file system.

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\cdf{delete-file} returns a non-{\nil} value if successful.
It is left to the discretion of the implementation whether an attempt
to delete a non-existent file is considered to be successful.
If the deleting operation is not successful, an error is signaled.

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{delete-file}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}
\end{defun}

\begin{defun}[Function]
probe-file file

This predicate is false if there is no file named \emph{file},
and otherwise returns a pathname that is the true name of the file
(which may be different from \emph{file} because of file links, version
numbers, or other artifacts of the file system).
Note that if the \emph{file} is an open stream associated with a file,
then \cdf{probe-file} cannot return {\nil} but will produce the
true name of the associated file.
See \cdf{truename} and the \cd{:probe} value for the
\cd{:direction} argument to \cdf{open}.

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that \cdf{probe-file} accepts only non-wild pathnames;
an error is signaled if \cdf{wild-pathname-p} would be true of
the \emph{file} argument.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{probe-file}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
However, \cdf{probe-file} never returns a logical pathname.
\end{newer}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that \cdf{probe-file} is unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, \cdf{probe-file} behaves as if the function \cdf{pathname}
were applied to the stream and the resulting pathname used instead.
However, X3J13 further commented that the treatment of open streams
may differ considerably from one implementation to another; for example,
in some operating systems open files are written under a temporary or
invisible name and later renamed when closed.  In general, programmers writing
code intended to be portable should be very careful when using \cdf{probe-file}.
\end{new}
\end{defun}

\begin{defun}[Function]
file-write-date file

\emph{file} can be a file name or a stream that is open to a file.
This returns the time at which the file was created
or last written as an integer in
universal time format (see section \ref{TIME-SECTION}),
or {\false} if this cannot be determined.

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that \cdf{file-write-date} accepts only non-wild pathnames;
an error is signaled if \cdf{wild-pathname-p} would be true of
the \emph{file} argument.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{file-write-date}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}
\end{defun}

\begin{defun}[Function]
file-author file

\emph{file} can be a file name or a stream that is open to a file.
This returns the name of the author of the file as a string,
or {\false} if this cannot be determined.

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that \cdf{file-author} accepts only non-wild pathnames;
an error is signaled if \cdf{wild-pathname-p} would be true of
the \emph{file} argument.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{file-author}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}
\end{defun}

\begin{defun}[Function]
file-position file-stream &optional position

\cdf{file-position} returns or sets the current position within
a random-access file.

\cd{(file-position \emph{file-stream})} returns a non-negative integer
indicating the current position within the \emph{file-stream}, or {\false} if
this cannot be determined.  The file position at the start of a file will
be zero.  The value returned by \cdf{file-position} increases monotonically
as input or output operations are performed.  For a character file,
performing a single \cdf{read-char} or \cdf{write-char} operation
may cause the file position to be increased by more than 1 because of
character-set translations (such as translating between the Common Lisp
\cd{\#{\Xbackslash}Newline} character and an external {ASCII}
carriage-return/line-feed sequence) and other aspects of the
implementation.  For a binary file, every \cdf{read-byte} or \cdf{write-byte}
operation increases the file position by 1.

\cd{(file-position \emph{file-stream} \emph{position})} sets the position within
\emph{file-stream} to be \emph{position}.  The \emph{position} may be an integer,
or \cd{:start} for the beginning of the stream, or \cd{:end} for the end of the
stream.
If the integer is too large or otherwise inappropriate, an error
is signaled (the \cdf{file-length} function returns the length beyond
which \cdf{file-position} may not access).  An integer returned by
\cdf{file-position} of one argument should, in general, be acceptable
as a second argument for use with the same file.
With two arguments,
\cdf{file-position} returns {\true} if the repositioning was performed
successfully, or {\false} if it was not (for example,
because the file was not random-access).

\begin{implementation}
Implementations that have character files represented
as a sequence of records of bounded size might choose to encode the
file position as, for example,
\emph{record-number}*256+\emph{character-within-record}.
This is a valid encoding because it increases monotonically as
each character is read or written, though not necessarily by 1 at
each step.  An integer might then be considered ``inappropriate''
as a second argument to \cdf{file-position} if, when decoded into
record number and character number, it turned out that the
specified record was too short for the specified character number.
\end{implementation}
\end{defun}

\begin{defun}[Function]
file-length file-stream

\emph{file-stream} must be a stream that is open to a file.
The length of the file is returned as a non-negative integer,
or {\false} if the length cannot be determined.
For a binary file,
the length is specifically
measured in units of the \cd{:element-type} specified
when the file was opened (see \cdf{open}).
\end{defun}


\begin{newer}
\begin{defun}[Function]
file-string-length file-stream object

X3J13 voted in June 1989 \issue{MORE-CHARACTER-PROPOSAL} to add
the function \cdf{file-string-length}.
The \emph{object} must be a string or a character.  The function
\cdf{file-string-length} returns a non-negative integer
that is the difference between what the \cdf{file-position} of the
\emph{file-stream} would be after and before writing the \emph{object}
to the \emph{file-stream}, or \cdf{nil} if this
difference cannot be determined.  The value returned may
depend on the current state of the \emph{file-stream}; that is, calling
\cdf{file-string-length} on the same arguments twice may in certain circumstances
produce two different integers.
\end{defun}
\end{newer}

\section{Loading Files}

To \emph{load} a file is to read through the file, evaluating each form in
it.  Programs are typically stored in files containing calls to
constructs such as \cdf{defun}, \cdf{defmacro},
and \cdf{defvar}, which define
the functions and variables of the program.

Loading a compiled (``fasload'') file is similar, except that the file does not
contain text but rather pre-digested expressions created by the
compiler that can be loaded more quickly.

\begin{defun}[Function]
load filename &key :verbose :print :if-does-not-exist

This function loads the file named by \emph{filename} into the Lisp
environment.  It is assumed that a text (character file) can be
automatically distinguished from an object (binary) file by some appropriate
implementation-dependent means, possibly by the file type.
The defaults for \emph{filename} are taken from the variable
\cd{*default-pathname-defaults*}.
If the \emph{filename} (after the merging in of the defaults)
does not explicitly specify a type,
and both text and object types of the file are available in the file system,
\cdf{load} should
try to select the more appropriate file by some implementation-dependent means.

If the first argument is a stream rather than a pathname,
then \cdf{load} determines what kind of stream it is and loads
directly from the stream.

The \cd{:verbose} argument (which defaults to the value of
\cd{*load-verbose*}), if true, permits \cdf{load} to print a message
in the form of a comment (that is, with a leading
semicolon) to \cdf{*standard-output*} indicating what
file is being loaded and other useful information.

\begin{obsolete}
The \cd{:print} argument (default {\nil}),
if true, causes the value of each expression
loaded to be printed to \cdf{*standard-output*}.  If a binary file is
being loaded, then what is printed may not reflect precisely the contents
of the source file, but nevertheless some information will be printed.
\end{obsolete}
\begin{newer}
X3J13 voted in March 1989 \issue{COMPILER-VERBOSITY}
to add the variable \cd{*load-print*}; its value is used as the default
for the \cd{:print} argument to \cdf{load}.
\end{newer}

\begin{newer}
The function \cdf{load} rebinds \cdf{*package*} to its current value.  If
some form in the file changes the value of \cdf{*package*} during loading,
the old value will be restored when the loading is completed.
(This was specified in the first edition under the description of \cdf{*package*};
for convenience I now mention it here as well.)
\end{newer}

\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-WILD}
to clarify that supplying a wild pathname
as the \emph{filename} argument to \cdf{load} has implementation-dependent consequences;
\cdf{load} might signal an error, for example,
or might load all files that match the pathname.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{load}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
\end{newer}

If a file is successfully loaded, \cdf{load} always returns a non-{\false}
value.  If \cd{:if-does-not-exist} is specified and is {\false},
\cdf{load} just returns {\false} rather than signaling an error if the file
does not exist.

\begin{newer}
X3J13 voted in March 1989 \issue{IN-SYNTAX}
to require that \cdf{load} bind \cd{*readtable*} to its current value
at the time \cdf{load} is called; the dynamic extent of the binding
should encompass all of the file-loading activity.
This allows a portable program to include forms such as
\begin{lisp}
(in-package "FOO") \\*
\\*
(eval-when (:execute :load-toplevel :compile-toplevel) \\*
~~(setq *readtable* foo:my-readtable))
\end{lisp}
without performing a net global side effect on the loading environment.
Such statements allow the remainder of such a file to be read either as
interpreted code or by \cdf{compile-file} in a syntax determined by
an alternative readtable.
\end{newer}

\begin{newer}
X3J13 voted in June 1989 \issue{LOAD-TRUENAME}
to require that \cdf{load} bind two new variables
\cd{*load-pathname*} and \cd{*load-truename*}; the dynamic extent of the bindings
should encompass all of the file-loading activity.
\end{newer}
\end{defun}

\begin{defun}[Variable]
*load-verbose*

This variable provides the default for the \cd{:verbose} argument
to \cdf{load}.  Its initial value is implementation-dependent.
\end{defun}


\begin{newer}
\begin{defun}[Variable]
*load-print*

X3J13 voted in March 1989 \issue{COMPILER-VERBOSITY}
to add \cd{*load-print*}.
This variable provides the default for the \cd{:print} argument
to \cdf{load}.  Its initial value is \cdf{nil}.
\end{defun}
\end{newer}

\begin{newer}
\begin{defun}[Variable]
*load-pathname*

X3J13 voted in June 1989 \issue{LOAD-TRUENAME} to introduce \cd{*load-pathname*};
it is initially \cdf{nil} but \cdf{load} binds it to a pathname that
represents the file name given as the first argument to \cdf{load} merged
with the defaults (see \cdf{merge-pathname}).
\end{defun}

\begin{defun}[Variable]
*load-truename*

X3J13 voted in June 1989 \issue{LOAD-TRUENAME} to introduce \cd{*load-truename*};
it is initially \cdf{nil} but \cdf{load} binds it to the ``true name'' of
the file being loaded.  See \cdf{truename}.
\end{defun}
\end{newer}

\begin{newer}
X3J13 voted in March 1989 \issue{LOAD-OBJECTS} to introduce a facility
based on the Object System
whereby a user can specify how \cdf{compile-file} and \cdf{load}
must cooperate to reconstruct compile-time constant objects at load time.
The protocol is simply this:
  \cdf{compile-file} calls the generic
  function \cdf{make-load-form} on any object that is referenced as
  a constant or as a self-evaluating form, if the object's metaclass is
  \cdf{standard-class}, \cdf{structure-class}, any user-defined metaclass (not a
  subclass of \cdf{built-in-class}), or any of a possibly empty
  implementation-defined list of other metaclasses; \cdf{compile-file} will
  call \cdf{make-load-form} only once for any given object (as determined by \cdf{eq})
  within a single file.  The user-programmability stems from the possibility
  of user-defined methods for \cdf{make-load-form}.  The helper function
  \cdf{make-load-form-saving-slots} makes it easy to write commonly used
  versions of such methods.

\begin{defun}[Generic function]
make-load-form object

The argument is an object that is
  referenced as a constant or as a self-evaluating form in a file being
  compiled by \cdf{compile-file}.  The objective is to enable \cdf{load} to
  construct an equivalent object.

  The first value, called the \emph{creation form}, is a form that, when
  evaluated at load time, should return an object that is equivalent to
  the argument.  The exact meaning of ``equivalent'' depends on the type
  of object and is up to the programmer who defines a method for
  \cdf{make-load-form}.  This allows the user to program the notion
  of ``similar as a constant'' (see section~\ref{COMPILER-SECTION}).

  The second value, called the \emph{initialization form}, is a form that,
  when evaluated at load time, should perform further initialization of
  the object.  The value returned by the initialization form is ignored.
  If the \cdf{make-load-form} method returns only one value, the
  initialization form is \cdf{nil}, which has no effect.  If the object used
  as the argument to \cdf{make-load-form} appears as a constant in the
  initialization form, at load time it will be replaced by the
  equivalent object constructed by the creation form; this is how the
  further initialization gains access to the object.

  Two values are returned so that circular structures may be handled.
  The order of evaluation rules discussed below
  for creation and initialization forms
  eliminates the possibility of partially initialized objects in the
  absence of circular structures and reduces the possibility to a minimum
  in the presence of circular structures.  This allows nodes in
  non-circular structures to be built out of fully initialized subparts.

  Both the creation form and the initialization form can contain
  references to objects of user-defined types (defined precisely below).
  However, there must not be any circular dependencies in creation forms.
  An example of a circular dependency: the creation form for the
  object \emph{X\/} contains a reference to the object \emph{Y\/}, and the creation form
  for the object \emph{Y\/} contains a reference to the object \emph{X\/}.  A simpler
  example: the creation form for the object \emph{X\/} contains
  a reference to \emph{X\/} itself.  Initialization forms are not subject to
  any restriction against circular dependencies, which is the entire
  reason for having initialization forms.  See the example of circular
  data structures below.

  The creation form for an object is always evaluated before the
  initialization form for that object.  When either the creation form or
  the initialization form refers to other objects of user-defined types
  that have not been referenced earlier in the \cdf{compile-file}, the
  compiler collects all of the creation and initialization forms.  Each
  initialization form is evaluated as soon as possible after its
  creation form, as determined by data flow.  If the initialization form
  for an object does not refer to any other objects of user-defined
  types that have not been referenced earlier in the \cdf{compile-file}, the
  initialization form is evaluated immediately after the creation form.
  If a creation or initialization form \emph{F\/} references other objects of
  user-defined types that have not been referenced earlier in the
  \cdf{compile-file}, the creation forms for those other objects are evaluated
  before \emph{F\/} and the initialization forms for those other objects are
  also evaluated before \emph{F\/} whenever they do not depend on the object
  created or initialized by \emph{F}.  Where the above rules do not uniquely
  determine an order of evaluation, it is unspecified
  which of the possible orders of evaluation is chosen.

  While these creation and initialization forms are being evaluated, the
  objects are possibly in an uninitialized state, analogous to the state
  of an object between the time it has been created by \cdf{allocate-instance}
  and it has been processed fully by \cdf{initialize-instance}.  Programmers
  writing methods for \cdf{make-load-form} must take care in manipulating
  objects not to depend on slots that have not yet been initialized.

  It is unspecified whether \cdf{load} calls \cdf{eval} on the forms or does some
  other operation that has an equivalent effect.  For example, the
  forms might be translated into different but equivalent forms and
  then evaluated; they might be compiled and the resulting functions
  called by \cdf{load} (after they themselves have been loaded);
  or they might be interpreted by a special-purpose
  interpreter different from \cdf{eval}.  All that is required is that the
  effect be equivalent to evaluating the forms.

  It is valid for user programs to call \cdf{make-load-form} in
  circumstances other than compilation, providing the argument's
  metaclass is not \cdf{built-in-class} or a subclass of \cdf{built-in-class}.

  Applying \cdf{make-load-form} to an object whose metaclass is \cdf{standard-class} or
  \cdf{structure-class} for which no user-defined method is applicable signals
  an error.  It is valid to implement this either by defining default
  methods for the classes \cdf{standard-object} and \cdf{structure-object} that signal an error
  or by having no applicable method for those classes.

See \cdf{load-time-eval}.

In the following example, an equivalent instance of \cdf{my-class} is reconstructed
  by using the values of two of its slots.  The value of the third slot
  is derived from those two values.
\begin{lisp}
(defclass my-class ()
~~((a :initarg :a :reader my-a) \\*
~~~(b :initarg :b :reader my-b) \\*
~~~(c :accessor my-c))) \\
\\
(defmethod shared-initialize ((self my-class) slots \&rest inits) \\*
~~(declare (ignore slots inits)) \\*
~~(unless (slot-boundp self 'c) \\*
~~~~(setf (my-c self) \\*
~~~~~~~~~~(some-computation (my-a self) (my-b self))))) \\
\\
(defmethod make-load-form ((self my-class)) \\*
~~{\Xbq}(make-instance ',(class-name (class-of self)) \\*
~~~~~~~~~~~~~~~~~~:a ',(my-a self) :b ',(my-b self)))
\end{lisp}
This code will fail if either of the first two slots of some instance
of \cdf{my-class} contains the instance itself.
Another way to write the last form in the preceding example is
\begin{lisp}
(defmethod make-load-form ((self my-class)) \\*
~~(make-load-form-saving-slots self '(a b)))
\end{lisp}
This has the advantages of conciseness and handling circularities correctly.

In the next example, instances of class \cdf{my-frob} are ``interned'' in some way.
  An equivalent instance is reconstructed by using the value of the
  \cdf{name} slot as a key for searching for existing objects.  In this case
  the programmer has chosen to create a new object if no existing
  object is found; an alternative possibility would be to signal an
  error in that case.
\begin{lisp}
(defclass my-frob () \\*
~~((name :initarg :name :reader my-name))) \\
\\
(defmethod make-load-form ((self my-frob)) \\*
~~{\Xbq}(find-my-frob ',(my-name self) :if-does-not-exist :create))
\end{lisp}

  In the following example, the data structure to be dumped is circular, because
  each node of a tree has a list of its children and each child has a reference
  back to its parent.  
\begin{lisp}
(defclass tree-with-parent () ((parent :accessor tree-parent) \\*
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~(children :initarg :children)))
\end{lisp}

\begin{lisp}
(defmethod make-load-form ((x tree-with-parent)) \\*
~~(values \\*
~~~~{\Xbq}(make-instance ',(class-of x) \\*
~~~~~~~~~~~~~~~~~~~~:children ',(slot-value x 'children)) \\*
~~~~{\Xbq}(setf (tree-parent ',x) ',(slot-value x 'parent))))
\end{lisp}
Suppose \cdf{make-load-form} is called on one object in
  such a structure.  The creation form creates an equivalent object and
  fills in the \cdf{children} slot, which forces creation of equivalent
  objects for all of its children, grandchildren, etc.  At this point
  none of the parent slots have been filled in.  The initialization form
  fills in the \cdf{parent} slot, which forces creation of an equivalent
  object for the parent if it was not already created.  Thus the entire
  tree is recreated at load time.  At compile time, \cdf{make-load-form} is
  called once for each object in the tree.  All the creation forms
  are evaluated, in unspecified order, and then all  the
  initialization forms are evaluated, also in unspecified order.

  In this final example, the data structure to be dumped has no special
  properties and an equivalent structure can be reconstructed
  simply by reconstructing the slots' contents.
\begin{lisp}
(defstruct my-struct a b c) \\[2pt]
(defmethod make-load-form ((s my-struct)) \\*
~~(make-load-form-saving-slots s))
\end{lisp}
This is easy to code using \cdf{make-load-form-saving-slots}.
\end{defun}

\begin{defun}[Function]
make-load-form-saving-slots object &optional slots

This returns two values suitable for return from a \cdf{make-load-form} method.
  The first argument is the object.  The optional second argument is a
  list of the names of slots to preserve; it defaults to all of the
  local slots.

\cdf{make-load-form-saving-slots} returns forms that construct
  an equivalent object using \cdf{make-instance}
  and \cdf{setf} of \cdf{slot-value} for
  slots with values, or \cdf{slot-makunbound} for slots without values, or
  other functions of equivalent effect.

  Because \cdf{make-load-form-saving-slots} returns two values, it can deal with
  circular structures; it works for any object
  of metaclass \cdf{standard-class} or \cdf{structure-class}.
  Whether the result is
  useful depends on whether the object's type and slot
  contents fully capture an application's idea of the object's state.
\end{defun}
\end{newer}


\section {Accessing Directories}

% \section {Доступ к директориям}

The following function is a very simple portable primitive for examining
a directory.  Most file systems can support much more powerful
directory-searching primitives, but no two are alike.
It is expected that most implementations of Common Lisp will extend the
\cdf{directory} function or provide more powerful
primitives.

Следующие функции это простые портируемые примитивы для работы с
директорией. Большинство файловых систем поддерживают гораздо более
мощные примитивы.  Ожидается, что реализации Common Lisp'а расширят
функцию \cdf{directory} или предоставят более мощные примитивы.

\begin{defun}[Function]
directory pathname &key

A list of pathnames is returned, one for each
file in the file system that matches the given \emph{pathname}.
(The \emph{pathname} argument may be a pathname, a string,
or a stream associated with a file.)
For a file that matches, the \cdf{truename} appears
in the result list.
If no file matches the \emph{pathname}, it is not an error;
\cdf{directory} simply returns {\nil}, the list of no results.
Keywords such as \cd{:wild} and \cd{:newest} may
be used in \emph{pathname} to indicate the search space.

Возвращается список имён-файлов, каждое для одного файла, который
подходит для переданного имени-файла \emph{pathname}.


\begin{new}
X3J13 voted in March 1988
\issue{PATHNAME-STREAM}
to specify exactly which streams may be used as pathnames.
See section \ref{PATHNAME-FUNCTIONS}.
\end{new}

\begin{new}
X3J13 voted in January 1989
\issue{CLOSED-STREAM-OPERATIONS}
to specify that \cdf{directory} is unaffected by
whether the first argument, if a stream, is open or closed. If the first
argument is a stream, \cdf{directory} behaves as if the function \cdf{pathname}
were applied to the stream and the resulting pathname used instead.
However, X3J13 commented that the treatment of open streams
may differ considerably from one implementation to another; for example,
in some operating systems open files are written under a temporary or
invisible name and later renamed when closed.  In general, programmers writing
code intended to be portable should be careful when using \cdf{directory}.
\end{new}

\begin{newer}
X3J13 voted in June 1989 \issue{PATHNAME-LOGICAL} to require \cdf{directory}
to accept logical pathnames (see section~\ref{LOGICAL-PATHNAMES-SECTION}).
However, the result returned by \cdf{directory} never contains a logical pathname.
\end{newer}

\beforenoterule
\begin{implementation}
It is anticipated that
an implementation may need to provide additional
parameters to control the directory search.  Therefore \cdf{directory}
is specified to take additional keyword arguments so that implementations
may experiment with extensions,
even though no particular keywords are specified here.

As a simple example of such an extension, for a file system that
supports the notion of cross-directory file links,
a keyword argument \cd{:links} might, if non-{\nil},
specify that such links be included in the result list.
\end{implementation}
\afternoterule
\end{defun}

\begin{defun}[Function]
ensure-directories-exist file &key :verbose

If the directories of file do not exist then this function creates them
returning two values, file and a second value true if the directories were
created or nil if not.

Если директории не существовали, тогда данная функция создаёт их и возвращает
два значения file и, если создание происходило - t, иначе - nil.
\end{defun}