126 lines
5.0 KiB
Markdown
126 lines
5.0 KiB
Markdown
# Файловая система — `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")
|
|
```
|