# Файловая система — `api.path`

Группа `api.path` даёт базовые операции с файлами и каталогами. Все методы,
принимающие путь, понимают две формы:

```lua
api.path:list("src/main")          -- строка с разделителями
api.path:list({ "src", "main" })   -- массив сегментов
```

Путь отсчитывается от текущего рабочего каталога процесса. Пустой путь,
`nil` и `{ }` означают сам текущий каталог (для `list` и `mkdir`).

## Методы

| Метод | Описание |
| --- | --- |
| `api.path:list(path)` | Содержимое каталога |
| `api.path:mkdir(path)` | Создать каталоги, включая родительские; вернуть созданный путь |
| `api.path:remove(path)` | Удалить файл или каталог рекурсивно |
| `api.path:touch(path)` | Создать пустой файл, если его нет, и обновить время изменения |
| `api.path:read(path)` | Прочитать файл в строку |
| `api.path:write(path, text, append)` | Записать строку в файл и вернуть путь |

### `list`

Возвращает массив элементов каталога:

```lua
{
  { id = "src/main.rs", name = "main.rs", is_dir = false },
  { id = "src/tools",   name = "tools",   is_dir = true  },
}
```

- `id` — путь элемента относительно текущего каталога, если переданный путь
  тоже относительный. Его можно сразу передать в `api.editor:open(id)` и
  использовать как идентификатор узла дерева.
- `name` — имя без пути.
- `is_dir` — является ли элемент каталогом.

Элементы отсортированы по имени без учёта регистра. Ошибка чтения каталога
становится ошибкой Lua.

```lua
for _, entry in ipairs(api.path:list("src")) do
  print(entry.name, entry.is_dir)
end
```

### `mkdir`

Создаёт каталоги последовательно, вместе со всеми отсутствующими родителями,
и возвращает созданный путь с разделителями `/`. Пустые сегменты
пропускаются. Для пустого пути ничего не создаёт и возвращает пустую строку.

```lua
api.path:mkdir({ "foo", "bar" })  -- foo, затем foo/bar; вернёт "foo/bar"
api.path:mkdir("foo/bar")         -- то же самое
```

### `remove`

Удаляет файл, символическую ссылку или каталог вместе со всем содержимым.
Для каталога используется рекурсивное удаление.

Возвращает `true`, если что-то было удалено, и `false`, если пути не
существовало. Пустой путь удалять нельзя — это ошибка Lua.

```lua
api.path:remove("build")
api.path:remove({ "src", "generated" })
```

### `touch`

Создаёт пустой файл, если его нет. Содержимое существующего файла не
меняется, обновляется только время изменения. Родительский каталог должен
существовать — при необходимости создайте его через `mkdir`.

Возвращает путь с разделителями `/`.

```lua
api.path:touch({ "src", "notes.txt" })
```

### `read`

Читает файл целиком и возвращает строку. Ошибка чтения становится ошибкой Lua.

```lua
local text = api.path:read("src/main.rs")
```

### `write`

Записывает строку в файл:

```lua
api.path:write(path, text, append)
```

- `append = true` — дописать содержимое в конец;
- `append = false` или `nil` — перезаписать файл с нуля.

Файл создаётся, если его нет. Родительский каталог должен существовать.
Ошибка записи становится ошибкой Lua. Метод возвращает путь с разделителями `/`.

```lua
api.path:write("notes.txt", "first\n")
api.path:write("notes.txt", "second\n", true)  -- "first\nsecond\n"
api.path:write("notes.txt", "reset\n")         -- "reset\n"
```

## Пример: создание файла из Lua

```lua
local function create_file(parent, name, content)
  api.path:mkdir(parent)
  local path = api.path:write({ parent, name }, content or "")
  api.editor:open(path, {})
end

create_file("src", "new.lua", "-- новый файл\n")
```