Filesystem
Read and write files in the Lynx workspace.
- Files and folders
- readfile
- writefile
- appendfile
- listfiles
- isfile
- isfolder
- makefolder
- delfile
- delfolder
- loadfile
- dofile
- getcustomasset
- Asynchronous file operations
- readfileasync
- writefileasync
- appendfileasync
- loadfileasync
- Native file dialogs
- openfiledialog
- openfilesdialog
- openfolderdialog
- savefiledialog
- DialogFile and DialogFolder
- DialogFile:GetName
- DialogFile:IsFile
- DialogFile:IsFolder
- DialogFile:Delete
- DialogFile:Read
- DialogFile:Write
- DialogFile:Append
- DialogFolder:List
- DialogFolder:MakeFolder
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): stringreadfile returns the contents of a workspace file as a binary string.
Parameters
pathstring- The file or directory path relative to the workspace.
Returns
stringThe 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): booleanisfile returns whether a path refers to an existing regular file.
Parameters
pathstring- The file or directory path relative to the workspace.
Returns
booleanWhether a regular file exists at path.
isfolder
isfolder(path: string): booleanisfolder returns whether a path refers to an existing directory.
Parameters
pathstring- The file or directory path relative to the workspace.
Returns
booleanWhether 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): stringgetcustomasset 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
stringThe 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
Yieldsreadfileasync(path: string): stringreadfileasync reads a workspace file asynchronously and returns its binary contents.
Parameters
pathstring- The file or directory path relative to the workspace.
Returns
stringThe file’s binary contents after the read completes.
writefileasync
Yieldswritefileasync(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
Yieldsappendfileasync(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
Yieldsloadfileasync(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.
openfiledialog
Yieldsopenfiledialog(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
openfilesdialog
Yieldsopenfilesdialog(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
Yieldsopenfolderdialog(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
Yieldssavefiledialog(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(): stringDialogFile:GetName returns the selected item’s name without its parent directory.
Also available as DialogFolder:GetName.
Returns
stringThe basename of the selected file or folder.
DialogFile:IsFile
file:IsFile(): booleanDialogFile:IsFile returns whether the selected item is a file.
Also available as DialogFolder:IsFile.
Returns
booleanTrue for a file object; false for a folder object.
DialogFile:IsFolder
file:IsFolder(): booleanDialogFile:IsFolder returns whether the selected item is a directory.
Also available as DialogFolder:IsFolder.
Returns
booleanTrue 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(): stringDialogFile:Read returns the selected file’s contents as a binary string.
Returns
stringThe 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): DialogFolderDialogFolder: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
DialogFolderA folder object for the resulting path.
Written for Lynx 0.747
Something unclear? Tell us on Discord