
:mod:`chunk` --- IFFチャンクデータの読み込み
============================================

.. module:: chunk
   :synopsis: IFFチャンクデータの読み込み。
.. moduleauthor:: Sjoerd Mullender <sjoerd@acm.org>
.. sectionauthor:: Sjoerd Mullender <sjoerd@acm.org>


.. index::
   single: Audio Interchange File Format
   single: AIFF
   single: AIFF-C
   single: Real Media File Format
   single: RMFF

このモジュールはEA IFF 85チャンクを使用しているファイルの読み込みのためのインターフェースを提供します。 [#]_
このフォーマットは少なくとも、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個かそれ以上のチャンクからなります。
このモジュールで定義される :class:`Chunk` クラスの使い方として提案しているのは、
それぞれのチャンクの始めにインスタンスを作り、終わりに達するまでそのインスタンスから読み取り、
その後で新しいインスタンスを作るということです。
ファイルの終わりで新しいインスタンスを作ろうとすると、 :exc:`EOFError` の例外が発生して失敗します。


.. class:: Chunk(file[, align, bigendian, inclheader])

   チャンクを表現するクラス。引数 *file* はファイルのようなオブジェクトであることが想定されています。
   このクラスのインスタンスは一つだけ特別に許可されています。
   必要とされるメソッドは :meth:`read` だけです。
   もし :meth:`seek` と :meth:`tell` メソッドが呼び出されて例外を発生させなかったら、これらのメソッドも動作します。
   これらのメソッドが呼び出されて例外を発生させても、オブジェクトを変化させないようになっています。

   省略可能な引数 *align* がtrueなら、チャンクデータが偶数個で2バイトごとに整頓されていると想定します。
   もし *align* がfalseなら、チャンクデータが奇数個になっていると想定します。デフォルト値はtrueです。

   もし省略可能な引数 *bigendian* がfalseなら、チャンクサイズは little-endianであると想定します。
   この引数の設定はWAVEオーディオファイルで必要です。デフォルト値はtrueです。

   もし省略可能な引数 *inclheader* がtrueなら、チャンクのヘッダから得られるサイズはヘッダのサイズを含んでいると想定します。
   デフォルト値はfalseです。

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


   .. method:: getname()

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


   .. method:: getsize()

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


   .. method:: close()

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

   残りの以下のメソッドは、 :meth:`close` メソッドを呼び出した後に呼び出すと例外 :exc:`IOError` を発生します。


   .. method:: isatty()

      ``False`` を返します。


   .. method:: seek(pos[, whence])

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


   .. method:: tell()

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


   .. method:: read([size])

      チャンクから最大で *size* バイト（
      *size* バイトを読み込むまで、少なくともチャンクの最後に行き着くまで）読み込みます。
      もし引数 *size* が負か省略されたら、チャンクの最後まで全てのデータを読み込みます。
      バイト値は文字列のオブジェクトとして返されます。
      チャンクの最後に行き着いたら、空文字列を返します。


   .. method:: skip()

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

.. rubric:: 注記

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

