refactoring

docs/path.md

@@ -0,0 +1,125 @@
+# Файловая система — `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")
+```