"fileinput" --- 複数の入力ストリームをまたいだ行の繰り返し処理をサポートする
****************************************************************************

**ソースコード:** Lib/fileinput.py

======================================================================

このモジュールは標準入力やファイルの並びにまたがるループを素早く書くた
めのヘルパークラスと関数を提供しています。単一のファイルを読み書きした
いだけなら、 "open()" を参照してください。

典型的な使い方は以下の通りです:

   import fileinput
   for line in fileinput.input():
       process(line)

このスクリプトは "sys.argv[1:]" に列挙されている全てのファイルの行に渡
って反復処理を行います。もし列挙されているものがなければ、 "sys.stdin"
がデフォルトとして扱われます。 ファイル名として "'-'" が与えられた場合
も、 "sys.stdin" に置き換えられ、 *mode* と *openhook* は無視されます
。 別のファイル名リストを使いたい時には、そのリストを "input()" の最初
の引数に与えます。 ファイル名が 1 つでも受け付けます。

全てのファイルはデフォルトでテキストモードでオープンされます。しかし、
"input()" や "FileInput" をコールする際に *mode* パラメータを指定すれ
ば、これをオーバーライドすることができます。オープン中あるいは読み込み
中にI/Oエラーが発生した場合には、 "OSError" が発生します。

バージョン 3.3 で変更: 以前は "IOError" が送出されました; それは現在
"OSError" のエイリアスです。

"sys.stdin" が2回以上使われた場合は、2回目以降は行を返しません。ただし
インタラクティブに利用している時や明示的にリセット
("sys.stdin.seek(0)" を使う) を行った場合はその限りではありません。

空のファイルは開いた後すぐ閉じられます。空のファイルはファイル名リスト
の最後にある場合にしか外部に影響を与えません。

ファイルの各行は、各種改行文字まで含めて返されます。ファイルの最後が改
行文字で終っていない場合には、改行文字で終わらない行が返されます。

ファイルのオープン方法を制御するためのオープン時フックは、
"fileinput.input()" あるいは "FileInput()" の *openhook* パラメータで
設定します。このフックは、ふたつの引数 *filename* と *mode* をとる関数
でなければなりません。そしてその関数の返り値はオープンしたファイルオブ
ジェクトとなります。このモジュールには、便利なフックが既に用意されてい
ます。

以下の関数がこのモジュールの基本的なインタフェースです:

fileinput.input(files=None, inplace=False, backup='', *, mode='r', openhook=None)

   "FileInput" クラスのインスタンスを作ります。生成されたインスタンス
   は、このモジュールの関数群が利用するグローバルな状態として利用され
   ます。この関数への引数は "FileInput" クラスのコンストラクタへ渡され
   ます。

   "FileInput" のインスタンスは "with" 文の中でコンテキストマネージャ
   ーとして使用できます。 次の例では、仮に例外が生じたとしても "with"
   文から抜けた後で *input* は閉じられます:

      with fileinput.input(files=('spam.txt', 'eggs.txt')) as f:
          for line in f:
              process(line)

   バージョン 3.2 で変更: コンテキストマネージャとして使うことができる
   ようになりました。

   バージョン 3.8 で変更: キーワード引数 *mode* と *openhook* は、キー
   ワード専用引数になりました。

以下の関数は "fileinput.input()" 関数によって作られたグローバルな状態
を利用します。アクティブな状態が無い場合には、 "RuntimeError" が発生し
ます。

fileinput.filename()

   現在読み込み中のファイル名を返します。一行目が読み込まれる前は
   "None" を返します。

fileinput.fileno()

   現在のファイルの "ファイル記述子" を整数値で返します。ファイルがオ
   ープンされていない場合 (最初の行の前、ファイルとファイルの間) は
   "-1" を返します。

fileinput.lineno()

   最後に読み込まれた行の、累積した行番号を返します。1行目が読み込まれ
   る前は "0" を返します。最後のファイルの最終行が読み込まれた後には、
   その行の行番号を返します。

fileinput.filelineno()

   現在のファイル中での行番号を返します。1行目が読み込まれる前は "0"
   を返します。最後のファイルの最終行が読み込まれた後には、その行のフ
   ァイル中での行番号を返します。

fileinput.isfirstline()

   最後に読み込まれた行がファイルの1行目なら "True" 、そうでなければ
   "False" を返します。

fileinput.isstdin()

   最後に読み込まれた行が "sys.stdin" から読み込まれていれば "True" 、
   そうでなければ  "False" を返します。

fileinput.nextfile()

   現在のファイルを閉じます。次の繰り返しでは(存在すれば)次のファイル
   の最初の行が読み込まれます。閉じたファイルの読み込まれなかった行は
   、累積の行数にカウントされません。ファイル名は次のファイルの最初の
   行が読み込まれるまで変更されません。最初の行の読み込みが行われるま
   では、この関数は呼び出されても何もしませんので、最初のファイルをス
   キップするために利用することはできません。最後のファイルの最終行が
   読み込まれた後にも、この関数は呼び出されても何もしません。

fileinput.close()

   シーケンスを閉じます。

このモジュールのシーケンスの振舞いを実装しているクラスのサブクラスを作
ることもできます:

class fileinput.FileInput(files=None, inplace=False, backup='', *, mode='r', openhook=None)

   "FileInput" クラスはモジュールの関数に対応するメソッド "filename()"
   、 "fileno()" 、 "lineno()" 、 "filelineno()" 、 "isfirstline()" 、
   "isstdin()" 、 "nextfile()" および "close()" を実装しています。それ
   に加えて、次の入力行を返す "readline()" メソッドと、シーケンスの振
   舞いの実装をしている "__getitem__()" メソッドがあります。シーケンス
   はシーケンシャルに読み込むことしかできません。つまりランダムアクセ
   スと "readline()" を混在させることはできません。

   *mode* を使用すると、 "open()" に渡すファイルモードを指定することが
   できます。これは "'r'" 、 "'rU'" 、 "'U'" および "'rb'" のうちのい
   ずれかとなります。

   *openhook* を指定する場合は、ふたつの引数 *filename* と *mode* をと
   る関数でなければなりません。この関数の返り値は、オープンしたファイ
   ルオブジェクトとなります。*inplace* と *openhook* を同時に使うこと
   はできません。

   "FileInput" のインスタンスは "with" 文の中でコンテキストマネージャ
   ーとして使用できます。 次の例では、仮に例外が生じたとしても "with"
   文から抜けた後で *input* は閉じられます:

      with FileInput(files=('spam.txt', 'eggs.txt')) as input:
          process(input)

   バージョン 3.2 で変更: コンテキストマネージャとして使うことができる
   ようになりました。

   バージョン 3.4 で非推奨: "'rU'" および "'U'" モード。

   バージョン 3.8 で非推奨: meth:*__getitem__* メソッドのサポートは非
   推奨になりました。

   バージョン 3.8 で変更: キーワード引数 *mode* と *openhook* は、キー
   ワード専用引数になりました。

**インプレース(in-place)フィルタオプション:** キーワード引数
"inplace=True" が "fileinput.input()" か "FileInput" クラスのコンスト
ラクタに渡された場合には、入力ファイルはバックアップファイルに移動され
、標準出力が入力ファイルに設定されます(バックアップファイルと同じ名前
のファイルが既に存在していた場合には、警告無しに置き替えられます)。こ
れによって入力ファイルをその場で書き替えるフィルタを書くことができます
。キーワード引数 *backup* (通常は "backup='.<拡張子>'" という形で利用
します)が与えられていた場合、バックアップファイルの拡張子として利用さ
れ、バックアップファイルは削除されずに残ります。デフォルトでは、拡張子
は "'.bak'" になっていて、出力先のファイルが閉じられればバックアップフ
ァイルも消されます。インプレースフィルタ機能は、標準入力を読み込んでい
る間は無効にされます。

このモジュールには、次のふたつのオープン時フックが用意されています:

fileinput.hook_compressed(filename, mode)

   gzip や bzip2 で圧縮された (拡張子が "'.gz'" や "'.bz2'" の) ファイ
   ルを、 "gzip" モジュールや "bz2" モジュールを使って透過的にオープン
   します。ファイルの拡張子が "'.gz'" や "'.bz2'" でない場合は、通常通
   りファイルをオープンします (つまり、 "open()" をコールする際に伸長
   を行いません)。

   使用例: "fi =
   fileinput.FileInput(openhook=fileinput.hook_compressed)"

fileinput.hook_encoded(encoding, errors=None)

   各ファイルを "open()" でオープンするフックを返します。指定した
   *encoding* および *errors* でファイルを読み込みます。

   使用例: "fi =
   fileinput.FileInput(openhook=fileinput.hook_encoded("utf-8",
   "surrogateescape"))"

   バージョン 3.6 で変更: オプションの *errors* 引数が追加されました。
