> ## Documentation Index
> Fetch the complete documentation index at: https://lua.starline.one/llms.txt
> Use this file to discover all available pages before exploring further.

# File

> Read and write script data inside the Starline sandboxed data directory.

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

```lua theme={"dark"}
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

```lua theme={"dark"}
local text, err = file.Read(path)
```

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

## Write

```lua theme={"dark"}
local ok, err = file.Write(path, content)
```

Creates or replaces the file. `content` is a string.

## Append

```lua theme={"dark"}
local ok, err = file.Append(path, content)
```

Adds to the end, creating the file if missing.

## Exists

```lua theme={"dark"}
if file.Exists(path) then ... end
```

`true` for a file or folder.

## Delete

```lua theme={"dark"}
local ok, err = file.Delete(path)
```

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

## List

```lua theme={"dark"}
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

```lua theme={"dark"}
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.