Pular para o conteúdo principal

Mover um arquivo ou diretório (file.move)

Declaração​

sucesso, mensagem_de_erro = file.move(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 movimentação, incluindo o nome do arquivo ou diretório de destino.
  • modo (20250914+)
    Texto opcional; modo de movimentação:
    • 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​

Move o arquivo ou diretório indicado por caminho_de_origem para o caminho exato caminho_de_destino; alterar o nome no mesmo diretório equivale a renomeá-lo.
Esta função significa “mover como”, e não “mover para dentro de”. caminho_de_destino especifica 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 mover /a/b/c para dentro de /d/e/ preservando o nome c, o caminho de destino deve ser /d/e/c, não apenas /d/e/.
Se o destino já existir, aplica-se o parâmetro modo: 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: renomear arquivo, renomear diretório, renomear pasta, mover arquivo, mover diretório, mover pasta.
Disponível somente em versões posteriores a 20250313.

Exemplo​

ok, err = file.move(XXT_SCRIPTS_PATH..'/1.zip', XXT_SCRIPTS_PATH..'/2.zip')
if not ok then
sys.alert('Falha ao mover: '..err)
end

Observação: o código acima usa a função sys.alert, que não pertence a este capítulo.

Mover 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.move('/a/b/c', '/d/e/c') -- Correto: mover c para /d/e/c

-- Exemplo incorreto independente: o destino é o próprio e, não c dentro do diretório e
-- file.move('/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.move('/a/b/c', '/d/e/', 'overwrite')

Definir uma função para mover 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.move. Conflitos de nomes continuam sendo tratados conforme o modo indicado.

local function file_move_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.move(src_path, dst_path, mode)
end

-- Suponha que /d/e seja um diretório existente; mover c para /d/e/c
local ok, err = file_move_into("/a/b/c", "/d/e/")
if not ok then
print("Falha ao mover: "..err)
end

-- Para substituir /d/e/c, especifique o modo de substituição na chamada:
-- file_move_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.