mirror of
https://github.com/python/cpython.git
synced 2024-11-24 18:34:43 +08:00
f8316638af
SourceForge doesn't choke on this batch :-)
I'm not entirely sure this is 100% correct. The patch changes an
\index{persistency} to \index{presistence}, and I don't know what \index{}
does. But it seems to do so persi--er, consistently, so I hope it isn't a
problem.
112 lines
4.5 KiB
TeX
112 lines
4.5 KiB
TeX
\section{\module{chunk} ---
|
|
Read IFF chunked data}
|
|
|
|
\declaremodule{standard}{chunk}
|
|
\modulesynopsis{Module to read IFF chunks.}
|
|
\moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
|
|
\sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
|
|
|
|
|
|
|
|
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) and the Real\index{Real Media File Format} Media File
|
|
Format\index{RMFF} (RMFF). The WAVE audio file format is closely
|
|
related and can also be read using this module.
|
|
|
|
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, not including the
|
|
header}
|
|
\lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
|
|
the preceding 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 chunk data, not including the 8-byte header.
|
|
|
|
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.
|
|
|
|
\begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}}
|
|
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. If the
|
|
optional argument \var{bigendian} is false, the chunk size is assumed
|
|
to be in little-endian order. This is needed for WAVE audio files.
|
|
The default value is true. If the optional argument \var{inclheader}
|
|
is true, the size given in the chunk header includes the size of the
|
|
header. The default value is false.
|
|
\end{classdesc}
|
|
|
|
A \class{Chunk} object supports the following methods:
|
|
|
|
\begin{methoddesc}{getname}{}
|
|
Returns the name (ID) of the chunk. This is the first 4 bytes of the
|
|
chunk.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{getsize}{}
|
|
Returns the size of the chunk.
|
|
\end{methoddesc}
|
|
|
|
\begin{methoddesc}{close}{}
|
|
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 \code{0}.
|
|
\end{methoddesc}
|
|
|
|
\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 into the chunk.
|
|
\end{methoddesc}
|
|
|
|
\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}{}
|
|
Skip to the end of the chunk. All further calls to \method{read()}
|
|
for the chunk will return \code{''}. If you are not interested in the
|
|
contents of the chunk, this method should be called so that the file
|
|
points to the start of the next chunk.
|
|
\end{methoddesc}
|