File - Starline Lua API

Read and write files under Documents\Starline\scripts\data. Paths cannot escape this directory.

local settings = { volume = 0.5, names = { "a", "b" } }

file.Write("myscript/settings.json", json.Encode(settings))

local text = file.Read("myscript/settings.json")
if text then
    settings = json.Decode(text) or settings
end

Paths

Paths are relative to the data folder. Both / and \ separate folders. Writes create parent folders.

Rejected
`..`, `.`	as a path component
`C:\...`, `/foo`, `\foo`	absolute paths
`:` `*` `?` `"` `<` `>` `\|`	and control characters
`CON`, `NUL`, `COM1`, …	Windows device names
trailing `.` or space	in a component
over 200 characters

A bad path raises an error. Everything else below returns a value or nil/false plus an error string.

Read

local text, err = file.Read(path)

The whole file as a string, or nil and an error. Bytes are returned as-is.

Write

local ok, err = file.Write(path, content)

Creates or replaces the file. content is a string.

Append

local ok, err = file.Append(path, content)

Adds to the end, creating the file if missing.

Exists

if file.Exists(path) then ... end

true for a file or folder.

Delete

local ok, err = file.Delete(path)

Deletes a file, or an empty folder. Deleting something that isn’t there returns false, "not found".

List

local names = file.List()          -- files in the data folder
local names = file.List("myscript") -- files in a subfolder

Table of file names (no folders, not recursive), relative to the folder listed. A folder that doesn’t exist lists as empty.

Dir

print(file.Dir())   -- C:\Users\you\Documents\Starline\scripts\data

Limits


file size	8 MB, for Read, Write and Append
errors	`not found`, `access denied`, `file in use`, `folder not empty`, `disk full`, `file too large`, `content too large`, otherwise `error N` with the Win32 code

Calls are synchronous. Files are shared between scripts, so use a script-specific subfolder.

​Paths

​Read

​Write

​Append

​Exists

​Delete

​List

​Dir

​Limits