1Mail::Message::Replace:U:sMearilCIonntterrinbeutt(e3d)PMearill:D:oMceusmseangtea:t:iRoenplace::MailInternet(3)
2
6 Mail::Message::Replace::MailInternet - fake Mail::Internet
7
9 Mail::Message::Replace::MailInternet
10 is a Mail::Message
11 is a Mail::Reporter
12
14 !!! BETA !!!
15 # change
17 use Mail::Internet;
18 # into
19 use Mail::Message::Replace::MailInternet;
20 # in existing code, and the code should still work, but
21 # with the Mail::Message features.
22
24 This module is a wrapper around a Mail::Message, which simulates a
25 Mail::Internet object. The name-space of that module is hijacked and
26 many methods are added.
27 Most methods will work without any change, but you may need to have a
29 look at your smtpsend() and send() calls.
30
32 Constructors
33 $obj->clone(OPTIONS)
34 See "Constructors" in Mail::Message
35 $obj->dup
37 Duplicate the message. The result will again be a Mail::Internet
38 compatible object.
39 $obj->empty
41 Remove all data from this object. Very dangerous!
42 Mail::Message::Replace::MailInternet->new([ARG], [OPTIONS])
44 -Option --Defined in --Default
45 Body undef
46 FoldLength 79
47 Header undef
48 MailFrom 'KEEP'
49 Modify 0
50 body Mail::Message undef
51 body_type Mail::Message Mail::Message::Body::Lines
52 deleted Mail::Message <false>
53 field_type Mail::Message undef
54 head Mail::Message undef
55 head_type Mail::Message Mail::Message::Replace::MailHeader
56 labels Mail::Message {}
57 log Mail::Reporter 'WARNINGS'
58 messageId Mail::Message undef
59 modified Mail::Message <false>
60 trace Mail::Reporter 'WARNINGS'
61 trusted Mail::Message <false>
62 Body => ARRAY-OF-LINES
64 Array of "\n" terminated lines. If not specified, the lines will
65 be read from ARG.
66 FoldLength => INTEGER
68 Number of characters permitted on any refolded header line.
69 Passed to Mail::Message::Replace::MailHeader::new(FoldLength).
70 Header => OBJECT
72 The Mail::Header object, which is passed here, is a fake one as
73 well... It is translated into a new(head). If not given, the
74 header will be parsed from the ARG.
75 MailFrom => 'IGNORE'|'ERROR'|'COERCE'|'KEEP'
77 What to do with leading ""From "" lines in e-mail data. Passed
78 to Mail::Message::Replace::MailHeader::new(MailFrom).
79 Modify => BOOLEAN
81 Whether to re-fold all the incoming fields. Passed to
82 Mail::Message::Replace::MailHeader::new(Modify).
83 body => OBJECT
85 body_type => CLASS
86 deleted => BOOLEAN
87 field_type => CLASS
88 head => OBJECT
89 head_type => CLASS
90 labels => ARRAY|HASH
91 log => LEVEL
92 messageId => STRING
93 modified => BOOLEAN
94 trace => LEVEL
95 trusted => BOOLEAN
96 example: replace traditional Mail::Internet by this wrapper
98 # was
100 use Mail::Internet;
101 my $mi = Mail::Internet->new(@options);
102 # becomes
104 use Mail::Message::Replace::MailInternet;
105 my $mi = Mail::Internet->new(@options);
106 Attributes
108 $obj->MailFrom([STRING])
109 Your email address.
110 Constructing a message
112 $obj->add_signature([FILENAME])
113 Replaced by sign(), but still usable. FILENAME is the file which
114 contains the signature, which defaults to "$ENV{HOME}/.signature".
115 $obj->bounce([RG-OBJECT|OPTIONS])
117 See "Constructing a message" in Mail::Message::Construct::Bounce
118 Mail::Message::Replace::MailInternet->build([MESSAGE|PART|BODY],
120 CONTENT)
121 See "Constructing a message" in Mail::Message::Construct::Build
122 Mail::Message::Replace::MailInternet->buildFromBody(BODY, [HEAD],
124 HEADERS)
125 See "Constructing a message" in Mail::Message::Construct::Build
126 $obj->extract(ARRAY or FILEHANDLE)
128 Read header and body from an ARRAY or FILEHANDLE
129 $obj->forward(OPTIONS)
131 See "Constructing a message" in Mail::Message::Construct::Forward
132 $obj->forwardAttach(OPTIONS)
134 See "Constructing a message" in Mail::Message::Construct::Forward
135 $obj->forwardEncapsulate(OPTIONS)
137 See "Constructing a message" in Mail::Message::Construct::Forward
138 $obj->forwardInline(OPTIONS)
140 See "Constructing a message" in Mail::Message::Construct::Forward
141 $obj->forwardNo(OPTIONS)
143 See "Constructing a message" in Mail::Message::Construct::Forward
144 $obj->forwardPostlude
146 See "Constructing a message" in Mail::Message::Construct::Forward
147 $obj->forwardPrelude
149 See "Constructing a message" in Mail::Message::Construct::Forward
150 $obj->forwardSubject(STRING)
152 See "Constructing a message" in Mail::Message::Construct::Forward
153 $obj->read(ARRAY|FILEHANDLE, OPTIONS)
155 Mail::Message::Replace::MailInternet->read(ARRAY|FILEHANDLE,
156 OPTIONS)
157 Read header and body from the specified ARRAY or FILEHANDLE. When
159 used as object method, Mail::Message::read() is called, to be
160 MailBox compliant. As class method, the Mail::Internet compatible
161 read is called. OPTIONS are only available in the first case.
162 -Option --Defined in --Default
164 body_type Mail::Message::Construct::Read undef
165 strip_status_fields Mail::Message::Construct::Read <true>
166 body_type => CLASS
168 strip_status_fields => BOOLEAN
169 $obj->read_body(ARRAY|FILEHANDLE)
170 Read only the message's body from the ARRAY or FILEHANDLE.
171 $obj->read_header(ARRAY|FILEHANDLE)
173 Read only the message's header from the ARRAY or FILEHANDLE
174 $obj->rebuild(OPTIONS)
176 See "Constructing a message" in Mail::Message::Construct::Rebuild
177 $obj->reply(OPTIONS)
179 BE WARNED: the main job for creating a reply is done by
180 Mail::Message::reply(), which may produce a result which is
181 compatible, but may be different from Mail::Internet's version.
182 -Option --Defined in --Default
184 Bcc Mail::Message::Construct::Reply undef
185 Cc Mail::Message::Construct::Reply <'cc' in current>
186 Exclude []
187 From Mail::Message::Construct::Reply <'to' in current>
188 Inline >
189 Keep []
190 Message-ID Mail::Message::Construct::Reply <uniquely generated>
191 ReplyAll <false>
192 Subject Mail::Message::Construct::Reply replySubject()
193 To Mail::Message::Construct::Reply <sender in current>
194 body Mail::Message::Construct::Reply undef
195 group_reply Mail::Message::Construct::Reply <true>
196 header_template $ENV{HOME}/.mailhdr
197 include Mail::Message::Construct::Reply 'INLINE'
198 max_signature Mail::Message::Construct::Reply 10
199 message_type Mail::Message::Construct::Reply Mail::Message
200 postlude Mail::Message::Construct::Reply undef
201 prelude Mail::Message::Construct::Reply undef
202 quote Mail::Message::Construct::Reply '> '
203 signature Mail::Message::Construct::Reply undef
204 strip_signature Mail::Message::Construct::Reply qr/^--\s/
205 Bcc => ADDRESSES
207 Cc => ADDRESSES
208 Exclude => ARRAY-OF-NAMES
209 Remove the fields witht the specified names from the produced
210 reply message.
211 From => ADDRESSES
213 Inline => STRING
214 Quotation STRING, which is translated into reply(quote). The
215 normal default of "quote" is "> ", in stead of ">".
216 Keep => ARRAY-OF-NAMES
218 Copy all header fields with the specified NAMES from the source
219 to the reply message.
220 Message-ID => STRING
222 ReplyAll => BOOLEAN
223 Reply to the group? Translated into reply(group_reply), which
224 has as default the exact oposite of this option, being "true".
225 Subject => STRING|CODE
227 To => ADDRESSES
228 body => BODY
229 group_reply => BOOLEAN
230 header_template => FILENAME|"undef"
231 Read the return header from the template file. When this is
232 explicitly set to "undef", or the file does not exist, then a
233 header will be created.
234 include => 'NO'|'INLINE'|'ATTACH'
236 max_signature => INTEGER
237 message_type => CLASS
238 postlude => BODY|LINES
239 prelude => BODY|LINES
240 quote => CODE|STRING
241 signature => BODY|MESSAGE
242 strip_signature => REGEXP|STRING|CODE
243 $obj->replyPrelude([STRING|FIELD|ADDRESS|ARRAY-OF-THINGS])
244 See "Constructing a message" in Mail::Message::Construct::Reply
245 $obj->replySubject(STRING)
247 Mail::Message::Replace::MailInternet->replySubject(STRING)
248 See "Constructing a message" in Mail::Message::Construct::Reply
250 $obj->sign(OPTIONS)
252 Add a signature (a few extra lines) to the message.
253 -Option --Default
255 File undef
256 Signature ''
257 File => FILENAME
259 Specifies a filename where the signature is in.
260 Signature => STRING|ARRAY-OF-LINES
262 The signature in memory.
263 The message
265 $obj->container
266 See "The message" in Mail::Message
267 $obj->isDummy
269 See "The message" in Mail::Message
270 $obj->isPart
272 See "The message" in Mail::Message
273 $obj->messageId
275 See "The message" in Mail::Message
276 $obj->nntppost(OPTIONS)
278 Send an NNTP message (newsgroup message), which is equivalent to
279 Mail::Transport::NNTP or Mail::Message::send() with "via 'nntp'".
280 -Option--Default
282 Debug <false>
283 Host <from Net::Config>
284 Port 119
285 Debug => BOOLEAN
287 Host => HOSTNAME
288 Port => INTEGER
289 $obj->print([FILEHANDLE])
290 Prints the whole message to the specified FILEHANDLE, which default
291 to STDOUT. This calls Mail::Message::print().
292 $obj->send(TYPE, OPTIONS)
294 Send via Mail Transfer Agents (MUA). These will be handled by
295 various Mail::Transport::Send extensions. The "test" TYPE is not
296 supported.
297 $obj->size
299 See "The message" in Mail::Message
300 $obj->toplevel
302 See "The message" in Mail::Message
303 $obj->write([FILEHANDLE])
305 See "The message" in Mail::Message
306 The header
308 $obj->add(LINES)
309 Add header lines, which simply calls "Mail::Message::Head::add()"
310 on the header for each specified LINE. The last added LINE is
311 returned.
312 $obj->bcc
314 See "The header" in Mail::Message
315 $obj->cc
317 See "The header" in Mail::Message
318 $obj->clean_header
320 Not to be used, replaced by header().
321 $obj->combine(TAG, [WITH])
323 Not implemented, because I see no use for it.
324 $obj->date
326 See "The header" in Mail::Message
327 $obj->delete(NAME, [INDEX]])
329 Delete the fields with the specified NAME. The deleted fields are
330 returned.
331 BE WARNED: if no NAME is specified, the "delete" is interpreted as
333 the deletion of the message in a folder, so
334 Mail::Box::Message::delete() will be called. This may have no
335 negative effect at all...
336 Calls Mail::Message::Replace::MailHeader::delete()
338 $obj->destinations
340 See "The header" in Mail::Message
341 $obj->fold([LENGTH])
343 Fold all the fields to a certain maximum LENGTH. Implemented by
344 Mail::Message::Replace::MailHeader::fold()
345 $obj->fold_length([[TAG], LENGTH])
347 Set the maximum line LENGTH. TAG is ignored. Implemented by
348 Mail::Message::Replace::MailHeader::fold_length()
349 $obj->from
351 See "The header" in Mail::Message
352 $obj->get(NAME, [INDEX])
354 Get all the header fields with the specified NAME. In scalar
355 context, only the first fitting NAME is returned. Even when only
356 one NAME is specified, multiple lines may be returned: some fields
357 appear more than once in a header. Calls
358 Mail::Message::Replace::MailHeader::get()
359 $obj->guessTimestamp
361 See "The header" in Mail::Message
362 $obj->head([HEAD])
364 Returns the head of the message, or creates an empty one if none is
365 defined. The HEAD argument, which sets the header, is not
366 available for Mail::Internet, but is there to be compatible with
367 the "head" method of Mail::Message.
368 $obj->header([ARRAY])
370 Optionally reads a header from the ARRAY, and then returns those
371 fields as array-ref nicely folded. Implemented by
372 Mail::Message::Replace::MailHeader::header()
373 $obj->nrLines
375 See "The header" in Mail::Message
376 $obj->print_header(FILEHANDLE)
378 Calls Mail::Message::Head::Complete::print().
379 $obj->replace(TAG, LINE, [INDEX])
381 Adds LINES to the header, but removes fields with the same name if
382 they already exist. Calls
383 Mail::Message::Replace::MailHeader::replace()
384 $obj->sender
386 See "The header" in Mail::Message
387 $obj->study(FIELDNAME)
389 See "The header" in Mail::Message
390 $obj->subject
392 See "The header" in Mail::Message
393 $obj->tidy_headers
395 No effect anymore (always performed).
396 $obj->timestamp
398 See "The header" in Mail::Message
399 $obj->to
401 See "The header" in Mail::Message
402 The body
404 $obj->body([ARRAY-OF-LINES|LIST-OF-LINES])
405 Returns an array of lines, representing the body. With arguments,
406 a new body will be created. In Mail::Internet, the body is not an
407 object but a simple array.
408 BE WARNED: this overrules the Mail::Message::body() method, which
410 may cause some confusion. Use bodyObject() to get access to that
411 body's data.
412 $obj->bodyObject([BODY])
414 Calls Mail::Message::body(), because that "body" method is
415 overruled by the one which has a Mail::Internet compatible
416 interface.
417 $obj->contentType
419 See "The body" in Mail::Message
420 $obj->decoded(OPTIONS)
422 See "The body" in Mail::Message
423 $obj->encode(OPTIONS)
425 See "The body" in Mail::Message
426 $obj->isMultipart
428 See "The body" in Mail::Message
429 $obj->isNested
431 See "The body" in Mail::Message
432 $obj->parts(['ALL'|'ACTIVE'|'DELETED'|'RECURSE'|FILTER])
434 See "The body" in Mail::Message
435 $obj->print_body([FILEHANDLE])
437 Prints the body to the specified FILEHANDLE, which defaults to
438 STDOUT. This calls Mail::Message::Body::print().
439 $obj->remove_sig([NRLINES])
441 Remove the signature of a message with a maximum of NRLINES lines,
442 which defaults to 10. The work is done on the decoded body
443 content, by Mail::Message::Body::stripSignature().
444 $obj->smtpsend(OPTIONS)
446 This method is calling Mail::Message::send() via "smtp", which is
447 implemented in Mail::Transport::SMTP. The implementation is
448 slightly different, so this method is not 100% compliant.
449 -Option --Default
451 Debug <false>
452 Hello <helo_domain from Net::Config>
453 Host $ENV{SMTPHOSTS} or from Net::Config
454 MailFrom $ENV{MAILADDRESS} or $ENV{USER}
455 Port 25
456 Debug => BOOLEAN
458 Hello => STRING
459 Host => HOSTNAME
460 Only the first detected HOSTNAME is taken, so differs from the
461 original implementation.
462 MailFrom => STRING
464 Your e-mail address. This simulated Mail::Internet object does
465 not try to create an e-mail address from the sendmail
466 configuration file, because that is generally a bad idea in
467 environments with virtual hosts, as we have now-adays.
468 Port => INTEGER
470 $obj->tidy_body
471 Removes blank lines from begin and end of the body.
472 Flags
474 $obj->deleted([BOOLEAN])
475 See "Flags" in Mail::Message
476 $obj->isDeleted
478 See "Flags" in Mail::Message
479 $obj->isModified
481 See "Flags" in Mail::Message
482 $obj->label(LABEL|PAIRS)
484 See "Flags" in Mail::Message
485 $obj->labels
487 See "Flags" in Mail::Message
488 $obj->labelsToStatus
490 See "Flags" in Mail::Message
491 $obj->modified([BOOLEAN])
493 See "Flags" in Mail::Message
494 $obj->statusToLabels
496 See "Flags" in Mail::Message
497 The whole message as text
499 $obj->as_mbox_string
500 Returns the whole message as one string, which can be included in
501 an MBOX folder (while not using Mail::Box::Mbox). Lines in the
502 body which start with "From " are escaped with an >.
503 $obj->file
505 See "The whole message as text" in Mail::Message::Construct::Text
506 $obj->lines
508 See "The whole message as text" in Mail::Message::Construct::Text
509 $obj->printStructure([FILEHANDLE|undef],[INDENT])
511 See "The whole message as text" in Mail::Message::Construct::Text
512 $obj->string
514 See "The whole message as text" in Mail::Message::Construct::Text
515 The nasty bits
517 $obj->isa(CLASS)
518 Mail::Message::Replace::MailInternet->isa(CLASS)
519 Of course, the "isa()" class inheritance check should not see our
521 nasty trick.
522 Internals
524 $obj->clonedFrom
525 See "Internals" in Mail::Message
526 Mail::Message::Replace::MailInternet->coerce(MESSAGE)
528 Coerce (adapt type) of the specified MESSAGE (anything
529 Mail::Message::coerce() accepts) into an Mail::Internet simulating
530 object.
531 $obj->isDelayed
533 See "Internals" in Mail::Message
534 $obj->readBody(PARSER, HEAD [, BODYTYPE])
536 See "Internals" in Mail::Message
537 $obj->readFromParser(PARSER, [BODYTYPE])
539 See "Internals" in Mail::Message
540 $obj->readHead(PARSER [,CLASS])
542 See "Internals" in Mail::Message
543 $obj->recursiveRebuildPart(PART, OPTIONS)
545 See "Internals" in Mail::Message::Construct::Rebuild
546 $obj->storeBody(BODY)
548 See "Internals" in Mail::Message
549 $obj->takeMessageId([STRING])
551 See "Internals" in Mail::Message
552 Error handling
554 $obj->AUTOLOAD
555 See "METHODS" in Mail::Message::Construct
556 $obj->addReport(OBJECT)
558 See "Error handling" in Mail::Reporter
559 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
561 Mail::Message::Replace::MailInternet->defaultTrace([LEVEL]|[LOGLEVEL,
562 TRACELEVEL]|[LEVEL, CALLBACK])
563 See "Error handling" in Mail::Reporter
565 $obj->errors
567 See "Error handling" in Mail::Reporter
568 $obj->log([LEVEL [,STRINGS]])
570 Mail::Message::Replace::MailInternet->log([LEVEL [,STRINGS]])
571 See "Error handling" in Mail::Reporter
573 $obj->logPriority(LEVEL)
575 Mail::Message::Replace::MailInternet->logPriority(LEVEL)
576 See "Error handling" in Mail::Reporter
578 $obj->logSettings
580 See "Error handling" in Mail::Reporter
581 $obj->notImplemented
583 See "Error handling" in Mail::Reporter
584 $obj->report([LEVEL])
586 See "Error handling" in Mail::Reporter
587 $obj->reportAll([LEVEL])
589 See "Error handling" in Mail::Reporter
590 $obj->shortSize([VALUE])
592 Mail::Message::Replace::MailInternet->shortSize([VALUE])
593 See "Error handling" in Mail::Message
595 $obj->shortString
597 See "Error handling" in Mail::Message
598 $obj->trace([LEVEL])
600 See "Error handling" in Mail::Reporter
601 $obj->warnings
603 See "Error handling" in Mail::Reporter
604 Cleanup
606 $obj->DESTROY
607 See "Cleanup" in Mail::Message
608 $obj->destruct
610 See "Cleanup" in Mail::Message
611 $obj->inGlobalDestruction
613 See "Cleanup" in Mail::Reporter
614
616 Error: Cannot include forward source as $include.
617 Unknown alternative for the forward(include). Valid choices are
618 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
619 Error: Mail::Internet does not support this kind of data
621 The ARGS data can only be a file handle or an ARRAY. Other data
622 types are not supported (see read() if you want to have more).
623 Error: Method bounce requires To, Cc, or Bcc
625 The message bounce() method forwards a received message off to
626 someone else without modification; you must specified it's new
627 destination. If you have the urge not to specify any destination,
628 you probably are looking for reply(). When you wish to modify the
629 content, use forward().
630 Error: Method forwardAttach requires a preamble
632 Error: Method forwardEncapsulate requires a preamble
633 Error: No address to create forwarded to.
634 If a forward message is created, a destination address must be
635 specified.
636 Error: No rebuild rule $name defined.
638 Error: Only build() Mail::Message's; they are not in a folder yet
639 You may wish to construct a message to be stored in a some kind of
640 folder, but you need to do that in two steps. First, create a
641 normal Mail::Message, and then add it to the folder. During this
642 Mail::Box::addMessage() process, the message will get coerce()-d
643 into the right message type, adding storage information and the
644 like.
645 Error: Package $package does not implement $method.
647 Fatal error: the specific package (or one of its superclasses) does
648 not implement this method where it should. This message means that
649 some other related classes do implement this method however the
650 class at hand does not. Probably you should investigate this and
651 probably inform the author of the package.
652
654 This module is part of Mail-Box distribution version 2.097, built on
655 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
656
658 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
659 ChangeLog.
660 This program is free software; you can redistribute it and/or modify it
662 under the same terms as Perl itself. See
663 http://www.perl.com/perl/misc/Artistic.html
664perl v5.12.3 2011-0M1a-i2l6::Message::Replace::MailInternet(3)