1MIME::Body(3)         User Contributed Perl Documentation        MIME::Body(3)
2
3
4

NAME

6       MIME::Body - the body of a MIME message
7

SYNOPSIS

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
13       Ready?  Ok...
14
15   Obtaining bodies
16          ### Get the bodyhandle of a MIME::Entity object:
17          $body = $entity->bodyhandle;
18
19          ### Create a body which stores data in a disk file:
20          $body = new MIME::Body::File "/path/to/file";
21
22          ### Create a body which stores data in an in-core array:
23          $body = new MIME::Body::InCore \@strings;
24
25   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
31          ### 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
38   Other I/O
39          ### Dump the ENCODED body data to a filehandle:
40          $body->print(\*STDOUT);
41
42          ### Slurp all the UNENCODED data in, and put it in a scalar:
43          $string = $body->as_string;
44
45          ### Slurp all the UNENCODED data in, and put it in an array of lines:
46          @lines = $body->as_lines;
47
48   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
57          ### Get rid of anything on disk:
58          $body->purge;
59

DESCRIPTION

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
65       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
69       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
75       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
81       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
87       4.  Body object is destructed.
88
89       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
94       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
99       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

PUBLIC INTERFACE

103       new ARGS...
104           Class method, constructor.  Create a new body.  Any ARGS are sent
105           to init().
106
107       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
113       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
119           Note: the default method gets the data via repeated getline()
120           calls; your subclass might wish to override this.
121
122       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
128           Note: the default method uses print(), which gets the data via
129           repeated read() calls; your subclass might wish to override this.
130
131       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
136       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
141       dup Instance method.  Duplicate the bodyhandle.
142
143           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
148       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
153           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
158       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
164           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
168       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
172       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

SUBCLASSES

179       The following built-in classes are provided:
180
181          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
188   MIME::Body::File
189       A body class that stores the data in a disk file.  Invoke the
190       constructor as:
191
192           $body = new MIME::Body::File "/path/to/file";
193
194       In this case, the "path()" method would return the given path, so you
195       could say:
196
197           if (defined($body->path)) {
198               open BODY, $body->path or die "open: $!";
199               while (<BODY>) {
200                   ### do stuff
201               }
202               close BODY;
203           }
204
205       But you're best off not doing this.
206
207   MIME::Body::Scalar
208       A body class that stores the data in-core, in a simple scalar.  Invoke
209       the constructor as:
210
211           $body = new MIME::Body::Scalar \$string;
212
213       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
217           $body = new MIME::Body::Scalar "Line 1\nLine 2\nLine 3";
218
219       A single array reference sets the body to the result of joining all the
220       elements of that array together:
221
222           $body = new MIME::Body::Scalar ["Line 1\n",
223                                           "Line 2\n",
224                                           "Line 3"];
225
226   MIME::Body::InCore
227       A body class that stores the data in-core.  Invoke the constructor as:
228
229           $body = new MIME::Body::InCore \$string;
230           $body = new MIME::Body::InCore  $string;
231           $body = new MIME::Body::InCore \@stringarray
232
233       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
237           $body = new MIME::Body::InCore "Line 1\nLine 2\nLine 3";
238
239       A single array reference sets the body to the concatenation of all
240       scalars that it holds:
241
242           $body = new MIME::Body::InCore ["Line 1\n",
243                                           "Line 2\n",
244                                           "Line 3"];
245
246   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
252       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
256       The default inherited method should suffice for all these:
257
258           new
259           binmode [ONOFF]
260           path
261
262       The default inherited method may suffice for these, but perhaps there's
263       a better implementation for your subclass.
264
265           init ARGS...
266           as_lines
267           as_string
268           dup
269           print
270           purge
271
272       The default inherited method will probably not suffice for these:
273
274           open
275

NOTES

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
282          ### 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
290       ...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
294       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

SEE ALSO

301       MIME::Tools
302

AUTHOR

304       Eryq (eryq@zeegee.com), ZeeGee Software Inc (http://www.zeegee.com).
305       David F. Skoll (dfs@roaringpenguin.com) http://www.roaringpenguin.com
306
307       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
310       Thanks to Achim Bohnet for suggesting that MIME::Parser not be
311       restricted to the use of FileHandles.
312
313       #------------------------------ 1;
314
315
316
317perl v5.34.0                      2021-07-22                     MIME::Body(3)
Impressum