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:
17 $body = $entity->bodyhandle;
18 ### Create a body which stores data in a disk file:
20 $body = new MIME::Body::File "/path/to/file";
21 ### Create a body which stores data in an in-core array:
23 $body = new MIME::Body::InCore \@strings;
24 Opening, closing, and using IO handles
26 ### Write data to the body:
27 $IO = $body->open("w") || die "open body: $!";
28 $IO->print($message);
29 $IO->close || die "close I/O handle: $!";
30 ### Read data from the body (in this case, line by line):
32 $IO = $body->open("r") || die "open body: $!";
33 while (defined($_ = $IO->getline)) {
34 ### do stuff
35 }
36 $IO->close || die "close I/O handle: $!";
37 Other I/O
39 ### Dump the ENCODED body data to a filehandle:
40 $body->print(\*STDOUT);
41 ### Slurp all the UNENCODED data in, and put it in a scalar:
43 $string = $body->as_string;
44 ### Slurp all the UNENCODED data in, and put it in an array of lines:
46 @lines = $body->as_lines;
47 Working directly with paths to underlying files
49 ### Where's the data?
50 if (defined($body->path)) { ### data is on disk:
51 print "data is stored externally, in ", $body->path;
52 }
53 else { ### data is in core:
54 print "data is already in core, and is...\n", $body->as_string;
55 }
56 ### Get rid of anything on disk:
58 $body->purge;
59
61 MIME messages can be very long (e.g., tar files, MPEGs, etc.) or very
62 short (short textual notes, as in ordinary mail). Long messages are
63 best stored in files, while short ones are perhaps best stored in core.
64 This class is an attempt to define a common interface for objects which
66 contain message data, regardless of how the data is physically stored.
67 The lifespan of a "body" object usually looks like this:
68 1. Body object is created by a MIME::Parser during parsing. It's at
70 this point that the actual MIME::Body subclass is chosen, and new()
71 is invoked. (For example: if the body data is going to a file,
72 then it is at this point that the class MIME::Body::File, and the
73 filename, is chosen).
74 2. Data is written to the body (usually by the MIME parser) like this:
76 The body is opened for writing, via "open("w")". This will trash
77 any previous contents, and return an "I/O handle" opened for
78 writing. Data is written to this I/O handle, via print(). Then
79 the I/O handle is closed, via close().
80 3. Data is read from the body (usually by the user application) like
82 this: The body is opened for reading by a user application, via
83 "open("r")". This will return an "I/O handle" opened for reading.
84 Data is read from the I/O handle, via read(), getline(), or
85 getlines(). Then the I/O handle is closed, via close().
86 4. Body object is destructed.
88 You can write your own subclasses, as long as they follow the interface
90 described below. Implementers of subclasses should assume that steps 2
91 and 3 may be repeated any number of times, and in different orders
92 (e.g., 1-2-2-3-2-3-3-3-3-3-2-4).
93 In any case, once a MIME::Body has been created, you ask to open it for
95 reading or writing, which gets you an "i/o handle": you then use the
96 same mechanisms for reading from or writing to that handle, no matter
97 what class it is.
98 Beware: unless you know for certain what kind of body you have, you
100 should not assume that the body has an underlying filehandle.
101
103 new ARGS...
104 Class method, constructor. Create a new body. Any ARGS are sent
105 to init().
106 init ARGS...
108 Instance method, abstract, initiallizer. This is called
109 automatically by "new()", with the arguments given to "new()". The
110 arguments are optional, and entirely up to the subclass. The
111 default method does nothing,
112 as_lines
114 Instance method. Return the contents of the body as an array of
115 lines (each terminated by a newline, with the possible exception of
116 the final one). Returns empty on failure (NB: indistinguishable
117 from an empty body!).
118 Note: the default method gets the data via repeated getline()
120 calls; your subclass might wish to override this.
121 as_string
123 Instance method. Return the body data as a string (slurping it
124 into core if necessary). Best not to do this unless you're sure
125 that the body is reasonably small! Returns empty string for an
126 empty body, and undef on failure.
127 Note: the default method uses print(), which gets the data via
129 repeated read() calls; your subclass might wish to override this.
130 binmode [ONOFF]
132 Instance method. With argument, flags whether or not open() should
133 return an I/O handle which has binmode() activated. With no
134 argument, just returns the current value.
135 is_encoded [ONOFF]
137 Instance method. If set to yes, no decoding is applied on output.
138 This flag is set by MIME::Parser, if the parser runs in
139 decode_bodies(0) mode, so the content is handled unmodified.
140 dup Instance method. Duplicate the bodyhandle.
142 Beware: external data in bodyhandles is not copied to new files!
144 Changing the data in one body's data file, or purging that body,
145 will affect its duplicate. Bodies with in-core data probably need
146 not worry.
147 open READWRITE
149 Instance method, abstract. This should do whatever is necessary to
150 open the body for either writing (if READWRITE is "w") or reading
151 (if mode is "r").
152 This method is expected to return an "I/O handle" object on
154 success, and undef on error. An I/O handle can be any object that
155 supports a small set of standard methods for reading/writing data.
156 See the IO::Handle class for an example.
157 path [PATH]
159 Instance method. If you're storing the body data externally (e.g.,
160 in a disk file), you'll want to give applications the ability to
161 get at that data, for cleanup. This method should return the path
162 to the data, or undef if there is none.
163 Where appropriate, the path should be a simple string, like a
165 filename. With argument, sets the PATH, which should be undef if
166 there is none.
167 print FILEHANDLE
169 Instance method. Output the body data to the given filehandle, or
170 to the currently-selected one if none is given.
171 purge
173 Instance method, abstract. Remove any data which resides external
174 to the program (e.g., in disk files). Immediately after a purge(),
175 the path() should return undef to indicate that the external data
176 is no longer available.
177
179 The following built-in classes are provided:
180 Body Stores body When open()ed,
182 class: data in: returns:
183 --------------------------------------------------------
184 MIME::Body::File disk file IO::Handle
185 MIME::Body::Scalar scalar IO::Handle
186 MIME::Body::InCore scalar array IO::Handle
187 MIME::Body::File
189 A body class that stores the data in a disk file. Invoke the
190 constructor as:
191 $body = new MIME::Body::File "/path/to/file";
193 In this case, the "path()" method would return the given path, so you
195 could say:
196 if (defined($body->path)) {
198 open BODY, $body->path or die "open: $!";
199 while (<BODY>) {
200 ### do stuff
201 }
202 close BODY;
203 }
204 But you're best off not doing this.
206 MIME::Body::Scalar
208 A body class that stores the data in-core, in a simple scalar. Invoke
209 the constructor as:
210 $body = new MIME::Body::Scalar \$string;
212 A single scalar argument sets the body to that value, exactly as though
214 you'd opened for the body for writing, written the value, and closed
215 the body again:
216 $body = new MIME::Body::Scalar "Line 1\nLine 2\nLine 3";
218 A single array reference sets the body to the result of joining all the
220 elements of that array together:
221 $body = new MIME::Body::Scalar ["Line 1\n",
223 "Line 2\n",
224 "Line 3"];
225 MIME::Body::InCore
227 A body class that stores the data in-core. Invoke the constructor as:
228 $body = new MIME::Body::InCore \$string;
230 $body = new MIME::Body::InCore $string;
231 $body = new MIME::Body::InCore \@stringarray
232 A simple scalar argument sets the body to that value, exactly as though
234 you'd opened for the body for writing, written the value, and closed
235 the body again:
236 $body = new MIME::Body::InCore "Line 1\nLine 2\nLine 3";
238 A single array reference sets the body to the concatenation of all
240 scalars that it holds:
241 $body = new MIME::Body::InCore ["Line 1\n",
243 "Line 2\n",
244 "Line 3"];
245 Defining your own subclasses
247 So you're not happy with files and scalar-arrays? No problem: just
248 define your own MIME::Body subclass, and make a subclass of
249 MIME::Parser or MIME::ParserBase which returns an instance of your body
250 class whenever appropriate in the "new_body_for(head)" method.
251 Your "body" class must inherit from MIME::Body (or some subclass of
253 it), and it must either provide (or inherit the default for) the
254 following methods...
255 The default inherited method should suffice for all these:
257 new
259 binmode [ONOFF]
260 path
261 The default inherited method may suffice for these, but perhaps there's
263 a better implementation for your subclass.
264 init ARGS...
266 as_lines
267 as_string
268 dup
269 print
270 purge
271 The default inherited method will probably not suffice for these:
273 open
275
277 One reason I didn't just use IO::Handle objects for message bodies was
278 that I wanted a "body" object to be a form of completely encapsulated
279 program-persistent storage; that is, I wanted users to be able to write
280 code like this...
281 ### Get body handle from this MIME message, and read its data:
283 $body = $entity->bodyhandle;
284 $IO = $body->open("r");
285 while (defined($_ = $IO->getline)) {
286 print STDOUT $_;
287 }
288 $IO->close;
289 ...without requiring that they know anything more about how the $body
291 object is actually storing its data (disk file, scalar variable, array
292 variable, or whatever).
293 Storing the body of each MIME message in a persistently-open IO::Handle
295 was a possibility, but it seemed like a bad idea, considering that a
296 single multipart MIME message could easily suck up all the available
297 file descriptors on some systems. This risk increases if the user
298 application is processing more than one MIME entity at a time.
299
301 MIME::Tools
302
304 Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
305 David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com
306 All rights reserved. This program is free software; you can
308 redistribute it and/or modify it under the same terms as Perl itself.
309 Thanks to Achim Bohnet for suggesting that MIME::Parser not be
311 restricted to the use of FileHandles.
312 #------------------------------ 1;
314perl v5.12.0 2010-04-22 MIME::Body(3)