ファイルシステム API

ファイルシステムヘルパーは ptool.fs と p.fs にあります。

ptool.fs.read

v0.1.0 - Introduced.

ptool.fs.read(path) はファイルを生のバイト列として読み取り、Lua 文字列を 返します。

• path (string, 必須): ファイルパス。
• 戻り値: string。

注意:

• 返される Lua 文字列には、ディスク上のファイルバイトがそのまま入ります。
• テキストファイルは従来どおり扱えますが、バイナリファイルも読み取れます。

例:

local content = ptool.fs.read("README.md")
print(content)

local png = ptool.fs.read("logo.png")
print(#png)

ptool.fs.write

v0.1.0 - Introduced.

ptool.fs.write(path, content) は Lua 文字列を生のバイト列としてファイルへ 書き込み、既存の内容を上書きします。

• path (string, 必須): ファイルパス。
• content (string, 必須): 書き込む内容。

注意:

• content は 1 バイトずつそのまま書き込まれます。
• 埋め込み NUL バイトや非 UTF-8 バイトも保持されます。

例:

ptool.fs.write("tmp/hello.txt", "hello\n")
ptool.fs.write("tmp/blob.bin", "\x00\xffABC")

ptool.fs.append

v0.8.0 - 導入されました。

ptool.fs.append(path, content) は Lua 文字列を生のバイト列としてファイルの末尾に追加します。ファイルが存在しない場合は作成されます。

• path (string, 必須): ファイルパス。
• content (string, 必須): 追加する内容。

注意:

• content はファイルの末尾に 1 バイトずつそのまま書き込まれます。
• 埋め込み NUL バイトや非 UTF-8 バイトも保持されます。

例:

ptool.fs.append("tmp/log.txt", "first line\n")
ptool.fs.append("tmp/log.txt", "second line\n")

ptool.fs.open

v0.8.0 - 導入されました。

ptool.fs.open(path[, mode]) はローカルファイルを開き、File オブジェクトを返します。

引数:

• path (string, 必須): ファイルパス。
• mode (string, 任意): ファイルモード。デフォルトは "r" です。

サポートされるモード:

• "r": 読み込み用に開きます。
• "w": 書き込み用に開き、既存内容を切り詰め、必要ならファイルを作成します。
• "a": 追記用に開き、必要ならファイルを作成します。
• "r+": 切り詰めずに読み書き用で開きます。
• "w+": 読み書き用に開き、既存内容を切り詰め、必要ならファイルを作成します。
• "a+": 読み込みと追記用に開き、必要ならファイルを作成します。

注意:

• モードには "rb" や "w+b" のように b を含められます。
• a と a+ の書き込みは常にファイル末尾に行われます。

例:

local file = ptool.fs.open("tmp/log.txt", "a+")
file:write("hello\n")
file:flush()
file:close()

File

v0.8.0 - 導入されました。

File は ptool.fs.open() が返す、開かれたローカルファイルハンドルです。

Lua userdata として実装されています。

メソッド:

• file:read([n]) -> string
• file:write(content) -> nil
• file:flush() -> nil
• file:seek([whence[, offset]]) -> integer
• file:close() -> nil

read

v0.8.0 - 導入されました。

正規 API 名: ptool.fs.File:read。

file:read([n]) は現在のファイル位置からバイト列を読み取り、Lua 文字列として返します。

• n (integer, 任意): 読み取る最大バイト数。省略時は現在位置から EOF まで読み取ります。
• 戻り値: string。

動作:

• EOF では空文字列を返します。
• 生のバイト列を読むため、バイナリデータはそのまま保持されます。

例:

local file = ptool.fs.open("README.md")
local prefix = file:read(16)
local rest = file:read()
file:close()

write

v0.8.0 - 導入されました。

正規 API 名: ptool.fs.File:write。

file:write(content) は現在のファイル位置に Lua 文字列を書き込みます。

• content (string, 必須): 書き込むバイト列。

動作:

• 指定したとおりの生バイト列を書き込みます。
• append モードのハンドルでは、書き込みはファイル末尾に追加されます。

flush

v0.8.0 - 導入されました。

正規 API 名: ptool.fs.File:flush。

file:flush() はバッファされたファイル書き込みを OS にフラッシュします。

seek

v0.8.0 - 導入されました。

正規 API 名: ptool.fs.File:seek。

file:seek([whence[, offset]]) は現在のファイル位置を移動します。

• whence (string, 任意): "set"、"cur"、"end" のいずれか。デフォルトは "cur" です。
• offset (integer, 任意): whence からの相対バイトオフセット。デフォルトは 0 です。
• 戻り値: integer。

動作:

• 新しい絶対ファイル位置を返します。
• "set" では offset に 0 以上の値が必要です。

例:

local file = ptool.fs.open("tmp/data.bin", "w+")
file:write("abcdef")
file:seek("set", 2)
print(file:read(2)) -- cd
file:close()

close

v0.8.0 - 導入されました。

正規 API 名: ptool.fs.File:close。

file:close() はファイルハンドルを閉じます。

動作:

• 閉じた後は、そのファイルハンドルは使えなくなります。

ptool.fs.mkdir

v0.1.0 - Introduced.

ptool.fs.mkdir(path) はディレクトリを作成します。親ディレクトリが存在 しない場合は再帰的に作成されます。

• path (string, 必須): ディレクトリパス。

例:

ptool.fs.mkdir("tmp/a/b")

ptool.fs.exists

v0.1.0 - Introduced.

ptool.fs.exists(path) はパスが存在するか確認します。

• path (string, 必須): ファイルまたはディレクトリのパス。
• 戻り値: boolean。

例:

if ptool.fs.exists("tmp/hello.txt") then
  print("exists")
end

ptool.fs.is_file

v0.6.0 - 導入されました。

ptool.fs.is_file(path) は、パスが存在し通常ファイルかどうかを確認します。

• path (string, 必須): 確認するパス。
• 戻り値: boolean。

例:

if ptool.fs.is_file("tmp/hello.txt") then
  print("file")
end

ptool.fs.is_dir

v0.6.0 - 導入されました。

ptool.fs.is_dir(path) は、パスが存在しディレクトリかどうかを確認します。

• path (string, 必須): 確認するパス。
• 戻り値: boolean。

例:

if ptool.fs.is_dir("tmp") then
  print("dir")
end

ptool.fs.remove

v0.6.0 - 導入されました。

ptool.fs.remove(path[, options]) は、ファイル、シンボリックリンク、 ディレクトリを削除します。

• path (string, 必須): 削除するパス。
• options (table, 任意): 削除オプション。サポートされるフィールド:
  • recursive (boolean, 任意): ディレクトリを再帰的に削除するかどうか。 デフォルトは false。
  • missing_ok (boolean, 任意): パスが存在しない場合に無視するかどうか。 デフォルトは false。

動作:

• ファイルとシンボリックリンクは recursive なしで削除できます。
• 空でないディレクトリは recursive = true が必要です。
• 不明なオプション名や不正な値型はエラーになります。

例:

ptool.fs.remove("tmp/hello.txt")
ptool.fs.remove("tmp/cache", { recursive = true })
ptool.fs.remove("tmp/missing.txt", { missing_ok = true })

ptool.fs.copy

v0.1.0-alpha.4 - Introduced. v0.9.0 - ローカル間コピーでディレクトリと、ファイルコピー時の宛先ディレクトリ動作をサポート。

ptool.fs.copy(src, dst[, options]) は、ローカルパス間、またはローカルパスと SSH リモートパスの間でファイルやディレクトリをコピーします。

• src (string|remote path, required): コピー元パス。ローカルパスには文字列を使います。リモートパスには conn:path(...) で作成した値を使います。
• dst (string|remote path, required): コピー先パス。ローカルパスには文字列を使います。リモートパスには conn:path(...) で作成した値を使います。
• options (table, optional): 転送オプション。
• 戻り値: 次のフィールドを持つテーブル。
  • bytes (integer): コピーされた通常ファイルのバイト数。ディレクトリをコピーする場合は、コピーされた各ファイルサイズの合計です。
  • from (string): コピー元パス。
  • to (string): コピー先パス。

サポートされる転送オプション:

• parents (boolean, optional): 必要に応じて最終的なローカルまたはリモートのコピー先パスの親ディレクトリを作成します。デフォルトは false です。
• overwrite (boolean, optional): 既存のコピー先ファイルや最終コピー先ディレクトリを置き換えたり再利用したりできるかどうか。デフォルトは true です。
• echo (boolean, optional): 実行前に転送内容を表示するかどうか。デフォルトは false です。

動作:

• ローカル間コピーはファイルとディレクトリの両方をサポートします。
• src がファイルで dst がファイルパスの場合、その正確なパスにコピーされます。
• src がファイルで dst がすでにディレクトリとして存在する場合、コピー元ファイルの basename を使ってそのディレクトリ配下にコピーされます。
• src がファイルで dst が / または \\ で終わる場合、dst はコピー先ディレクトリパスとして扱われ、コピー後のファイルはコピー元ファイルの basename を保持します。そのディレクトリがまだ存在しない場合は、parents = true で作成できます。
• src がディレクトリで dst が存在しない場合、dst がコピー先ディレクトリのルートになります。
• src がディレクトリで dst がすでにディレクトリとして存在する場合、コピー元ディレクトリの basename を使ってその配下にコピー元ディレクトリが作成されます。
• overwrite = false の場合、すでに存在するコピー先ファイルや最終コピー先ディレクトリは拒否されます。
• ローカルディレクトリのコピーでは、コピー元ディレクトリの内側にあるコピー先は拒否されます。
• ローカルからリモートへのコピーは conn:upload(...) と同じコピー先ルールに従います。
• リモートからローカルへのコピーは conn:download(...) と同じコピー先ルールに従います。
• リモート間コピーはサポートされません。

例:

local res = ptool.fs.copy("./dist/app.tar.gz", "./tmp/releases/", {
  parents = true,
  overwrite = true,
  echo = true,
})

print(res.bytes)
print(res.to)

ディレクトリ例:

local res = ptool.fs.copy("./dist/assets", "./tmp/releases", {
  parents = true,
  overwrite = true,
})

print(res.bytes)
print(res.to)

リモート例:

local ssh = ptool.ssh.connect("deploy@example.com")

local res = ptool.fs.copy("./dist/assets", ssh:path("/srv/app/releases"), {
  parents = true,
  overwrite = true,
  echo = true,
})

print(res.bytes)
print(res.to)

ptool.fs.glob

v0.2.0 - Introduced. v0.5.0 - working_dir オプションを追加。

ptool.fs.glob(pattern[, options]) は Unix 風 glob 構文でファイルシステムパスを 照合し、辞書順に並んだ一致パスの文字列配列を返します。

• pattern (string, 必須): glob パターン。相対パターンは現在の ptool ランタイムディレクトリから解決されるため、 ptool.cd(...) に従います。
• options (table, 任意): glob オプション。サポートされるフィールド:
  • working_dir (string, 任意): 相対パターンの解決に使う基準 ディレクトリを上書きします。相対 working_dir は現在の ptool ランタイムディレクトリから解決されます。
• 戻り値: string[]。
• 隠しファイルや隠しディレクトリは、対応するパターン要素が明示的に . で始まる場合にだけ一致します。

例:

ptool.cd("src")

local rust_files = ptool.fs.glob("**/*.rs")
local hidden = ptool.fs.glob("**/.secret/*.txt")
local lua_scripts = ptool.fs.glob("**/*.lua", {
  working_dir = "../scripts",
})