Append a file extension (file.path.add_extension)

Declaration

new_path, err = file.path.add_extension(path, extension)

Parameters

• path
  String. The base path string.
• extension
  String. The file extension to append, usually without a leading ..

Returns

• new_path
  String or nil. Returns the path string with the extension appended on success, or nil if it cannot be appended.
• err
  String. Returns "Invalid path" if the path string is invalid, or "Invalid extension" if the extension string is invalid. If the extension cannot be appended, for example because it contains /, the function may return only nil without an error message.

Description

Append . and the specified extension to the path. If the path already has an extension, append the new extension after it; for example, appending bak to file.txt produces file.txt.bak.
The supplied extension may contain a leading ., but this function does not remove it; passing .txt appends ..txt.
This function only generates a path string; it does not rename any actual file or directory.
This function is available only in versions released after 20250914.

Example

local new_path = file.path.add_extension("/path/to/file", "txt") -- Returns "/path/to/file.txt"
local archive_path = file.path.add_extension("/path/to/file.tar", "gz") -- Returns "/path/to/file.tar.gz"
local backup_path = file.path.add_extension("/path/to/file.txt", "bak") -- Returns "/path/to/file.txt.bak"
local dotted_path = file.path.add_extension("/path/to/file", ".txt") -- Returns "/path/to/file..txt"