Перейти к основному содержимому

Копирование файла или каталога (file.copy)

Объявление​

успех, сообщение_об_ошибке = file.copy(исходный_путь, целевой_путь [, режим])

Параметры​

  • исходный_путь
    Строка, абсолютный путь к исходному файлу или каталогу
  • целевой_путь
    Строка, полный абсолютный путь к файлу или каталогу после операции, включая имя целевого файла или каталога
  • Режим, начиная с 20250914
    Строка, необязательный параметр, режим копирования. Возможные значения:
    • пустая строка или отсутствие параметра: режим по умолчанию (no-clobber), при существовании цели возвращается ошибка
    • "overwrite" или "o": режим перезаписи, существующая цель заменяется напрямую (существующая цель удаляется)
    • "merge" или "m": режим объединения (только для каталогов), существующие в цели файлы сохраняются
    • "overwrite-merge" или "om"/"mo": режим объединения с перезаписью, каталоги объединяются, но одноимённые файлы заменяются

Возвращаемое значение​

  • успех
    Логическое значение: true при успехе и false при ошибке
  • сообщение_об_ошибке
    Строка, сообщение об ошибке при неудаче

Описание​

Выполняет копирование файла или каталога, на который указывает исходный_путь, под именем и по адресу, заданным параметром целевой_путь
Функция выполняет копирование «в объект с указанным путём», а не «внутрь указанного каталога». целевой_путь задаёт конечный файл или каталог; имя исходного файла или каталога автоматически не добавляется. Даже если цель уже существует и является каталогом либо целевой путь заканчивается на /, исходный файл или каталог не помещается внутрь этого каталога
Например, чтобы выполнить копирование /a/b/c внутрь /d/e/ с сохранением имени c, нужно указать целевой путь /d/e/c, а не просто /d/e/
Если цель уже существует, обработка определяется параметром режим: режим по умолчанию возвращает неудачу, режим перезаписи заменяет саму цель, а режим объединения каталогов объединяет содержимое исходного каталога с целевым каталогом
Ключевые слова: копирование файла, копирование каталога, копирование папки
Доступно в версиях после 20250313

Пример​

ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('Ошибка копирования: '..err)
end

Примечание: приведённый выше код использует функцию не из этой главы — sys.alert.

Копирование в другой каталог с сохранением имени​

-- Предположим, что /d/e — существующий каталог, а /d/e/c ещё не существует
file.copy('/a/b/c', '/d/e/c') -- Верно: копирование c по пути /d/e/c

-- Неверная запись: целью является сам e, а не c в каталоге e
file.copy('/a/b/c', '/d/e/') -- В режиме по умолчанию операция завершится неудачей, поскольку цель уже существует

-- Режим перезаписи заменит сам e, а не создаст /d/e/c (20250914+)
-- file.copy('/a/b/c', '/d/e/', 'overwrite')

Функция-обёртка для операции «копирование внутрь каталога»​

Ниже приведён пример пользовательской функции-обёртки, для которой требуется версия после 20250914. Целевой каталог должен существовать. Функция сохраняет имя исходного файла или каталога и передаёт необязательный параметр mode в file.copy. При совпадении имён обработка по-прежнему определяется указанным режимом.

local function file_copy_into(src_path, dst_dir, mode)
if file.exists(dst_dir) ~= "directory" then
return false, "Target is not a directory"
end

local name, err = file.path.last_component(src_path)
if not name then
return false, err
end
-- Не допускаем использования самого целевого каталога или его родителя в качестве конечной цели.
if name == "" or name == "/" or name == "." or name == ".." then
return false, "Source path must end with a file or directory name"
end

local dst_path, path_err = file.path.add_component(dst_dir, name)
if not dst_path then
return false, path_err
end
return file.copy(src_path, dst_path, mode)
end

-- Предположим, что /d/e — существующий каталог; выполняем копирование c по пути /d/e/c
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
print("Ошибка копирования: "..err)
end

-- Чтобы заменить /d/e/c, при вызове можно указать режим перезаписи:
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")

Примечание: код выше использует file.exists, file.path.last_component и file.path.add_component.