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 @ Seq[Str] ^[get]

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) ^[get]

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 ^[get]

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

name @ (Str | nil) ^[get]

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) ^[get]

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) ^[get]

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

(div) other -> Path

Joins a path, or derives the path of a directory entry.

Parameters

Name	Type	Description
other	(Str | Path | DirEntry)

(lt) other -> Bool

Orders paths lexically.

Parameters

Name	Type	Description
other	Path

(rdiv) other -> Path

Joins this path onto a string.

Parameters

Name	Type	Description
other	Str

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[fs.unix.DirEntry | fs.windows.DirEntry]

The method form of fs.entries.

exists() -> Bool

The method form of fs.exists.

fs_metadata … -> (fs.unix.FsMetadata | fs.windows.FsMetadata)

The method form of fs.fs_metadata.

Parameters

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

glob pattern … -> UnpackIter[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 … -> (fs.unix.Metadata | fs.windows.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 ^{overload 1 of 6}

The method form of fs.open.

Parameters

Name	Type	Description
mode?	OpenMode	File access mode. Defaults to "r".
:buffer?	true	Whether to buffer the file.

open[R] func … -> R ^{overload 2 of 6}

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.
:buffer?	true	Whether to buffer the file.

open[R] mode func … -> R ^{overload 3 of 6}

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.
:buffer?	true	Whether to buffer the file.

open :buffer … -> RawFile ^{overload 4 of 6}

The method form of fs.open for an unbuffered file.

Parameters

Name	Type	Description
mode?	OpenMode	File access mode. Defaults to "r".
:buffer	false	Opens an unbuffered RawFile.

open[R] func :buffer -> R ^{overload 5 of 6}

The method form of fs.open for an unbuffered file with a block.

Parameters

Name	Type	Description
func	((RawFile) -> R)	Block to run with the file; it is closed when the block returns.
:buffer	false	Opens an unbuffered RawFile.

open[R] mode func :buffer -> R ^{overload 6 of 6}

The method form of fs.open for an unbuffered file with a mode and a block.

Parameters

Name	Type	Description
mode	OpenMode	File access mode.
func	((RawFile) -> R)	Block to run with the file; it is closed when the block returns.
:buffer	false	Opens an unbuffered RawFile.

read() -> Bin

The method form of fs.read.

read_link() -> Path

The method form of fs.read_link.

read_str() -> Str

The method form of fs.read_str.

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:.

shorten … -> Path

The method form of fs.shorten.

Parameters

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

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:.
:mode?	(Int | fs.unix.Mode)
:owner?	(Int | Str | security.windows.Sid)
:group?	(Int | Str | security.windows.Sid)
:modified?	time.DateTime
:accessed?	time.DateTime
:created?	time.DateTime
:readonly?	Bool
:hidden?	Bool
:system?	Bool
:archive?	Bool
:compressed?	Bool
:sparse?	Bool
:temporary?	Bool
:offline?	Bool
:not_content_indexed?	Bool
:immutable?	Bool
:append_only?	Bool
:no_dump?	Bool
:no_atime?	Bool
:no_copy_on_write?	Bool
:dir_sync?	Bool
:casefold?	Bool
:data_journaling?	Bool
:no_compress?	Bool
:project_inherit?	Bool
:secure_delete?	Bool
:sync?	Bool
:no_tail_merge?	Bool
:top_dir?	Bool
:undelete?	Bool
:direct_access?	Bool
:extent_format?	Bool
:opaque?	Bool

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:.