names=open
visibility=public
kind=defined

--- open(file, mode_enc = "r", perm = 0666) -> IO
--- open(file, mode_enc = "r", perm = 0666) {|io| ... } -> object

file をオープンして、[[c:IO]]（[[c:File]]を含む）クラスのインスタンスを返します。

ブロックが与えられた場合、指定されたファイルをオープンし、
生成した [[c:IO]] オブジェクトを引数としてブロックを実行します。
ブロックの終了時や例外によりブロックを脱出するとき、
ファイルをクローズします。ブロックを評価した結果を返します。

ファイル名 file が `|' で始まる時には続く文字列をコマンドとして起動し、
コマンドの標準入出力に対してパイプラインを生成します

ファイル名が "|-" である時、open は Ruby の子プロセス
を生成し、その子プロセスとの間のパイプ([[c:IO]]オブジェクト)を返し
ます。(このときの動作は、[[m:IO.popen]] と同じです。
[[m:File.open]] にはパイプラインを生成する機能はありません)。

Perlと異なりコマンドは常に `|' で始まります。

@param file ファイルを文字列で指定します。整数を指定した場合はファイルディスクリプタとして扱います。
@param mode_enc モード・エンコーディングを文字列か定数の論理和で指定します。後述。
@param perm [[man:open(2)]] の第 3 引数のように、ファイルを生成する場合の
  ファイルのパーミッションを整数で指定します。
@raise Errno::EXXX ファイルのオープンに失敗した場合に発生します。 


@see [[m:File.open]],[[m:IO.popen]],[[m:IO.open]]

==== 第二引数のオープンモード・エンコーディング
文字列("mode" か "mode:ext_enc" か "mode:ext_enc:int_enc" という形式)か
整数([[c:File::Constants]] モジュールの定数の論理和)を組み合わせて指定します。

mode は以下の三つのうちのいずれかです。

: "r", RDONLY
    ファイルを読み込みモードでオープンします。（デフォルトのモード）

: "w", WRONLY|CREAT|TRUNC
    ファイルを書き込みモードでオープンします。
    オープン時にファイルがすでに存在していれば
    その内容を空にします。

: "a", WRONLY|CREAT|APPEND
    ファイルを書き込みモードでオープンします。
    出力は 常に ファイルの末尾に追加されます。
    例えば、ファイルオープン中にファイルのサイズが小さ
    くなってもその末尾に出力されます。

以上の3つの後に "+" があれば、ファイルは読み書き両用モード (RDWR)
でオープンされます。

: "r+"
    ファイルの読み書き位置は先頭にセットされます。

: "w+"
    "r+" と同じですが、オープン時にファイルがすでに
    存在していればその内容を空にします。

: "a+"
    "r+"と同様、ファイルの読み込み位置は先頭にセットされますが、
    書き込みは常にファイル末尾に行われます。書き込みは
    [[m:IO#seek]] などの影響を受けません。

これらのいずれに対しても "b" フラグを ("r+b"のように) つけることがで
きます (整数なら File::BINARY )。この場合、バイナリモードでオープン
します (ただし、DOS/Windowsのようにシステムがテキスト／バイナリでファイルを区別する場
合に限ります)

==== Universal Newline
改行をLFに揃えます。一言で言えばPEP:278 [[url:http://www.python.org/dev/peps/pep-0278/]]のことです。

: "rt"
    CR、LF、CRLFのいずれをもLFとして読み込む。
: "rb"
    CR、LF、CRLFはいずれもそのまま読み込まれる。
: "r"
    "rt"と"rb"のどちらの扱いになるかはプラットフォーム依存。
    (Unix系ならばなら"rb"、mswinやmingwなら"rt"扱いとなる)
: "wb"
    LFはそのままLFとして書き込まれる。
: "wt" または "w"
    LFはLFのままか、CR+LFか、どちらかになる。どちらになるかはプラットフォーム依存。
    (Unix系ならばLFのまま、mswinやmingwならばCRLFとなる)

なお、以上のCR、LF、CRLFは入力のエンコーディングを解釈した後に処理されます。例えば、UTF-16LEでは、LFはバイト列"\x0a\x00"のことになります。

==== エンコーディングの指定
ext_enc(外部エンコーディング)が指定されている場合、
読み込まれた文字列にはこのエンコーディングが指定され、
出力する文字列はそのエンコーディングに変換されます。

ext_encが'BOM|'で始まる場合、その入力に含まれるBOMはあらかじめ削られます。
また、BOMがあった場合、入力された文字列にはそのBOMに対応するエンコーディングが設定されます。
  # BOMでUTF-16BEかLEかを判別する例
  File.open("utf16.txt", "rb:BOM|utf-16"){|file| .... }

int_encも指定されていた場合、入力された文字列をext_encでエンコーディングされた文字列とみなしてint_encへと変換し、その結果にint_encを設定して返します。

