@c Generated by the sb-manual contrib. Do not edit.

@node pathnames
@cindex pathname
@chapter Pathnames

@menu
* Lisp Pathnames: lisp pathnames.
* Native Filenames: native filenames.
@end menu

@node lisp pathnames
@section Lisp Pathnames

@menu
* Home Directory Specifiers: home directory specifiers.
* The SYS Logical Pathname Host: the sys logical pathname host.
@end menu

There are many aspects of ANSI Common Lisp's pathname support
which are implementation-defined and so need documentation.

@node home directory specifiers
@subsection Home Directory Specifiers

SBCL accepts the keyword @code{:home} and a list of the form
@code{(:home} @code{"username")} as a directory component immediately
following @code{:absolute}.

@code{:home} is represented in namestrings by @code{~/} and @code{(:home}
@code{"username")} by @code{~username/} at the start of the namestring.
Tilde-characters elsewhere in namestrings represent themselves.

Home directory specifiers are resolved to home directory of the
current or specified user by @code{sb-ext:native-namestring}, which is used
by the implementation to translate pathnames before passing them on
to operating system specific routines.

Using @code{(:home} @code{"user")} form on Windows signals an error.

@node the sys logical pathname host
@subsection The SYS Logical Pathname Host

@cindex logical pathname
@cindex pathname, logical
The logical pathname host named by @code{"SYS"} exists in SBCL.
Its @code{logical-pathname-translations} may be set by the site or the user
applicable to point to the locations of the system's sources; in
particular, the core system's source files match the logical
pathname @code{"SYS:SRC;**;*.*.*"}, and the contributed modules' source
files match @code{"SYS:CONTRIB;**;*.*.*"}.

@anchor{Function sb-ext set-sbcl-source-location}
@ffindex @sortas{set-sbcl-source-location sb-ext} set-sbcl-source-location [sb-ext]
@deffn{Function} sb-ext:set-sbcl-source-location pathname
Initialize the @code{SYS} logical host based on @code{pathname}, which should
be the top-level directory of the SBCL sources. This will replace any
existing translations for @code{"SYS:SRC;"}, @code{"SYS:CONTRIB;"}, and
@code{"SYS:OUTPUT;"}. Other @code{"SYS:"} translations are preserved.
@end deffn
@node native filenames
@section Native Filenames

In some circumstances, what is wanted is a Lisp pathname object which
corresponds to a string produced by the Operating System. In this
case, some of the default parsing rules are inappropriate: most
filesystems do not have a native understanding of wild pathnames;
such functionality is often provided by shells above the OS, often
in mutually-incompatible ways.

To allow the user to deal with this, the following functions are
provided: @code{sb-ext:parse-native-namestring} and @code{sb-ext:native-pathname}
return the closest equivalent Lisp pathname to a given string
(appropriate for the Operating System), while
@code{sb-ext:native-namestring} converts a non-wild pathname designator to
the equivalent native namestring, if possible. Some Lisp pathname
concepts (such as the @code{:back} directory component) have no direct
equivalents in most Operating Systems; the behaviour of
@code{sb-ext:native-namestring} is unspecified if an inappropriate pathname
designator is passed to it. Additionally, note that conversion from
pathname to native filename and back to pathname should not be
expected to preserve equivalence under @code{equal}.

@anchor{Function sb-ext parse-native-namestring}
@ffindex @sortas{parse-native-namestring sb-ext} parse-native-namestring [sb-ext]
@deffn{Function} sb-ext:parse-native-namestring thing &optional host defaults &key start end junk-allowed as-directory
Convert @code{thing} into a pathname, using the native conventions
appropriate for the pathname host @code{host}, or if not specified the
host of @code{defaults}.  If @code{thing} is a string, the parse is bounded by
@code{start} and @code{end}, and error behaviour is controlled by @code{junk-allowed},
as with @code{parse-namestring}.  For file systems whose native
conventions allow directories to be indicated as files, if
@code{as-directory} is true, return a pathname denoting @code{thing} as a
directory.
@end deffn
@anchor{Function sb-ext native-pathname}
@ffindex @sortas{native-pathname sb-ext} native-pathname [sb-ext]
@deffn{Function} sb-ext:native-pathname pathspec
Convert @code{pathspec} (a pathname designator) into a pathname, assuming
the operating system native pathname conventions.
@end deffn
@anchor{Function sb-ext native-namestring}
@ffindex @sortas{native-namestring sb-ext} native-namestring [sb-ext]
@deffn{Function} sb-ext:native-namestring pathname &key as-file
Construct the full native (name)string form of @code{pathname}.  For
file systems whose native conventions allow directories to be
indicated as files, if @code{as-file} is true and the name, type, and
version components of @code{pathname} are all @code{nil} or @code{:unspecific},
construct a string that names the directory according to the file
system's syntax for files.
@end deffn
Because some file systems permit the names of directories to be
expressed in multiple ways, it is occasionally necessary to parse a
native file name as a directory name or to produce a native file
name that names a directory as a file. For these cases,
PARSE-NATIVE-NAMESTRING accepts the keyword argument
@code{:as-directory} to force a filename to parse as a directory, and
@code{sb-ext:native-namestring} accepts the keyword argument @code{:as-file}
to force a pathname to unparse as a file. For example,

@example
; On Unix, the directory "/tmp/" can be denoted by "/tmp/" or "/tmp".
; Under the default rules for native filenames, these parse and
; unparse differently.
(defvar *p*)
(setf *p* (parse-native-namestring "/tmp/")) => #P"/tmp/"
(pathname-name *p*) => NIL
(pathname-directory *p*) => (:ABSOLUTE "tmp")
(native-namestring *p*) => "/tmp/"

(setf *p* (parse-native-namestring "/tmp")) => #P"/tmp"
(pathname-name *p*) => "tmp"
(pathname-directory *p*) => (:ABSOLUTE)
(native-namestring *p*) => "/tmp"

; A non-NIL AS-DIRECTORY argument to PARSE-NATIVE-NAMESTRING forces
; both the second string to parse the way the first does.
(setf *p* (parse-native-namestring "/tmp"
                                   nil *default-pathname-defaults*
                                   :as-directory t)) => #P"/tmp/"
(pathname-name *p*) => NIL
(pathname-directory *p*) => (:ABSOLUTE "tmp")

; A non-NIL AS-FILE argument to NATIVE-NAMESTRING forces the pathname
; parsed from the first string to unparse as the second string.
(setf *p* (parse-native-namestring "/tmp/")) => #P"/tmp/"
(native-namestring *p* :as-file t) => "/tmp"
@end example

