The Standard ML Basis Library

The OS.Path structure

The OS.Path structure provides support for manipulating the syntax of file system paths independent of the underlying file system. It is purposely designed not to rely on any file system operations: none of the functions accesses the actual file system. There are two good reasons for this. Many systems support multiple file systems that may have different semantics, and applications may need to manipulate paths that do not exist in the underlying file system.

Before discussing the model and the semantics of the individual operations, we need to define some terms:

• An arc denotes a directory or file relative to the directory in which it is recorded. In a path string, arcs are separated by an arc separator character. This character is #"/" in Unix and #"\\" in DOS. For example, in Unix, the path "abc/def" contains two arcs: "abc" and "def". There are two special arcs: parentArc and currentArc. Under Unix and DOS, the parentArc and currentArc correspond to the strings ".." and ".", respectively. An empty arc corresponds to an empty string.
• A path corresponds to a list of arcs, with an optional root, that denotes the path of directories leading to a file or directory in the file system hierarchy.
• An absolute path has a root. Unix examples include "/" and "/a/b"; DOS examples include "\", "\a\b" and "A:\a\b".
• A relative path is one without a root. Unix examples include ".." and "a/b"; DOS examples include "..", "a\b" and "A:a\b".
• A canonical path contains no occurrences of the empty arc, no occurrences of the current arc unless the current arc is the only arc in the path, and contains parent arcs only at the beginning and only if the path is relative. Some examples of canonical paths, using Unix syntax, are

  "."   "/."   "/"   "a"   "a/b/c"
  ".." "../a" "../../a/b/c" "/a/b/c"
  

• A path has an associated volume. Under Unix, there is only one volume, whose name is "". Under DOS, example volume names are "", "A:" and "C:".

In addition to operations for canonicalizing paths and computing relative paths, the Path structure supports path manipulations relative to three different views of a path:

1. A navigation oriented view, where a path is broken down into its root and a non-empty list of arcs. A path is either absolute or relative. The root of a path specifies the volume to which the path is taken to be relative. For Unix, there is only the "" volume.
2. A directory/file view, where a path is broken down into a directory specifier and a file name.
3. A base/extension view, where a path is broken down into a base filename, and an extension. We make the assumption that the extension separator character is #".". This works for Windows, OS/2, and Unix; the Macintosh does not really have a notion of extension.

Our main design principle is that the functions should behave in a natural fashion when applied to canonical paths. All functions, except concat, preserve canonical paths, i.e., if all arguments are canonical, then so is the result.

Note that although the model of path manipulation provided by the Path structure is operating system independent, the analysis of strings is not. In particular, any given implementation of the Path structure has an implicit notion of what the arc separator character is. Thus, on a DOS system, Path will treat the string "\\d\\e" as representing an absolute path with two arcs, whereas on a Unix system, it will correspond to a relative path with one arc.

Synopsis

signature OS_PATH
structure Path : OS_PATH


Interface

exception Path
val parentArc : string
val currentArc : string
val validVolume : {isAbs : bool, vol : string} -> bool
val fromString : string -> {isAbs : bool, vol : string, arcs : string list}
val toString : {isAbs : bool, vol : string, arcs : string list} -> string
val getVolume : string -> string
val getParent : string -> string
val splitDirFile : string -> {dir : string, file : string}
val joinDirFile : {dir : string, file : string} -> string
val dir : string -> string
val file : string -> string
val splitBaseExt : string -> {base : string, ext : string option}
val joinBaseExt : {base : string, ext : string option} -> string
val base : string -> string
val ext : string -> string option
val mkCanonical : string -> string
val isCanonical : string -> bool
val mkAbsolute : (string * string) -> string
val mkRelative : (string * string) -> string
val isAbsolute : string -> bool
val isRelative : string -> bool
val isRoot : string -> bool
val concat : (string * string) -> string


Description

exception Path

parentArc

denotes the parent directory (e.g., ".." on DOS and UNIX).

currentArc

denotes the current directory (e.g., "." on DOS and UNIX).

validVolume {isAbs, vol}

returns true if vol is a valid volume name for an absolute or relative path, respectively as isAbs is true or false. Under Unix, the only valid volume name is "". Under DOS, the valid volume names have the form "a:", "A:", "b:", "B:", etc. and, if isAbs = false, also "". Under MacOS, isAbs can be true if and only if vol is "".

fromString s

returns the decomposition {isAbs, vol, arcs} of the path specified by s. vol is the volume name and arcs is the list of (possibly empty) arcs of the path. isAbs is true if the path is absolute. Under Unix, the volume name is always the empty string; under DOS, in addition it can have the form "A:", "C:", etc.

Here are some examples for UNIX paths:

          fromString ""           = {isAbs=false, vol="", arcs=[]}
          fromString "/"          = {isAbs=true,  vol="", arcs=[""]}
          fromString "//"         = {isAbs=true,  vol="", arcs=["", ""]}
          fromString "a"          = {isAbs=false, vol="", arcs=["a"]}
          fromString "/a"         = {isAbs=true,  vol="", arcs=["a"]}
          fromString "//a"        = {isAbs=true,  vol="", arcs=["","a"]}
          fromString "a/"         = {isAbs=false, vol="", arcs=["a", ""]}
          fromString "a//"        = {isAbs=false, vol="", arcs=["a", "", ""]}
          fromString "a/b"        = {isAbs=false, vol="", arcs=["a", "b"]}
          

toString {isAbs, vol, arcs}

makes a string out of a path represented as a list of arcs. isAbs specifies whether or not the path is absolute, and vol provides a corresponding volume. It returns "" when applied to {isAbs=false, vol="", arcs=[]}. The exception Path is raised if validVolume{isAbs, vol} is false, or if isAbs is false and arcs has an initial empty arc.

toString o fromString is the identity. fromString o toString is also the identity, provided no exception is raised and none of the strings in arcs contains an embedded arc separator character. In addition, isRelative(toString {isAbs=false, vol, arcs}) evaluates to true when defined.

getVolume s

returns the volume portion of the path.

getParent s

returns a string denoting the parent directory of s. It holds that getParent s = s if and only if s is a root. If the last arc is empty or the parent arc, then getParent appends a parent arc. If the last arc is the current arc, then it is replaced with the parent arc. Note that if s is canonical, then the result of getParent will also be canonical.

Here are some examples for UNIX paths:

            getParent "/"           = "/"
            getParent "a"           = "."
            getParent "a/"          = "a/.."
            getParent "a///"        = "a///.."
            getParent "a/b"         = "a"
            getParent "a/b/"        = "a/b/.."
            getParent ".."          = "../.."
            getParent "."           = ".."
            getParent ""            = ".."
          

splitDirFile s

splits the string path s into its directory and file parts, where the file part is defined to be the last arc. The file will be "", if the last arc is "".

Here are some examples for UNIX paths:

          splitDirFile ""         = {dir = "", file = ""}
          splitDirFile "."        = {dir = "", file = "."}
          splitDirFile "b"        = {dir = "", file = "b"}
          splitDirFile "b/"       = {dir = "b", file = ""}
          splitDirFile "a/b"      = {dir = "a", file = "b"}
          splitDirFile "/a"       = {dir = "/", file = "a"}
          

joinDirFile {dir, file}

creates a whole path out of a directory and a file by extending the path dir with the arc file.

dir s

file s

return the directory and file parts of a path, respectively. They are equivalent to #dir o splitDirFile and #file o splitDirFile, respectively, although they are probably more efficient.

splitBaseExt s

splits the path s into its base and extension parts. The extension is a non-empty sequence of characters following the right-most, non-initial, occurrence of "." in the last arc; NONE is returned if the extension is not defined. The base part is everything to the left of the extension except the final ".". Note that if there is no extension, a terminating "." is included with the base part.

Here are some examples for UNIX paths:

          splitBaseExt ""           = {base = "", ext = NONE}
          splitBaseExt ".login"     = {base = ".login", ext = NONE}
          splitBaseExt "/.login"    = {base = "/.login", ext = NONE}
          splitBaseExt "a"          = {base = "a", ext = NONE}
          splitBaseExt "a."         = {base = "a.", ext = NONE}
          splitBaseExt "a.b"        = {base = "a", ext = SOME "b"}
          splitBaseExt "a.b.c"      = {base = "a.b", ext = SOME "c"}
          splitBaseExt ".news/comp" = {base = ".news/comp", ext = NONE} 
          

joinBaseExt {base, ext}

returns an arc composed of the base name and the extension (if different from NONE). It is a left inverse of splitBaseExt, i.e., joinBaseExt o splitBaseExt is the identity. The opposite does not hold, since the extension may be empty, or may contain extension separators. Note that although splitBaseExt will never return the extension SOME "", joinBaseExt treats this as equivalent to NONE.

base s

ext s

return the base and extension parts of a path, respectively. They are equivalent to #base o splitBaseExt and #ext o splitBaseExt, respectively, although they are probably more efficient.

mkCanonical s

returns the canonical path equivalent to s. Redundant occurrences of the parent arc, the current arc, and the empty arc are removed. The canonical path will never be the empty string; the empty path is converted to the current directory path ("." under Unix and DOS).

Note that the syntactic canonicalization provided by mkCanonical may not preserve file system meaning in the presence of symbolic links (cf. concat).

isCanonical s

returns true if s is a canonical path. It is equivalent to (s = mkCanonical s).

mkAbsolute (p, abs)

returns an absolute path that is equivalent to the path p relative to the absolute path abs. If p is already absolute, it is returned unchanged. Otherwise, the function returns the canonical concatenation of abs with p, i.e., mkCanonical (concat (abs, p)) Thus, if p and abs are canonical, the result will be canonical. If abs is not absolute, or if the two paths refer to different volumes, then the Path exception is raised.

mkRelative (p, abs)

returns a relative path p' that, when taken relative to the canonical form of the absolute path abs, is equivalent to the path p. If p is relative, it is returned unchanged. If p is absolute, the procedure for computing the relative path is to first compute the canonical form abs' of abs. If p and abs' are equal, then the current arc is the result. Otherwise, the common prefix is stripped from p and abs' giving p'' and abs'', and p'' is appended to a path consisting of one parent arc for each arc in abs''. Note that if both paths are canonical, then the result will be canonical.

If abs is not absolute, or if p and abs are both absolute but have different roots, the Path exception is raised.

Here are some examples for UNIX paths:

          mkRelative ("a/b", "/c/d")              = "a/b"
          mkRelative ("/", "/a/b/c")              = "../../.."
          mkRelative ("/a/b/", "/a/c")            = "../b/"
          mkRelative ("/a/b",  "/a/c")            = "../b"
          mkRelative ("/a/b/", "/a/c/")           = "../b/"
          mkRelative ("/a/b",  "/a/c/")           = "../b"
          mkRelative ("/", "/")                   = "."
          mkRelative ("/", "/.")                  = "."
          mkRelative ("/", "/..")                 = "."
          mkRelative ("/a/b/../c", "/a/d")        = "../b/../c"
          mkRelative ("/a/b", "/c/d")             = "../../a/b"
          mkRelative ("/c/a/b", "/c/d")           = "../a/b"
          mkRelative ("/c/d/a/b", "/c/d")         = "a/b"
          

isAbsolute s

isRelative s

return true if s is, respectively, absolute or relative.

isRoot s

returns true if s is a canonical specification of a root directory.

concat (s, t)

returns the path consisting of s followed by t. It raises the exception Path if t is not a relative path or if s and t refer to different volumes.

Note that concat does not preserve canonical paths. For example, concat("a/b", "../c") returns "a/b/../c". The parent arc is not removed because "a/b/../c" and "a/c" may not be equivalent in the presence of symbolic links.

See Also

OS, OS.FileSys, OS.Process, OS.IO, Posix.FileSys

Last Modified June 14, 1996
Copyright © 1996 AT&T