"chunk" --- IFFチャンクデータの読み込み
***************************************

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

バージョン 3.11 で非推奨、バージョン 3.13 で削除予定: The "chunk"
module is deprecated (see **PEP 594** for details).

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

このモジュールはEA IFF 85チャンクを使用しているファイルの読み込みのた
めのインターフェースを提供します。[1] このフォーマットは少なくとも、
Audio Interchange File Format (AIFF/AIFF-C) とReal Media File Format
(RMFF)で使われています。WAVEオーディオファイルフォーマットも厳密に対応
しているので、このモジュールで読み込みできます。

チャンクは以下の構造を持っています:

+-----------+----------+---------------------------------+
| Offset値  | 長さ     | 内容                            |
|===========|==========|=================================|
| 0         | 4        | チャンクID                      |
+-----------+----------+---------------------------------+
| 4         | 4        | big- endianで示したチャンクのサ |
|           |          | イズで、ヘッダは含みません      |
+-----------+----------+---------------------------------+
| 8         | *n*      | バイトデータで、*n* はこれより  |
|           |          | 先のフィールドのサイズ          |
+-----------+----------+---------------------------------+
| 8 + *n*   | 0 or 1   | *n* が奇数ならチャンクの整頓の  |
|           |          | ために埋められるバイト          |
+-----------+----------+---------------------------------+

IDはチャンクの種類を識別する4バイトの文字列です。

サイズフィールド（big-endianでエンコードされた32ビット値）は、8バイト
のヘッダを含まないチャンクデータのサイズを示します。

普通、IFFタイプのファイルは1個かそれ以上のチャンクからなります。このモ
ジュールで定義される "Chunk" クラスの使い方として提案しているのは、そ
れぞれのチャンクの始めにインスタンスを作り、終わりに達するまでそのイン
スタンスから読み取り、その後で新しいインスタンスを作るということです。
ファイルの終わりで新しいインスタンスを作ろうとすると、 "EOFError" の例
外が発生して失敗します。

class chunk.Chunk(file, align=True, bigendian=True, inclheader=False)

   チャンクを表わすクラス。 *file* 引数はファイル風オブジェクトである
   と期待されます。このクラスのインスタンスは特別に許可されます。唯一
   の必要なメソッドは "read()" です。メソッド "seek()" および "tell()"
   が存在し、例外を上げない場合、それらも使用されます。これらのメソッ
   ドが存在し、例外を上げる場合、それらのメソッドはオブジェクトを変更
   しないことが想定されます。オプションの引数 *align* が true の場合、
   チャンクは2バイト境界上で整列されていると仮定されます。 *align* が
   false の場合、整列は仮定されません。デフォルト値は true です。オプ
   ションの引数 *bigendian* が false の場合、チャンクサイズはリトルエ
   ンディアン順になっていると仮定されます。これは WAVE オーディオファ
   イルに必要とされます。デフォルト値は true です。オプションの引数
   *inclheader* が true の場合、チャンクヘッダ中で与えられたサイズはヘ
   ッダのサイズを含んでいます。デフォルト値は false です。

   "Chunk" オブジェクトには以下のメソッドが定義されています:

   getname()

      チャンクの名前（ID）を返します。これはチャンクの始めの4バイトで
      す。

   getsize()

      チャンクのサイズを返します。

   close()

      オブジェクトを閉じて、チャンクの終わりまで飛びます。これは元のフ
      ァイル自体は閉じません。

   "close()" メソッドが呼ばれた後で他のメソッドを呼ぶと "OSError" が送
   出されます。 Python 3.3 以前は "IOError" (現在は "OSError" の別名)
   が送出されていました。

   isatty()

      "False" を返します。

   seek(pos, whence=0)

      チャンクの現在位置を設定します。引数 *whence* は省略可能で、デフ
      ォルト値は "0" （ファイルの絶対位置）です; 他に "1" （現在位置か
      ら相対的にシークします）と "2" （ファイルの末尾から相対的にシー
      クします）の値を取ります。何も値は返しません。もし元のファイルが
      シークに対応していなければ、前方へのシークのみが可能です。

   tell()

      チャンク内の現在位置を返します。

   read(size=-1)

      チャンクから最大で *size* バイト読み込みます ( *size* バイトを読
      み込むより前にチャンクの最後に行き着いたら、それより少なくなりま
      す) 。もし引数 *size* が負か省略されたら、チャンクの最後まで全て
      のデータを読み込みます。チャンクの最後に行き着いたら、空の bytes
      オブジェクトを返します。

   skip()

      チャンクの最後まで飛びます。さらにチャンクの "read()" を呼び出す
      と、 "b''" が返されます。もしチャンクの内容に興味がないなら、こ
      のメソッドを呼び出してファイルポインタを次のチャンクの始めに設定
      します。

-[ 脚注 ]-

[1] "EA IFF 85" Standard for Interchange Format Files, Jerry Morrison,
    Electronic Arts, January 1985.
