Path

Abstract supertype of UnixPath and WindowsPath.

Constructor

`Path path`

Parameters:

Name	Type	Description
`path`	`Str`\|`Path`	Path value

Returns: UnixPath or WindowsPath.

The returned path type is chosen according to the current VFS context.

Fields

`name`

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

`stem`

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

let no_ext = Path "/home/user/Makefile"
echo $no_ext.stem  # Makefile

`parent`

The parent directory as a Path of the same subtype, or nil if the path is empty or contains only one component.

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

`ext`

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

let no_ext = Path "/home/user/noextension"
echo $no_ext.ext  # nil

`is_absolute`

Whether the path is absolute (starts from the filesystem root).

let abs = Path "/home/user/file.txt"
echo $abs.is_absolute  # true

let rel = Path "./file.txt"
echo $rel.is_absolute  # false

`components`

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.

Class Methods

`join ...components`

Joins multiple path components into a single path. Components may be Path objects or strings.

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

Parameters

Name	Type	Description
`components`	`Str`\|`Path`	Path components to join

Returns

Path

Example

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

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

Methods

`open :mode? :block?`

Equivalent to fs.open

`metadata :resolve = :TARGET:`

Equivalent to fs.metadata

`fs_metadata :resolve = :TARGET:`

Equivalent to fs.fs_metadata.

`exists()`

Equivalent to fs.exists.

`read mode?`

Equivalent to fs.read.

`write content`

Equivalent to fs.write.

`append content`

Equivalent to fs.append.

`set_size size`

Equivalent to fs.set_size.

`set_metadata :resolve? ...`

Equivalent to fs.set_metadata.

`xattrs :namespace? :resolve = :TARGET:`

Equivalent to fs.xattrs.

`xattr name :namespace? :resolve = :TARGET:`

Equivalent to fs.xattr.

`acl :default? :resolve = :TARGET:`

Equivalent to fs.acl.

`set_acl acl :default? :resolve = :TARGET:`

Equivalent to fs.set_acl.

`set_xattr name value :namespace? :resolve = :TARGET:`

Equivalent to fs.set_xattr.

`remove_xattr name :namespace? :resolve = :TARGET:`

Equivalent to fs.remove_xattr.

`copy to :all?`

Equivalent to fs.copy.

`rename to :replace?`

Equivalent to fs.rename.

`move to :all?`

Equivalent to fs.move.

`hard_link to`

Equivalent to fs.hard_link.

`entries()`

Equivalent to fs.entries.

`add_ext ext`

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

Parameters

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

Returns

Path

Example

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

let file = Path "report"
echo file.add_ext "txt"  # report.txt

`canonical()`

Equivalent to fs.canonical.

`read_link()`

Equivalent to fs.read_link.

`without_ext()`

Returns a new path with the final extension removed.

Returns

Path

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

let plain = Path "Makefile"
echo plain.without_ext()  # Makefile

`with_ext ext`

Returns a new path with the final extension replaced.

Parameters

Name	Type	Description
`ext`	`Str`	Replacement extension

Returns

Path

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

let plain = Path "Makefile"
echo plain.with_ext "txt"  # Makefile.txt

`with_name name`

Returns a new path with the final component replaced.

Parameters

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

Returns

Path

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

`with_stem stem`

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

Parameters

Name	Type	Description
`stem`	`Str`	Replacement stem

Returns

Path

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

let plain = Path "Makefile"
echo plain.with_stem "Dockerfile"  # Dockerfile

`remove :all? :ignore?`

Equivalent to remove.

`create_dir :all?`

Equivalent to create_dir.

`remove_dir :all? :ignore?`

Equivalent to remove_dir.

`normalize()`

Equivalent to normalize

`absolute()`

Equivalent to absolute

`relative base?`

Equivalent to relative

`glob pattern :max_depth? :resolve?`

Equivalent to glob, but searches within this path. Yielded paths will contain this path as a prefix.