Built-in path tools

This page describes the built-in I/O tools:

abspath tool

tool string abspath(string path)
tool string abspath(string path, string workdir)

Returns an absolute local file system path, given an absolute or relative local file system path.

Parameters

path

The absolute or relative local file system path. May contain both \ and / as file separators.

workdir

The optional absolute local file system path of the working directory against which to resolve relative paths. May contain both \ and / as file separators. If not specified, relative paths are resolved against the current working directory.

Returns

The absolute local file system path. The path contains file separators for the current platform.

basename tool

tool string basename(string path)

Returns the base name of the given absolute or relative local file system path. The base name of a file or directory is the name of that file or directory. In other words, returns the last part of the given path.

Parameters

path

The absolute or relative local file system path to the file or directory for which to return the base name. May contain both \ and / as file separators. Must not end with \ or /.

Returns

The base name.

Runtime errors

  • If the path ends with \ or /.

chdir tool

tool chdir(string path)

Changes the current working directory to the directory referred to by the given path.

Parameters

path

The absolute or relative local file system path to the new current working directory. Relative paths are resolved against the current working directory. May contain both \ and / as file separators.

Runtime errors

  • If the given path does not exist.

  • If the given path refers to a file rather than a directory.

  • If it can not be determined whether the given path refers to a file or a directory.

chfileext tool

tool string chfileext(string path, string? oldext = null, string? newext = null)

Modifies a path such that it ends with a new extension, removing an old extension if it exists.

Parameters

path

The absolute or relative local file system path to modify. May contain both \ and / as file separators.

oldext

The old extension that can be removed (case insensitive, no . at the start). Use null to not remove an old extension.

newext

The new extension to use (case sensitive, no . at the start). Use null to not add a new extension.

Returns

The changed path, ending with the new extension (if any).

curdir tool

tool string curdir()

Returns the script execution’s current working directory, as an absolute local file system path. The path contains file separators for the current platform.

Returns

The script execution’s current working directory.

dirname tool

tool string dirname(string path)

Returns the absolute directory path of the directory that contains the given file or directory.

Parameters

path

The absolute local file system path that refers to a file or directory. May contain both \ and / as file separators. Must not end with \ or /.

Returns

The absolute directory path of the directory that contains the given file or directory. May contain both \ and / as file separators.

Runtime errors

  • If the given path is not an absolute local file system path.

  • If the given path ends with \ or /.

fileext tool

tool string fileext(string path)

Returns the file extension of the given file, or "" if the file has no file extension.

Parameters

path

The absolute or relative local file system path to the file. May contain both \ and / as file separators.

Returns

The file extension, or "".

hasfileext tool

tool bool hasfileext(string path, string ext)

Does the given file have the given file extension?

Parameters

path

The absolute or relative local file system path to the file. May contain both \ and / as file separators.

ext

The file extension to check for (case sensitive, no . at the start).

Returns

true if the file has the given file extension, false otherwise.

pathjoin tool

tool string pathjoin(string... paths)
tool string pathjoin(list string paths)

Joins paths together. If no paths are given, an empty string is returned. If one path is given, the path is returned.

Parameters

paths

The paths to join together. The first path may be an absolute or relative local file system path. The remaining paths must be relative local file system paths. All paths may contain both \ and / as file separators.

Returns

The joined path. The path contains file separators for the current platform.

scriptpath tool

tool string scriptpath()

Returns the absolute local file system path to the script being executed. The path contains file separators for the current platform.

Returns

The absolute local file system path to the script being executed.