メインコンテンツまでスキップ

ファイルまたはディレクトリを移動する (file.move)

宣言​

操作成否, エラー情報 = file.move(移動元パス, 移動先パス [, モード])

パラメータ​

  • 移動元パス
    文字列型。元のファイルまたはディレクトリの絶対パス
  • 移動先パス
    文字列型。移動後のファイルまたはディレクトリの完全な絶対パス。対象のファイル名またはディレクトリ名を含みます
  • モード 20250914+
    文字列型。省略可能。移動モード。指定できる値:
    • 空文字列または省略:デフォルトモード(no-clobber)。移動先がすでに存在する場合は失敗を返します
    • "overwrite" または "o":上書きモード。既存の移動先をそのまま置き換えます(既存の移動先は削除されます)
    • "merge" または "m":マージモード(ディレクトリのみ)。移動先にすでに存在するファイルを保持します
    • "overwrite-merge" または "om"/"mo":上書きマージモード。ディレクトリをマージし、同名のファイルを上書きします

戻り値​

  • 操作成否
    ブール型。操作に成功した場合は true、失敗した場合は false を返します
  • エラー情報
    文字列型。操作に失敗した場合のエラー情報

説明​

移動元パス が指すファイルまたはディレクトリを、移動先パス で指定した名前と場所に移動します。同じディレクトリ内で名前を変更する場合は、リネームに相当します
この関数は「指定したパスを移動先にする」操作であり、「指定したディレクトリの中に移動する」操作ではありません。移動先パス は最終的なファイルまたはディレクトリを指定し、元のファイル名やディレクトリ名は自動追加されません。移動先がすでに存在するディレクトリである場合や、パスが / で終わる場合でも、そのディレクトリ内に元のファイルやディレクトリを配置することはありません
例えば、/a/b/c を名前 c のまま /d/e/ 内に移動するには、移動先パスを /d/e/c と指定する必要があります。/d/e/ だけではいけません
移動先がすでに存在する場合は モード に従います。デフォルトモードでは失敗を返し、上書きモードでは移動先自体を置き換え、ディレクトリのマージモードでは元のディレクトリの内容を移動先ディレクトリにマージします
キーワード:ファイル名の変更、ディレクトリ名の変更、フォルダー名の変更、ファイルの移動、ディレクトリの移動、フォルダーの移動
この関数は 20250313 以降のバージョンでのみ使用できます

使用例​

ok, err = file.move(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.move('/a/b/c', '/d/e/c') -- 正しい指定:c を /d/e/c として移動します

-- 以下は独立した誤った指定の例です。対象は e 自体であり、e ディレクトリ内の c ではありません
-- file.move('/a/b/c', '/d/e/') -- デフォルトモードでは対象がすでに存在するため失敗します

-- 上書きモードでは e 自体を置き換え、/d/e/c は作成しません(20250914+)
-- file.move('/a/b/c', '/d/e/', 'overwrite')

「ディレクトリ内に移動する」関数の作成​

以下は独自のラッパー関数の例で、20250914 以降のバージョンが必要です。対象のディレクトリは存在している必要があります。この関数は元のファイル名またはディレクトリ名を保持し、省略可能な mode パラメータを file.move に渡します。同名の項目がある場合も、指定したモードに従って処理します。

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
-- 対象のディレクトリ自体やその親ディレクトリを最終的な対象にしないためのチェックです。
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

-- /d/e が既存のディレクトリであるとして、c を /d/e/c として移動します
local ok, err = file_move_into("/a/b/c", "/d/e/")
if not ok then
print("移動失敗:"..err)
end

-- /d/e/c を置き換えるには、呼び出し時に上書きモードを指定します:
-- file_move_into("/a/b/c", "/d/e/", "overwrite")

注:上記のコードでは、file.exists、file.path.last_component、file.path.add_component を使用しています。