Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libchunk.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents fdfd1049f36e
children 2392af05f052
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{chunk} ---
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
2 Read IFF chunked data}
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \declaremodule{standard}{chunk}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
5 \modulesynopsis{Module to read IFF chunks.}
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
6 \moduleauthor{Sjoerd Mullender}{sjoerd@acm.org}
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
7 \sectionauthor{Sjoerd Mullender}{sjoerd@acm.org}
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
11 This module provides an interface for reading files that use EA IFF 85
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
12 chunks.\footnote{``EA IFF 85'' Standard for Interchange Format Files,
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
13 Jerry Morrison, Electronic Arts, January 1985.} This format is used
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
14 in at least the Audio\index{Audio Interchange File
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
15 Format}\index{AIFF}\index{AIFF-C} Interchange File Format
11229
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
16 (AIFF/AIFF-C) and the Real\index{Real Media File Format} Media File
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
17 Format\index{RMFF} (RMFF). The WAVE audio file format is closely
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
18 related and can also be read using this module.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
20 A chunk has the following structure:
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 \begin{tableiii}{c|c|l}{textrm}{Offset}{Length}{Contents}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 \lineiii{0}{4}{Chunk ID}
11229
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
24 \lineiii{4}{4}{Size of chunk in big-endian byte order, not including the
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25 header}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
26 \lineiii{8}{\var{n}}{Data bytes, where \var{n} is the size given in
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 11229
diff changeset
27 the preceding field}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
28 \lineiii{8 + \var{n}}{0 or 1}{Pad byte needed if \var{n} is odd and
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
29 chunk alignment is used}
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30 \end{tableiii}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
32 The ID is a 4-byte string which identifies the type of chunk.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
34 The size field (a 32-bit value, encoded using big-endian byte order)
11229
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
35 gives the size of the chunk data, not including the 8-byte header.
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
36
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
37 Usually an IFF-type file consists of one or more chunks. The proposed
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
38 usage of the \class{Chunk} class defined here is to instantiate an
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
39 instance at the start of each chunk and read from the instance until
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
40 it reaches the end, after which a new instance can be instantiated.
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
41 At the end of the file, creating a new instance will fail with a
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
42 \exception{EOFError} exception.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
11229
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
44 \begin{classdesc}{Chunk}{file\optional{, align, bigendian, inclheader}}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
45 Class which represents a chunk. The \var{file} argument is expected
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
46 to be a file-like object. An instance of this class is specifically
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
47 allowed. The only method that is needed is \method{read()}. If the
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
48 methods \method{seek()} and \method{tell()} are present and don't
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
49 raise an exception, they are also used. If these methods are present
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
50 and raise an exception, they are expected to not have altered the
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
51 object. If the optional argument \var{align} is true, chunks are
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
52 assumed to be aligned on 2-byte boundaries. If \var{align} is
11229
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
53 false, no alignment is assumed. The default value is true. If the
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
54 optional argument \var{bigendian} is false, the chunk size is assumed
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
55 to be in little-endian order. This is needed for WAVE audio files.
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
56 The default value is true. If the optional argument \var{inclheader}
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
57 is true, the size given in the chunk header includes the size of the
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
58 header. The default value is false.
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
59 \end{classdesc}
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
60
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
61 A \class{Chunk} object supports the following methods:
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 \begin{methoddesc}{getname}{}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
64 Returns the name (ID) of the chunk. This is the first 4 bytes of the
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
65 chunk.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 \end{methoddesc}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67
11229
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
68 \begin{methoddesc}{getsize}{}
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
69 Returns the size of the chunk.
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
70 \end{methoddesc}
10ebb25b242d Doco update from Sjoerd Mullender.
Guido van Rossum <guido@python.org>
parents: 11061
diff changeset
71
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 \begin{methoddesc}{close}{}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
73 Close and skip to the end of the chunk. This does not close the
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
74 underlying file.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 \end{methoddesc}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
77 The remaining methods will raise \exception{IOError} if called after
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
78 the \method{close()} method has been called.
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
79
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \begin{methoddesc}{isatty}{}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
81 Returns \code{0}.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 \end{methoddesc}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
84 \begin{methoddesc}{seek}{pos\optional{, whence}}
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
85 Set the chunk's current position. The \var{whence} argument is
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
86 optional and defaults to \code{0} (absolute file positioning); other
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
87 values are \code{1} (seek relative to the current position) and
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
88 \code{2} (seek relative to the file's end). There is no return value.
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
89 If the underlying file does not allow seek, only forward seeks are
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
90 allowed.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 \end{methoddesc}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93 \begin{methoddesc}{tell}{}
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
94 Return the current position into the chunk.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 \end{methoddesc}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96
11061
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
97 \begin{methoddesc}{read}{\optional{size}}
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
98 Read at most \var{size} bytes from the chunk (less if the read hits
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
99 the end of the chunk before obtaining \var{size} bytes). If the
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
100 \var{size} argument is negative or omitted, read all data until the
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
101 end of the chunk. The bytes are returned as a string object. An
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
102 empty string is returned when the end of the chunk is encountered
e3ddb8761637 Update to Sjoerd's documentation of the chunk module, with some
Fred Drake <fdrake@acm.org>
parents: 11032
diff changeset
103 immediately.
11032
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
104 \end{methoddesc}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
105
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
106 \begin{methoddesc}{skip}{}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
107 Skip to the end of the chunk. All further calls to \method{read()}
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
108 for the chunk will return \code{''}. If you are not interested in the
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
109 contents of the chunk, this method should be called so that the file
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
110 points to the start of the next chunk.
36684ce0d40d New section from Moshe Zadka, modified by FLD for markup, some
Fred Drake <fdrake@acm.org>
parents:
diff changeset
111 \end{methoddesc}