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. (Procedures that build pathnames or merely check the form of a pathname do not perform this expansion.) Under Unix, a user directory specification using ``~'' is expanded. Under MacOS, file and folder aliases are resolved to real pathnames. Under Windows, multiple slashes are converted to single slashes (except at the beginning of a shared folder name), and a slash is inserted after the colon in a drive specification (if it is missing). In a Windows pathname, slash and backslash are always equivalent (and can be mixed together in the same pathname).

A pathname string cannot contain a null character (#\nul). When a string containing a null character is provided as a pathname to any procedure except absolute-path?, relative-path?, complete-path?, or normal-case-path, the exn:i/o:filesystem:path exception is raised.

The pathname utilites are:

• (build-path base subpath ) 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). Under Windows, if base is a drive specification (with or without a trailing slash) the first subpath can be an absolute (driveless) path. 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:path exception is raised. On all platforms, if base or subpath is an illegal path string (e.g., it contains a null character), the exn:i/o:filesystem:path exception is raised.

  The build-path procedure builds a pathname without checking the validity of the path or accessing the filesystem.

  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-path p2 p1) 
    ; Unix: raises exn:i/o:filesystem:path because p1 is absolute 
    ; MacOS: => ":::docs:MzScheme:My Disk:Joe's Files:src:scheme" 
    (build-path p1 p2) 
    ; Unix: => "/home/joeuser/src/scheme/../../docs/MzScheme" 
    ; MacOS: => "My Disk:Joe's Files:src:scheme:::docs:MzScheme" 
  

• (absolute-path? path) returns #t if path is an absolute pathname, #f otherwise. If path is not a legal pathname string (e.g., it contains a null character), #f is returned. This procedure does not access the filesystem.
• (relative-path? path) returns #t if path is a relative pathname, #f otherwise. If path is not a legal pathname string (e.g., it contains a null character), #f is returned. This procedure does not access the filesystem.
• (complete-path? path) returns #t if path is a completely determined pathname (not relative to a directory or drive), #f otherwise. Note that under Windows, an absolute path can omit the drive specification, in which case the path is niether relative nor complete. If path is not a legal pathname string (e.g., it contains a null character), #f is returned. This procedure does not access the filesystem.
• (path->complete-path path [base]) returns path as a complete path. If path is already a complete path, it is returned as the result. Otherwise, path is resolved with respect to the complete path base. If base is omitted, path is resolved with respect to the current directory. If base is provided and it is not a complete path, the exn:i/o:filesystem:path exception is raised. This procedure does not access the filesystem.
• (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 (after expansion).
• (expand-path path) returns the expanded version of path (as described at the beginning of this section). The filesystem might be accessed, but the source or expanded pathname might be a non-existant path.
• (simplify-path path) eliminates up-directory (``..'' in Unix and Windows) and same-directory (``.'') indicators in path. If no indicators are in path, then path is returned. Otherwise, a complete path is returned; if path is relative, it is resolved with respect to the current directory. Up-directory indicators are dropped when they refer to the parent of a root directory. The filesystem might be accessed, but the source or expanded pathname might be a non-existant path. If path cannot be simplified due to a cycle of links, the exn:i/o:filesystem:link exception is raised (but a successfully simplified path may still involve a cycle of links if the cycle did not inhibit the simplification).
• (normal-case-path string) returns string with normalized case letters. Under Unix, this procedure always returns the input path. Under Windows and MacOS, the resulting string uses only lowercase letters. Under Windows, all forward slashes (``/'') are converted to backward slashes (``\''). This procedure does not access the filesystem or guarantee that the output string is a legal pathname (i.e., string and the result may contain a null character).
• (split-path path) deconstructs path into a smaller pathname and an immediate directory or file name. Three values are returned (see Chapter 2):
  • 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), #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. This procedure does not access the filesystem.
• (find-executable-path program related) finds an absolute executable pathname that is synonymous with the executable pathname program (a path string) such that the file or directory related (a relative path string) exists in the same directory. If such a path cannot be found, #f is returned.

  This procedure is used by MzScheme (as a stand-alone executable) to find the standard library collection directory (see Chapter 15); in this case, program is the name used to start MzScheme and related is "collects".

  If program is an absolute path, find-executable-path determines whether related exists in the directory of program. If so, program is returned. Otherwise, if program is a link to another path, the destination directory of the link is checked for related. Further links are inspected until related is found or the end of the chain of links is reached.

  If program is a relative path, find-executable-path gets the value of the PATH environment variable; if this environment variable is defined, find-executable-path tries each colon-separated path in PATH as a prefix for program using the search algorithm described above. If the environment variable is not defined, program is prefixed with the current directory and used in the search algorithm above. (Under Windows, the current directory is always implicitly the first item in PATH, so find-executable-path checks the current directory first under Windows.)

  The related argument is used because, under Unix, program may involve to a sequence of soft links; in this case, related determines which link in the chain is relevant.

• (find-system-path kind-sym) returns a machine-specific path for a standard type of path specified by kind-sym, which must be one of the following:
  • 'home-dir -- the current user's home directory. Under MacOS, this is the preferences directory. Under Windows, this is the directory specified by the HOMEDRIVE and HOMEPATH environment variables; if those environment variables are not defined or the directory does not exist, the directory containing the MzScheme executable is returned, instead.
  • 'pref-dir -- the standard directory for storing the current user's preferences. Under Windows and Unix, this is the user's home directory.
  • 'temp-dir -- the standard directory for storing temporary files. Under Unix and Windows, this is the directory specified by the TMPDIR environment variable, if it is defined.
  • 'init-dir -- the directory containing the initialization file used by stand-alone MzScheme application. It is the same as the current user's home directory.
  • 'init-file -- the file loaded at start-up by the stand-alone MzScheme application. The directory part of the path is the same path as returned for 'init-dir. The file name is platform-specific:
    • Unix: .mzschemerc
    • Windows: mzscheme.rc
    • MacOS: mzscheme.rc
• (path-list-string->path-list string default-path-list) parses a string containing a list of paths, and returns a list of path strings. Under Unix, paths in a path list are separated by a colon (``:''); under Windows and MacOS, paths are separated by a semi-colon (``;''). Whenever the path list contains an empty path, the list default-path-list is spliced into the returned list of paths. Parts of string that do not form a valid path are not included in the returned list. (The content of the list default-path-list is not inspected.)