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 Extends "DESCRIPTION" in Mail::Message.
32
35 Extends "METHODS" in Mail::Message.
36 Constructors
38 Extends "Constructors" in Mail::Message.
39 $obj->clone(%options)
41 Inherited, see "Constructors" in Mail::Message
42 $obj->dup()
44 Duplicate the message. The result will again be a Mail::Internet
45 compatible object.
46 $obj->empty()
48 Remove all data from this object. Very dangerous!
49 Mail::Message::Replace::MailInternet->new( [$arg], [%options] )
51 -Option --Defined in --Default
52 Body undef
53 FoldLength 79
54 Header undef
55 MailFrom 'KEEP'
56 Modify 0
57 body Mail::Message undef
58 body_type Mail::Message Mail::Message::Body::Lines
59 deleted Mail::Message <false>
60 field_type Mail::Message undef
61 head Mail::Message undef
62 head_type Mail::Message Mail::Message::Replace::MailHeader
63 labels Mail::Message {}
64 log Mail::Reporter 'WARNINGS'
65 messageId Mail::Message undef
66 modified Mail::Message <false>
67 trace Mail::Reporter 'WARNINGS'
68 trusted Mail::Message <false>
69 Body => \@lines
71 Array of "\n" terminated lines. If not specified, the lines will
72 be read from $arg.
73 FoldLength => INTEGER
75 Number of characters permitted on any refolded header line.
76 Passed to Mail::Message::Replace::MailHeader::new(FoldLength).
77 Header => OBJECT
79 The Mail::Header object, which is passed here, is a fake one as
80 well... It is translated into a new(head). If not given, the
81 header will be parsed from the $arg.
82 MailFrom => 'IGNORE'|'ERROR'|'COERCE'|'KEEP'
84 What to do with leading ""From "" lines in e-mail data. Passed
85 to Mail::Message::Replace::MailHeader::new(MailFrom).
86 Modify => BOOLEAN
88 Whether to re-fold all the incoming fields. Passed to
89 Mail::Message::Replace::MailHeader::new(Modify).
90 body => OBJECT
92 body_type => CLASS
93 deleted => BOOLEAN
94 field_type => CLASS
95 head => OBJECT
96 head_type => CLASS
97 labels => ARRAY|HASH
98 log => LEVEL
99 messageId => STRING
100 modified => BOOLEAN
101 trace => LEVEL
102 trusted => BOOLEAN
103 example: replace traditional Mail::Internet by this wrapper
105 # was
107 use Mail::Internet;
108 my $mi = Mail::Internet->new(@options);
109 # becomes
111 use Mail::Message::Replace::MailInternet;
112 my $mi = Mail::Internet->new(@options);
113 Attributes
115 $obj->MailFrom( [STRING] )
116 Your email address.
117 Constructing a message
119 Extends "Constructing a message" in Mail::Message.
120 $obj->add_signature( [$filename] )
122 Replaced by sign(), but still usable. $filename is the file which
123 contains the signature, which defaults to "$ENV{HOME}/.signature".
124 $obj->bounce( [<$rg_object|%options>] )
126 Inherited, see "Constructing a message" in
127 Mail::Message::Construct::Bounce
128 Mail::Message::Replace::MailInternet->build( [$message|$part|$body],
130 $content )
131 Inherited, see "Constructing a message" in
132 Mail::Message::Construct::Build
133 Mail::Message::Replace::MailInternet->buildFromBody($body, [$head],
135 $headers)
136 Inherited, see "Constructing a message" in
137 Mail::Message::Construct::Build
138 $obj->extract(\@lines|$fh)
140 Read header and body from an ARRAY or $fh
141 $obj->forward(%options)
143 Inherited, see "Constructing a message" in
144 Mail::Message::Construct::Forward
145 $obj->forwardAttach(%options)
147 Inherited, see "Constructing a message" in
148 Mail::Message::Construct::Forward
149 $obj->forwardEncapsulate(%options)
151 Inherited, see "Constructing a message" in
152 Mail::Message::Construct::Forward
153 $obj->forwardInline(%options)
155 Inherited, see "Constructing a message" in
156 Mail::Message::Construct::Forward
157 $obj->forwardNo(%options)
159 Inherited, see "Constructing a message" in
160 Mail::Message::Construct::Forward
161 $obj->forwardPostlude()
163 Inherited, see "Constructing a message" in
164 Mail::Message::Construct::Forward
165 $obj->forwardPrelude()
167 Inherited, see "Constructing a message" in
168 Mail::Message::Construct::Forward
169 $obj->forwardSubject(STRING)
171 Inherited, see "Constructing a message" in
172 Mail::Message::Construct::Forward
173 $obj->read(\@lines|$fh, %options)
175 Mail::Message::Replace::MailInternet->read(\@lines|$fh, %options)
176 Read header and body from the specified ARRAY or $fh. When used as
177 object method, Mail::Message::read() is called, to be MailBox
178 compliant. As class method, the Mail::Internet compatible read is
179 called. %options are only available in the first case.
180 -Option --Defined in --Default
182 body_type Mail::Message::Construct::Read undef
183 strip_status_fields Mail::Message::Construct::Read <true>
184 body_type => CLASS
186 strip_status_fields => BOOLEAN
187 $obj->read_body(\@lines|$fh)
188 Read only the message's body from the ARRAY or $fh.
189 $obj->read_header(\@lines|$fh)
191 Read only the message's header from the ARRAY or $fh
192 $obj->rebuild(%options)
194 Inherited, see "Constructing a message" in
195 Mail::Message::Construct::Rebuild
196 $obj->reply(%options)
198 BE WARNED: the main job for creating a reply is done by
199 Mail::Message::reply(), which may produce a result which is
200 compatible, but may be different from Mail::Internet's version.
201 -Option --Defined in --Default
203 Bcc Mail::Message::Construct::Reply undef
204 Cc Mail::Message::Construct::Reply <'cc' in current>
205 Exclude []
206 From Mail::Message::Construct::Reply <'to' in current>
207 Inline >
208 Keep []
209 Message-ID Mail::Message::Construct::Reply <uniquely generated>
210 ReplyAll <false>
211 Subject Mail::Message::Construct::Reply replySubject()
212 To Mail::Message::Construct::Reply <sender in current>
213 body Mail::Message::Construct::Reply undef
214 group_reply Mail::Message::Construct::Reply <true>
215 header_template $ENV{HOME}/.mailhdr
216 include Mail::Message::Construct::Reply 'INLINE'
217 max_signature Mail::Message::Construct::Reply 10
218 message_type Mail::Message::Construct::Reply Mail::Message
219 postlude Mail::Message::Construct::Reply undef
220 prelude Mail::Message::Construct::Reply undef
221 quote Mail::Message::Construct::Reply '> '
222 signature Mail::Message::Construct::Reply undef
223 strip_signature Mail::Message::Construct::Reply qr/^--\s/
224 Bcc => ADDRESSES
226 Cc => ADDRESSES
227 Exclude => \@names
228 Remove the fields with the specified names from the produced
229 reply message.
230 From => ADDRESSES
232 Inline => STRING
233 Quotation STRING, which is translated into reply(quote). The
234 normal default of "quote" is "> ", in stead of ">".
235 Keep => \@names
237 Copy all header fields with the specified NAMES from the source
238 to the reply message.
239 Message-ID => STRING
241 ReplyAll => BOOLEAN
242 Reply to the group? Translated into reply(group_reply), which
243 has as default the exact oposite of this option, being "true".
244 Subject => STRING|CODE
246 To => ADDRESSES
247 body => BODY
248 group_reply => BOOLEAN
249 header_template => $filename|"undef"
250 Read the return header from the template file. When this is
251 explicitly set to "undef", or the file does not exist, then a
252 header will be created.
253 include => 'NO'|'INLINE'|'ATTACH'
255 max_signature => INTEGER
256 message_type => CLASS
257 postlude => BODY|LINES
258 prelude => BODY|LINES
259 quote => CODE|STRING
260 signature => BODY|MESSAGE
261 strip_signature => REGEXP|STRING|CODE
262 $obj->replyPrelude( [STRING|$field|$address|ARRAY-$of-$things] )
263 Inherited, see "Constructing a message" in
264 Mail::Message::Construct::Reply
265 $obj->replySubject(STRING)
267 Mail::Message::Replace::MailInternet->replySubject(STRING)
268 Inherited, see "Constructing a message" in
269 Mail::Message::Construct::Reply
270 $obj->sign(%options)
272 Add a signature (a few extra lines) to the message.
273 -Option --Default
275 File undef
276 Signature ''
277 File => $filename
279 Specifies a filename where the signature is in.
280 Signature => STRING|\@lines
282 The signature in memory.
283 The message
285 Extends "The message" in Mail::Message.
286 $obj->container()
288 Inherited, see "The message" in Mail::Message
289 $obj->isDummy()
291 Inherited, see "The message" in Mail::Message
292 $obj->isPart()
294 Inherited, see "The message" in Mail::Message
295 $obj->messageId()
297 Inherited, see "The message" in Mail::Message
298 $obj->nntppost(%options)
300 Send an NNTP message (newsgroup message), which is equivalent to
301 Mail::Transport::NNTP or Mail::Message::send() with "via 'nntp'".
302 -Option--Default
304 Debug <false>
305 Host <from Net::Config>
306 Port 119
307 Debug => BOOLEAN
309 Host => $hostname
310 Port => INTEGER
311 $obj->partNumber()
312 Inherited, see "The message" in Mail::Message
313 $obj->print( [$fh] )
315 Prints the whole message to the specified $fh, which default to
316 STDOUT. This calls Mail::Message::print().
317 $obj->send($type, %options)
319 Send via Mail Transfer Agents (MUA). These will be handled by
320 various Mail::Transport::Send extensions. The "test" $type is not
321 supported.
322 $obj->size()
324 Inherited, see "The message" in Mail::Message
325 $obj->toplevel()
327 Inherited, see "The message" in Mail::Message
328 $obj->write( [$fh] )
330 Inherited, see "The message" in Mail::Message
331 The header
333 Extends "The header" in Mail::Message.
334 $obj->add(\@lines)
336 Add header lines, which simply calls "Mail::Message::Head::add()"
337 on the header for each specified LINE. The last added LINE is
338 returned.
339 $obj->bcc()
341 Inherited, see "The header" in Mail::Message
342 $obj->cc()
344 Inherited, see "The header" in Mail::Message
345 $obj->clean_header()
347 Not to be used, replaced by header().
348 $obj->combine( $tag, [$with] )
350 Not implemented, because I see no use for it.
351 $obj->date()
353 Inherited, see "The header" in Mail::Message
354 $obj->delete( $name, [$index]] )
356 Delete the fields with the specified $name. The deleted fields are
357 returned.
358 BE WARNED: if no $name is specified, the "delete" is interpreted as
360 the deletion of the message in a folder, so
361 Mail::Box::Message::delete() will be called. This may have no
362 negative effect at all...
363 Calls Mail::Message::Replace::MailHeader::delete()
365 $obj->destinations()
367 Inherited, see "The header" in Mail::Message
368 $obj->fold( [$length] )
370 Fold all the fields to a certain maximum $length. Implemented by
371 Mail::Message::Replace::MailHeader::fold()
372 $obj->fold_length( [[$tag], $length] )
374 Set the maximum line $length. $tag is ignored. Implemented by
375 Mail::Message::Replace::MailHeader::fold_length()
376 $obj->from()
378 Inherited, see "The header" in Mail::Message
379 $obj->get( $name, [$index] )
381 Get all the header fields with the specified $name. In scalar
382 context, only the first fitting $name is returned. Even when only
383 one $name is specified, multiple lines may be returned: some fields
384 appear more than once in a header. Calls
385 Mail::Message::Replace::MailHeader::get()
386 $obj->guessTimestamp()
388 Inherited, see "The header" in Mail::Message
389 $obj->head( [$head] )
391 Returns the head of the message, or creates an empty one if none is
392 defined. The $head argument, which sets the header, is not
393 available for Mail::Internet, but is there to be compatible with
394 the "head" method of Mail::Message.
395 $obj->header( [\@lines] )
397 Optionally reads a header from the ARRAY of lines, and then returns
398 those fields as array-ref nicely folded. Implemented by
399 Mail::Message::Replace::MailHeader::header()
400 $obj->nrLines()
402 Inherited, see "The header" in Mail::Message
403 $obj->print_header($fh)
405 Calls Mail::Message::Head::Complete::print().
406 $obj->replace( $tag, $line, [$index] )
408 Adds LINES to the header, but removes fields with the same name if
409 they already exist. Calls
410 Mail::Message::Replace::MailHeader::replace()
411 $obj->sender()
413 Inherited, see "The header" in Mail::Message
414 $obj->study($fieldname)
416 Inherited, see "The header" in Mail::Message
417 $obj->subject()
419 Inherited, see "The header" in Mail::Message
420 $obj->tidy_headers()
422 No effect anymore (always performed).
423 $obj->timestamp()
425 Inherited, see "The header" in Mail::Message
426 $obj->to()
428 Inherited, see "The header" in Mail::Message
429 The body
431 Extends "The body" in Mail::Message.
432 $obj->body($lines|@lines)
434 Returns an ARRAY of lines, representing the body. With arguments,
435 a new body will be created. In Mail::Internet, the body is not an
436 object but a simple array.
437 BE WARNED: this overrules the Mail::Message::body() method, which
439 may cause some confusion. Use bodyObject() to get access to that
440 body's data.
441 $obj->bodyObject( [$body] )
443 Calls Mail::Message::body(), because that "body" method is
444 overruled by the one which has a Mail::Internet compatible
445 interface.
446 $obj->contentType()
448 Inherited, see "The body" in Mail::Message
449 $obj->decoded(%options)
451 Inherited, see "The body" in Mail::Message
452 $obj->encode(%options)
454 Inherited, see "The body" in Mail::Message
455 $obj->isMultipart()
457 Inherited, see "The body" in Mail::Message
458 $obj->isNested()
460 Inherited, see "The body" in Mail::Message
461 $obj->parts( [<'ALL'|'ACTIVE'|'DELETED'|'RECURSE'|$filter>] )
463 Inherited, see "The body" in Mail::Message
464 $obj->print_body( [$fh] )
466 Prints the body to the specified $fh, which defaults to STDOUT.
467 This calls Mail::Message::Body::print().
468 $obj->remove_sig( [$nrlines] )
470 Remove the signature of a message with a maximum of $nrlines lines,
471 which defaults to 10. The work is done on the decoded body
472 content, by Mail::Message::Body::stripSignature().
473 $obj->smtpsend(%options)
475 This method is calling Mail::Message::send() via "smtp", which is
476 implemented in Mail::Transport::SMTP. The implementation is
477 slightly different, so this method is not 100% compliant.
478 -Option --Default
480 Debug <false>
481 Hello <helo_domain from Net::Config>
482 Host $ENV{SMTPHOSTS} or from Net::Config
483 MailFrom $ENV{MAILADDRESS} or $ENV{USER}
484 Port 25
485 Debug => BOOLEAN
487 Hello => STRING
488 Host => HOSTNAME
489 Only the first detected HOSTNAME is taken, so differs from the
490 original implementation.
491 MailFrom => STRING
493 Your e-mail address. This simulated Mail::Internet object does
494 not try to create an e-mail address from the sendmail
495 configuration file, because that is generally a bad idea in
496 environments with virtual hosts, as we have now-adays.
497 Port => INTEGER
499 $obj->tidy_body()
500 Removes blank lines from begin and end of the body.
501 Flags
503 Extends "Flags" in Mail::Message.
504 $obj->deleted( [BOOLEAN] )
506 Inherited, see "Flags" in Mail::Message
507 $obj->isDeleted()
509 Inherited, see "Flags" in Mail::Message
510 $obj->isModified()
512 Inherited, see "Flags" in Mail::Message
513 $obj->label($label|PAIRS)
515 Inherited, see "Flags" in Mail::Message
516 $obj->labels()
518 Inherited, see "Flags" in Mail::Message
519 $obj->labelsToStatus()
521 Inherited, see "Flags" in Mail::Message
522 $obj->modified( [BOOLEAN] )
524 Inherited, see "Flags" in Mail::Message
525 $obj->statusToLabels()
527 Inherited, see "Flags" in Mail::Message
528 The whole message as text
530 Extends "The whole message as text" in Mail::Message.
531 $obj->as_mbox_string()
533 Returns the whole message as one string, which can be included in
534 an MBOX folder (while not using Mail::Box::Mbox). Lines in the
535 body which start with "From " are escaped with an >.
536 $obj->file()
538 Inherited, see "The whole message as text" in
539 Mail::Message::Construct::Text
540 $obj->lines()
542 Inherited, see "The whole message as text" in
543 Mail::Message::Construct::Text
544 $obj->printStructure( [$fh|undef],[$indent] )
546 Inherited, see "The whole message as text" in
547 Mail::Message::Construct::Text
548 $obj->string()
550 Inherited, see "The whole message as text" in
551 Mail::Message::Construct::Text
552 The nasty bits
554 $obj->isa($class)
555 Mail::Message::Replace::MailInternet->isa($class)
556 Of course, the "isa()" class inheritance check should not see our
557 nasty trick.
558 Internals
560 Extends "Internals" in Mail::Message.
561 $obj->clonedFrom()
563 Inherited, see "Internals" in Mail::Message
564 Mail::Message::Replace::MailInternet->coerce($message)
566 Coerce (adapt type) of the specified $message (anything
567 Mail::Message::coerce() accepts) into an Mail::Internet simulating
568 object.
569 $obj->isDelayed()
571 Inherited, see "Internals" in Mail::Message
572 $obj->readBody( $parser, $head, [$bodytype] )
574 Inherited, see "Internals" in Mail::Message
575 $obj->readFromParser( $parser, [$bodytype] )
577 Inherited, see "Internals" in Mail::Message
578 $obj->readHead( $parser, [$class] )
580 Inherited, see "Internals" in Mail::Message
581 $obj->recursiveRebuildPart($part, %options)
583 Inherited, see "Internals" in Mail::Message::Construct::Rebuild
584 $obj->storeBody($body)
586 Inherited, see "Internals" in Mail::Message
587 $obj->takeMessageId( [STRING] )
589 Inherited, see "Internals" in Mail::Message
590 Error handling
592 Extends "Error handling" in Mail::Message.
593 $obj->AUTOLOAD()
595 Inherited, see "METHODS" in Mail::Message::Construct
596 $obj->addReport($object)
598 Inherited, see "Error handling" in Mail::Reporter
599 $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
601 $callback] )
602 Mail::Message::Replace::MailInternet->defaultTrace(
603 [$level]|[$loglevel, $tracelevel]|[$level, $callback] )
604 Inherited, see "Error handling" in Mail::Reporter
605 $obj->errors()
607 Inherited, see "Error handling" in Mail::Reporter
608 $obj->log( [$level, [$strings]] )
610 Mail::Message::Replace::MailInternet->log( [$level, [$strings]] )
611 Inherited, see "Error handling" in Mail::Reporter
612 $obj->logPriority($level)
614 Mail::Message::Replace::MailInternet->logPriority($level)
615 Inherited, see "Error handling" in Mail::Reporter
616 $obj->logSettings()
618 Inherited, see "Error handling" in Mail::Reporter
619 $obj->notImplemented()
621 Inherited, see "Error handling" in Mail::Reporter
622 $obj->report( [$level] )
624 Inherited, see "Error handling" in Mail::Reporter
625 $obj->reportAll( [$level] )
627 Inherited, see "Error handling" in Mail::Reporter
628 $obj->shortSize( [$value] )
630 Mail::Message::Replace::MailInternet->shortSize( [$value] )
631 Inherited, see "Error handling" in Mail::Message
632 $obj->shortString()
634 Inherited, see "Error handling" in Mail::Message
635 $obj->trace( [$level] )
637 Inherited, see "Error handling" in Mail::Reporter
638 $obj->warnings()
640 Inherited, see "Error handling" in Mail::Reporter
641 Cleanup
643 Extends "Cleanup" in Mail::Message.
644 $obj->DESTROY()
646 Inherited, see "Cleanup" in Mail::Reporter
647 $obj->destruct()
649 Inherited, see "Cleanup" in Mail::Message
650
652 Extends "DETAILS" in Mail::Message.
653
655 Error: Cannot include forward source as $include.
656 Unknown alternative for the forward(include). Valid choices are
657 "NO", "INLINE", "ATTACH", and "ENCAPSULATE".
658 Error: Mail::Internet does not support this kind of data
660 The ARGS data can only be a file handle or an ARRAY. Other data
661 types are not supported (see read() if you want to have more).
662 Error: Method bounce requires To, Cc, or Bcc
664 The message bounce() method forwards a received message off to
665 someone else without modification; you must specified it's new
666 destination. If you have the urge not to specify any destination,
667 you probably are looking for reply(). When you wish to modify the
668 content, use forward().
669 Error: Method forwardAttach requires a preamble
671 Error: Method forwardEncapsulate requires a preamble
672 Error: No address to create forwarded to.
673 If a forward message is created, a destination address must be
674 specified.
675 Error: No rebuild rule $name defined.
677 Error: Only build() Mail::Message's; they are not in a folder yet
678 You may wish to construct a message to be stored in a some kind of
679 folder, but you need to do that in two steps. First, create a
680 normal Mail::Message, and then add it to the folder. During this
681 Mail::Box::addMessage() process, the message will get coerce()-d
682 into the right message type, adding storage information and the
683 like.
684 Error: Package $package does not implement $method.
686 Fatal error: the specific package (or one of its superclasses) does
687 not implement this method where it should. This message means that
688 some other related classes do implement this method however the
689 class at hand does not. Probably you should investigate this and
690 probably inform the author of the package.
691
693 This module is part of Mail-Message distribution version 3.009, built
694 on February 07, 2020. Website: http://perl.overmeer.net/CPAN/
695
697 Copyrights 2001-2020 by [Mark Overmeer <markov@cpan.org>]. For other
698 contributors see ChangeLog.
699 This program is free software; you can redistribute it and/or modify it
701 under the same terms as Perl itself. See http://dev.perl.org/licenses/
702perl v5.32.0 2020-0M7a-i2l8::Message::Replace::MailInternet(3)