Path objects represent filesystem pathnames with semantics appropriate for different operating systems. This proposal is essentially a straight transliteration into Scheme of the pure portion of the Python pathlib library (also documented in PEP 428). As a result, it does not provide any operations on the file system; convert the path object to a string to pass it to open-input-file or any other procedure expecting a pathname.
Path objects are immutable objects of a disjoint type. They are divided into two subtypes, Posix paths and Windows paths. Most procedures in this proposal operate correctly on both subtypes.
Every path object has a drive, a root, and a possibly empty sequence of components, all of which are strings.
(make-posix-path string)
Parses string as a Posix pathname and returns a corresponding path object, setting the components to the slash-separated substrings of string. The drive and root are set according to the following examples:
(define absolute (make-posix-path "/etc/passwd)) (path-drive absolute) => "" (path-root absolute) => "/" (define relative (make-posix-path "foo")) (path-drive relative) => "" (path-root relative) => "" (define implementation-defined (make-posix-path "//foo/bar")) (path-drive implementation-defined) => "" (path-root implementation-defined) => "//"Except for the case of two initial slashes, consecutive slashes and backslashes are collapsed, and components consisting of a single period are removed. However, components consisting of two periods are not removed, as this would produce the wrong result in the presence of symbolic links.
(make-windows-path string)
Parses string as a Windows pathname and returns a corresponding path object, setting the components to the slash-separated or backslash-separated substrings of string. The drive and root are set according to the following examples:
(define absolute (make-windows-path "C:\\Windows)) (path-drive absolute) => "C:" (path-root absolute) => "/" (define unc (make-windows-path "\\\\host\\share\\file")) (path-drive unc) => "//host/share" (path-root unc) => "/" (define current-drive-relative (make-windows-path "\\Windows\\System32")) (path-drive current-drive-relative) => "" (path-root current-drive-relative) => "/" (define relative (make-windows-path "foo")) (path-drive relative) => "" (path-root relative) => "" (define relative-with-drive (make-windows-path "C:foo")) (path-drive relative-with-drive) => "C:" (path-root relative-with-drive) => ""The last format is meaningful because Windows maintains a separate current directory on each drive, so "C:foo" means the file named foo relative to the current directory on drive C:, regardless of whether that is the current drive.
Consecutive slashes or backslashes are collapsed, and components consisting of a single period are removed. However, components consisting of two periods are not removed, as this would produce the wrong result in the presence of symbolic links.
If any of the characters of string are illegal in Windows pathnames, namely < > " : | ? *, an error is signaled.
(make-path string)
Invokes make-posix-path on non-Windows systems and make-windows-path on Windows systems.
(path? obj)
Returns #t if obj is a path object and #f otherwise.
(posix-path? obj)
Returns #t if obj is a Posix path object and #f otherwise.
(windows-path? obj)
Returns #t if obj is a Windows path object and #f otherwise.
(path-absolute? path)
Returns #t if path represents an absolute path and #f otherwise. On Posix, a path is absolute if its root is non-empty. On Windows, both the drive and the root must be non-empty.
(path-reserved? path)
Returns #t if path is a Windows path containing a reserved component from this list, possibly with a suffix, and #f otherwise. Posix paths always return #f.
(path=? path1 path2)
Returns #t if path1 and path2 are the same path; that is, the drive, root, and components are equal. Posix paths are compared case-sensitively; Windows paths are compared case-insensitively. It is implementation-defined whether a Windows path is ever path=? to a Posix path; for example, a Cygwin implementation might choose to treat (make-posix-path "/cygdrive/c/Windows") and (make-windows-path "C:\\Windows") as path=?. In all other cases, path=? returns #f.
(path-drive path)
Returns the drive part of path.
(path-root path)
Returns the root part of path.
(path-anchor path)
Returns the drive and root parts of path concatenated.
(path-parts path)
Returns a list whose car is the anchor of path and whose cdr is a list of the components of path.
(path-parent path)
Returns a path representing the parent directory of path, or path itself if it is a root directory.
(path-filename path)
Returns the filename (last component) of path, or the empty string if there are no components.
(path-suffix path)
Returns the suffix (the rightmost part after a period) of the filename of path, or the empty string if there are no periods.
(path-suffixes path)
Returns a list of all the suffixes of the filename of path.
(path-stem path)
Returns the filename of path with all suffixes removed.
(path->string path)
Returns a string pathname based on the contents of path. Windows paths use backslash as the separator.
(path->slashed-string path)
Returns a string pathname based on the contents of path. Windows paths use slash as the separator.
(path->file-uri path)
Returns a file URI corresponding to path. If path is not absolute, an error is signaled.
(path-join path string-or-path'' ...)
If a single string-or-path argument is given, path-join returns a path object representing the results of appending the components of the string-or-path arguments to path in order. If the string-or-path argument is a string, path-join behaves as if it was converted to a path first by make-posix-path or make-windows-path, depending on the subtype of path.
If the string-or-path argument has a non-empty drive, the drive, root, and components of path are discarded. If the drive is empty, but the root is non-empty, the root and components of path are discarded.
If two string-or-path arguments are given, path-join returns what (path-join (path-join path string-or-path1) string-or-path2) returns, and so on for any additional arguments.
(path-match path string)
Returns #t if path matches the glob pattern in string. Glob patterns may contain the wildcards *, ?, and [...] where ... represents a set of characters to match. If string is relative, the path can be either relative or absolute, and matching is done from the right. If string is absolute, the path must be absolute, and the whole path must match. Posix paths are compared case-sensitively; Windows paths are compared case-insensitively.
(path-relative-to path1 path2)
Return a version of path1 that is relative to path2. If it is not possible to do so without introducing double-period components, an error is signaled.
(path-with-name path name)
Returns a path object based on path with the name (including any suffixes) replaced by name. If the path does not contain a name, an error is signaled.
(path-with-suffix path suffix)
Returns a path object based on path with the final suffix of the name replaced by suffix. If the name does not contain a suffix, suffix is appended after a separating period. If the path does not contain a name, an error is signaled.