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

# file

> Сырое чтение и запись файлов в собственном каталоге плагина

# file

Сырое чтение и запись файлов в собственном каталоге плагина.

`file` читает и пишет обычные файлы — байтовую строку целиком, без разбора
формата. Для структурированных данных (таблиц) есть `store`/`datafile`; `file`
для всего остального: csv-экспорт, готовый json, любой текстовый или бинарный
формат, который плагин собирает сам.

```lua theme={null}
file.write("report.csv", "name,score\nplayer1,10\n")
local content = file.read("report.csv")
```

## Песочница

Все имена — только внутри `plugin.data_dir()`, той же папки, куда пишут
`db.open()` и `store`. Подпапок нет — `name` не может содержать `/`, `\`
или что-то похожее на путь.

Имя — это `stem` или `stem.ext`:

* `stem`: буквы, цифры, `_`, `-`
* `.ext` — необязательно, ровно одна точка на всё имя, только буквы и цифры
* максимум 64 символа

Валидно: `report.csv`, `export_2026.json`, `state`.
Невалидно: `../evil.txt`, `sub/dir.txt`, `a.b.c`, `.hidden`, `hidden.`.

## Предел размера

Одно чтение или одна запись/дозапись — не больше 4 МиБ. Больше — `nil` и
причина, ещё до того, как файл открыт: частично записанного файла при отказе
не остаётся.

<h2 id="read">
  file.read
</h2>

Читает содержимое файла целиком.

```lua theme={null}
file.read(name)
```

### Аргументы

| # | имя    | тип    |                                                   |
| - | ------ | ------ | ------------------------------------------------- |
| 1 | `name` | string | имя файла в каталоге плагина (см. песочницу выше) |

### Возвращает

| тип             |                                                             |
| --------------- | ----------------------------------------------------------- |
| `string \| nil` | содержимое файла                                            |
| `string`        | причина, если файл не открылся, его нет или он больше 4 МиБ |

### Пример

```lua theme={null}
local content, err = file.read("report.csv")
if not content then
  print("не смог прочитать: " .. err)
  return
end
```

<Warning>
  Отсутствие файла — тоже ошибка здесь (`nil, "cannot open ..."`), в отличие от
  `file.size`, где отсутствие файла — просто `nil` без причины.
</Warning>

### Смотри также

* [file.size](index.md#size)

<h2 id="write">
  file.write
</h2>

Перезаписывает файл целиком (или создаёт его).

```lua theme={null}
file.write(name, content)
```

### Аргументы

| # | имя       | тип    |                                                   |
| - | --------- | ------ | ------------------------------------------------- |
| 1 | `name`    | string | имя файла в каталоге плагина (см. песочницу выше) |
| 2 | `content` | string | что записать, до 4 МиБ                            |

### Возвращает

| тип              |                    |
| ---------------- | ------------------ |
| `boolean \| nil` | `true` при успехе  |
| `string`         | причина при ошибке |

### Пример

```lua theme={null}
local ok, err = file.write("report.csv", "name,score\n")
if not ok then
  print("не смог записать: " .. err)
end
```

Для дозаписи в конец существующего файла — `file.append`.

### Смотри также

* [file.append](index.md#append)

<h2 id="append">
  file.append
</h2>

Дописывает в конец файла, не трогая то, что уже было (или создаёт его).

```lua theme={null}
file.append(name, content)
```

### Аргументы

| # | имя       | тип    |                                                   |
| - | --------- | ------ | ------------------------------------------------- |
| 1 | `name`    | string | имя файла в каталоге плагина (см. песочницу выше) |
| 2 | `content` | string | что дописать, до 4 МиБ за один вызов              |

### Возвращает

| тип              |                    |
| ---------------- | ------------------ |
| `boolean \| nil` | `true` при успехе  |
| `string`         | причина при ошибке |

### Пример

```lua theme={null}
hook.add("player:death", "myplugin.kills_log", function(e)
  file.append("kills.csv", ("%s,%s\n"):format(e.attacker and e.attacker:name() or "world", e.player:name()))
end)
```

<Warning>
  Предел 4 МиБ — на один вызов, не на итоговый размер файла: у `file.append`
  нет ограничения на то, насколько большим станет файл со временем. Для
  самоограничивающегося лога с ротацией по дням — [`log.write`](../log/index.md).
</Warning>

<h2 id="exists">
  file.exists
</h2>

Проверяет, есть ли файл в каталоге плагина.

```lua theme={null}
file.exists(name)
```

### Аргументы

| # | имя    | тип    |                                                   |
| - | ------ | ------ | ------------------------------------------------- |
| 1 | `name` | string | имя файла в каталоге плагина (см. песочницу выше) |

### Возвращает

| тип       |                                                                                        |
| --------- | -------------------------------------------------------------------------------------- |
| `boolean` | `true`/`false`; неверное имя или отсутствие каталога плагина — тоже `false`, не ошибка |

### Пример

```lua theme={null}
if not file.exists("config.json") then
  file.write("config.json", "{}")
end
```

<h2 id="remove">
  file.remove
</h2>

Удаляет файл из каталога плагина.

```lua theme={null}
file.remove(name)
```

### Аргументы

| # | имя    | тип    |                                                   |
| - | ------ | ------ | ------------------------------------------------- |
| 1 | `name` | string | имя файла в каталоге плагина (см. песочницу выше) |

### Возвращает

| тип              |                                                      |
| ---------------- | ---------------------------------------------------- |
| `boolean \| nil` | `true` при успехе                                    |
| `string`         | причина при ошибке, в том числе если файла и не было |

### Пример

```lua theme={null}
local ok, err = file.remove("tmp.csv")
```

<h2 id="size">
  file.size
</h2>

Возвращает размер файла в байтах.

```lua theme={null}
file.size(name)
```

### Аргументы

| # | имя    | тип    |                                                   |
| - | ------ | ------ | ------------------------------------------------- |
| 1 | `name` | string | имя файла в каталоге плагина (см. песочницу выше) |

### Возвращает

| тип             |                                                                                             |
| --------------- | ------------------------------------------------------------------------------------------- |
| `number \| nil` | размер в байтах; `nil` без причины, если файла нет, имя не годится или нет каталога плагина |

### Пример

```lua theme={null}
local size = file.size("report.csv")
if size and size > 1024 * 1024 then
  file.remove("report.csv")
end
```

### Смотри также

* [file.read](index.md#read)

<h2 id="list">
  file.list
</h2>

Возвращает имена всех файлов верхнего уровня в каталоге плагина.

```lua theme={null}
file.list()
```

### Возвращает

| тип     |                                                           |
| ------- | --------------------------------------------------------- |
| `table` | массив имён файлов; пустой, если каталога плагина ещё нет |

### Пример

```lua theme={null}
for _, name in ipairs(file.list()) do
  print(name)
end
```

<Warning>
  Подпапка `logs/`, которую создаёт [`log.write`](../log/index.md), в список не
  попадает — это отдельное хранилище, не файлы плагина.
</Warning>