Copiar um arquivo ou diretório (file.copy)
Declaração
sucesso, mensagem_de_erro = file.copy(caminho_de_origem, caminho_de_destino [, modo])
Parâmetros
- caminho de origem
Texto; caminho absoluto do arquivo ou diretório de origem. - caminho de destino
Texto; caminho absoluto completo do arquivo ou diretório após a cópia, incluindo o nome do arquivo ou diretório de destino. - modo (20250914+)
Texto opcional; modo de cópia:- string vazia ou omitido: modo padrão (no-clobber), falha quando o destino já existe
- "overwrite" ou "o": modo de substituição, substitui diretamente o destino existente (o destino existente será excluído)
- "merge" ou "m": modo de mesclagem (somente para diretórios), preserva arquivos já existentes no destino
- "overwrite-merge" ou "om"/"mo": modo de mesclagem com substituição, mescla diretórios mas substitui arquivos com o mesmo nome
Valores retornados
- sucesso
Booleano; retorna true em caso de sucesso e false em caso de falha. - mensagem de erro
Texto; mensagem de erro em caso de falha.
Observações
Copia o arquivo ou diretório indicado por
caminho_de_origemcom o caminho exatocaminho_de_destino.
Esta função significa “copiar como”, e não “copiar para dentro de”.caminho_de_destinoespecifica o arquivo ou diretório final; o nome do arquivo ou diretório de origem não é adicionado automaticamente. Mesmo que o destino já exista e seja um diretório, ou que seu caminho termine em/, a origem não será colocada dentro desse diretório.
Por exemplo, para copiar/a/b/cpara dentro de/d/e/preservando o nomec, o caminho de destino deve ser/d/e/c, não apenas/d/e/.
Se o destino já existir, aplica-se o parâmetromodo: o modo padrão falha, o modo de substituição substitui o próprio destino e os modos de mesclagem de diretórios mesclam o conteúdo do diretório de origem no diretório de destino.
Palavras-chave: copiar arquivo, copiar diretório, copiar pasta.
Disponível somente em versões posteriores a 20250313.
Exemplo
ok, err = file.copy(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('Falha ao copiar: '..err)
end
Observação: o código acima usa a função sys.alert, que não pertence a este capítulo.
Copiar para outro diretório preservando o nome
-- Suponha que /d/e seja um diretório existente e que /d/e/c ainda não exista
file.copy('/a/b/c', '/d/e/c') -- Correto: copiar c como /d/e/c
-- Forma incorreta: o destino é o próprio e, não c dentro do diretório e
file.copy('/a/b/c', '/d/e/') -- Falha no modo padrão porque o destino já existe
-- O modo de substituição substitui o próprio e e não cria /d/e/c (20250914+)
-- file.copy('/a/b/c', '/d/e/', 'overwrite')
Definir uma função para copiar para dentro de um diretório
O exemplo a seguir define uma função auxiliar personalizada e requer uma versão posterior a 20250914. O diretório de destino deve existir. A função preserva o nome do arquivo ou diretório de origem e passa o parâmetro opcional mode para file.copy. Conflitos de nomes continuam sendo tratados conforme o modo indicado.
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
-- Evita usar o próprio diretório de destino ou seu diretório pai como destino final.
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
-- Suponha que /d/e seja um diretório existente; copiar c como /d/e/c
local ok, err = file_copy_into("/a/b/c", "/d/e/")
if not ok then
print("Falha ao copiar: "..err)
end
-- Para substituir /d/e/c, especifique o modo de substituição na chamada:
-- file_copy_into("/a/b/c", "/d/e/", "overwrite")
Observação: o código acima usa file.exists, file.path.last_component e file.path.add_component.