6.8 入出力機能

I/O ライブラリはファイル操作を二つのスタイルで提供します。一つ目のスタイルは暗黙のファイルハンドルを使うものです。デフォルトの入出力ファイルを設定するための関数が提供され、全ての入出力操作はこのデフォルトファイルを使って行われます。もう一つのスタイルは明示的なファイルハンドルを使うものです。

暗黙なファイルハンドルを使う全ての操作は io テーブルを通して提供されます。明示的なファイルハンドルを使う全ての操作は io.open が返すファイルハンドラのメソッドとして提供されます。

ファイルハンドラのメタテーブルには __gc と __close が設定されており、この二つのメタメソッドはファイルのクローズを試みます。

io テーブルには stdio, stdout, stderr というファイルハンドラが定義されています。意味は C と同様であり、I/O ライブラリはこれらのファイルをクローズしません。

特に断っていない限り、I/O 関数が失敗すると次の三つの値が返ります:

POSIX でないシステムではエラーメッセージの計算処理が C 変数 errno に依存していてスレッドセーフでない可能性があります。

io.close ([file])

file:close() と等価です。file を指定しないと、デフォルトの出力ファイルをクローズします。

io.flush ()

io.output():flush() と等価です。

io.input ([file])

ファイル名を与えて呼び出すと、指定されたファイルを (テキストモードで) オープンし、そのハンドルをデフォルトの入力ファイルに設定します。ファイルハンドルを与えて呼び出すと、そのファイルハンドルをデフォルトの入力ファイルに設定する処理だけが行われます。引数を与えずに呼び出すと、現在設定されているデフォルトの入力ファイルを返します。

この関数はエラーが起こるとエラーを送出します。エラーコードを返すことはありません。

io.lines ([filename, ...])

指定されたファイルを読み込みモードで開き、そのファイルに対する file:lines(...) が返すのと同じイテレータを返します。ただしこの関数が返すイテレータ関数は値を読むのに失敗したときにファイルを自動的にクローズします。io.lines はイテレータ関数の他に二つの nil (プレースホルダー) と作成されたファイルハンドルという三つの値を返します。このため一般的な for 文を使うと、エラーや break でループを抜けたときにもファイルがクローズされます。

ファイル名を指定しない io.lines() という呼び出しは io.input():lines("l") と等価です。つまりデフォルトの入力ファイルの各行をイテレートします。この場合イテレータはループの終わりにファイルをクローズしません。

ファイルのオープンでエラーが起こると、この関数はエラーを送出します。エラーコードを返すことはありません。

io.open (filename [, mode])

文字列 mode で指定されるモードでファイルをオープンします。成功すると新しいファイルハンドルが返ります。

文字列 mode は次のいずれかです:

一部のシステムではファイルをバイナリモードで開くときに mode 文字列の終端に b が必要になります。

io.output ([file])

io.input と同じ処理をデフォルトの出力ファイルに対して行います。

io.popen (prog [, mode])

この関数はシステム依存であり、一部のプラットフォームでは利用できません。

プログラム prog を別のプロセスで開始します。mode が "r" (デフォルト値) ならこのプログラムからデータを読み込むためのファイルハンドルを返し、mode が "w" ならこのプログラムへデータを書き込むためのファイルハンドルを返します。

io.read (...)

io.input():read() と等価です。

io.tmpfile ()

成功すると、一時ファイルのハンドルを返します。このファイルは更新モードでオープンされ、プログラムが終了するときに削除されます。

io.type (obj)

obj が正当なファイルハンドルかどうかを判定します。obj がオープンされたファイルハンドルなら文字列 "file" を返し、クローズされたファイルハンドルなら文字列 "closed file" を返します。obj がファイルハンドルでない場合には fail が返ります。

io.write (...)

io.input():write() と等価です。

file:close ()

file をクローズします。この関数を使わずともファイルハンドルがガベージコレクトされるときにファイルは自動的にクローズされますが、そうするとクローズのタイミングを制御できないことに注意してください。

io.popen で作成したファイルハンドルをクローズする場合には、file:close の返り値は os.execute の返り値と同じになります。

file:flush ()

今までに書き込んだ全てのデータを file に保存します。

file:lines (...)

呼び出されるたびに指定されたフォーマットに従ってファイルを読み込むイテレータ関数を返します。フォーマットの指定方法は file:read と同様であり、フォーマットが指定されない場合には "l" がデフォルトで使われます。例えばコード

for c in file:lines(1) do body end

はファイルに含まれる文字を現在位置から終わりまで一文字ずつイテレートします。io.lines と異なり、この関数はループの終わりでファイルをクローズしません。

file:read (...)

指定されたフォーマットでファイル file からデータを読み込みます。フォーマットに応じて、この関数は読み込んだ文字列または数値、そして読み込んだ文字数を返します。指定されたフォーマットでデータを読み込めなかった場合には fail を返します (それ以降のフォーマットは読み込まれません)。引数無しに呼ばれた場合には次の行を読むデフォルトのフォーマットが使われます (下記参照)。

利用可能なフォーマットは次の通りです:

フォーマット "l" と "L" はテキストファイルに対してだけ使われるべきです。

file:seek ([whence [, offset]])

ファイルの位置を設定および取得します。この関数が返すファイルの位置はファイルの先頭から測定した値であり、文字列 whence で指定される基準から offset だけ進んだ位置を表します。whence として可能な値とその意味は次の通りです:

成功すると、seek は最終的なファイルの位置をファイルの先頭から測った値を返します。seek が失敗した場合には fail とエラーを説明する文字列が返ります。

デフォルトでは whence は "cur" で offset は 0 です。このため file:seek() は現在のファイルの位置を返し、そのとき位置は変更されません。また file:seek("set") を呼び出すと現在位置がファイル先頭に移動して 0 が返り、file:seek("end") を呼び出すと位置がファイル末尾に移動してファイルのサイズが返ります。

file:setvbuf (mode [, size])

ファイルのバッファリングモードを設定します。利用可能なモードは次の三つです:

最後の二つのモードでは、size がバッファのサイズのヒントとなります (単位はバイト)。デフォルトでは常識的なサイズ1が設定されています。

各モードの動作の詳細はポータブルではありません。詳細は内部で利用される ISO C 関数 sevbuf をプラットフォームごとに確認してください。

file:write (...)

引数の値を file に書き込みます。引数は文字列または数値である必要があります。

成功すると file を返します。

  1. 訳注: ソースコードによると 16 * sizeof(void*) * sizeof(lua_Number) バイト。64 ビットマシンで 64 ビット浮動小数点数を使っているなら 1024 バイトとなる。[return]

広告
このページの文章はテキストゆれないくんを使って校正されました。