Doc/lib/libchunk.tex

   1 \section{\module{chunk} ---
   2          Read IFF chunked data}
   3
   4 \declaremodule{standard}{chunk}
   5 \modulesynopsis{Module to read IFF chunks.}
   6 \moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
   7 \sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
   8
   9
  10
  11 This module provides an interface for reading files that use EA IFF 85
  12 chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
  13 Jerry Morrison, Electronic Arts, January 1985.}  This format is used
  14 in at least the Audio\index{Audio Interchange File
  15 Format}\index{AIFF}\index{AIFF-C} Interchange File Format
  16 (AIFF/AIFF-C), the Real\index{Real Media File Format} Media File
  17 Format\index{RMFF} (RMFF), and the
  18 Tagged\index{Tagged Image File Format} Image File Format\index{TIFF}
  19 (TIFF).
  20
  21 A chunk has the following structure:
  22
  23 \begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
  24   \lineiii{0}{4}{Chunk ID}
  25   \lineiii{4}{4}{Size of chunk in big-endian byte order, including the
  26                  header}
  27   \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
  28                        the preceeding field}
  29   \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and
  30                                 chunk alignment is used}
  31 \end{tableiii}
  32
  33 The ID is a 4-byte string which identifies the type of chunk.
  34
  35 The size field (a 32-bit value, encoded using big-endian byte order)
  36 gives the size of the whole chunk, including the 8-byte header.
  37
  38 Usually an IFF-type file consists of one or more chunks.  The proposed
  39 usage of the \class{Chunk} class defined here is to instantiate an
  40 instance at the start of each chunk and read from the instance until
  41 it reaches the end, after which a new instance can be instantiated.
  42 At the end of the file, creating a new instance will fail with a
  43 \exception{EOFError} exception.
  44
  45 \begin{classdesc}{Chunk}{file\optional{, align}}
  46 Class which represents a chunk.  The \var{file} argument is expected
  47 to be a file-like object.  An instance of this class is specifically
  48 allowed.  The only method that is needed is \method{read()}.  If the
  49 methods \method{seek()} and \method{tell()} are present and don't
  50 raise an exception, they are also used.  If these methods are present
  51 and raise an exception, they are expected to not have altered the
  52 object.  If the optional argument \var{align} is true, chunks are
  53 assumed to be aligned on 2-byte boundaries.  If \var{align} is
  54 false, no alignment is assumed.  The default value is true.
  55 \end{classdesc}
  56
  57 A \class{Chunk} object supports the following methods:
  58
  59 \begin{methoddesc}{getname}{}
  60 Returns the name (ID) of the chunk.  This is the first 4 bytes of the
  61 chunk.
  62 \end{methoddesc}
  63
  64 \begin{methoddesc}{close}{}
  65 Close and skip to the end of the chunk.  This does not close the
  66 underlying file.
  67 \end{methoddesc}
  68
  69 The remaining methods will raise \exception{IOError} if called after
  70 the \method{close()} method has been called.
  71
  72 \begin{methoddesc}{isatty}{}
  73 Returns \code{0}.
  74 \end{methoddesc}
  75
  76 \begin{methoddesc}{seek}{pos\optional{, whence}}
  77 Set the chunk's current position.  The \var{whence} argument is
  78 optional and defaults to \code{0} (absolute file positioning); other
  79 values are \code{1} (seek relative to the current position) and
  80 \code{2} (seek relative to the file's end).  There is no return value.
  81 If the underlying file does not allow seek, only forward seeks are
  82 allowed.
  83 \end{methoddesc}
  84
  85 \begin{methoddesc}{tell}{}
  86 Return the current position into the chunk.
  87 \end{methoddesc}
  88
  89 \begin{methoddesc}{read}{\optional{size}}
  90 Read at most \var{size} bytes from the chunk (less if the read hits
  91 the end of the chunk before obtaining \var{size} bytes).  If the
  92 \var{size} argument is negative or omitted, read all data until the
  93 end of the chunk.  The bytes are returned as a string object.  An
  94 empty string is returned when the end of the chunk is encountered
  95 immediately.
  96 \end{methoddesc}
  97
  98 \begin{methoddesc}{skip}{}
  99 Skip to the end of the chunk.  All further calls to \method{read()}
 100 for the chunk will return \code{''}.  If you are not interested in the
 101 contents of the chunk, this method should be called so that the file
 102 points to the start of the next chunk.
 103 \end{methoddesc}