14.1 Paths🔗ℹ

A path value represents a filesystem path for the host operating system. A cross-platform path is a generalization of a path, and most path operations also accept cross-platform paths, but they produce specifically paths when given paths. See Filesystem Paths in Rhombus Language Model for more information about paths, path syntax, and path representations.

Paths are comparable, which means that generic operations like < and > work on paths.

The Path.Absolute annotation only matches Paths that begin with a root directory or drive. The Path.Relative annotation only matches Paths that are relative to some base directory. The Path.DriveRelative annotation only matches Windows Paths that are relative to a drive.

The Path.Directory annotation only matches Paths that syntactically refer to a directory; see filesystem.directory_exists for checking whether a path refers to a directory on the filesystem.

The Path.Element annotation matches a path that represents a single path element—that is, a path for which Path.split returns a list containing one element.

A Path.Dot symbols refer to an abstract directory-navigation path element. For both path conventions currently supported, the symbol #'same as a Path.Dot is equivalent to ".", and the symbol #'same as a Path.Dot is equivalent to "..".

A Path.like(expr) annotation is satisfied by a cross-platform path with the same convention as the result of expr, where the result of expr must satisfy PathString || CrossPath || Path.Dot, and a PathString or Path.Dot implies the current platform’s convention.

> def p = Path("/home/rhombus/shape.txt")

> p

Path("/home/rhombus/shape.txt")

> Path(p)

Path("/home/rhombus/shape.txt")

> p.string()

"/home/rhombus/shape.txt"

> def Path(bstr) = Path("/home/rhombus/shape.txt")

> bstr

#"/home/rhombus/shape.txt"

> def p = Path("/home/rhombus/shape.txt")

> Path.bytes(p)

#"/home/rhombus/shape.txt"

> p.bytes()

#"/home/rhombus/shape.txt"

> def p = Path(#"/home/rhombus/shape.txt")

> Path.string(p)

"/home/rhombus/shape.txt"

> p.string()

"/home/rhombus/shape.txt"

> def p = CrossPath(#"/home/rhombus/shape.txt", #'unix)

> p.convention()

#'unix

The path and each part must be either a relative path, the symbol #'up (indicating the relative parent directory), or the symbol #'same (indicating the relative current directory). For Windows paths, if path is a drive specification (with or without a trailing slash) the first part can be a drive-relative path. For all platforms, the last part can be a filename.

The path and part arguments can be paths or cross-platform paths. The platform for the resulting path is inferred from the path and part arguments, where string arguments imply a path for the current platform. If different arguments are for different platforms, the Exn.Fail.Annot exception is thrown. If no argument implies a platform (i.e., all are #'up or #'same), the generated path is for the current platform.

Each part and path can optionally end in a directory separator. If the last part ends in a separator, it is included in the resulting path.

The Path.add function builds a path without checking the validity of the path or accessing the filesystem.

> def p = Path("/home/rhombus")

> Path.add(p, "shape.txt")

Path("/home/rhombus/shape.txt")

> p.add("shape.txt")

Path("/home/rhombus/shape.txt")

> p +/ "shape.txt"

Path("/home/rhombus/shape.txt")

The Path.split function computes its result in time proportional to the length of path.

> def p = Path("/home/rhombus/shape.txt")

> Path.split(p)

[Path("/"), Path("home"), Path("rhombus"), Path("shape.txt")]

> p.split()

[Path("/"), Path("home"), Path("rhombus"), Path("shape.txt")]

The Path.directory_only function returns path without its final path element in the case that path is not syntactically a directory; if path has only a single, non-directory path element, #f is returned. If path is syntactically a directory, then path is returned unchanged (but as a path, if it was a string).

The Path.to_directory_path function converts path to one that syntactically represents a directory path if it does not already, typically by adding a path separator to the end.

> def p = Path("/home/rhombus/shape.txt")

> Path.name(p)

Path("shape.txt")

> Path.parent(p)

Path("/home/rhombus/")

> Path.directory_only(p)

Path("/home/rhombus/")

> Path.directory_only(Path.parent(p))

Path("/home/rhombus/")

> Path.to_directory_path(p)

Path("/home/rhombus/shape.txt/")

> def p = CrossPath(#"shape.txt", #'unix)

> p.to_absolute_path(     ~relative_to: CrossPath(#"/home/rhombus", #'unix)   ).bytes()

#"/home/rhombus/shape.txt"

The Path.replace_suffix function removes the suffix from a path, if any, and then adds suffix, which can be "" or #"" to just remove a suffix from path or otherwise normally starts with Char"." or Byte#".".

The Path.add_suffix function first changes a Byte#"." in the path that starts its current prefix with sep, and then it adds the given suffix.

> def p = Path("/home/rhombus/shape.txt")

> p.suffix()

#".txt"

> p.replace_suffix(".rhm")

Path("/home/rhombus/shape.rhm")

> p.add_suffix(".rhm")

Path("/home/rhombus/shape_txt.rhm")

The Path.simplify function performs the same cleansing, and then removes #'same path elements and syntactically resolves #'up elements where preceding elements can be removed. This simplification is purely syntactic and does not consult the filesystem; see also filesystem.simplify_path.

The Path.normal_case function has no effect on platforms that use Unix path conventions, and it case-folds a path’s string form on Windows.

> Path.cleanse("a/..//b")

Path("a/../b")

> Path.simplify("a/..//b")

Path("b")

If more_than_root is #true, then if path and rel_to_path has only a root path element in common, then path is returned unchanged (except converted to a Path object if it is a string).

If more_than_same is #true, then if path and rel_to_path are syntactically equivalent, then path is returned unchanged.

If normal is #true, then on Windows, path elements are normalized for comparison. Otherwise, path elements are considered equivalent only when they have the same case.

If path and rel_to_path use different path conventions, the Exn.Fail.Annot exception is thrown.

> def p = Path("/home/rhombus/shape.txt")

> p.as_relative_to("/home")

Path("rhombus/shape.txt")

> p.as_relative_to("/home/racket")

Path("../rhombus/shape.txt")