![[index]](../icons/index.gif)
Next: Files
Up: Filesystem Utilities
Previous: Filesystem Utilities
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 and BeOS, 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 exception is raised.
The pathname utilites are:
- (build-path base-path sub-path
)
creates an pathname given a base pathname and any
number of sub-pathname extensions. If base-path is an
absolute pathname, the result is an absolute pathname;
if base is a relative pathname, the result is a relative
pathname. Each sub-path 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-path is a drive specification (with or
without a trailing slash) the first sub-path can be an absolute
(driveless) path. The last sub-path can be a filename.
Each sub-path and base-path can optionally end in a
directory separator. If the last sub-path ends in a separator,
it is included in the resulting pathname.
Under MacOS, if a sub-path argument does not begin with a colon,
one is added automatically. This means that sub-path arguments
are never interpreted as absolute paths under MacOS. For other
platforms, if an absolute path is provided for any sub-path,
then the exn:i/o:filesystem exception is raised. On all platforms, if
base-base or sub-path is an illegal path string (e.g., it
contains a null character), the exn:i/o:filesystem 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-path]) 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-path. If base-path is
omitted, path is resolved with respect to the current
directory. If base-path is provided and it is not a complete
path, the exn:i/o:filesystem 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 or BeOS, 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
owningpath) 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, BeOS, 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 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 and BeOS, 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-sub-path related-sub-path)
finds an absolute executable pathname that is synonymous with the
executable pathname program-sub-path such that the file or
directory related-sub-path (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-sub-path is an absolute path,
find-executable-path determines whether related-sub-path
exists in the directory of program-sub-path. If so,
program is returned. Otherwise, if program-sub-path is a
link to another path, the destination directory of the link is
checked for related-sub-path. Further links are inspected until
related-sub-path is found or the end of the chain of links is
reached.
If program-sub-path 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-sub-path using the search
algorithm described above. If the environment variable is not
defined, program-sub-path 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-sub-path argument is used because, under Unix and
BeOS, program-sub-path may involve to a sequence of soft links;
in this case, related-sub-path determines which link in the
chain is relevant.
- (find-system-path kind-symbol) returns a
machine-specific path for a standard type of path specified by
kind-symbol, 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 Unix, Windows, and BeOS, this
is the user's home directory.
- 'temp-dir -- the standard directory for storing
temporary files. Under Unix, Windows, and BeOS, 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 and BeOS: .mzschemerc
- Windows and MacOS: mzschemerc.ss
- (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 and BeOS, 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.)
![[index]](../icons/index.gif)
Next: Files
Up: Filesystem Utilities
Previous: Filesystem Utilities
PLT