libraryDocs / path

path

librarysharedsource

The file path library.

Works with POSIX-style paths: / is the only separator and a path is absolute when it starts with /. Backslashes are ordinary bytes, except in stripTrailingSlash, stripLeadingSlash and normalizeSlashes, which also treat \ as a separator.

Nothing here touches the file system; all functions work on the strings only.

Classes & types

type

path.ParsedData

The result table of executing path.parse.

Fields

Name	Type	Description
`delimiter`	`string`	The delimiter between paths in a path list, always `":"`. = `":"`
`sep`	`string`	The path segment separator, always `"/"`. = `"/"`

Functions

`path.ensureLeadingSlash`	Adds a leading / to the file path if it does not start with one, which makes a relative path absolute.
`path.ensureTrailingSlash`	Adds a trailing / to the file path if it does not end with one.
`path.equals`
`path.get`	Returns the path of the file that a function was loaded from.
`path.getDirectory`	Returns the directory, the part before the last /.
`path.getExtension`	Returns the extension of the file name, the part after its last dot.
`path.getFile`	Returns the file name, the part after the last /, without its extension by default.
`path.isAbsolute`	Checks if the file path is absolute, i.e. starts with /.
`path.isRelative`	Checks if the file path is relative, i.e. does not start with /.
`path.join`	Joins the file paths with / and normalizes the result (see path.normalize).
`path.normalize`	Normalizes a file path: collapses repeated slashes, removes . segments and resolves .. segments against the segments be…
`path.normalizeSlashes`	Replaces every run of slashes (/ and \) with a single /.
`path.parse`	Parses a file path into a table of its parts.
`path.relative`	Returns the relative path from the from directory to to.
`path.replaceDirectory`	Replaces the directory, the part before the last /, and keeps the file name.
`path.replaceExtension`	Replaces the extension of the file name, or adds one if there is none.
`path.replaceName`	Replaces the file name (with extension), the part after the last /.
`path.resolve`	Resolves a file path to an absolute, normalized file path.
`path.split`	Splits a file path at the last / into a directory and a file name.
`path.splitExtension`	Splits a file path at the last dot of the file name into the path without the extension and the extension.
`path.stripLeadingSlash`	Removes all leading slashes (/ and \) from the file path, which makes an absolute path relative.
`path.stripTrailingSlash`	Removes all trailing slashes (/ and \) from the file path.
`path.wildcard`	Converts a wildcard (glob) string to a Lua pattern.

#path.ensureLeadingSlash

sharednodiscardsource

function path.ensureLeadingSlash(file_path: string): string

Adds a leading / to the file path if it does not start with one, which makes a relative path absolute.

lua

path.ensureLeadingSlash( "game/lua" ) -- "/game/lua"
path.ensureLeadingSlash( "/game/lua" ) -- "/game/lua"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.ensureTrailingSlash

sharednodiscardsource

function path.ensureTrailingSlash(file_path: string): string

Adds a trailing / to the file path if it does not end with one.

lua

path.ensureTrailingSlash( "/game/lua" ) -- "/game/lua/"
path.ensureTrailingSlash( "/game/lua/" ) -- "/game/lua/"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.equals

nodiscardsource

function path.equals(file_path1: string, file_path2: string): boolean

Parameters

Name	Type	Description
`file_path1`	`string`
`file_path2`	`string`

Returns

Type	Name	Description
`boolean`	`is_equal`

#path.get

sharednodiscardsource

function path.get(f?: ( function | integer )?): string

Returns the path of the file that a function was loaded from.

With a stack level, the __file object in the function's environment is used first (set for files loaded by dreamwork), then the source of the main chunk on the stack. With a function, its source is used.

If the file can't be found, "/game/lua/unknown.lua" is returned.

lua

-- in /game/lua/autorun/init.lua
path.get() -- "/game/lua/autorun/init.lua"

Parameters

Name	Type	Description
`f`optional	`( function \| integer )?`	The function, or the stack level, where `1` (default) is the function calling `get`.

Returns

Type	Name	Description
`string`	`file_path`	The absolute path of the file.

#path.getDirectory

sharednodiscardsource

function path.getDirectory(file_path: string, keep_trailing_slash?: boolean): string | nil

Returns the directory, the part before the last /.

The root directory is always returned as "/", even if keep_trailing_slash is not true.

lua

path.getDirectory( "/game/lua/init.lua" ) -- "/game/lua"
path.getDirectory( "/game/lua/init.lua", true ) -- "/game/lua/"
path.getDirectory( "/init.lua" ) -- "/"
path.getDirectory( "init.lua" ) -- nil

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`keep_trailing_slash`optional	`boolean`	`true` to keep the trailing slash, `false` otherwise.

Returns

Type	Name	Description
`string \| nil`	`directory`	The directory of the file, or `nil` if the file path has no `/`.

#path.getExtension

sharednodiscardsource

function path.getExtension(file_path: string, keep_dot?: boolean): string

Returns the extension of the file name, the part after its last dot.

A leading dot is part of the name, so dotfiles like .bashrc have no extension.

lua

path.getExtension( "/game/lua/init.lua" ) -- "lua"
path.getExtension( "/game/lua/init.lua", true ) -- ".lua"
path.getExtension( "archive.tar.gz" ) -- "gz"
path.getExtension( "/home/.bashrc" ) -- ""
path.getExtension( "/data.d/file" ) -- ""

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`keep_dot`optional	`boolean`	`true` to keep the dot, `false` otherwise.

Returns

Type	Name	Description
`string`	`extension`	The extension of the file, or an empty string if there is none.

#path.getFile

sharednodiscardsource

function path.getFile(file_path: string, keep_extension?: boolean): string

Returns the file name, the part after the last /, without its extension by default.

Only the last extension is removed, and a leading dot is part of the name, so dotfiles like .bashrc have no extension.

lua

path.getFile( "/game/lua/init.lua" ) -- "init"
path.getFile( "/game/lua/init.lua", true ) -- "init.lua"
path.getFile( "archive.tar.gz" ) -- "archive.tar"
path.getFile( "/home/.bashrc" ) -- ".bashrc"
path.getFile( "/game/lua/" ) -- ""

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`keep_extension`optional	`boolean`	`true` to keep the extension, `false` otherwise.

Returns

Type	Name	Description
`string`	`file_name`	The name of the file.

#path.isAbsolute

sharednodiscardsource

function path.isAbsolute(file_path: string): boolean

Checks if the file path is absolute, i.e. starts with /.

lua

path.isAbsolute( "/game/lua/init.lua" ) -- true
path.isAbsolute( "lua/init.lua" ) -- false

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`boolean`	`is_abs`	`true` if the file path is absolute, `false` otherwise.

#path.isRelative

sharednodiscardsource

function path.isRelative(file_path: string): boolean

Checks if the file path is relative, i.e. does not start with /.

An empty string is relative.

lua

path.isRelative( "lua/init.lua" ) -- true
path.isRelative( "/game/lua/init.lua" ) -- false

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`boolean`	`is_rel`	`true` if the file path is relative, `false` otherwise.

#path.join

sharednodiscardsource

function path.join(segments: string[], segment_count?: integer): string

Joins the file paths with / and normalizes the result (see path.normalize).

Empty paths are skipped, and a leading / is kept only on the first path, so the result is absolute only if the first non-empty path is. The segments table is not modified.

lua

path.join( { "/game", "lua/", "autorun/init.lua" } ) -- "/game/lua/autorun/init.lua"
path.join( { "/game/lua", "../data", "x.txt" } ) -- "/game/data/x.txt"
path.join( { "lua", "/autorun" } ) -- "lua/autorun"
path.join( {} ) -- "."

Parameters

Name	Type	Description
`segments`	`string[]`	The file paths to join.
`segment_count`optional	`integer`	The number of file paths to join, defaults to the length of `segments`.

Returns

Type	Name	Description
`string`	`file_path`	The joined file path.

#path.normalize

sharednodiscardsource

function path.normalize(file_path: string, keep_trailing_slash?: boolean): string

Normalizes a file path: collapses repeated slashes, removes . segments and resolves .. segments against the segments before them.

.. segments that can't be resolved stay at the start of a relative path, and are dropped from an absolute path, since nothing is above the root. An empty result becomes "." (or "/" for absolute paths).

Already normalized paths are returned as is, without creating a new string.

lua

path.normalize( "/game//lua/./x/../init.lua" ) -- "/game/lua/init.lua"
path.normalize( "lua/../../init.lua" ) -- "../init.lua"
path.normalize( "/../init.lua" ) -- "/init.lua"
path.normalize( "lua/.." ) -- "."
path.normalize( "lua/x/" ) -- "lua/x"
path.normalize( "lua/x/", true ) -- "lua/x/"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`keep_trailing_slash`optional	`boolean`	`true` to keep the trailing slash, `false` otherwise.

Returns

Type	Name	Description
`string`	`new_file_path`	The normalized file path.

#path.normalizeSlashes

sharednodiscardsource

function path.normalizeSlashes(file_path: string): string

Replaces every run of slashes (/ and \) with a single /.

Useful for paths that came from Windows. Unlike path.normalize, . and .. segments are left as is.

lua

path.normalizeSlashes( "garrysmod\\lua//init.lua" ) -- "garrysmod/lua/init.lua"
path.normalizeSlashes( "a\\..\\b" ) -- "a/../b"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.parse

sharednodiscardsource

function path.parse(file_path: string): path.ParsedData

Parses a file path into a table of its parts.

┌─────────────────────┬────────────┐ │ dir │ base │ ├──────┬ ├──────┬─────┤ │ root │ │ name │ ext │ " / home/user/dir/ file .txt " └──────┴──────────────┴──────┴─────┘ (All spaces in the "" line should be ignored. They are purely for formatting.)

dir keeps its trailing slash and ext keeps its dot, so dir .. name .. ext is always the original path. The path is not normalized.

lua

local data = path.parse( "/home/user/dir/file.txt" )
-- data.root = "/", data.dir = "/home/user/dir/", data.base = "file.txt"
-- data.name = "file", data.ext = ".txt", data.abs = true

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`path.ParsedData`	`data`	The parsed file path data.

#path.relative

sharednodiscardsource

function path.relative(from: string, to: string, stack_level?: integer): string

Returns the relative path from the from directory to to.

Both paths are resolved with path.resolve first, so relative paths are relative to the calling file. Segments are compared with path.equals.

If both resolve to the same path, "." is returned.

lua

path.relative( "/game/lua/autorun", "/game/lua/shared/util.lua" ) -- "../shared/util.lua"
path.relative( "/game/lua", "/game/lua/autorun/init.lua" ) -- "autorun/init.lua"
path.relative( "/game/lua/autorun", "/game" ) -- "../.."
path.relative( "/game/lua", "/game/lua/" ) -- "."

Parameters

Name	Type	Description
`from`	`string`	The directory to get the relative path from.
`to`	`string`	The path to get the relative path to.
`stack_level`optional	`integer`	The stack level of the file to resolve relative paths against, where `1` (default) is the function calling `relative`.

Returns

Type	Name	Description
`string`	`relative_path`	The relative path.

#path.replaceDirectory

sharednodiscardsource

function path.replaceDirectory(file_path: string, dir_name: string): string

Replaces the directory, the part before the last /, and keeps the file name.

A / is added between the directory and the file name if needed. An empty directory leaves only the file name.

lua

path.replaceDirectory( "/game/lua/init.lua", "/data/cache" ) -- "/data/cache/init.lua"
path.replaceDirectory( "/game/lua/init.lua", "/data/cache/" ) -- "/data/cache/init.lua"
path.replaceDirectory( "/game/lua/init.lua", "" ) -- "init.lua"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`dir_name`	`string`	The new directory, with or without a trailing slash.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.replaceExtension

sharednodiscardsource

function path.replaceExtension(file_path: string, ext_name: string): string

Replaces the extension of the file name, or adds one if there is none.

lua

path.replaceExtension( "/game/lua/init.lua", "txt" ) -- "/game/lua/init.txt"
path.replaceExtension( "archive.tar.gz", "zip" ) -- "archive.tar.zip"
path.replaceExtension( "/home/.bashrc", "bak" ) -- "/home/.bashrc.bak"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`ext_name`	`string`	The new extension, without the leading dot.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.replaceName

sharednodiscardsource

function path.replaceName(file_path: string, file_name: string): string

Replaces the file name (with extension), the part after the last /.

lua

path.replaceName( "/game/lua/init.lua", "shared.lua" ) -- "/game/lua/shared.lua"
path.replaceName( "init.lua", "shared.lua" ) -- "shared.lua"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`file_name`	`string`	The new file name, including its extension.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.resolve

sharednodiscardsource

function path.resolve(file_path: string, stack_level?: integer): string

Resolves a file path to an absolute, normalized file path.

Absolute paths are only normalized. Relative paths are resolved against the directory of the file that calls resolve (see path.get), similar to require.

lua

-- in /game/lua/autorun/init.lua
path.resolve( "client.lua" ) -- "/game/lua/autorun/client.lua"
path.resolve( "../shared/util.lua" ) -- "/game/lua/shared/util.lua"
path.resolve( "/data/./x.txt" ) -- "/data/x.txt"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`stack_level`optional	`integer`	The stack level of the file to resolve against, where `1` (default) is the function calling `resolve`.

Returns

Type	Name	Description
`string`	`abs_path`	The resolved file path.

#path.split

sharednodiscardsource

function path.split(file_path: string, keep_trailing_slash?: boolean): string, string

Splits a file path at the last / into a directory and a file name.

The root directory is always returned as "/", even if keep_trailing_slash is not true.

lua

path.split( "/game/lua/init.lua" ) -- "/game/lua", "init.lua"
path.split( "/game/lua/init.lua", true ) -- "/game/lua/", "init.lua"
path.split( "/init.lua" ) -- "/", "init.lua"
path.split( "init.lua" ) -- "", "init.lua"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`keep_trailing_slash`optional	`boolean`	`true` to keep the trailing slash, `false` otherwise.

Returns

Type	Name	Description
`string`	`directory_path`	The directory from the file path, or an empty string if the file path has no `/`.
`string`	`file_name`	The file name with extension from the file path.

#path.splitExtension

sharednodiscardsource

function path.splitExtension(file_path: string, keep_dot?: boolean): string, string

Splits a file path at the last dot of the file name into the path without the extension and the extension.

A leading dot is part of the name, so dotfiles like .bashrc have no extension.

lua

path.splitExtension( "/game/lua/init.lua" ) -- "/game/lua/init", "lua"
path.splitExtension( "/game/lua/init.lua", true ) -- "/game/lua/init", ".lua"
path.splitExtension( "/home/.bashrc" ) -- "/home/.bashrc", ""

Parameters

Name	Type	Description
`file_path`	`string`	The file path.
`keep_dot`optional	`boolean`	`true` to keep the extension dot, `false` otherwise.

Returns

Type	Name	Description
`string`	`file_path_without_extension`	The file path without the extension.
`string`	`extension`	The extension, or an empty string if there is none.

#path.stripLeadingSlash

sharednodiscardsource

function path.stripLeadingSlash(file_path: string): string

Removes all leading slashes (/ and \) from the file path, which makes an absolute path relative.

lua

path.stripLeadingSlash( "/game/lua" ) -- "game/lua"
path.stripLeadingSlash( "\\/game/lua" ) -- "game/lua"
path.stripLeadingSlash( "/" ) -- ""

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.stripTrailingSlash

sharednodiscardsource

function path.stripTrailingSlash(file_path: string): string

Removes all trailing slashes (/ and \) from the file path.

The first byte is never removed, so the root directory stays "/".

lua

path.stripTrailingSlash( "/game/lua/" ) -- "/game/lua"
path.stripTrailingSlash( "lua\\//" ) -- "lua"
path.stripTrailingSlash( "/" ) -- "/"

Parameters

Name	Type	Description
`file_path`	`string`	The file path.

Returns

Type	Name	Description
`string`	`new_file_path`	The new file path.

#path.wildcard

sharednodiscardsource

function path.wildcard(wildcard_str: string, anchor_to_slash?: boolean): string

Converts a wildcard (glob) string to a Lua pattern.

Supported syntax:

? - any single byte except /.
* - any sequence of bytes except /.
** - any sequence of bytes, **/ also matches zero directories.
[abc], [a-z] - one byte from the set.
[!a-z], [^a-z] - one byte not in the set, never /.
\x - the literal byte x, e.g. \* or \[.

A ] right after [ or [! is a member of the set, e.g. []]. A [ without a closing ] is a literal [. Other bytes match themselves, Lua pattern magic characters are escaped. Brace expansion ({a,b}) is not supported.

The pattern always has to match up to the end of the string. By default it also has to match from the start; with anchor_to_slash it can start at the beginning or right after any /, so it matches the last segments of a full path.

lua

path.wildcard( "*.lua" ) -- "^[^/]*%.lua$"
path.wildcard( "**/init.lua" ) -- "^.*%f[^%z/]init%.lua$"
string.match( "init.lua", path.wildcard( "*.lua" ) ) -- "init.lua"
string.match( "lua/init.lua", path.wildcard( "*.lua" ) ) -- nil
string.match( "/game/lua/init.lua", path.wildcard( "*.lua", true ) ) -- "init.lua"
string.match( "x2.txt", path.wildcard( "x[0-9].txt" ) ) -- "x2.txt"

Parameters

Name	Type	Description
`wildcard_str`	`string`	The path wildcard string.
`anchor_to_slash`optional	`boolean`	If `true`, the pattern can match after any `/` instead of only at the start of the string.

Returns

Type	Name	Description
`string`	`pattern_str`	The Lua pattern that represents the wildcard string.