1MIME::Body(3) User Contributed Perl Documentation MIME::Body(3)
2
6 MIME::Body - the body of a MIME message
7
9 Before reading further, you should see MIME::Tools to make sure that
10 you understand where this module fits into the grand scheme of things.
11 Go on, do it now. I'll wait.
12 Ready? Ok...
14 Obtaining bodies
16 ### Get the bodyhandle of a MIME::Entity object:
18 $body = $entity->bodyhandle;
19 ### Create a body which stores data in a disk file:
21 $body = new MIME::Body::File "/path/to/file";
22 ### Create a body which stores data in an in-core array:
24 $body = new MIME::Body::InCore \@strings;
25 Opening, closing, and using IO handles
27 ### Write data to the body:
29 $IO = $body->open("w") ⎪⎪ die "open body: $!";
30 $IO->print($message);
31 $IO->close ⎪⎪ die "close I/O handle: $!";
32 ### Read data from the body (in this case, line by line):
34 $IO = $body->open("r") ⎪⎪ die "open body: $!";
35 while (defined($_ = $IO->getline)) {
36 ### do stuff
37 }
38 $IO->close ⎪⎪ die "close I/O handle: $!";
39 Other I/O
41 ### Dump the ENCODED body data to a filehandle:
43 $body->print(\*STDOUT);
44 ### Slurp all the UNENCODED data in, and put it in a scalar:
46 $string = $body->as_string;
47 ### Slurp all the UNENCODED data in, and put it in an array of lines:
49 @lines = $body->as_lines;
50 Working directly with paths to underlying files
52 ### Where's the data?
54 if (defined($body->path)) { ### data is on disk:
55 print "data is stored externally, in ", $body->path;
56 }
57 else { ### data is in core:
58 print "data is already in core, and is...\n", $body->as_string;
59 }
60 ### Get rid of anything on disk:
62 $body->purge;
63
65 MIME messages can be very long (e.g., tar files, MPEGs, etc.) or very
66 short (short textual notes, as in ordinary mail). Long messages are
67 best stored in files, while short ones are perhaps best stored in core.
68 This class is an attempt to define a common interface for objects which
70 contain message data, regardless of how the data is physically stored.
71 The lifespan of a "body" object usually looks like this:
72 1. Body object is created by a MIME::Parser during parsing. It's at
74 this point that the actual MIME::Body subclass is chosen, and new()
75 is invoked. (For example: if the body data is going to a file,
76 then it is at this point that the class MIME::Body::File, and the
77 filename, is chosen).
78 2. Data is written to the body (usually by the MIME parser) like this:
80 The body is opened for writing, via "open("w")". This will trash
81 any previous contents, and return an "I/O handle" opened for writ‐
82 ing. Data is written to this I/O handle, via print(). Then the
83 I/O handle is closed, via close().
84 3. Data is read from the body (usually by the user application) like
86 this: The body is opened for reading by a user application, via
87 "open("r")". This will return an "I/O handle" opened for reading.
88 Data is read from the I/O handle, via read(), getline(), or get‐
89 lines(). Then the I/O handle is closed, via close().
90 4. Body object is destructed.
92 You can write your own subclasses, as long as they follow the interface
94 described below. Implementers of subclasses should assume that steps 2
95 and 3 may be repeated any number of times, and in different orders
96 (e.g., 1-2-2-3-2-3-3-3-3-3-2-4).
97 In any case, once a MIME::Body has been created, you ask to open it for
99 reading or writing, which gets you an "i/o handle": you then use the
100 same mechanisms for reading from or writing to that handle, no matter
101 what class it is.
102 Beware: unless you know for certain what kind of body you have, you
104 should not assume that the body has an underlying filehandle.
105
107 new ARGS...
108 Class method, constructor. Create a new body. Any ARGS are sent
109 to init().
110 init ARGS...
112 Instance method, abstract, initiallizer. This is called automati‐
113 cally by "new()", with the arguments given to "new()". The argu‐
114 ments are optional, and entirely up to the subclass. The default
115 method does nothing,
116 as_lines
118 Instance method. Return the contents of the body as an array of
119 lines (each terminated by a newline, with the possible exception of
120 the final one). Returns empty on failure (NB: indistinguishable
121 from an empty body!).
122 Note: the default method gets the data via repeated getline()
124 calls; your subclass might wish to override this.
125 as_string
127 Instance method. Return the body data as a string (slurping it
128 into core if necessary). Best not to do this unless you're sure
129 that the body is reasonably small! Returns empty string for an
130 empty body, and undef on failure.
131 Note: the default method uses print(), which gets the data via
133 repeated read() calls; your subclass might wish to override this.
134 binmode [ONOFF]
136 Instance method. With argument, flags whether or not open() should
137 return an I/O handle which has binmode() activated. With no argu‐
138 ment, just returns the current value.
139 is_encoded [ONOFF]
141 Instance method. If set to yes, no decoding is applied on output.
142 This flag is set by MIME::Parser, if the parser runs in decode_bod‐
143 ies(0) mode, so the content is handled unmodified.
144 dup Instance method. Duplicate the bodyhandle.
146 Beware: external data in bodyhandles is not copied to new files!
148 Changing the data in one body's data file, or purging that body,
149 will affect its duplicate. Bodies with in-core data probably need
150 not worry.
151 open READWRITE
153 Instance method, abstract. This should do whatever is necessary to
154 open the body for either writing (if READWRITE is "w") or reading
155 (if mode is "r").
156 This method is expected to return an "I/O handle" object on suc‐
158 cess, and undef on error. An I/O handle can be any object that
159 supports a small set of standard methods for reading/writing data.
160 See the IO::Handle class for an example.
161 path [PATH]
163 Instance method. If you're storing the body data externally (e.g.,
164 in a disk file), you'll want to give applications the ability to
165 get at that data, for cleanup. This method should return the path
166 to the data, or undef if there is none.
167 Where appropriate, the path should be a simple string, like a file‐
169 name. With argument, sets the PATH, which should be undef if there
170 is none.
171 print FILEHANDLE
173 Instance method. Output the body data to the given filehandle, or
174 to the currently-selected one if none is given.
175 purge
177 Instance method, abstract. Remove any data which resides external
178 to the program (e.g., in disk files). Immediately after a purge(),
179 the path() should return undef to indicate that the external data
180 is no longer available.
181
183 The following built-in classes are provided:
184 Body Stores body When open()ed,
186 class: data in: returns:
187 --------------------------------------------------------
188 MIME::Body::File disk file IO::Handle
189 MIME::Body::Scalar scalar IO::Scalar
190 MIME::Body::InCore scalar array IO::ScalarArray
191 MIME::Body::File
193 A body class that stores the data in a disk file. The I/O handle is a
195 wrapped filehandle. Invoke the constructor as:
196 $body = new MIME::Body::File "/path/to/file";
198 In this case, the "path()" method would return the given path, so you
200 could say:
201 if (defined($body->path)) {
203 open BODY, $body->path or die "open: $!";
204 while (<BODY>) {
205 ### do stuff
206 }
207 close BODY;
208 }
209 But you're best off not doing this.
211 MIME::Body::Scalar
213 A body class that stores the data in-core, in a simple scalar. Invoke
215 the constructor as:
216 $body = new MIME::Body::Scalar \$string;
218 A single scalar argument sets the body to that value, exactly as though
220 you'd opened for the body for writing, written the value, and closed
221 the body again:
222 $body = new MIME::Body::Scalar "Line 1\nLine 2\nLine 3";
224 A single array reference sets the body to the result of joining all the
226 elements of that array together:
227 $body = new MIME::Body::Scalar ["Line 1\n",
229 "Line 2\n",
230 "Line 3"];
231 Uses IO::Scalar as the I/O handle.
233 MIME::Body::InCore
235 A body class that stores the data in-core. Invoke the constructor as:
237 $body = new MIME::Body::InCore \$string;
239 $body = new MIME::Body::InCore $string;
240 $body = new MIME::Body::InCore \@stringarray
241 A simple scalar argument sets the body to that value, exactly as though
243 you'd opened for the body for writing, written the value, and closed
244 the body again:
245 $body = new MIME::Body::InCore "Line 1\nLine 2\nLine 3";
247 A single array reference sets the body to the concatenation of all
249 scalars that it holds:
250 $body = new MIME::Body::InCore ["Line 1\n",
252 "Line 2\n",
253 "Line 3"];
254 Uses IO::ScalarArray as the I/O handle.
256 Defining your own subclasses
258 So you're not happy with files and scalar-arrays? No problem: just
260 define your own MIME::Body subclass, and make a subclass of
261 MIME::Parser or MIME::ParserBase which returns an instance of your body
262 class whenever appropriate in the "new_body_for(head)" method.
263 Your "body" class must inherit from MIME::Body (or some subclass of
265 it), and it must either provide (or inherit the default for) the fol‐
266 lowing methods...
267 The default inherited method should suffice for all these:
269 new
271 binmode [ONOFF]
272 path
273 The default inherited method may suffice for these, but perhaps there's
275 a better implementation for your subclass.
276 init ARGS...
278 as_lines
279 as_string
280 dup
281 print
282 purge
283 The default inherited method will probably not suffice for these:
285 open
287
289 One reason I didn't just use FileHandle or IO::Handle objects for mes‐
290 sage bodies was that I wanted a "body" object to be a form of com‐
291 pletely encapsulated program-persistent storage; that is, I wanted
292 users to be able to write code like this...
293 ### Get body handle from this MIME message, and read its data:
295 $body = $entity->bodyhandle;
296 $IO = $body->open("r");
297 while (defined($_ = $IO->getline)) {
298 print STDOUT $_;
299 }
300 $IO->close;
301 ...without requiring that they know anything more about how the $body
303 object is actually storing its data (disk file, scalar variable, array
304 variable, or whatever).
305 Storing the body of each MIME message in a persistently-open IO::Handle
307 was a possibility, but it seemed like a bad idea, considering that a
308 single multipart MIME message could easily suck up all the available
309 file descriptors on some systems. This risk increases if the user
310 application is processing more than one MIME entity at a time.
311
313 Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
314 David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com
315 All rights reserved. This program is free software; you can redis‐
317 tribute it and/or modify it under the same terms as Perl itself.
318 Thanks to Achim Bohnet for suggesting that MIME::Parser not be
320 restricted to the use of FileHandles.
321
323 $Revision: 1.13 $ $Date: 2006/03/17 21:03:23 $
324perl v5.8.8 2006-03-17 MIME::Body(3)