Pathnames are immutable record-style objects of a disjoint type that represent the natural components of (string) filenames in a way that is intended to be system-independent. This design is mostly based on MIT Scheme, which is mostly based on Common Lisp. However, it is extended to accept additional components which are required to represent URIs and IRIs as well as filenames. In addition, given the pervasiveness of Windows and Posix filenames nowadays, specific provisions for them has been made.
The components of a pathname are scheme, host, port, username, password, device, directory, name, type, query, and fragment.
Scheme is the scheme part of a URI/IRI. It is a string.
Username is the username associated with a URI/IRI host. It is a string.
Password is the password associated with a username. It is a string.
Host is the host part of a URI/IRI. It is a string.
Port is the port part of a URI/IRI. It is an exact integer.
Device is a Windows-style device name without a trailing colon. It is a string, typically but not always a single character.
Directory is a directory path, which is represented as a list. The first element is always a symbol, which can be absolute or relative or unc, representing absolute, relative, and UNC directory paths respectively. The root directory is represented by the list (absolute). A null directory path is represented by the empty list. The other elements are strings.
Name is a simple file name without the associated file type or extension, if any. It is a string.
Type is the type or extension of the filename, without any leading period. It is a string.
Query is the query part of a URI/IRI. It is a string.
Fragment is the fragment part of an IRI/URI. It is a string.
All of these components can also be #f to indicate that the component is not present. In particular, a filename or URI ending in / or \ will result in the file and type components being #f.
(pathname-syntax [value])
This is a (SRFI 39) parameter whose value is either windows or posix, and is used to define whether parsing and construction of filenames uses Windows or Posix syntax. It may have other values, but the result is implementation defined. The initial value is also implementation-defined.
The procedures pathname? and pathname=? do what you expect. Note that two pathnames may be different according to pathname=? but still access the same resource. Host components are compared case-insensitively.
There are 11 accessors corresponding to the 11 components of a pathname, which take the form pathname-* where * is one of the components.
It is an error to mutate anything returned by any of these accessors.
(make-pathname components)
Constructs and returns a pathname. Components is an a-list mapping component names to values. Component names not defined in this specification are allowed, but the results are implementation-specific. Any component names not appearing in components are set to #f.
The following procedures accept a string and construct and return a pathname corresponding to that string.
(filename->pathname filename)
Constructs and returns a pathname. Filename is a string to be converted to a filename.
If (pathname-syntax) is posix, then filename is parsed using / as the component separator, the directory, name, and type components are potentially populated from it, and the device component is set to #f.
If (pathname-syntax) is windows, then filename is parsed using both \ and / as component separators, a leading // or \\ results in a directory component beginning with unc, and the device, directory, name, and type components are potentially populated from it.
Finally, the scheme component is set to "file", and the username, password, port, query, and fragment components are set to #f.
(uri->pathname uri)
Constructs and returns a pathname. Uri is a string to be converted to a pathname. It is parsed according to IRI rules, which are the same as URI rules except that sequences of %-hexdigit-hexdigit escapes that represent UTF-8 byte sequences are parsed into characters, provided the requisite characters are supported by the implementation.
The scheme, host, port, username, password, directory, name, type, query, and fragment components are potentially populated from uri. The device component is set to #f. If the query part of the IRI consists of name-value pairs separated by & or ; and with = between the name and the value, then the query component will be an a-list of strings; otherwise, it will just be a string.
The following procedures accept a pathname and construct and return a string corresponding to that pathname.
(pathname->filename pathname)
Constructs and returns a string from pathname.
If (pathname-syntax) is posix, then the result is constructed using / as the component separator from the directory, name, and type components of pathname.
If (pathname-syntax) is windows, then the result is constructed using \ as the component separator from the device, directory, name, and type components.
It is an error if the username, password, port, query, and fragment components are not #f. It is an error if the scheme component is not "file".
(pathname->uri pathname)
Constructs and returns a string according to RFC 3986 rules. In addition to required %-escaping, non-ASCII characters are converted to UTF-8 byte strings and %-escaped.
The scheme, host, port, username, password, directory, name, type, query, and fragment components are used to construct the URI. It is an error if the device component is not #f, or if the directory component is relative.
(pathname->iri pathname)
Constructs and returns a string according to RFC 3987 rules. No escaping of non-ASCII characters is done.
The scheme, host, port, username, password, directory, name, type, query, and fragment components are used to construct the URI. It is an error if the device component is not #f, or if the directory component is relative.
(merge-pathnames pathname1 pathname2)
Constructs and returns a new pathname with the same components as pathname1. However, if any component of pathname1 is #f, the corresponding component of pathname2 is used instead. The directory component is handled specially; if the pathname1 component begins with relative, the rest of it is appended to the pathname2 component.
(pathname-absolute-filename? pathname options)
Returns #t if pathname specifies an absolute or UNC filename. If (pathname-syntax) is windows, the device component must be specified.
(pathname-absolute-uri? pathname options)
Returns #t if pathname specifies an absolute URI (the fragment component must be #f).
(pathname-uri? pathname options)
Returns #t if pathname specifies a URI/IRI (that is, an absolute URI with a possible fragment).
(pathname-query->alist pathname)
Returns the query component of pathname as an a-list, where & and ; separate the entries in the alist, and = separates the car from the cdr.
(pathname-directory->string pathname)
Returns the directory component of pathname as a string. The result consists of the strings in the cdr of the directory component joined using the path separator, with the separator prepended if the car is absolute. If (pathname-syntax) is posix, the path separator is /; if (pathname-syntax) is windows, the path separator is \.