API Path

Path

Protocol-aware path value with static text helpers and mutable instance methods.

Script API Reference

Overview

Path manipulates path text only. It normalizes separators, dot segments, and protocol paths such as mem://app/main.as, but it never touches the file system, so no method checks whether a path exists.

The two halves of the API behave differently:

• Static methods take path text or a Path and mostly return a normalized string.
• Instance methods mutate the receiver in place and return the same Path, so they can be chained.

Note

Path.baseModule, Path.currentFile, and Path.currentDirectory need a module context. They return null when called outside a module.

Quick Reference

Member	Returns	Summary
new Path([root], ...segments)	Path	Creates a normalized mutable path.
Path.of(root, ...segments)	Path	Creates a normalized mutable path.
Path.isPath(value)	boolean	Reports whether the value is a Path.
Path.join(root, ...segments)	string	Joins and normalizes segments.
Path.baseModule(...segments)	string	Joins segments onto the current module directory.
Path.normalize(path)	string	Normalizes separators and dot segments.
Path.directoryName(path)	string	Parent directory of a path.
Path.fileName(path)	string	Final segment of a path.
Path.extName(path)	string	Extension of a path, including the dot.
Path.protocol(path)	string	Protocol scheme of a path.
Path.changeExt(path, extension)	string	Changes or adds an extension.
Path.isRooted(path)	boolean	Reports whether a path is rooted or protocol-qualified.
Path.isUnderRoot(root, path)	boolean	Reports whether a path sits under a root.
Path.currentFile()	string	Full path of the current module.
Path.currentDirectory()	string	Directory of the current module.
path.append(...segments)	Path	Appends segments in place.
path.reset(root, ...segments)	Path	Replaces the current path in place.
path.changeExt(extension)	Path	Changes the extension in place.
path.directoryName()	string	Parent directory of the current path.
path.fileName()	string	Final segment of the current path.
path.extName()	string	Extension of the current path.
path.protocol()	string	Protocol scheme of the current path.
path.clone()	Path	Copies the path into a new Path.
path.toString()	string	Normalized path text.

Constructors

new Path([root], ...segments)

Parameters

Name	Type	Required	Description
root	string or Path	No	Root path the result starts from.
segments	string or Path	No	Additional segments, passed as variadic arguments.

Returns

Path — a mutable, normalized path.

Example

var path = new Path("mem://app/scripts", "..", "main.as");
return path.toString(); // mem://app/main.as

Methods

Path.of(root, ...segments)

Parameters

Name	Type	Required	Description
root	string or Path	Yes	Root path the result starts from.
segments	string or Path	No	Additional segments, passed as variadic arguments.

Returns

Path — a mutable, normalized path.

Behavior

Equivalent to the constructor, and often easier to read inside an expression.

Example

return Path.of("assets", "ui", "icon.png").toString(); // assets/ui/icon.png

Path.isPath(value)

Parameters

Name	Type	Required	Description
value	any	Yes	Value to inspect.

Returns

boolean — whether the value is a Path object.

Behavior

Path text alone is a string, so Path.isPath("assets") is false.

Example

return Path.isPath(new Path("scripts")); // true

Path.join(root, ...segments)

Parameters

Name	Type	Required	Description
root	string or Path	Yes	Starting path.
segments	string or Path	No	Segments to join, passed as variadic arguments.

Returns

string — the joined, normalized path text.

Behavior

Pure text manipulation; the file system is never consulted.

Example

return Path.join("scripts", "shared", "main.as"); // scripts/shared/main.as

Path.baseModule(...segments)

Parameters

Name	Type	Required	Description
segments	string or Path	No	Segments relative to the current module source directory.

Returns

string — the normalized path, or null outside a module context.

Example

@module(MAIN);

export func assetPath() {
    return Path.baseModule("../assets", "config.json");
}

Path.normalize(path)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Path text or Path to normalize.

Returns

string — text with normalized separators and dot segments resolved.

Example

return Path.normalize("assets/../scripts/main.as"); // scripts/main.as

Path.directoryName(path)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Path text or Path.

Returns

string — the parent directory path.

Example

return Path.directoryName("assets/ui/icon.png"); // assets/ui

Path.fileName(path)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Path text or Path.

Returns

string — the final path segment.

Example

return Path.fileName("assets/ui/icon.png"); // icon.png

Path.extName(path)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Path text or Path.

Returns

string — the extension of the final segment, including the leading dot, or an empty string when there is none.

Example

return Path.extName("assets/ui/icon.png"); // .png

Path.protocol(path)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Path text or Path.

Returns

string — the protocol scheme without its trailing separator, or an empty string for a non-protocol path.

Example

return Path.protocol("mem://app/main.as"); // mem

Path.changeExt(path, extension)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Original path.
extension	string or Path	Yes	New extension, with or without the leading dot.

Returns

string — the normalized path text with the extension changed or added.

Example

return Path.changeExt("scripts/main", "as"); // scripts/main.as

Path.isRooted(path)

Parameters

Name	Type	Required	Description
path	string or Path	Yes	Path text or Path.

Returns

boolean — whether the path is rooted or carries a protocol scheme.

Example

return Path.isRooted("mem://app/main.as"); // true

Path.isUnderRoot(root, path)

Parameters

Name	Type	Required	Description
root	string or Path	Yes	Root path.
path	string or Path	Yes	Path to check.

Returns

boolean — whether the normalized path sits under the normalized root.

Behavior

Both arguments are normalized first, so .. segments cannot be used to escape the root undetected. This makes it a useful containment check for host-supplied paths.

Example

return Path.isUnderRoot("scripts", "scripts/shared/main.as"); // true

Path.currentFile()

Parameters

None.

Returns

string — the full path of the current module, or null outside a module context.

Example

@module(MAIN);

export func location() {
    return Path.currentFile();
}

Path.currentDirectory()

Parameters

None.

Returns

string — the directory of the current module, or null outside a module context.

Example

@module(MAIN);

export func directory() {
    return Path.currentDirectory();
}

path.append(...segments)

Parameters

Name	Type	Required	Description
segments	string or Path	No	Segments to append, passed as variadic arguments.

Returns

Path — this path.

Behavior

Mutates the receiver in place, then normalizes the result.

Example

var path = new Path("assets");
return path.append("ui", "icon.png").toString(); // assets/ui/icon.png

path.reset(root, ...segments)

Parameters

Name	Type	Required	Description
root	string or Path	Yes	New root path.
segments	string or Path	No	Additional segments, passed as variadic arguments.

Returns

Path — this path.

Behavior

Discards the current text and replaces it in place, which lets one Path instance be reused across a loop.

Example

var path = new Path("old");
return path.reset("new", "main.as").toString(); // new/main.as

path.changeExt(extension)

Parameters

Name	Type	Required	Description
extension	string or Path	Yes	New extension, with or without the leading dot.

Returns

Path — this path.

Behavior

Changes or adds the extension in place.

Example

var path = new Path("scripts/main");
return path.changeExt("as").toString(); // scripts/main.as

path.directoryName()

Parameters

None.

Returns

string — the parent directory of the current path.

Example

return new Path("mem://app/main.as").directoryName(); // mem://app

path.fileName()

Parameters

None.

Returns

string — the final segment of the current path.

Example

return new Path("mem://app/main.as").fileName(); // main.as

path.extName()

Parameters

None.

Returns

string — the extension of the current path, including the leading dot, or an empty string when there is none.

Example

return new Path("mem://app/main.as").extName(); // .as

path.protocol()

Parameters

None.

Returns

string — the protocol scheme of the current path without its trailing separator, or an empty string for a non-protocol path.

Example

return new Path("mem://app/main.as").protocol(); // mem

path.clone()

Parameters

None.

Returns

Path — a new Path holding the same text.

Behavior

Because instance methods mutate in place, clone before handing a path to code that may modify it.

Example

var original = new Path("scripts/main.as");
var copy = original.clone();
copy.changeExt("json");
return original.toString(); // scripts/main.as

path.toString()

Parameters

None.

Returns

string — the normalized path text.

Example

return new Path("assets", "..", "scripts/main.as").toString(); // scripts/main.as