diff options
Diffstat (limited to 'Doc/lib/libchunk.tex')
-rw-r--r-- | Doc/lib/libchunk.tex | 111 |
1 files changed, 0 insertions, 111 deletions
diff --git a/Doc/lib/libchunk.tex b/Doc/lib/libchunk.tex deleted file mode 100644 index 8e2a494..0000000 --- a/Doc/lib/libchunk.tex +++ /dev/null @@ -1,111 +0,0 @@ -\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{False}. -\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} |