% -*- Mode: TeX -*-

\beginSubsection{Pathname Components}
\DefineSection{PathnameComponents}

% \long\def\possiblecomponentvalues#1{\goodbreak
% Possible values for this component:\par
% \beginlist\par#1\par
% \itemitem{\nil, \kwd{wild}, or \kwd{unspecific}}\par
% See details and restrictions in \secref\SpecialComponentValues.\par
% \endlist\par}
%
% \possiblecomponentvalues{\itemitem{...}\par...}

A \term{pathname} has six components:
     a host,
     a device,
     a directory,
     a name,
     a type,
 and a version.

%% 23.1.1 4
%% 23.1.1 5
%% 23.1.1 17

\beginsubsubsection{The Pathname Host Component}

The name of the file system on which the file resides,
or the name of a \term{logical host}.

%\possiblecomponentvalues{\itemitem{...}\par...}

\endsubsubsection%{The Pathname Host Component}

\beginsubsubsection{The Pathname Device Component}

Corresponds to the ``device'' or ``file structure'' concept in many
host file systems: the name of a logical or physical device containing files.

%\possiblecomponentvalues{\itemitem{...}\par...}

\endsubsubsection%{The Pathname Device Component}

%% 23.1.1 6
\beginsubsubsection{The Pathname Directory Component}

Corresponds to the ``directory'' concept in many host file systems:
the name of a group of related files.

%\possiblecomponentvalues{\itemitem{...}\par...}

\endsubsubsection%{The Pathname Directory Component}

%% 23.1.1 7
\beginsubsubsection{The Pathname Name Component}

The ``name'' part of a group of \term{files} that can be thought of
as conceptually related.

%\possiblecomponentvalues{\itemitem{...}\par...}

\endsubsubsection%{The Pathname Name Component}

%% 23.1.1 8
%% 23.1.1 15
\beginsubsubsection{The Pathname Type Component}

Corresponds to the ``filetype'' or ``extension'' concept in many host
file systems.  This says what kind of file this is.  
This component is always a \term{string}, \nil, \kwd{wild}, or \kwd{unspecific}.

%\possiblecomponentvalues{\itemitem{...}\par...}

\endsubsubsection%{The Pathname Type Component}

%% 23.1.1 9
%% 23.1.1 16  
\beginsubsubsection{The Pathname Version Component}

Corresponds to the ``version number'' concept in many host file systems.

The version is either a positive \term{integer} 
or a \term{symbol} from the following list:
\nil, \kwd{wild}, \kwd{unspecific}, or \kwd{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).  Implementations 
can define other special version \term{symbols}.

%\possiblecomponentvalues{\itemitem{...}\par...}

\endsubsubsection%{The Pathname Version Component}

\endSubsection%{Pathname Components}

\beginSubsection{Interpreting Pathname Component Values}

\beginsubsubsection{Strings in Component Values}

\issue{PATHNAME-COMPONENT-VALUE:SPECIFY}

\beginsubsubsubsection{Special Characters in Pathname Components}

\term{Strings} in \term{pathname} component values 
never contain special \term{characters} that represent
separation between \term{pathname} fields, 
such as \term{slash} in \Unix\ \term{filenames}.
Whether separator \term{characters} are permitted as 
part of a \term{string} in a \term{pathname} component
is \term{implementation-defined}; 
however, if the \term{implementation} does permit it, 
it must arrange to properly ``quote'' the character for the 
\term{file system} when constructing a \term{namestring}.
For example,

\code
 ;; In a TOPS-20 implementation, which uses {\hat}V to quote 
 (NAMESTRING (MAKE-PATHNAME :HOST "OZ" :NAME "<TEST>"))
\EV #P"OZ:PS:{\hat}V<TEST{\hat}V>"
\NV #P"OZ:PS:<TEST>"
\endcode

%Such punctuation \term{characters} appear only in \term{namestrings}.
%Characters used as punctuation can appear in \term{pathname} component values
%with a non-punctuation meaning if the file system allows it 
%(\eg a \Unix\ file name that begins with a dot).
 
\endsubsubsubsection%{Special Characters in Pathname Components}

\endissue{PATHNAME-COMPONENT-VALUE:SPECIFY}

\issue{PATHNAME-COMPONENT-CASE:KEYWORD-ARGUMENT}
\beginsubsubsubsection{Case in Pathname Components}
\DefineSection{PathnameComponentCase}

\term{Namestrings} always use local file system \term{case} conventions, 
but \clisp\ \term{functions} that manipulate \term{pathname} components
allow the caller to select either of two conventions for representing
\term{case} in component values by supplying a value for the
\kwd{case} keyword argument.

\beginsubsubsubsubsection{Local Case in Pathname Components}

A value of \kwd{local}, the default for these \term{functions}, indicates that the
\term{functions} should receive and yield \term{strings} in component values
as if they were already represented according to the host \term{file system}'s 
convention for \term{case}.

If the \term{file system} supports both \term{cases}, \term{strings} given or received
as \term{pathname} component values under this protocol are to be used exactly
as written.  If the file system only supports one \term{case}, 
the \term{strings} will be translated to that \term{case}.

\endsubsubsubsubsection%{Local Case in Pathname Components}

\beginsubsubsubsubsection{Common Case in Pathname Components}

A value of \kwd{common} indicates that these \term{functions} should receive 
and yield \term{strings} in component values according to the following conventions:

\beginlist
\itemitem{\bull}
All \term{uppercase} means to use a file system's customary \term{case}.
\itemitem{\bull}
All \term{lowercase} means to use the opposite of the customary \term{case}.
\itemitem{\bull}
Mixed \term{case} represents itself.
\endlist
Note that these conventions have been chosen in such a way that translation
from \kwd{local} to \kwd{common} and back to \kwd{local} is information-preserving.
 
\endsubsubsubsubsection%{Common Case in Pathname Components}

\endsubsubsubsection%{Case in Pathname Components}
\endissue{PATHNAME-COMPONENT-CASE:KEYWORD-ARGUMENT}

\endsubsubsection%{Strings in Component Values}

\beginsubsubsection{Special Pathname Component Values}
\DefineSection{SpecialComponentValues}

\beginsubsubsubsection{NIL as a Component Value}

If \nil\ is the value of a \term{pathname} component,
that component is considered to be unfilled.
\Seesection\MergingPathnames.

\endsubsubsubsection%{NIL as a Component Value}

\issue{PATHNAME-COMPONENT-VALUE:SPECIFY}
\beginsubsubsubsection{:WILD as a Component Value}
\DefineSection{WildComponents}

If \kwd{wild} is the value of a \term{pathname} component,
that component is considered to be a wildcard, which matches anything.

A \term{conforming program} must be prepared to encounter a value of \kwd{wild}
as the value of any \term{pathname} component,
or as an \term{element} of a \term{list} that is the value of the directory component.

\issue{PATHNAME-SUBDIRECTORY-LIST:NEW-REPRESENTATION}
When constructing a \term{pathname},
a \term{conforming program} may use \kwd{wild} as the value of any or all of
the directory, name, type, 
or version component, but must not use \kwd{wild} as the value of the host,
%% "version" commented out per Barmar--
%% PATHNAME-COMPONENT-VALUE:SPECIFY says that wild versions are permitted.
%device, or version
or device component.

If \kwd{wild} is used as the value of the directory component in the construction
of a \term{pathname}, the effect is equivalent to specifying the list
\f{(:absolute :wild-inferiors)},
or the same as \f{(:absolute :wild)} in a \term{file system} that does not support
\kwd{wild-inferiors}.
\endissue{PATHNAME-SUBDIRECTORY-LIST:NEW-REPRESENTATION}

\endsubsubsubsection%{:WILD as a Component Value}
\endissue{PATHNAME-COMPONENT-VALUE:SPECIFY}

\issue{PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN}
\beginsubsubsubsection{:UNSPECIFIC as a Component Value}
\DefineSection{UnspecificComponent}

If \kwd{unspecific} is the value of a \term{pathname} component,
the component is considered to be absent in the \term{filename}
being represented by the \term{pathname}.

Note that this is similar to a value of \nil\ in that it
does not supply a value for the component, but it is different
because the component is considered to have been filled.

Whether a value of \kwd{unspecific} is permitted for this component
on any given \term{file system} accessible to the \term{implementation}
is \term{implementation-defined}.
A \term{conforming program} must never unconditionally use a
\kwd{unspecific} as the value of a \term{pathname} component because
such a value is not guaranteed to be permissible in all implementations.
However, a \term{conforming program} can, if it is careful, 
successfully manipulate user-supplied data 
which contains or refers to non-portable \term{pathname} components.
And certainly a \term{conforming program} should be prepared for the
possibility that any components of a \term{pathname} could be \kwd{unspecific}.

\endsubsubsubsection%{:UNSPECIFIC as a Component Value}
\endissue{PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN}

\endsubsubsection%{Special Pathname Component Values}

\issue{PATHNAME-COMPONENT-VALUE:SPECIFY}

\beginsubsubsection{Restrictions on Examining Pathname Components}

When examining \term{pathname} components, conforming programs must be prepared
to encounter any of the following values:
  
\beginlist
\itemitem{\bull}
Any component can be \nil, which means that the component has not
    been supplied.
  
\issue{PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN}
\itemitem{\bull}          
Any component can be \kwd{unspecific}, which means that the component has
    no meaning in this particular \term{pathname}.
   The consequences of supplying \kwd{unspecific} to a file system for which
  it does not make sense are undefined.
 
  When a \term{pathname} is converted to a namestring, 
the symbols \nil\ and \kwd{unspecific}
  cause the field to be treated as if it were empty. 
That is, both \nil\ and \kwd{unspecific} cause the
  component not to appear in the namestring.
   When merging (see \funref{merge-pathnames}), 
however, only a \nil\ value for a component will be
  replaced with the default for that component, while 
a value of \kwd{unspecific}
  will be left alone as if the field were filled.
 
\endissue{PATHNAME-UNSPECIFIC-COMPONENT:NEW-TOKEN}
  
\itemitem{\bull}
The device, directory, name, and type can be \term{strings}.
%!!! Laddaga:
%  But cannot cannot contain directory separators.  Or, put another way, if
%  a directory component is a string, it can only name a simple level of 
%  directory structure?  This doesn't seem right, but otherwise rule 1 is violated.
%  Perhaps directory here is an error?
  
\itemitem{\bull}
It is \term{implementation-dependent} what \term{object}
is used to represent the host. 
  
\itemitem{\bull}
The directory can be a \term{list} of \term{strings} and \term{symbols}. 
\issue{PATHNAME-SUBDIRECTORY-LIST:NEW-REPRESENTATION}
The \term{car} of the \term{list} is one of the symbols \kwd{absolute} or 
\kwd{relative}. Each remaining element of the \term{list} is a \term{string} 
or a \term{symbol}.  Each \term{string} names a single level of directory 
structure.  The \term{strings} should contain only the directory names 
themselves---no punctuation characters.
The following information applies to the structure of the directory component.
\beginlist
\itemitem{--}
  A \term{list} whose \term{car} is the symbol \kwd{absolute} represents 
  a directory path starting from the root directory.  The list 
  \f{(:absolute)} represents the root directory.  The list 
  \f{(:absolute "foo" "bar" "baz")} represents the directory called
  \f{"/foo/bar/baz"} in Unix (except possibly for \term{case}).
 
\itemitem{--}
  A \term{list} whose \term{car} is the symbol \kwd{relative} represents 
  a directory path starting from a default directory.  
  The list \f{(:relative)} has the same meaning as \nil\ and hence is not used.
  The list {\tt (:relative "foo" "bar")} represents the directory named {\tt "bar"} 
  in the directory named {\tt "foo"} in the default directory.
 
\itemitem{--}
  In place of a \term{string}, at any point in the \term{list}, \term{symbols} 
  can occur to indicate special file notations.  \Thenextfigure\ lists
  the \term{symbols} that have standard meanings.  Implementations are 
  permitted to add additional \term{objects} of any \term{type} 
  that is disjoint from \typeref{string}
  if necessary to represent features of their file systems that cannot be
  represented with the standard \term{strings} and \term{symbols}.
  Supplying any non-\term{string}, including any of the \term{symbols} listed below, 
  to a file system for which it does not make sense
  signals an error \oftype{file-error}.
  For example, Unix does not support \kwd{wild-inferiors} in most implementations.
 
\tablefigtwo{Special Markers In Directory Component}{Symbol}{Meaning}{
\kwd{wild}           & Wildcard match of one level of directory structure \cr
\kwd{wild-inferiors} & Wildcard match of any number of directory levels   \cr
\kwd{up}             & Go upward in directory structure (semantic) \cr
\kwd{back}           & Go upward in directory structure (syntactic) \cr
}

The following notes apply to the previous figure:
\beginlist
\itemitem{}
\kwd{absolute} or \kwd{wild-inferiors} 
immediately followed by \kwd{up} or \kwd{back}
  signals an error \oftype{file-error}.
 
\itemitem{}
  ``Syntactic'' means that the action of 
\kwd{back} depends only on the \term{pathname}
  and not on the contents of the file system.  
``Semantic'' means that the
  action of \kwd{up} depends on the contents of the file system; to resolve
  a \term{pathname} containing 
\kwd{up} to a \term{pathname} whose directory component
  contains only \kwd{absolute} and 
\term{strings} requires probing the file system.
\kwd{up} differs from 
\kwd{back} only in file systems that support multiple
  names for directories, perhaps via symbolic links.  For example,
  suppose that there is a directory
\f{(:absolute "X" "Y" "Z")}
  linked to 
\f{(:absolute "A" "B" "C")}
  and there also exist directories
\f{(:absolute "A" "B" "Q")} and 
\f{(:absolute "X" "Y" "Q")}.
Then
\f{(:absolute "X" "Y" "Z" :up "Q")}
  designates
\f{(:absolute "A" "B" "Q")}
  while
\f{(:absolute "X" "Y" "Z" :back "Q")}
  designates
\f{(:absolute "X" "Y" "Q")}
\endlist 

\itemitem{--}
  In non-hierarchical file systems, the only valid \term{list} values for the
  directory component of a \term{pathname} are \f{(:absolute \term{string})} 
  and \f{(:absolute :wild)}.  \kwd{relative} directories and the keywords
  \kwd{wild-inferiors}, \kwd{up}, and \kwd{back} are not used 
  in non-hierarchical file systems.
 
%!!! Laddaga thinks this isn't the right place for this information.
\itemitem{--}
  A relative directory in the \term{pathname} argument to a function such as
  \funref{open} is merged with \varref{*default-pathname-defaults*} 
  before accessing the file system.
\endlist
\endissue{PATHNAME-SUBDIRECTORY-LIST:NEW-REPRESENTATION}
 
  
\itemitem{\bull}
The version can be any \term{symbol} or any \term{integer}.  
The symbol \kwd{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, and refers to the smallest version number
    greater than any existing version number when creating a new file.
    Other \term{symbols} and 
\term{integers} have \term{implementation-defined} meaning.
    It is suggested, but not required, that implementations use positive
    \term{integers} 
starting at 1 as version numbers, recognize the symbol \kwd{oldest}
    to designate the smallest existing version number, and use \term{keywords}
for other special versions.
\endlist 

\endsubsubsection%{Restrictions on Examining Pathname Components}

\beginsubsubsection{Restrictions on Wildcard Pathnames}
\DefineSection{WildcardRestrictions}

  Wildcard \term{pathnames} can be used with \funref{directory} but not with 
  \funref{open},
%!!! Laddaga: LOAD?
  and return true from \funref{wild-pathname-p}. When examining
  wildcard components of a wildcard \term{pathname}, conforming programs
  must be prepared to encounter any of the following additional values
  in any component or any element of a \term{list} that is the directory component:
 
\beginlist

\itemitem{\bull}
  \kwd{wild}, which matches anything.
 
\itemitem{\bull}
  A \term{string} containing \term{implementation-dependent} special wildcard
  characters.
 
\itemitem{\bull}
  Any \term{object}, representing an \term{implementation-dependent} wildcard
  pattern.

\endlist 

\endsubsubsection%{Restrictions on Wildcard Pathnames}

\beginsubsubsection{Restrictions on Constructing Pathnames}

  When constructing a \term{pathname} from components, conforming programs
  must follow these rules:
  
\beginlist

\itemitem{\bull}
  Any component can be \nil.  \nil\ in the host might mean a default host
  rather than an actual \nil\ in some implementations.
           
\itemitem{\bull}
%!!! Laddaga questions the "directory" part here.
  The host, device, directory, name, and type can be \term{strings}.  There
  are \term{implementation-dependent} limits on the number and type of
  \term{characters} in these \term{strings}.
  
\itemitem{\bull}
  The directory can be a \term{list} of \term{strings} and \term{symbols}.
  There are \term{implementation-dependent} limits on the \term{list}'s
  length and contents.
  
\itemitem{\bull}
The version can be \kwd{newest}.
 
\itemitem{\bull}
Any component can be taken from the corresponding component
    of another \term{pathname}.  When 
the two \term{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 \term{implementation-dependent}.
  
\itemitem{\bull}
An implementation might support other values for some components,
    but a portable program cannot use those values.  A conforming program
    can use \term{implementation-dependent} values but this can make it
    non-portable, for example, it might work only with \Unix\ file systems.
\endlist                                   

%%% 23.1.1 14 omitted.
%%% 23.1.1 18 omitted.

\endsubsubsection%{Restrictions on Constructing Pathnames}

\endissue{PATHNAME-COMPONENT-VALUE:SPECIFY}

\endSubsection%{Interpreting Pathname Component Values}

\beginsubSection{Merging Pathnames}
\DefineSection{MergingPathnames}

Merging takes a \term{pathname} with unfilled components
and supplies values for those components from a source of defaults.

If a component's value is \nil, that component is considered to be unfilled.
If a component's value is any \term{non-nil} \term{object}, 
including \kwd{unspecific}, that component is considered to be filled.

\beginsubsubsection{Examples of Merging Pathnames}

Although the following examples are possible to execute only in
\term{implementations} which permit \kwd{unspecific} in the indicated
position andwhich permit four-letter type components, they serve to illustrate
the basic concept of \term{pathname} merging.

\medbreak
\code
 (pathname-type 
   (merge-pathnames (make-pathname :type "LISP")
                    (make-pathname :type "TEXT")))
\EV "LISP"
\smallbreak
 (pathname-type 
   (merge-pathnames (make-pathname :type nil)
                    (make-pathname :type "LISP")))
\EV "LISP"
\smallbreak
 (pathname-type 
   (merge-pathnames (make-pathname :type :unspecific)
                    (make-pathname :type "LISP")))
\EV :UNSPECIFIC
\endcode

\endsubsubsection%{Examples of Merging Pathnames}

\endsubSection%{Merging Pathnames}