singleton method IO.read

path で指定されたファイルを offset 位置から length バイト分読み込んで返します。

既に EOF に達している場合は nil を返します。ただし、length に nil か 0 が指定されている場合は、空文字列 "" を返します。例えば、IO.read(空ファイル) は "" を返します。

引数 length が指定された場合はバイナリ読み込みメソッド、そうでない場合はテキスト読み込みメソッドとして動作します。

Kernel.#open と同様 path の先頭が "|" ならば、"|" に続くコマンドの出力を読み取ります。ただし、この "|コマンド名" の特別扱いはレシーバが IO である場合のみ有効です。 File は IO.read を継承していますが、File.read では path の先頭が "|" であっても普通のファイル名として扱われ、コマンドは実行されません。

p IO.read("|echo hello")  # => "hello\n" (コマンドを実行する)
p File.read("|echo hello")  # => Errno::ENOENT ("|echo hello" という名前のファイルを探そうとする)

なお、この "|" によるコマンド起動は Ruby 3.3 から deprecated であり、Ruby 4.0 で削除されました。IO.popen を使用してください。

[PARAM] path:

ファイル名を表す文字列か "|コマンド名" を指定します。 "|コマンド名" はレシーバが IO の場合のみ有効です。

[PARAM] length:

読み込む長さを整数で指定します。nil であるか省略した場合には、EOF まで読み込みます。

[PARAM] offset:

読み込みを始めるオフセットを整数で指定します。

[PARAM] opt:

ファイル path を open する時に使われるオプションをキーワード引数で指定します。

[EXCEPTION] Errno::EXXX:

path のオープン、offset 位置への設定、ファイルの読み込みに失敗した場合に発生します。

[EXCEPTION] ArgumentError:

length が負の場合に発生します。

キーワード引数で有効なキーと値は以下のとおりです。

:encoding

読み込んだ文字列のエンコーディングを指定します。読み込む長さを指定した場合はこれは無視されます。

:mode

IO.open のモードを指定します。 "r" で始まる文字列である必要があります。

:open_args

IO.open に渡される引数を配列で指定します。

これらの他、 :external_encoding など IO.open のオプション引数が指定できます。

[SEE_ALSO] IO.binread

p IO.read(empty_file)           #=> ""
p IO.read(empty_file, 1)        #=> nil
p IO.read(one_byte_file, 0, 10) #=> ""
p IO.read(one_byte_file, nil, 10) #=> "" 
p IO.read(one_byte_file, 1, 10) #=> nil