Filesystem

Read and write files in the Lynx workspace.

29 functionssUNC 100%Lynx 0.747

The Filesystem API reads and writes files, manages directories, and opens native file pickers. File paths are relative to the workspace; an empty path selects its root. Paths outside the workspace and disallowed write extensions are rejected. File contents are binary-safe strings. DialogFile and DialogFolder objects operate on the user’s selected items.

Files and folders

readfile

readfile(path: string): string

readfile returns the contents of a workspace file as a binary string.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

string

The file’s bytes, including any embedded NUL characters.

writefile

writefile(path: string, data: string): ()

writefile writes data to a workspace file, replacing any existing contents.

Parameters

pathstring
The file or directory path relative to the workspace.
datastring
The bytes that replace the file’s contents.

Returns

()

This function returns no values.

appendfile

appendfile(path: string, data: string): ()

appendfile adds data to the end of a workspace file without replacing its contents.

Parameters

pathstring
The file or directory path relative to the workspace.
datastring
The bytes to append to the file.

Returns

()

This function returns no values.

listfiles

listfiles(path: string): {string}

listfiles returns the files and folders directly inside a workspace directory.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

{string}

An array of workspace-relative child paths.

isfile

isfile(path: string): boolean

isfile returns whether a path refers to an existing regular file.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

boolean

Whether a regular file exists at path.

isfolder

isfolder(path: string): boolean

isfolder returns whether a path refers to an existing directory.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

boolean

Whether a directory exists at path.

makefolder

makefolder(path: string): ()

makefolder creates a workspace directory and any missing parent directories.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

()

This function returns no values.

delfile

delfile(path: string): ()

delfile removes a file from the workspace.

Also available as deletefile.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

()

This function returns no values.

delfolder

delfolder(path: string): ()

delfolder removes a workspace directory and all of its contents.

Also available as deletefolder.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

()

This function returns no values.

loadfile

loadfile(path: string): (function?, string?)

loadfile compiles the source in a workspace file and returns the resulting function without running it.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

(function?, string?)

The compiled function, or nil and a compilation error string.

dofile

dofile(path: string): ()

dofile schedules the source in a workspace file to run.

Also available as runfile.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

()

This function returns no values.

getcustomasset

getcustomasset(path: string): string

getcustomasset makes a workspace file available as a local asset and returns its content URI.

Also available as getsynasset.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

string

The local asset URI, or an explanatory comment string if asset creation fails.

Asynchronous file operations

These calls require a yieldable coroutine. File I/O runs off the calling thread; the coroutine resumes after completion. Embedded NUL bytes in paths are rejected. I/O exceptions propagate as errors rather than the synchronous write functions' log-only result.

readfileasync

Yields
readfileasync(path: string): string

readfileasync reads a workspace file asynchronously and returns its binary contents.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

string

The file’s binary contents after the read completes.

writefileasync

Yields
writefileasync(path: string, data: string): ()

writefileasync asynchronously writes data to a workspace file, replacing its contents.

Parameters

pathstring
The file or directory path relative to the workspace.
datastring
The bytes that replace the file’s contents.

Returns

()

This function returns no values.

appendfileasync

Yields
appendfileasync(path: string, data: string): ()

appendfileasync asynchronously adds data to the end of a workspace file.

Parameters

pathstring
The file or directory path relative to the workspace.
datastring
The bytes to append to the file.

Returns

()

This function returns no values.

loadfileasync

Yields
loadfileasync(path: string): (function?, string?)

loadfileasync asynchronously reads a workspace file and returns a compiled function without running it.

Parameters

pathstring
The file or directory path relative to the workspace.

Returns

(function?, string?)

The compiled function, or nil and a compilation error string.

Native file dialogs

File dialogs let the user choose files or directories through a Windows picker. These calls yield until the picker closes and return nil when cancelled. If options is not a table, defaults are used. Use the returned DialogFile or DialogFolder to work with the selection.

title
Typestring?
Window caption.
defaultPath
Typestring?
Initial filesystem folder.
extensionFilter
Type{string}?
Extensions without a leading dot, such as {"txt", "json"}. An All Files filter is also added. Applies to file pickers.
suggestedName
Typestring?
Initial filename for savefiledialog.
defaultExtension
Typestring?
Default extension for savefiledialog.

openfiledialog

Yields
openfiledialog(options: DialogOptions?): DialogFile?

openfiledialog lets the user choose a file and returns a DialogFile for that selection.

Parameters

optionsDialogOptions??
Optional.The options table for this operation.

Returns

DialogFile?

The selected file, or nil when no selection is available.

Example

local file = openfiledialog({title = "Choose a text file", extensionFilter = {"txt"}})
if file then
print(file:GetName(), file:Read())
end

openfilesdialog

Yields
openfilesdialog(options: DialogOptions?): {DialogFile}?

openfilesdialog lets the user choose multiple files and returns their DialogFile objects.

Parameters

optionsDialogOptions??
Optional.The options table for this operation.

Returns

{DialogFile}?

The selected files, or nil when none are selected.

openfolderdialog

Yields
openfolderdialog(options: DialogOptions?): DialogFolder?

openfolderdialog lets the user choose a directory and returns a DialogFolder for it.

Parameters

optionsDialogOptions??
Optional.The options table for this operation.

Returns

DialogFolder?

The selected folder, or nil when no selection is available.

savefiledialog

Yields
savefiledialog(data: string, options: DialogOptions?): DialogFile?

savefiledialog lets the user choose a destination, writes the supplied data, and returns the saved file.

Parameters

datastring
The bytes to write to the chosen destination.
optionsDialogOptions??
Optional.The options table for this operation.

Returns

DialogFile?

The chosen file, or nil when the dialog is cancelled or the output file cannot be opened.

DialogFile and DialogFolder

Call methods with a colon. Read, Write and Append are synchronous and binary-safe. IsFile and IsFolder report the kind of object selected, not a fresh existence check. Delete does not invalidate the userdata; later methods still use its stored path.

DialogFile:GetName

file:GetName(): string

DialogFile:GetName returns the selected item’s name without its parent directory.

Also available as DialogFolder:GetName.

Returns

string

The basename of the selected file or folder.

DialogFile:IsFile

file:IsFile(): boolean

DialogFile:IsFile returns whether the selected item is a file.

Also available as DialogFolder:IsFile.

Returns

boolean

True for a file object; false for a folder object.

DialogFile:IsFolder

file:IsFolder(): boolean

DialogFile:IsFolder returns whether the selected item is a directory.

Also available as DialogFolder:IsFolder.

Returns

boolean

True for a folder object; false for a file object.

DialogFile:Delete

file:Delete(): ()

DialogFile:Delete removes the selected item and, for a directory, its contents.

Also available as DialogFolder:Delete.

Returns

()

This function returns no values.

DialogFile:Read

file:Read(): string

DialogFile:Read returns the selected file’s contents as a binary string.

Returns

string

The selected file’s binary contents.

DialogFile:Write

file:Write(data: string): ()

DialogFile:Write replaces the selected file’s contents with the supplied data.

Parameters

datastring
The new binary file contents.

Returns

()

This function returns no values.

DialogFile:Append

file:Append(data: string): ()

DialogFile:Append adds data to the end of the selected file.

Parameters

datastring
The binary data to append.

Returns

()

This function returns no values.

DialogFolder:List

folder:List(recursive: boolean?): {DialogFile | DialogFolder}

DialogFolder:List returns the files and directories inside the selected folder.

Parameters

recursiveboolean??
Optional.Whether to include descendants as well as direct children. Default false.

Returns

{DialogFile | DialogFolder}

An array of file and folder objects.

DialogFolder:MakeFolder

folder:MakeFolder(name: string): DialogFolder

DialogFolder:MakeFolder creates a directory within the selected folder and returns its DialogFolder.

Parameters

namestring
The name or relative path of the child directory to create.

Returns

DialogFolder

A folder object for the resulting path.