Tecs
On this page
  1. tecs.io.Path
  2. Module contents
    1. Constructors
    2. Functions
  3. Constructors
    1. new
  4. Functions
    1. currentDirectory
    2. separator
    3. tecs.io.Path:absolute
    4. tecs.io.Path:canonicalize
    5. tecs.io.Path:extension
    6. tecs.io.Path:fileName
    7. tecs.io.Path:isAbsolute
    8. tecs.io.Path:isRelative
    9. tecs.io.Path:join
    10. tecs.io.Path:normalize
    11. tecs.io.Path:parent
    12. tecs.io.Path:relativeTo
    13. tecs.io.Path:resolve
    14. tecs.io.Path:stem
    15. tecs.io.Path:toString
    16. tecs.io.Path:withExtension
    17. tecs.io.Path:withFileName

tecs.io.Path

Immutable, platform-native filesystem paths.

Path is an immutable platform-native UTF-8 filesystem path. Methods interpret roots, separators, drive prefixes, and UNC paths according to the operating system running Tecs. They return new paths rather than mutating their receiver:

local root <const> = tecs.io.Path.new("assets")
local shader <const> = root:join("shaders", "sprite.glsl")

print(shader:fileName())
print(shader:withExtension("spv"))

normalize is lexical. It removes redundant separators and . components and resolves .. without reading the filesystem. That is useful for output paths which do not exist yet, but it can change which object a path denotes when a traversed component is a symbolic link. canonicalize reads the filesystem, requires the path to exist, and follows symbolic links: use resolve for a normalized absolute spelling of a configured output and canonicalize only when an existing object's filesystem identity matters.

Paths contain valid UTF-8 and no NUL byte, matching the string contract used by Tecs file and process APIs. Unix filenames containing invalid UTF-8 cannot be represented. A path object owns only its immutable Lua string and needs no close.

Module contents

Constructors

Constructor Description
new Creates an immutable path from platform-native components.

Functions

Function Kind Description
currentDirectory Static Returns the process's current working directory.
separator Static Returns the platform's preferred path separator.
absolute Instance Returns an absolute spelling without requiring the path to exist.
canonicalize Instance Resolves filesystem identity and follows symbolic links.
extension Instance Returns the final component's last extension without its dot.
fileName Instance Returns the final path component.
isAbsolute Instance Returns whether this path carries a platform root.
isRelative Instance Returns whether this path needs a base directory.
join Instance Appends path components and returns the result.
normalize Instance Returns a lexically normalized path without filesystem access.
parent Instance Returns this path without its final component.
relativeTo Instance Expresses this path relative to a base path.
resolve Instance Returns a normalized absolute spelling without filesystem access.
stem Instance Returns the final component without its last extension.
toString Instance Returns this path's platform-native UTF-8 spelling.
withExtension Instance Replaces or removes the final component's extension.
withFileName Instance Replaces the final component.

Constructors

tecs.io.Path.new Static

Creates an immutable path from platform-native components.

Construction joins the components lexically and does not require the path to exist. A later absolute component replaces the accumulated prefix according to the host platform's rules.

function tecs.io.Path.new(first: string, ...: string): Path

Arguments

Name Type Description
first string The caller supplies the first valid UTF-8 path component or complete path, without a NUL byte.
... string The caller supplies additional path components in order.

Returns

Type Description
Path Returns a new immutable path.

Examples

local shader <const> = tecs.io.Path.new(
    "assets", "shaders", "sprite.glsl"
)

assert(shader:fileName() == "sprite.glsl")

Functions

tecs.io.Path.currentDirectory Static

Returns the process's current working directory.

function tecs.io.Path.currentDirectory(): Path, string

Arguments

None.

Returns

Type Description
Path Returns a new immutable normalized absolute path.
string Returns the platform reason when the first return is nil.

tecs.io.Path.separator Static

Returns the platform's preferred path separator.

Paths accept the forms supported by the host platform; this value is only for text that must display or emit a separator itself.

function tecs.io.Path.separator(): string

Arguments

None.

Returns

Type Description
string Returns "\\" on Windows and "/" elsewhere.

tecs.io.Path:absolute Instance

Returns an absolute spelling without requiring the path to exist.

A relative receiver is based on the process's current directory. Unlike resolve, this preserves platform-significant parent components where the native absolute operation preserves them.

function tecs.io.Path.absolute(self): Path, string

Arguments

Name Type Description
self Path The path to make absolute.

Returns

Type Description
Path Returns a new immutable absolute path.
string Returns the platform reason when the current directory cannot be determined.

tecs.io.Path:canonicalize Instance

Resolves filesystem identity and follows symbolic links.

The receiver must exist. The result is absolute and normalized by the operating system.

function tecs.io.Path.canonicalize(self): Path, string

Arguments

Name Type Description
self Path The existing path to canonicalize.

Returns

Type Description
Path Returns a new immutable canonical path.
string Returns the filesystem reason when the first return is nil.

Examples

local executable, reason = tecs.io.Path.new("."):canonicalize()
if executable == nil then
    error(reason)
end

print(executable)

tecs.io.Path:extension Instance

Returns the final component's last extension without its dot.

function tecs.io.Path.extension(self): string

Arguments

Name Type Description
self Path The path to inspect without filesystem access.

Returns

Type Description
string Returns the extension, or nil when none exists.

tecs.io.Path:fileName Instance

Returns the final path component.

function tecs.io.Path.fileName(self): string

Arguments

Name Type Description
self Path The path to inspect without filesystem access.

Returns

Type Description
string Returns the final component, or nil for a root or terminal parent component.

tecs.io.Path:isAbsolute Instance

Returns whether this path carries a platform root.

function tecs.io.Path.isAbsolute(self): boolean

Arguments

Name Type Description
self Path The path to inspect without filesystem access.

Returns

Type Description
boolean Returns true when the path is absolute on this platform.

tecs.io.Path:isRelative Instance

Returns whether this path needs a base directory.

function tecs.io.Path.isRelative(self): boolean

Arguments

Name Type Description
self Path The path to inspect without filesystem access.

Returns

Type Description
boolean Returns true when the path is relative on this platform.

tecs.io.Path:join Instance

Appends path components and returns the result.

A later absolute argument replaces everything accumulated before it, following the host platform's path rules. The result is not normalized and no component needs to exist.

function tecs.io.Path.join(self, ...: string | Path): Path

Arguments

Name Type Description
self Path The base path left unchanged.
... string | Path The caller supplies strings or paths to append in order.

Returns

Type Description
Path Returns a new immutable path.

Examples

local assets <const> = tecs.io.Path.new("assets")
local shader <const> = assets:join("shaders", "sprite.glsl")

assert(tostring(assets) == "assets")
assert(
    shader:toString() == tecs.io.Path.new(
        "assets", "shaders", "sprite.glsl"
    ):toString()
)

tecs.io.Path:normalize Instance

Returns a lexically normalized path without filesystem access.

Redundant separators and . are removed and .. is resolved. A symbolic link can make that lexical result denote a different object.

function tecs.io.Path.normalize(self): Path

Arguments

Name Type Description
self Path The path to normalize.

Returns

Type Description
Path Returns a new immutable path.

Examples

local configured <const> = tecs.io.Path.new(
    "assets", ".", "shaders", "..", "sprite.glsl"
)
local normalized <const> = configured:normalize()

assert(normalized == tecs.io.Path.new("assets", "sprite.glsl"))

tecs.io.Path:parent Instance

Returns this path without its final component.

function tecs.io.Path.parent(self): Path

Arguments

Name Type Description
self Path The path to inspect without filesystem access.

Returns

Type Description
Path Returns a new immutable parent, or nil when the path has none.

tecs.io.Path:relativeTo Instance

Expresses this path relative to a base path.

Neither path is accessed. On Windows, paths on different drives or UNC roots have no relative spelling.

function tecs.io.Path.relativeTo(
    self, base: string | Path
): Path, string

Arguments

Name Type Description
self Path The destination path.
base string | Path The caller supplies the directory from which to describe the destination.

Returns

Type Description
Path Returns a new immutable relative path.
string Returns a reason when the two paths cannot share a coordinate system.

Examples

local root <const> = tecs.io.Path.new("assets")
local sprite <const> = root:join("sprites", "hero.png")
local relative, reason = sprite:relativeTo(root)
if relative == nil then
    error(reason)
end

assert(relative == tecs.io.Path.new("sprites", "hero.png"))

tecs.io.Path:resolve Instance

Returns a normalized absolute spelling without filesystem access.

Arguments are joined first. The process's current directory supplies the base when the joined path remains relative.

function tecs.io.Path.resolve(
    self, ...: string | Path
): Path, string

Arguments

Name Type Description
self Path The first path in the resolution.
... string | Path The caller supplies strings or paths to append in order.

Returns

Type Description
Path Returns a new immutable normalized absolute path.
string Returns the platform reason when the current directory cannot be determined.

Examples

local output, reason = tecs.io.Path.new("build", "game.pack"):resolve()
if output == nil then
    error(reason)
end

assert(output:isAbsolute())

tecs.io.Path:stem Instance

Returns the final component without its last extension.

function tecs.io.Path.stem(self): string

Arguments

Name Type Description
self Path The path to inspect without filesystem access.

Returns

Type Description
string Returns the stem, or nil when the path has no file name.

tecs.io.Path:toString Instance

Returns this path's platform-native UTF-8 spelling.

tostring(path) returns the same string.

function tecs.io.Path.toString(self): string

Arguments

Name Type Description
self Path The immutable path to render.

Returns

Type Description
string Returns the complete path without accessing the filesystem.

tecs.io.Path:withExtension Instance

Replaces or removes the final component's extension.

function tecs.io.Path.withExtension(self, extension: string): Path

Arguments

Name Type Description
self Path The path whose final component changes.
extension string The caller supplies one component without a leading dot, or an empty string to remove the extension.

Returns

Type Description
Path Returns a new immutable path.

Examples

local source <const> = tecs.io.Path.new("shaders", "sprite.glsl")
local compiled <const> = source:withExtension("spv")

assert(source:extension() == "glsl")
assert(compiled:fileName() == "sprite.spv")

tecs.io.Path:withFileName Instance

Replaces the final component.

function tecs.io.Path.withFileName(self, name: string): Path

Arguments

Name Type Description
self Path The path whose parent is retained.
name string The caller supplies one non-empty platform path component.

Returns

Type Description
Path Returns a new immutable path.