Pathnames

 

  File and directory paths are specified as strings. Since the syntax for pathnames can vary across platforms (e.g., under Unix, directories are separated by ``/'' while the Mac uses ``:''), MzScheme provides tools for portably constructing and deconstructing pathnames.

  Most MzScheme primitives that take pathnames perform an expansion on the pathname before using it. Under Unix, a user directory specification using `` '' is expanded. Under MacOS, file and folder aliases are resolved to real pathnames. Procedures that build paths or merely check the form of a pathname do not perform this expansion.

• (build-path base subpaths ) creates an pathname given a base pathname and any number of sub-pathname extensions. If base is an absolute pathname, the result is an absolute pathname; if base is a relative pathname, the result is a relative pathname. Each subpath must be either a relative pathname, a directory name, the symbol 'up (indicating the relative parent directory), or the symbol 'same (indicating the relative current directory). The last subpath can be a filename.

  Each subpath and base can optionally end in a directory separator. If the last subpath ends in a separator, it is included in the resulting pathname.

  Under MacOS, if a subpath argument does not begin with a colon, one is added automatically. This means that subpath arguments are never interpreted as absolute paths under MacOS. For other platforms, if an absolute path is provided for any subpath, then the  exn:i/o:filesystem:filename exception is raised.

  The following examples assume that the current directory is ``/home/joeuser'' for Unix examples and ``My Disk:Joe's Files'' for MacOS examples.

   
     (define p1 (build-path (current-directory) "src" "scheme")) 
      ; Unix: p1 => "/home/joeuser/src/scheme" 
      ; MacOS: p1 => "My Disk:Joe's Files:src:scheme" 
     (define p2 (build-path 'up 'up "docs" "MzScheme")) 
      ; Unix: p2 => "../../docs/MzScheme" 
      ; MacOS: p2 => ":::docs:MzScheme" 
     (build-pathname p2 p1) 
      ; Unix: raises exn:i/o:filesystem:filename because p1 is absolute 
      ; MacOS: => ":::docs:MzScheme:My Disk:Joe's Files:src:scheme" 
     (build-pathname p1 p2) 
      ; Unix: => "/home/joeuser/src/scheme/../../docs/MzScheme" 
      ; MacOS: => "My Disk:Joe's Files:src:scheme:::docs:MzScheme" 
  

•   (relative-path? path) returns #t if path is a relative pathname or #f otherwise.
•   (resolve-path path) expands path and returns a pathname that references the same file or directory as path. Under Unix, if path is a soft link to another pathname, then the referenced pathname is returned (this may be a relative pathname with respect to the directory owning path) otherwise path is returned.
•   (expand-path path) returns the expanded version of path. Under Windows, if an absolute pathname is provided without a drive specifier, the result pathname contains a drive specifier.
•   (normal-case-path path) returns path with normalized case letters. Under Unix, this procedure always returns the input path. Under Windows and MacOS, the resulting pathname uses only lowercase letters.
•   (split-path path) deconstructs path into a smaller pathname and an immediate directory or file name. Three values are returned (see section 2.26):
  • base is either
    • a string pathname,
    • 'relative if path is an immediate relative directory or filename, or
    • #f if path is a root directory.
  • name is either
    • a string directory name,
    • a string file name,
    • 'up if the last part of path specifies the parent directory of the preceding path (e.g., ``..'' under Unix), or
    • 'same if the last part of path specifies the same directory as the preceding path (e.g., ``.'' under Unix).
  • must-be-dir? is #t if path explicitly specifies a directory (e.g. with a trailing separator) or #f otherwise. Note that must-be-dir? does not specify whether name is actually a directory or not, but whether path syntactically specified a directory.
  If base is #f, then name cannot be 'up or 'same. All strings returned for base and name are newly allocated.
•   (find-executable-path progpath related) returns an absolute path for the executable progpath such that the file or directory related exists with respect to the executable's directory. This procedure is used to help MzScheme (as a stand-alone executable) find the MzLib library (see chapter 4). The related argument is used because, under Unix, progpath may depend on the PATH environment variable or involve to a sequence of soft links; in this case, related determines which directory is relevant.