6.9 – 入出力機能

I/Oライブラリは、ファイル操作に2つの異なる方式を提供します。1つ目は暗黙のファイルハンドルを使います。つまり、デフォルトの入力ファイルとデフォルトの出力ファイルを設定する操作があり、すべての入出力操作はこれらのデフォルトファイルに対して行われます。2つ目の方式は明示的なファイルハンドルを使います。

暗黙のファイルハンドルを使う場合、すべての操作はテーブルioによって提供されます。明示的なファイルハンドルを使う場合、操作io.openがファイルハンドルを返し、その後のすべての操作はファイルハンドルのメソッドとして提供されます。

ファイルハンドルのメタテーブルは、呼び出されたときにファイルを閉じようとする__gcと__closeのメタメソッドを提供します。

テーブルioは、Cにおける通常の意味を持つ、事前定義された3つのファイルハンドルも提供します：io.stdin、io.stdout、io.stderr。I/Oライブラリがこれらのファイルを閉じることはありません。

特に記載がない限り、すべてのI/O関数は、失敗時にfail、第2結果としてエラーメッセージ、第3結果としてシステム依存のエラーコードを返し、成功時には偽でない何らかの値を返します。POSIXでないシステムでは、エラー発生時のエラーメッセージとエラーコードの計算がグローバルC変数errnoに依存するため、スレッドセーフでない場合があります。

`io.close ([file])`

file:close()と等価です。fileがなければ、デフォルトの出力ファイルを閉じます。

`io.flush ()`

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

`io.input ([file])`

ファイル名を指定して呼び出すと、その名前のファイルをテキストモードで開き、そのハンドルをデフォルトの入力ファイルに設定します。ファイルハンドルを指定して呼び出すと、そのファイルハンドルをデフォルトの入力ファイルに設定するだけです。引数なしで呼び出すと、現在のデフォルト入力ファイルを返します。

エラーの場合、この関数はエラーコードを返す代わりにエラーを発生させます。

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

指定されたファイル名を読み取りモードで開き、開いたファイルに対してfile:lines(···)と同様に動作するイテレーター関数を返します。イテレーター関数が値の読み取りに失敗すると、ファイルを自動的に閉じます。io.linesはイテレーター関数に加えて3つの値、すなわちプレースホルダーとして2つのnil値と、作成したファイルハンドルを返します。したがって、汎用forループで使うと、エラーまたはbreakによってループが中断された場合もファイルが閉じられます。

呼び出しio.lines()（ファイル名なし）はio.input():lines("l")と等価です。つまり、デフォルト入力ファイルの行を反復処理します。この場合、ループ終了時にイテレーターはファイルを閉じません。

ファイルを開く際にエラーが起きた場合、この関数はエラーコードを返す代わりにエラーを発生させます。

`io.open (filename [, mode])`

この関数は、文字列modeで指定されたモードでファイルを開きます。成功した場合は新しいファイルハンドルを返します。

文字列modeには次のいずれかを指定できます。

“r”：読み取りモード（デフォルト）。
“w”：書き込みモード。
“a”：追記モード。
“r+”：更新モード。以前のデータはすべて保持されます。
“w+”：更新モード。以前のデータはすべて消去されます。
“a+”：追記更新モード。以前のデータは保持され、書き込みはファイル末尾でのみ許可されます。文字列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"、objが閉じたファイルハンドルなら"closed file"を返し、objがファイルハンドルでなければfailを返します。

`io.write (···)`

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

`file:close ()`

fileを閉じます。ファイルはハンドルがガベージコレクションされると自動的に閉じられますが、それが起こるまでの時間は予測できないことに注意してください。

io.popenで作成したファイルハンドルを閉じるとき、file:closeはos.executeが返す値と同じ値を返します。

`file:flush ()`

書き込まれたすべてのデータをfileへ保存します。

`file:lines (···)`

呼び出されるたびに、指定された形式に従ってファイルを読み取るイテレーター関数を返します。形式を指定しない場合、デフォルトとして”l”を使います。たとえば、次の構文は

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

現在位置から始めて、ファイルのすべての文字を反復処理します。io.linesとは異なり、この関数はループ終了時にファイルを閉じません。

`file:read (···)`

何を読み取るかを指定する形式に従って、ファイルfileを読み取ります。関数は形式ごとに、読み取った文字を持つ文字列または数値を返し、指定された形式でデータを読み取れなければfailを返します。（後者の場合、関数は後続の形式を読み取りません。）引数なしで呼び出すと、次の行を読み取るデフォルト形式を使います（以下を参照）。

利用可能な形式は次のとおりです。

“n”：数値表記を読み取り、Luaの字句規則に従って浮動小数点数または整数として返します。（数値表記の先頭には空白と符号があっても構いません。）この形式は常に、数値表記の有効な接頭辞となる最長の入力列を読み取ります。その接頭辞が有効な数値表記を構成しない場合（例：空文字列、” 0x “、または” 3.4e- ”）、あるいは長すぎる場合（200文字超）、その接頭辞を破棄し、この形式はfailを返します。
“a”：現在位置からファイル全体を読み取ります。ファイル末尾では空文字列を返します。この形式が失敗することはありません。
“l”：行末を除いて次の行を読み取り、ファイル末尾ではfailを返します。これはデフォルトの形式です。
“L”：行末文字（存在する場合）を残して次の行を読み取り、ファイル末尾ではfailを返します。
number：最大でこのバイト数までの文字列を読み取り、ファイル末尾ではfailを返します。 numberが0なら何も読み取らず、空文字列を返します。ファイル末尾ではfailを返します。形式”l”と”L”は、テキストファイルにのみ使用してください。

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

ファイル先頭から測ったファイル位置を、offsetと文字列whenceで指定された基準位置を足した位置に設定し、その位置を取得します。基準位置は次のとおりです。

“set”：基準は位置0（ファイルの先頭）。
“cur”：基準は現在位置。
“end”：基準はファイル末尾。成功した場合、seekはファイル先頭からバイト単位で測った最終的なファイル位置を返します。seekが失敗した場合は、failとエラーを説明する文字列を返します。

whenceのデフォルト値は"cur"、offsetのデフォルト値は0です。したがって、呼び出しfile:seek()は現在のファイル位置を変更せずに返します。呼び出しfile:seek("set")は位置をファイル先頭に設定して0を返します。呼び出しfile:seek("end")は位置をファイル末尾に設定し、そのサイズを返します。

`file:setvbuf (mode [, size])`

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

“no”：バッファリングなし。
“full”：完全バッファリング。
“line”：行バッファリング。後ろの2つの場合、sizeはバッファのバイト単位のサイズに対するヒントです。デフォルトは適切なサイズです。

各モードの具体的な動作には移植性がありません。詳細は、使用するプラットフォームの基盤となるISO C関数setvbufを確認してください。

`file:write (···)`

各引数の値をfileへ書き込みます。引数は文字列または数値でなければなりません。

成功した場合、この関数はfileを返します。それ以外の場合は4つの値、すなわちfail、エラーメッセージ、エラーコード、書き込めたバイト数を返します。