Utilities for working with system paths.

Edit on GitHub

---

This module treats paths purely as a data representation and does not provide functionality for interacting with the file system.

This module explicitly encodes whether a path is absolute or relative, and whether it refers to a file or a directory, as part of the Path type.

Paths in this module abide by a special POSIX-like representation/grammar rather than one defined by a specific operating system. The rules are as follows:

• Path separators are denoted by / for POSIX-like paths
• Absolute paths may be rooted either at the POSIX-like root / or at Windows-like drive roots like C:/
• Paths referencing files must not include trailing forward slashes, but paths referencing directories may
• The path segment . indicates the relative “current” directory of a path, and .. indicates the parent directory of a path

Added in 0.5.5

No other changes yet.

from "path" include Path

Type declarations included in the Path module.

enum AbsoluteRoot {
  Root,
  Drive(Char),
}

Represents an absolute path’s anchor point.

type Relative

Represents a relative path.

type Absolute

Represents an absolute path.

type File

Represents a path referencing a file.

type Directory

Represents a path referencing a directory.

type TypedPath<a, b>

Represents a path typed on (Absolute or Relative) and (File or Directory)

enum Path {
  AbsoluteFile(TypedPath<Absolute, File>),
  AbsoluteDir(TypedPath<Absolute, Directory>),
  RelativeFile(TypedPath<Relative, File>),
  RelativeDir(TypedPath<Relative, Directory>),
}

Represents a system path.

enum Platform {
  Windows,
  Posix,
}

Represents a platform-specific path encoding scheme.

enum PathOperationError {
  IncompatiblePathType,
}

Represents an error that can occur when finding a property of a path.

enum AppendError {
  AppendToFile,
  AppendAbsolute,
}

Represents an error that can occur when appending paths.

enum AncestryStatus {
  Descendant,
  Ancestor,
  Self,
  NoLineage,
}

Represents the status of an ancestry check between two paths.

enum IncompatibilityError {
  DifferentRoots,
  DifferentBases,
}

Represents an error that can occur when the types of paths are incompatible for an operation.

enum RelativizationError {
  Incompatible(IncompatibilityError),
  ImpossibleRelativization,
}

Represents possible errors for the relativeTo operation.

Functions and constants included in the Path module.

Added in 0.5.5

version	changes
0.6.0	Merged with `fromPlatformString`; modified signature to accept platform

fromString : (pathStr: String, ?platform: Platform) => Path

Parses a path string into a Path using the path separators appropriate to the given platform (/ for Posix and either / or \ for Windows). Paths will be parsed as file paths rather than directory paths if there is ambiguity.

Parameters:

Returns:

Examples:

fromString("file.txt") // a relative Path referencing the file ./file.txt

fromString(".") // a relative Path referencing the current directory

fromString("/bin/", Posix) // an absolute Path referencing the directory /bin/

fromString("C:\\file.txt", Windows) // a relative Path referencing the file C:\file.txt

Added in 0.5.5

version	changes
0.6.0	Merged with `toPlatformString`; modified signature to accept platform

toString : (path: Path, ?platform: Platform) => String

Converts the given Path into a string, using the canonical path separator appropriate to the given platform (/ for Posix and \ for Windows). A trailing slash is added to directory paths.

Parameters:

Returns:

Examples:

toString(fromString("/file.txt")) == "/file.txt"

toString(fromString("dir/"), Posix) == "./dir/"

toString(fromString("C:/file.txt"), Windows) == "C:\\file.txt"

Added in 0.5.5

No other changes yet.

isDirectory : (path: Path) => Bool

Determines whether the path is a directory path.

Parameters:

Returns:

Examples:

isDirectory(fromString("file.txt")) == false

isDirectory(fromString("/bin/")) == true

isAbsolute : (path: Path) => Bool

Determines whether the path is an absolute path.

Parameters:

Returns:

Examples:

isAbsolute(fromString("/Users/me")) == true

isAbsolute(fromString("./file.txt")) == false

Added in 0.5.5

No other changes yet.

append : (path: Path, toAppend: Path) => Result<Path, AppendError>

Creates a new path by appending a relative path segment to a directory path.

Parameters:

Returns:

Examples:

append(fromString("./dir/"), fromString("file.txt")) == Ok(fromString("./dir/file.txt"))

append(fromString("a.txt"), fromString("b.sh")) == Err(AppendToFile) // cannot append to file path

append(fromString("./dir/"), fromString("/dir2")) == Err(AppendAbsolute) // cannot append an absolute path

Added in 0.5.5

No other changes yet.

relativeTo : (source: Path, dest: Path) => Result<Path, RelativizationError>

Attempts to construct a new relative path which will lead to the destination path from the source path.

If the source and destination are incompatible in their bases, the result will be Err(IncompatibilityError).

If the route to the destination cannot be concretely determined from the source, the result will be Err(ImpossibleRelativization).

Parameters:

Returns:

Examples:

relativeTo(fromString("/usr"), fromString("/usr/bin")) == Ok(fromString("./bin"))

relativeTo(fromString("/home/me"), fromString("/home/me")) == Ok(fromString("."))

relativeTo(fromString("/file.txt"), fromString("/etc/")) == Ok(fromString("../etc/"))

relativeTo(fromString(".."), fromString("../../thing")) Ok(fromString("../thing"))

relativeTo(fromString("/usr/bin"), fromString("C:/Users")) == Err(Incompatible(DifferentRoots))

relativeTo(fromString("../here"), fromString("./there")) == Err(ImpossibleRelativization)

Added in 0.5.5

No other changes yet.

ancestry :
  (base: Path, path: Path) => Result<AncestryStatus, IncompatibilityError>

Determines the relative ancestry betwen two paths.

Parameters:

Returns:

Examples:

ancestry(fromString("/usr"), fromString("/usr/bin/bash")) == Ok(Ancestor)

ancestry(fromString("/Users/me"), fromString("/Users")) == Ok(Descendant)

ancestry(fromString("/usr"), fromString("/etc")) == Ok(Neither)

ancestry(fromString("C:/dir1"), fromString("/dir2")) == Err(DifferentRoots)

Added in 0.5.5

No other changes yet.

parent : (path: Path) => Path

Retrieves the path corresponding to the parent directory of the given path.

Parameters:

Returns:

Examples:

parent(fromString("./dir/inner")) == fromString("./dir/")

parent(fromString("/")) == fromString("/")

Added in 0.5.5

No other changes yet.

basename : (path: Path) => Option<String>

Retrieves the basename (named final segment) of a path.

Parameters:

Returns:

Examples:

basename(fromString("./dir/file.txt")) == Some("file.txt")

basename(fromString(".."))) == None

Added in 0.5.5

No other changes yet.

stem : (path: Path) => Result<String, PathOperationError>

Retrieves the basename of a file path without the extension.

Parameters:

Returns:

Examples:

stem(fromString("file.txt")) == Ok("file")

stem(fromString(".gitignore")) == Ok(".gitignore")

stem(fromString(".a.tar.gz")) == Ok(".a")

stem(fromString("/dir/")) == Err(IncompatiblePathType) // can only take stem of a file path

Added in 0.5.5

No other changes yet.

extension : (path: Path) => Result<String, PathOperationError>

Retrieves the extension on the basename of a file path.

Parameters:

Returns:

Examples:

extension(fromString("file.txt")) == Ok(".txt")

extension(fromString(".gitignore")) == Ok("")

extension(fromString(".a.tar.gz")) == Ok(".tar.gz")

extension(fromString("/dir/")) == Err(IncompatiblePathType) // can only take extension of a file path

Added in 0.5.5

No other changes yet.

root : (path: Path) => Result<AbsoluteRoot, PathOperationError>

Retrieves the root of the absolute path.

Parameters:

Returns:

Examples:

root(fromString("C:/Users/me/")) == Ok(Drive('C'))

root(fromString("/home/me/")) == Ok(Root)

root(fromString("./file.txt")) == Err(IncompatiblePathType)