doc/manual/pathnames.texinfo

   1 @node Pathnames
   2 @comment  node-name,  next,  previous,  up
   3 @chapter Pathnames
   4
   5 @cindex Pathnames
   6
   7 @menu
   8 * Lisp Pathnames::
   9 * Native Filenames::
  10 @end menu
  11
  12 @node Lisp Pathnames
  13 @comment  node-name,  next,  previous,  up
  14 @section Lisp Pathnames
  15
  16 There are many aspects of ANSI Common Lisp's pathname support which are
  17 implementation-defined and so need documentation.
  18
  19 @c FIXME: as a matter of ANSI conformance, we are required to document
  20 @c implementation-defined stuff, which for pathnames (chapter 19 of CLtS)
  21 @c includes:
  22 @c
  23 @c * Otherwise, the parsing of thing is implementation-defined.
  24 @c   (PARSE-NAMESTRING)
  25 @c
  26 @c * If thing contains an explicit host name and no explicit device name,
  27 @c   then it is implementation-defined whether parse-namestring will supply
  28 @c   the standard default device for that host as the device component of
  29 @c   the resulting pathname.  (PARSE-NAMESTRING)
  30 @c
  31 @c * The specific nature of the search is implementation-defined.
  32 @c   (LOAD-LOGICAL-PATHNAME-TRANSLATIONS)
  33 @c
  34 @c * Any additional elements are implementation-defined.
  35 @c   (LOGICAL-PATHNAME-TRANSLATIONS)
  36 @c
  37 @c * The matching rules are implementation-defined but should be consistent
  38 @c   with directory.  (PATHNAME-MATCH-P)
  39 @c
  40 @c * Any such additional translations are implementation-defined.
  41 @c   (TRANSLATE-LOGICAL-PATHNAMES)
  42 @c
  43 @c * ...or an implementation-defined portion of a component...
  44 @c   (TRANSLATE-PATHNAME)
  45 @c
  46 @c * The portion of source that is copied into the resulting pathname is
  47 @c   implementation-defined.  (TRANSLATE-PATHNAME)
  48 @c
  49 @c * During the copying of a portion of source into the resulting
  50 @c   pathname, additional implementation-defined translations of case or
  51 @c   file naming conventions might occur.  (TRANSLATE-PATHNAME)
  52 @c
  53 @c * In general, the syntax of namestrings involves the use of
  54 @c   implementation-defined conventions.  (19.1.1)
  55 @c
  56 @c * The nature of the mapping between structure imposed by pathnames and
  57 @c   the structure, if any, that is used by the underlying file system is
  58 @c   implementation-defined.  (19.1.2)
  59 @c
  60 @c * The mapping of the pathname components into the concepts peculiar to
  61 @c   each file system is implementation-defined.  (19.1.2)
  62 @c
  63 @c * Whether separator characters are permitted as part of a string in a
  64 @c   pathname component is implementation-defined;  (19.2.2.1.1)
  65 @c
  66 @c * Whether a value of :unspecific is permitted for any component on any
  67 @c   given file system accessible to the implementation is
  68 @c   implementation-defined.  (19.2.2.2.3)
  69 @c
  70 @c * Other symbols and integers have implementation-defined meaning.
  71 @c   (19.2.2.4.6)
  72
  73 @subsection Home Directory Specifiers
  74
  75 SBCL accepts the keyword @code{:home} and a list of the form
  76 @code{(:home "username")} as a directory component immediately
  77 following @code{:absolute}.
  78
  79 @code{:home} is represented in namestrings by @code{~/} and
  80 @code{(:home "username"} by @code{~username/} at the start of the
  81 namestring. Tilde-characters elsewhere in namestrings represent
  82 themselves.
  83
  84 Home directory specifiers are resolved to home directory of the
  85 current or specified user by @code{native-namestring}, which is used
  86 by the implementation to translate pathnames before passing them on to
  87 operating system specific routines.
  88
  89 Using @code{(:home "user")} form on Windows signals an error.
  90
  91 @subsection The SYS Logical Pathname Host
  92
  93 @cindex Logical pathnames
  94 @cindex Pathnames, logical
  95 @findex @cl{logical-pathname-translations}
  96 @findex @setf{@cl{logical-pathname-translations}}
  97
  98 @c * The existence and meaning of SYS: logical pathnames is
  99 @c   implementation-defined.  (19.3.1.1.1)
 100
 101 The logical pathname host named by @code{"SYS"} exists in SBCL.  Its
 102 @code{logical-pathname-translations} may be set by the site or the user
 103 applicable to point to the locations of the system's sources; in
 104 particular, the core system's source files match the logical pathname
 105 @code{"SYS:SRC;**;*.*.*"}, and the contributed modules' source files
 106 match @code{"SYS:CONTRIB;**;*.*.*"}.
 107
 108 @include fun-sb-ext-set-sbcl-source-location.texinfo
 109
 110 @node Native Filenames
 111 @comment  node-name,  next,  previous,  up
 112 @section Native Filenames
 113
 114 In some circumstances, what is wanted is a Lisp pathname object which
 115 corresponds to a string produced by the Operating System.  In this case,
 116 some of the default parsing rules are inappropriate: most filesystems do
 117 not have a native understanding of wild pathnames; such functionality is
 118 often provided by shells above the OS, often in mutually-incompatible
 119 ways.
 120
 121 To allow the user to deal with this, the following functions are
 122 provided: @code{parse-native-namestring} and @code{native-pathname}
 123 return the closest equivalent Lisp pathname to a given string
 124 (appropriate for the Operating System), while @code{native-namestring}
 125 converts a non-wild pathname designator to the equivalent native
 126 namestring, if possible.  Some Lisp pathname concepts (such as the
 127 @code{:back} directory component) have no direct equivalents in most
 128 Operating Systems; the behaviour of @code{native-namestring} is
 129 unspecified if an inappropriate pathname designator is passed to it.
 130 Additionally, note that conversion from pathname to native filename
 131 and back to pathname should not be expected to preserve equivalence
 132 under @code{equal}.
 133
 134 @include fun-sb-ext-parse-native-namestring.texinfo
 135 @include fun-sb-ext-native-pathname.texinfo
 136 @include fun-sb-ext-native-namestring.texinfo
 137
 138 Because some file systems permit the names of directories to be
 139 expressed in multiple ways, it is occasionally necessary to parse a
 140 native file name ``as a directory name'' or to produce a native file
 141 name that names a directory ``as a file''.  For these cases,
 142 @code{parse-native-namestring} accepts the keyword argument
 143 @code{as-directory} to force a filename to parse as a directory, and
 144 @code{native-namestring} accepts the keyword argument @code{as-file}
 145 to force a pathname to unparse as a file.  For example,
 146
 147 @lisp
 148 ; On Unix, the directory "/tmp/" can be denoted by "/tmp/" or "/tmp".
 149 ; Under the default rules for native filenames, these parse and
 150 ; unparse differently.
 151 (defvar *p*)
 152 (setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
 153 (pathname-name *p*) @result{} NIL
 154 (pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
 155 (native-namestring *p*) @result{} "/tmp/"
 156
 157 (setf *p* (parse-native-namestring "/tmp")) @result{} #P"/tmp"
 158 (pathname-name *p*) @result{} "tmp"
 159 (pathname-directory *p*) @result{} (:ABSOLUTE)
 160 (native-namestring *p*) @result{} "/tmp"
 161
 162 ; A non-NIL AS-DIRECTORY argument to PARSE-NATIVE-NAMESTRING forces
 163 ; both the second string to parse the way the first does.
 164 (setf *p* (parse-native-namestring "/tmp"
 165                                    nil *default-pathname-defaults*
 166                                    :as-directory t)) @result{} #P"/tmp/"
 167 (pathname-name *p*) @result{} NIL
 168 (pathname-directory *p*) @result{} (:ABSOLUTE "tmp")
 169
 170 ; A non-NIL AS-FILE argument to NATIVE-NAMESTRING forces the pathname
 171 ; parsed from the first string to unparse as the second string.
 172 (setf *p* (parse-native-namestring "/tmp/")) @result{} #P"/tmp/"
 173 (native-namestring *p* :as-file t) @result{} "/tmp"
 174 @end lisp