Path

Utilities for working with system paths.

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

Types

Type declarations included in the Path module.

Path.AbsoluteRoot

enum AbsoluteRoot {
  Root,
  Drive(Char),
}

Represents an absolute path’s anchor point.

Path.Relative

type Relative

Represents a relative path.

Path.Absolute

type Absolute

Represents an absolute path.

Path.File

type File

Represents a path referencing a file.

Path.Directory

type Directory

Represents a path referencing a directory.

Path.TypedPath

type TypedPath<a, b>

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

Path.Path

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

Represents a system path.

Path.Platform

enum Platform {
  Windows,
  Posix,
}

Represents a platform-specific path encoding scheme.

Path.PathOperationError

1
2
3

enum PathOperationError {
  IncompatiblePathType,
}

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

Path.AppendError

enum AppendError {
  AppendToFile,
  AppendAbsolute,
}

Represents an error that can occur when appending paths.

Path.AncestryStatus

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

Represents the status of an ancestry check between two paths.

Path.IncompatibilityError

enum IncompatibilityError {
  DifferentRoots,
  DifferentBases,
}

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

Path.RelativizationError

enum RelativizationError {
  Incompatible(IncompatibilityError),
  ImpossibleRelativization,
}

Represents possible errors for the relativeTo operation.

Values

Functions and constants included in the Path module.

Path.fromString

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:

param	type	description
`pathStr`	`String`	The string to parse as a path
`?platform`	`Platform`	The platform whose path separators should be used for parsing

Returns:

type	description
`Path`	The path wrapped with details encoded within the type

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

Path.toString

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:

param	type	description
`path`	`Path`	The path to convert to a string
`?platform`	`Platform`	The `Platform` to use to represent the path as a string

Returns:

type	description
`String`	A string representing the given path

Examples:

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

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

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

Path.isDirectory

Added in 0.5.5

No other changes yet.

isDirectory : (path: Path) => Bool

Determines whether the path is a directory path.

Parameters:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Bool`	`true` if the path is a directory path or `false` otherwise

Examples:

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

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

Path.isAbsolute

isAbsolute : (path: Path) => Bool

Determines whether the path is an absolute path.

Parameters:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Bool`	`true` if the path is absolute or `false` otherwise

Examples:

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

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

Path.append

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:

param	type	description
`path`	`Path`	The base path
`toAppend`	`Path`	The relative path to append

Returns:

type	description
`Result<Path, AppendError>`	`Ok(path)` combining the base and appended paths or `Err(err)` if the paths are incompatible

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

Path.relativeTo

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:

param	type	description
`source`	`Path`	The source path
`dest`	`Path`	The destination path to resolve

Returns:

type	description
`Result<Path, RelativizationError>`	`Ok(path)` containing the relative path if successfully resolved or `Err(err)` otherwise

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)

Path.ancestry

Added in 0.5.5

No other changes yet.

1
2

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

Determines the relative ancestry betwen two paths.

Parameters:

param	type	description
`base`	`Path`	The first path to consider
`path`	`Path`	The second path to consider

Returns:

type	description
`Result<AncestryStatus, IncompatibilityError>`	`Ok(ancestryStatus)` with the relative ancestry between the paths if they are compatible or `Err(err)` if they are incompatible

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)

Path.parent

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:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Path`	A path corresponding to the parent directory of the given path

Examples:

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

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

Path.basename

Added in 0.5.5

No other changes yet.

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

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

Parameters:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Option<String>`	`Some(path)` containing the basename of the path or `None` if the path does not have one

Examples:

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

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

Path.stem

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:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Result<String, PathOperationError>`	`Ok(path)` containing the stem of the file path or `Err(err)` if the path is a directory path

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

Path.extension

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:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Result<String, PathOperationError>`	`Ok(path)` containing the extension of the file path or `Err(err)` if the path is a directory path

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

Path.root

Added in 0.5.5

No other changes yet.

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

Retrieves the root of the absolute path.

Parameters:

param	type	description
`path`	`Path`	The path to inspect

Returns:

type	description
`Result<AbsoluteRoot, PathOperationError>`	`Ok(root)` containing the root of the path or `Err(err)` if the path is a relative path

Examples:

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

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

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