Update to Sjoerd's documentation of the chunk module, with some

freddrake · freddrake · commit 60b66e1f7b19 · 1999-06-25T17:52:17.000Z
additions from Moshe's version.  Used my table for describing the
chunk format, and added some markup and index entries.
diff --git a/Doc/lib/libchunk.tex b/Doc/lib/libchunk.tex
@@ -1,66 +1,98 @@
 \section{\module{chunk} ---
-         Helper for reading IFF chunks}
+	 Read IFF chunked data}
 
 \declaremodule{standard}{chunk}
-\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
-\modulesynopsis{Helper class for reading from IFF-based file formats.}
+\modulesynopsis{Module to read IFF chunks.}
+\moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
+\sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
 
-The \module{chunk} module defines a class for interfacing to ``IFF''
-chunk-based files, like TIFF or AIFF.  This is used as a helper module
-for the \refmodule{aifc} and \refmodule{wave} modules.
 
-The \module{chunk} module defines the following class:
 
-\begin{classdesc}{Chunk}{file\optional{, align}}
-The chunk from \var{file} starting at \var{file}'s current
-position. The \var{align} argument, which defaults to true, determines 
-whether to align chunk data on 2-byte boundaries.
-
-\exception{EOFError} is raised if \var{file} does not contain enough
-data to read the IFF header.
-\end{classdesc}
+This module provides an interface for reading files that use EA IFF 85
+chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
+Jerry Morrison, Electronic Arts, January 1985.}  This format is used
+in at least the Audio\index{Audio Interchange File
+Format}\index{AIFF}\index{AIFF-C} Interchange File Format
+(AIFF/AIFF-C), the Real\index{Real Media File Format} Media File
+Format\index{RMFF} (RMFF), and the
+Tagged\index{Tagged Image File Format} Image File Format\index{TIFF}
+(TIFF).
 
-The IFF header format is described in this table:
+A chunk has the following structure:
 
 \begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
   \lineiii{0}{4}{Chunk ID}
   \lineiii{4}{4}{Size of chunk in big-endian byte order, including the 
                  header}
+  \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
+                       the preceeding field}
+  \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and
+                                chunk alignment is used}
 \end{tableiii}
 
+The ID is a 4-byte string which identifies the type of chunk.
+
+The size field (a 32-bit value, encoded using big-endian byte order)
+gives the size of the whole chunk, including the 8-byte header.
 
-\subsection{Chunk Objects \label{iff-chunk-objects}}
+Usually an IFF-type file consists of one or more chunks.  The proposed
+usage of the \class{Chunk} class defined here is to instantiate an
+instance at the start of each chunk and read from the instance until
+it reaches the end, after which a new instance can be instantiated.
+At the end of the file, creating a new instance will fail with a
+\exception{EOFError} exception.
 
-Chunk objects have the following methods:
+\begin{classdesc}{Chunk}{file\optional{, align}}
+Class which represents a chunk.  The \var{file} argument is expected
+to be a file-like object.  An instance of this class is specifically
+allowed.  The only method that is needed is \method{read()}.  If the
+methods \method{seek()} and \method{tell()} are present and don't
+raise an exception, they are also used.  If these methods are present
+and raise an exception, they are expected to not have altered the
+object.  If the optional argument \var{align} is true, chunks are
+assumed to be aligned on 2-byte boundaries.  If \var{align} is
+false, no alignment is assumed.  The default value is true.
+\end{classdesc}
+
+A \class{Chunk} object supports the following methods:
 
 \begin{methoddesc}{getname}{}
-Return the ID of the chunk.
+Returns the name (ID) of the chunk.  This is the first 4 bytes of the
+chunk.
 \end{methoddesc}
 
 \begin{methoddesc}{close}{}
-Close the chunk, forwarding the file pointer to the end of the chunk.
+Close and skip to the end of the chunk.  This does not close the
+underlying file.
 \end{methoddesc}
 
+The remaining methods will raise \exception{IOError} if called after
+the \method{close()} method has been called.
+
 \begin{methoddesc}{isatty}{}
-Returns false unless the chunk has been closed, in which case
-\exception{ValueError} is raised.
+Returns \code{0}.
 \end{methoddesc}
 
-\begin{methoddesc}{seek}{offset\optional{, whence}}
-Seek to a position within the chunk. If file pointer is not seekable,
-or \var{offset} would point outside the chunk, an error is raised.
-\var{whence} is interpreted the same as for the \method{seek()} method
-on file objects; see section \ref{bltin-file-objects} for more
-information.
+\begin{methoddesc}{seek}{pos\optional{, whence}}
+Set the chunk's current position.  The \var{whence} argument is
+optional and defaults to \code{0} (absolute file positioning); other
+values are \code{1} (seek relative to the current position) and
+\code{2} (seek relative to the file's end).  There is no return value.
+If the underlying file does not allow seek, only forward seeks are
+allowed.
 \end{methoddesc}
 
 \begin{methoddesc}{tell}{}
-Return the current position within this chunk.
+Return the current position into the chunk.
 \end{methoddesc}
 
-\begin{methoddesc}{read}{\optional{n}}
-Read at most \var{n} bytes from the chunk. If \var{n} is omitted
-or negative, read until the end of the chunk.
+\begin{methoddesc}{read}{\optional{size}}
+Read at most \var{size} bytes from the chunk (less if the read hits
+the end of the chunk before obtaining \var{size} bytes).  If the
+\var{size} argument is negative or omitted, read all data until the
+end of the chunk.  The bytes are returned as a string object.  An
+empty string is returned when the end of the chunk is encountered
+immediately.
 \end{methoddesc}
 
 \begin{methoddesc}{skip}{}
