qode/docs/path.md

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

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

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

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

{
  { 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.

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

mkdir

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

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

remove

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

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

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

touch

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

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

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

read

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

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

write

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

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

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

Файл создаётся, если его нет. Родительский каталог должен существовать. Ошибка записи становится ошибкой 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

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")