Mail::Message::Replace::MailInternet(3pm)

1Mail::Message::Replace:U:sMearilCIonntterrinbeutt(e3d)PMearill:D:oMceusmseangtea:t:iRoenplace::MailInternet(3)
2
3
4

NAME

6       Mail::Message::Replace::MailInternet - fake Mail::Internet
7

INHERITANCE

9        Mail::Message::Replace::MailInternet
10          is a Mail::Message
11          is a Mail::Reporter
12

SYNOPSIS

14        !!! BETA !!!
15
16        # 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

DESCRIPTION

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
28       Most methods will work without any change, but you may need to have a
29       look at your smtpsend() and send() calls.
30

OVERLOADED

METHODS

33       Constructors
34
35       $obj->clone(OPTIONS)
36
37           See "Constructors" in Mail::Message
38
39       $obj->dup
40
41           Duplicate the message.  The result will again be a Mail::Internet
42           compatible object.
43
44       $obj->empty
45
46           Remove all data from this object.  Very dangerous!
47
48       Mail::Message::Replace::MailInternet->new([ARG], [OPTIONS])
49
50        Option    --Defined in     --Default
51        Body                         undef
52        FoldLength                   79
53        Header                       undef
54        MailFrom                     'KEEP'
55        Modify                       0
56        body        Mail::Message    undef
57        body_type   Mail::Message    Mail::Message::Body::Lines
58        deleted     Mail::Message    <false>
59        field_type  Mail::Message    undef
60        head        Mail::Message    undef
61        head_type   Mail::Message    Mail::Message::Replace::MailHeader
62        labels      Mail::Message    {}
63        log         Mail::Reporter   'WARNINGS'
64        messageId   Mail::Message    undef
65        modified    Mail::Message    <false>
66        trace       Mail::Reporter   'WARNINGS'
67        trusted     Mail::Message    <false>
68
69           . Body ARRAY-OF-LINES
70
71               Array of "\n" terminated lines.  If not specified, the lines
72               will be read from ARG.
73
74           . FoldLength INTEGER
75
76               Number of characters permitted on any refolded header line.
77               Passed to Mail::Message::Replace::MailHeader::new(FoldLength).
78
79           . Header OBJECT
80
81               The Mail::Header object, which is passed here, is a fake one as
82               well...  It is translated into a new(head).  If not given, the
83               header will be parsed from the ARG.
84
85           . MailFrom 'IGNORE'⎪'ERROR'⎪'COERCE'⎪'KEEP'
86
87               What to do with leading ""From "" lines in e-mail data.  Passed
88               to Mail::Message::Replace::MailHeader::new(MailFrom).
89
90           . Modify BOOLEAN
91
92               Whether to re-fold all the incoming fields.  Passed to
93               Mail::Message::Replace::MailHeader::new(Modify).
94
95           . body OBJECT
96
97           . body_type CLASS
98
99           . deleted BOOLEAN
100
101           . field_type CLASS
102
103           . head OBJECT
104
105           . head_type CLASS
106
107           . labels ARRAY⎪HASH
108
109           . log LEVEL
110
111           . messageId STRING
112
113           . modified BOOLEAN
114
115           . trace LEVEL
116
117           . trusted BOOLEAN
118
119           Example: replace traditional Mail::Internet by this wrapper
120
121             # was
122             use Mail::Internet;
123             my $mi = Mail::Internet->new(@options);
124
125             # becomes
126             use Mail::Message::Replace::MailInternet;
127             my $mi = Mail::Internet->new(@options);
128
129       Attributes
130
131       $obj->MailFrom([STRING])
132
133           Your email address.
134
135       Constructing a message
136
137       $obj->add_signature([FILENAME])
138
139           Replaced by sign(), but still usable. FILENAME is the file which
140           contains the signature, which defaults to "$ENV{HOME}/.signature".
141
142       $obj->bounce([RG-OBJECT⎪OPTIONS])
143
144           See "Constructing a message" in Mail::Message::Construct::Bounce
145
146       Mail::Message::Replace::MailInternet->build([MESSAGE⎪PART⎪BODY], CON‐
147       TENT)
148
149           See "Constructing a message" in Mail::Message::Construct::Build
150
151       Mail::Message::Replace::MailInternet->buildFromBody(BODY, [HEAD], HEAD‐
152       ERS)
153
154           See "Constructing a message" in Mail::Message::Construct::Build
155
156       $obj->extract(ARRAY or FILEHANDLE)
157
158           Read header and body from an ARRAY or FILEHANDLE
159
160       $obj->forward(OPTIONS)
161
162           See "Constructing a message" in Mail::Message::Construct::Forward
163
164       $obj->forwardAttach(OPTIONS)
165
166           See "Constructing a message" in Mail::Message::Construct::Forward
167
168       $obj->forwardEncapsulate(OPTIONS)
169
170           See "Constructing a message" in Mail::Message::Construct::Forward
171
172       $obj->forwardInline(OPTIONS)
173
174           See "Constructing a message" in Mail::Message::Construct::Forward
175
176       $obj->forwardNo(OPTIONS)
177
178           See "Constructing a message" in Mail::Message::Construct::Forward
179
180       $obj->forwardPostlude
181
182           See "Constructing a message" in Mail::Message::Construct::Forward
183
184       $obj->forwardPrelude
185
186           See "Constructing a message" in Mail::Message::Construct::Forward
187
188       $obj->forwardSubject(STRING)
189
190           See "Constructing a message" in Mail::Message::Construct::Forward
191
192       $obj->read(ARRAY⎪FILEHANDLE, OPTIONS)
193
194       Mail::Message::Replace::MailInternet->read(ARRAY⎪FILEHANDLE, OPTIONS)
195
196           Read header and body from the specified ARRAY or FILEHANDLE.  When
197           used as object method, Mail::Message::read() is called, to be Mail‐
198           Box compliant.  As class method, the Mail::Internet compatible read
199           is called.  OPTIONS are only available in the first case.
200
201            Option             --Defined in     --Default
202            body_type            Mail::Message::Construct::Read  undef
203            strip_status_fields  Mail::Message::Construct::Read  <true>
204
205           . body_type CLASS
206
207           . strip_status_fields BOOLEAN
208
209       $obj->read_body(ARRAY⎪FILEHANDLE)
210
211           Read only the message's body from the ARRAY or FILEHANDLE.
212
213       $obj->read_header(ARRAY⎪FILEHANDLE)
214
215           Read only the message's header from the ARRAY or FILEHANDLE
216
217       $obj->rebuild(OPTIONS)
218
219           See "Constructing a message" in Mail::Message::Construct::Rebuild
220
221       $obj->reply(OPTIONS)
222
223           BE WARNED: the main job for creating a reply is done by Mail::Mes‐
224           sage::reply(), which may produce a result which is compatible, but
225           may be different from Mail::Internet's version.
226
227            Option         --Defined in     --Default
228            Bcc              Mail::Message::Construct::Reply  undef
229            Cc               Mail::Message::Construct::Reply  <'cc' in current>
230            Exclude                           []
231            From             Mail::Message::Construct::Reply  <'to' in current>
232            Inline                            >
233            Keep                              []
234            Message-ID       Mail::Message::Construct::Reply  <uniquely generated>
235            ReplyAll                          <false>
236            Subject          Mail::Message::Construct::Reply  replySubject()
237            To               Mail::Message::Construct::Reply  <sender in current>
238            body             Mail::Message::Construct::Reply  undef
239            group_reply      Mail::Message::Construct::Reply  <true>
240            header_template                   $ENV{HOME}/.mailhdr
241            include          Mail::Message::Construct::Reply  'INLINE'
242            max_signature    Mail::Message::Construct::Reply  10
243            message_type     Mail::Message::Construct::Reply  Mail::Message
244            postlude         Mail::Message::Construct::Reply  undef
245            prelude          Mail::Message::Construct::Reply  undef
246            quote            Mail::Message::Construct::Reply  '> '
247            signature        Mail::Message::Construct::Reply  undef
248            strip_signature  Mail::Message::Construct::Reply  qr/^--\s/
249
250           . Bcc ADDRESSES
251
252           . Cc ADDRESSES
253
254           . Exclude ARRAY-OF-NAMES
255
256               Remove the fields witht the specified names from the produced
257               reply message.
258
259           . From ADDRESSES
260
261           . Inline STRING
262
263               Quotation STRING, which is translated into reply(quote).  The
264               normal default of "quote" is "> ", in stead of ">".
265
266           . Keep ARRAY-OF-NAMES
267
268               Copy all header fields with the specified NAMES from the source
269               to the reply message.
270
271           . Message-ID STRING
272
273           . ReplyAll BOOLEAN
274
275               Reply to the group?  Translated into reply(group_reply), which
276               has as default the exact oposite of this option, being "true".
277
278           . Subject STRING⎪CODE
279
280           . To ADDRESSES
281
282           . body BODY
283
284           . group_reply BOOLEAN
285
286           . header_template FILENAME⎪"undef"
287
288               Read the return header from the template file.  When this is
289               explicitly set to "undef", or the file does not exist, then a
290               header will be created.
291
292           . include 'NO'⎪'INLINE'⎪'ATTACH'
293
294           . max_signature INTEGER
295
296           . message_type CLASS
297
298           . postlude BODY⎪LINES
299
300           . prelude BODY⎪LINES
301
302           . quote CODE⎪STRING
303
304           . signature BODY⎪MESSAGE
305
306           . strip_signature REGEXP⎪STRING⎪CODE
307
308       $obj->replyPrelude([STRING⎪FIELD⎪ADDRESS⎪ARRAY-OF-THINGS])
309
310           See "Constructing a message" in Mail::Message::Construct::Reply
311
312       $obj->replySubject(STRING)
313
314       Mail::Message::Replace::MailInternet->replySubject(STRING)
315
316           See "Constructing a message" in Mail::Message::Construct::Reply
317
318       $obj->sign(OPTIONS)
319
320           Add a signature (a few extra lines) to the message.
321
322            Option   --Default
323            File       undef
324            Signature  ''
325
326           . File FILENAME
327
328               Specifies a filename where the signature is in.
329
330           . Signature STRING⎪ARRAY-OF-LINES
331
332               The signature in memory.
333
334       The message
335
336       $obj->container
337
338           See "The message" in Mail::Message
339
340       $obj->isDummy
341
342           See "The message" in Mail::Message
343
344       $obj->isPart
345
346           See "The message" in Mail::Message
347
348       $obj->messageId
349
350           See "The message" in Mail::Message
351
352       $obj->nntppost(OPTIONS)
353
354           Send an NNTP message (newsgroup message), which is equivalent to
355           Mail::Transport::NNTP or Mail::Message::send() with "via 'nntp'".
356
357            Option--Default
358            Debug   <false>
359            Host    <from Net::Config>
360            Port    119
361
362           . Debug BOOLEAN
363
364           . Host HOSTNAME
365
366           . Port INTEGER
367
368       $obj->print([FILEHANDLE])
369
370           Prints the whole message to the specified FILEHANDLE, which default
371           to STDOUT.  This calls Mail::Message::print().
372
373       $obj->send(TYPE, OPTIONS)
374
375           Send via Mail Transfer Agents (MUA).  These will be handled by var‐
376           ious Mail::Transport::Send extensions.  The "test" TYPE is not sup‐
377           ported.
378
379       $obj->size
380
381           See "The message" in Mail::Message
382
383       $obj->toplevel
384
385           See "The message" in Mail::Message
386
387       $obj->write([FILEHANDLE])
388
389           See "The message" in Mail::Message
390
391       The header
392
393       $obj->add(LINES)
394
395           Add header lines, which simply calls "Mail::Message::Head::add()"
396           on the header for each specified LINE. The last added LINE is
397           returned.
398
399       $obj->bcc
400
401           See "The header" in Mail::Message
402
403       $obj->cc
404
405           See "The header" in Mail::Message
406
407       $obj->clean_header
408
409           Not to be used, replaced by header().
410
411       $obj->combine(TAG, [WITH])
412
413           Not implemented, because I see no use for it.
414
415       $obj->date
416
417           See "The header" in Mail::Message
418
419       $obj->delete(NAME, [INDEX]])
420
421           Delete the fields with the specified NAME.  The deleted fields are
422           returned.
423
424           BE WARNED: if no NAME is specified, the "delete" is interpreted as
425           the deletion of the message in a folder, so Mail::Box::Mes‐
426           sage::delete() will be called.  This may have no negative effect at
427           all...
428
429           Calls Mail::Message::Replace::MailHeader::delete()
430
431       $obj->destinations
432
433           See "The header" in Mail::Message
434
435       $obj->fold([LENGTH])
436
437           Fold all the fields to a certain maximum LENGTH.  Implemented by
438           Mail::Message::Replace::MailHeader::fold()
439
440       $obj->fold_length([[TAG], LENGTH])
441
442           Set the maximum line LENGTH.  TAG is ignored.  Implemented by
443           Mail::Message::Replace::MailHeader::fold_length()
444
445       $obj->from
446
447           See "The header" in Mail::Message
448
449       $obj->get(NAME, [INDEX])
450
451           Get all the header fields with the specified NAME.  In scalar con‐
452           text, only the first fitting NAME is returned.  Even when only one
453           NAME is specified, multiple lines may be returned: some fields
454           appear more than once in a header.  Calls Mail::Mes‐
455           sage::Replace::MailHeader::get()
456
457       $obj->guessTimestamp
458
459           See "The header" in Mail::Message
460
461       $obj->head([HEAD])
462
463           Returns the head of the message, or creates an empty one if none is
464           defined.  The HEAD argument, which sets the header, is not avail‐
465           able for Mail::Internet, but is there to be compatible with the
466           "head" method of Mail::Message.
467
468       $obj->header([ARRAY])
469
470           Optionally reads a header from the ARRAY, and then returns those
471           fields as array-ref nicely folded.  Implemented by Mail::Mes‐
472           sage::Replace::MailHeader::header()
473
474       $obj->nrLines
475
476           See "The header" in Mail::Message
477
478       $obj->print_header(FILEHANDLE)
479
480           Calls Mail::Message::Head::Complete::print().
481
482       $obj->replace(TAG, LINE, [INDEX])
483
484           Adds LINES to the header, but removes fields with the same name if
485           they already exist.  Calls Mail::Message::Replace::Mail‐
486           Header::replace()
487
488       $obj->sender
489
490           See "The header" in Mail::Message
491
492       $obj->study(FIELDNAME)
493
494           See "The header" in Mail::Message
495
496       $obj->subject
497
498           See "The header" in Mail::Message
499
500       $obj->tidy_headers
501
502           No effect anymore (always performed).
503
504       $obj->timestamp
505
506           See "The header" in Mail::Message
507
508       $obj->to
509
510           See "The header" in Mail::Message
511
512       The body
513
514       $obj->body([ARRAY-OF-LINES⎪LIST-OF-LINES])
515
516           Returns an array of lines, representing the body.  With arguments,
517           a new body will be created.  In Mail::Internet, the body is not an
518           object but a simple array.
519
520           BE WARNED: this overrules the Mail::Message::body() method, which
521           may cause some confusion.  Use bodyObject() to get access to that
522           body's data.
523
524       $obj->bodyObject([BODY])
525
526           Calls Mail::Message::body(), because that "body" method is over‐
527           ruled by the one which has a Mail::Internet compatible interface.
528
529       $obj->decoded(OPTIONS)
530
531           See "The body" in Mail::Message
532
533       $obj->encode(OPTIONS)
534
535           See "The body" in Mail::Message
536
537       $obj->isMultipart
538
539           See "The body" in Mail::Message
540
541       $obj->isNested
542
543           See "The body" in Mail::Message
544
545       $obj->parts(['ALL'⎪'ACTIVE'⎪'DELETED'⎪'RECURSE'⎪FILTER])
546
547           See "The body" in Mail::Message
548
549       $obj->print_body([FILEHANDLE])
550
551           Prints the body to the specified FILEHANDLE, which defaults to STD‐
552           OUT.  This calls Mail::Message::Body::print().
553
554       $obj->remove_sig([NRLINES])
555
556           Remove the signature of a message with a maximum of NRLINES lines,
557           which defaults to 10.  The work is done on the decoded body con‐
558           tent, by Mail::Message::Body::stripSignature().
559
560       $obj->smtpsend(OPTIONS)
561
562           This method is calling Mail::Message::send() via "smtp", which is
563           implemented in Mail::Transport::SMTP.  The implementation is
564           slightly different, so this method is not 100% compliant.
565
566            Option  --Default
567            Debug     <false>
568            Hello     <helo_domain from Net::Config>
569            Host      $ENV{SMTPHOSTS} or from Net::Config
570            MailFrom  $ENV{MAILADDRESS} or $ENV{USER}
571            Port      25
572
573           . Debug BOOLEAN
574
575           . Hello STRING
576
577           . Host HOSTNAME
578
579               Only the first detected HOSTNAME is taken, so differs from the
580               original implementation.
581
582           . MailFrom STRING
583
584               Your e-mail address.  This simulated Mail::Internet object does
585               not try to create an e-mail address from the sendmail configu‐
586               ration file, because that is generally a bad idea in environ‐
587               ments with virtual hosts, as we have now-adays.
588
589           . Port INTEGER
590
591       $obj->tidy_body
592
593           Removes blank lines from begin and end of the body.
594
595       Flags
596
597       $obj->deleted([BOOLEAN])
598
599           See "Flags" in Mail::Message
600
601       $obj->isDeleted
602
603           See "Flags" in Mail::Message
604
605       $obj->isModified
606
607           See "Flags" in Mail::Message
608
609       $obj->label(LABEL⎪PAIRS)
610
611           See "Flags" in Mail::Message
612
613       $obj->labels
614
615           See "Flags" in Mail::Message
616
617       $obj->labelsToStatus
618
619           See "Flags" in Mail::Message
620
621       $obj->modified([BOOLEAN])
622
623           See "Flags" in Mail::Message
624
625       $obj->statusToLabels
626
627           See "Flags" in Mail::Message
628
629       The whole message as text
630
631       $obj->as_mbox_string
632
633           Returns the whole message as one string, which can be included in
634           an MBOX folder (while not using Mail::Box::Mbox).  Lines in the
635           body which start with "From " are escaped with an >.
636
637       $obj->file
638
639           See "The whole message as text" in Mail::Message::Construct::Text
640
641       $obj->lines
642
643           See "The whole message as text" in Mail::Message::Construct::Text
644
645       $obj->printStructure([FILEHANDLE⎪undef],[INDENT])
646
647           See "The whole message as text" in Mail::Message::Construct::Text
648
649       $obj->string
650
651           See "The whole message as text" in Mail::Message::Construct::Text
652
653       The nasty bits
654
655       $obj->isa(CLASS)
656
657       Mail::Message::Replace::MailInternet->isa(CLASS)
658
659           Of course, the "isa()" class inheritance check should not see our
660           nasty trick.
661
662       Internals
663
664       $obj->clonedFrom
665
666           See "Internals" in Mail::Message
667
668       Mail::Message::Replace::MailInternet->coerce(MESSAGE)
669
670           Coerce (adapt type) of the specified MESSAGE (anything Mail::Mes‐
671           sage::coerce() accepts) into an Mail::Internet simulating object.
672
673       $obj->isDelayed
674
675           See "Internals" in Mail::Message
676
677       $obj->readBody(PARSER, HEAD [, BODYTYPE])
678
679           See "Internals" in Mail::Message
680
681       $obj->readFromParser(PARSER, [BODYTYPE])
682
683           See "Internals" in Mail::Message
684
685       $obj->readHead(PARSER [,CLASS])
686
687           See "Internals" in Mail::Message
688
689       $obj->recursiveRebuildPart(PART, OPTIONS)
690
691           See "Internals" in Mail::Message::Construct::Rebuild
692
693       $obj->storeBody(BODY)
694
695           See "Internals" in Mail::Message
696
697       $obj->takeMessageId([STRING])
698
699           See "Internals" in Mail::Message
700
701       Error handling
702
703       $obj->AUTOLOAD
704
705           See "METHODS" in Mail::Message::Construct
706
707       $obj->addReport(OBJECT)
708
709           See "Error handling" in Mail::Reporter
710
711       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
712
713       Mail::Message::Replace::MailInternet->defaultTrace([LEVEL]⎪[LOGLEVEL,
714       TRACELEVEL]⎪[LEVEL, CALLBACK])
715
716           See "Error handling" in Mail::Reporter
717
718       $obj->errors
719
720           See "Error handling" in Mail::Reporter
721
722       $obj->log([LEVEL [,STRINGS]])
723
724       Mail::Message::Replace::MailInternet->log([LEVEL [,STRINGS]])
725
726           See "Error handling" in Mail::Reporter
727
728       $obj->logPriority(LEVEL)
729
730       Mail::Message::Replace::MailInternet->logPriority(LEVEL)
731
732           See "Error handling" in Mail::Reporter
733
734       $obj->logSettings
735
736           See "Error handling" in Mail::Reporter
737
738       $obj->notImplemented
739
740           See "Error handling" in Mail::Reporter
741
742       $obj->report([LEVEL])
743
744           See "Error handling" in Mail::Reporter
745
746       $obj->reportAll([LEVEL])
747
748           See "Error handling" in Mail::Reporter
749
750       $obj->shortSize([VALUE])
751
752       Mail::Message::Replace::MailInternet->shortSize([VALUE])
753
754           See "Error handling" in Mail::Message
755
756       $obj->shortString
757
758           See "Error handling" in Mail::Message
759
760       $obj->trace([LEVEL])
761
762           See "Error handling" in Mail::Reporter
763
764       $obj->warnings
765
766           See "Error handling" in Mail::Reporter
767
768       Cleanup
769
770       $obj->DESTROY
771
772           See "Cleanup" in Mail::Message
773
774       $obj->destruct
775
776           See "Cleanup" in Mail::Message
777
778       $obj->inGlobalDestruction
779
780           See "Cleanup" in Mail::Reporter
781

DETAILS

DIAGNOSTICS

784       Error: Cannot include forward source as $include.
785
786       Unknown alternative for the forward(include).  Valid choices are "NO",
787       "INLINE", "ATTACH", and "ENCAPSULATE".
788
789       Error: Mail::Internet does not support this kind of data
790
791       The ARGS data can only be a file handle or an ARRAY.  Other data types
792       are not supported (see read() if you want to have more).
793
794       Error: Method bounce requires To, Cc, or Bcc
795
796       The message bounce() method forwards a received message off to someone
797       else without modification; you must specified it's new destination.  If
798       you have the urge not to specify any destination, you probably are
799       looking for reply(). When you wish to modify the content, use for‐
800       ward().
801
802       Error: Method forwardAttach requires a preamble
803
804       Error: Method forwardEncapsulate requires a preamble
805
806       Error: No address to create forwarded to.
807
808       If a forward message is created, a destination address must be speci‐
809       fied.
810
811       Error: No rebuild rule $name defined.
812
813       Error: Only build() Mail::Message's; they are not in a folder yet
814
815       You may wish to construct a message to be stored in a some kind of
816       folder, but you need to do that in two steps.  First, create a normal
817       Mail::Message, and then add it to the folder.  During this
818       Mail::Box::addMessage() process, the message will get coerce()-d into
819       the right message type, adding storage information and the like.
820
821       Error: Package $package does not implement $method.
822
823       Fatal error: the specific package (or one of its superclasses) does not
824       implement this method where it should. This message means that some
825       other related classes do implement this method however the class at
826       hand does not.  Probably you should investigate this and probably
827       inform the author of the package.
828

LICENSE

834       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
835       ChangeLog.
836
837       This program is free software; you can redistribute it and/or modify it
838       under the same terms as Perl itself.  See
839       http://www.perl.com/perl/misc/Artistic.html
840
841
842
843perl v5.8.8                       2007-0M3a-i2l5::Message::Replace::MailInternet(3)