Path

A filesystem path.

The supertype of fs.unix.Path and fs.windows.Path; which of the two a constructed path is depends on the current VFS context.

Constructor

`Path path -> Path`

Converts a string or another path to a path of the current VFS context's type.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path value.

Returns

fs.unix.Path or fs.windows.Path.

Class Methods

`join *components -> Path`

Joins path components into a single path.

If any component is an absolute path, it replaces everything before it.

Parameters

Name	Type	Description
`*components`	`(Str \| Path)`	Path components to join.

Example

let path = Path.join home user docs file.txt
echo $path.name  # file.txt

# An absolute path replaces everything before it
let abs = Path.join home /etc config.txt
echo $abs  # /etc/config.txt

Fields

components @ std.Seq[Str]

Immutable array-like view of the lexical path components.

let path = Path "alpha/beta/gamma"
assert_eq [...path.components] ["alpha", "beta", "gamma"]

Windows paths carry the alternate data stream specified in the final path component if present.

ext @ (Str | nil)

The file extension without the leading dot, or nil if the final component has no extension.

let path = Path "/home/user/file.txt"
echo $path.ext  # txt

is_absolute @ Bool

Whether the path is absolute, meaning it starts from the filesystem root.

name @ (Str | nil)

The final component of the path, or nil if the path is empty.

let path = Path /home/user/file.txt
echo $path.name  # file.txt

parent @ (Path | nil)

The parent directory, or nil if the path is empty or contains only one component.

let path = Path /home/user/file.txt
echo $path.parent  # /home/user

stem @ (Str | nil)

The final component without its last extension, or nil if the path is empty.

let path = Path "/home/user/archive.tar.gz"
echo $path.stem  # archive.tar

Methods

`absolute() -> Path`

The method form of fs.absolute.

`acl … -> (security.AnyAcl | nil)`

The method form of fs.acl.

Parameters

Name	Type	Description
`:kind?`	`(:POSIX: \| :NFS4: \| :MACOS:)`	ACL format to query. Defaults to `:POSIX:`.
`:default?`	`Bool`	Query the directory's inheritable default ACL.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`add_ext ext -> Path`

Returns a new path with ext appended as an additional extension.

Parameters

Name	Type	Description
`ext`	`Str`	Extension to append.

Example

let path = Path "archive.tar"
echo (path.add_ext "gz")  # archive.tar.gz

`append content -> Int`

The method form of fs.append.

Parameters

Name	Type	Description
`content`	`(Str \| Bin)`	Content to append.

`canonical() -> Path`

The method form of fs.canonical.

`copy to …`

The method form of fs.copy.

Parameters

Name	Type	Description
`to`	`(Str \| Path)`	Destination path.
`:all?`	`Bool`	Allow a recursive directory copy.

`create_dir …`

The method form of fs.create_dir.

Parameters

Name	Type	Description
`:all?`	`Bool`	Create parent directories too.

`entries() -> Iter[DirEntry]`

The method form of fs.entries.

`exists() -> Bool`

The method form of fs.exists.

`fs_metadata … -> FsMetadata`

The method form of fs.fs_metadata.

Parameters

Name	Type	Description
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`glob pattern … -> Iter[Path]`

The method form of fs.glob, searching within this path.

Yielded paths contain this path as a prefix.

Parameters

Name	Type	Description
`pattern`	`Str`	Glob pattern.
`:max_depth?`	`Int`	Maximum directory depth to traverse. Defaults to unlimited.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:LINK:`.

`hard_link to`

The method form of fs.hard_link, with this path as the existing file.

Parameters

Name	Type	Description
`to`	`(Str \| Path)`	Path where the hard link is created.

`metadata … -> Metadata`

The method form of fs.metadata.

Parameters

Name	Type	Description
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`move to …`

The method form of fs.move.

Parameters

Name	Type	Description
`to`	`(Str \| Path)`	Destination path.
`:all?`	`Bool`	Allow a recursive directory move.

`normalize() -> Path`

The method form of fs.normalize.

`open … -> File`

The method form of fs.open.

Parameters

Name	Type	Description
`mode?`	`OpenMode`	File access mode. Defaults to `"r"`.

`open[R] func -> R`

The method form of fs.open with a block.

Parameters

Name	Type	Description
`func`	`((File) -> R)`	Block to run with the file; it is closed when the block returns.

`open[R] mode func -> R`

The method form of fs.open with a mode and a block.

Parameters

Name	Type	Description
`mode`	`OpenMode`	File access mode.
`func`	`((File) -> R)`	Block to run with the file; it is closed when the block returns.

`read() -> Str`

The method form of fs.read for a text file.

`read mode -> Bin`

The method form of fs.read in binary mode.

Parameters

Name	Type	Description
`mode`	`"b"`	Binary mode.

`read_link() -> Path`

The method form of fs.read_link.

`relative … -> Path`

The method form of fs.relative.

Parameters

Name	Type	Description
`base?`	`(Str \| Path)`	Base directory. Defaults to the current working directory.

`remove …`

The method form of fs.remove.

Parameters

Name	Type	Description
`:all?`	`Bool`	Remove directories recursively.
`:ignore?`	`Bool`	Treat a missing path as success.

`remove_dir …`

The method form of fs.remove_dir.

Parameters

Name	Type	Description
`:all?`	`Bool`	Recursively prune empty directory subtrees.
`:ignore?`	`Bool`	Ignore missing directories and file-blocked subtrees.

`remove_xattr name …`

The method form of fs.remove_xattr.

Parameters

Name	Type	Description
`name`	`(Str \| XattrEntry)`	Attribute name or entry from `xattrs`.
`:namespace?`	`XattrNamespace`	Namespace to update.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`rename to …`

The method form of fs.rename.

Parameters

Name	Type	Description
`to`	`(Str \| Path)`	Destination path.
`:replace?`	`Bool`	Whether to replace an existing destination.

`set_acl acl …`

The method form of fs.set_acl.

Untyped declarative ACL specifications require an explicit kind:; a built ACL supplies its kind and must match one when provided.

Parameters

Name	Type	Description
`acl`	`(security.AclSpec \| nil)`	ACL or declarative ACE sequence.
`:kind?`	`(:POSIX: \| :NFS4: \| :MACOS:)`	Required for an untyped ACL specification.
`:default?`	`Bool`	Update the directory's inheritable default ACL.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`set_size size`

The method form of fs.set_size.

Parameters

Name	Type	Description
`size`	`Int`	New file length in bytes.

`set_xattr name value …`

The method form of fs.set_xattr.

Parameters

Name	Type	Description
`name`	`(Str \| XattrEntry)`	Attribute name or entry from `xattrs`.
`value`	`(Str \| Bin)`	Attribute bytes; strings use UTF-8.
`:namespace?`	`XattrNamespace`	Namespace to update.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`sync …`

The method form of fs.sync.

Parameters

Name	Type	Description
`:data?`	`Bool`	Flush data only, skipping unneeded metadata.

`update_metadata …`

The method form of fs.update_metadata, which documents the metadata keyword arguments.

Parameters

Name	Type	Description
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`with_ext ext -> Path`

Returns a new path with the final extension replaced.

Parameters

Name	Type	Description
`ext`	`Str`	Replacement extension.

Example

let path = Path "archive.tar.gz"
echo (path.with_ext "zip")  # archive.tar.zip

`with_name name -> Path`

Returns a new path with the final component replaced.

Parameters

Name	Type	Description
`name`	`Str`	Replacement final component.

Example

let path = Path "src/main.rs"
echo (path.with_name "lib.rs")  # src/lib.rs

`with_stem stem -> Path`

Returns a new path with the final stem replaced, preserving the final extension when present.

Parameters

Name	Type	Description
`stem`	`Str`	Replacement stem.

Example

let path = Path "archive.tar.gz"
echo (path.with_stem "bundle")  # bundle.gz

`without_ext() -> Path`

Returns a new path with the final extension removed.

Example

let path = Path "archive.tar.gz"
echo (path.without_ext())  # archive.tar

`write content -> Int`

The method form of fs.write.

Parameters

Name	Type	Description
`content`	`(Str \| Bin)`	Value to write.

`xattr name … -> Bin`

The method form of fs.xattr.

Parameters

Name	Type	Description
`name`	`(Str \| XattrEntry)`	Attribute name or entry from `xattrs`.
`:namespace?`	`XattrNamespace`	Namespace to query.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

`xattrs … -> Iter[XattrEntry]`

The method form of fs.xattrs.

Parameters

Name	Type	Description
`:namespace?`	`(XattrNamespace \| :ANY:)`	Namespace to query; `:ANY:` lists all namespaces.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.