1Mail::Message::Field(3)User Contributed Perl DocumentatioMnail::Message::Field(3)
2
6 Mail::Message::Field - one line of a message header
7
9 Mail::Message::Field
10 is a Mail::Reporter
11 Mail::Message::Field is extended by
13 Mail::Message::Field::Fast
14 Mail::Message::Field::Flex
15 Mail::Message::Field::Full
16
18 my $field = Mail::Message::Field->new(From => 'fish@tux.aq');
19 print $field->name;
20 print $field->body;
21 print $field->comment;
22 print $field->content; # body & comment
23 $field->print(\*OUT);
24 print $field->string;
25 print "$field\n";
26 print $field->attribute('charset') || 'us-ascii';
27
29 This implementation follows the guidelines of rfc2822 as close as
30 possible, and may there produce a different output than implementations
31 based on the obsolete rfc822. However, the old output will still be
32 accepted.
33 These objects each store one header line, and facilitates access
35 routines to the information hidden in it. Also, you may want to have a
36 look at the added methods of a message:
37 my @from = $message->from;
39 my $sender = $message->sender;
40 my $subject = $message->subject;
41 my $msgid = $message->messageId;
42 my @to = $message->to;
44 my @cc = $message->cc;
45 my @bcc = $message->bcc;
46 my @dest = $message->destinations;
47 my $other = $message->get('Reply-To');
49
51 overload: ""
52 (stringification) produces the unfolded body of the field, which
53 may be what you expect. This is what makes what the field object
54 seems to be a simple string. The string is produced by
55 unfoldedBody().
56 example:
58 print $msg->get('subject'); # via overloading
60 print $msg->get('subject')->unfoldedBody; # same
61 my $subject = $msg->get('subject') || 'your mail';
63 print "Re: $subject\n";
64 overload: +0
66 (numification) When the field is numeric, the value will be
67 returned. The result is produced by toInt(). If the value is not
68 correct, a 0 is produced, to simplify calculations.
69 overload: <=>
71 (numeric comparison) Compare the integer field contents with
72 something else.
73 example:
75 if($msg->get('Content-Length') > 10000) ...
77 if($msg->size > 10000) ... ; # same, but better
78 overload: bool
80 Always true, to make it possible to say "if($field)".
81 overload: cmp
83 (string comparison) Compare the unfolded body of a field with an
84 other field or a string, using the buildin "cmp".
85
87 Constructors
88 $obj->clone
89 Create a copy of this field object.
90 Mail::Message::Field->new(DATA)
92 See Mail::Message::Field::Fast::new(),
93 Mail::Message::Field::Flex::new(), and
94 Mail::Message::Field::Full::new(). By default, a "Fast" field is
95 produced.
96 -Option--Defined in --Default
98 log Mail::Reporter 'WARNINGS'
99 trace Mail::Reporter 'WARNINGS'
100 log => LEVEL
102 trace => LEVEL
103 The field
105 $obj->isStructured
106 Mail::Message::Field->isStructured
107 Some fields are described in the RFCs as being structured: having a
109 well described syntax. These fields have common ideas about
110 comments and the like, what they do not share with unstructured
111 fields, like the "Subject" field.
112 example:
114 my $field = Mail::Message::Field->new(From => 'me');
116 if($field->isStructured)
117 Mail::Message::Field->isStructured('From');
119 $obj->length
121 Returns the total length of the field in characters, which includes
122 the field's name, body and folding characters.
123 $obj->nrLines
125 Returns the number of lines needed to display this header-line.
126 $obj->print([FILEHANDLE])
128 Print the whole header-line to the specified file-handle. One line
129 may result in more than one printed line, because of the folding of
130 long lines. The FILEHANDLE defaults to the selected handle.
131 $obj->size
133 Returns the number of bytes needed to display this header-line,
134 Same as length().
135 $obj->string([WRAP])
137 Returns the field as string. By default, this returns the same as
138 folded(). However, the optional WRAP will cause to re-fold to take
139 place (without changing the folding stored inside the field).
140 $obj->toDisclose
142 Returns whether this field can be disclosed to other people, for
143 instance when sending the message to an other party. Returns a
144 "true" or "false" condition. See also
145 Mail::Message::Head::Complete::printUndisclosed().
146 Access to the name
148 $obj->Name
149 Returns the name of this field in original casing. See name() as
150 well.
151 $obj->name
153 Returns the name of this field, with all characters lower-cased for
154 ease of comparison. See Name() as well.
155 $obj->wellformedName([STRING])
157 (Instance method class method) As instance method, the current
158 field's name is correctly formatted and returned. When a STRING is
159 used, that one is formatted.
160 example:
162 print Mail::Message::Field->Name('content-type')
164 # --> Content-Type
165 my $field = $head->get('date');
167 print $field->Name;
168 # --> Date
169 Access to the body
171 $obj->body
172 This method may be what you want, but usually, the foldedBody() and
173 unfoldedBody() are what you are looking for. This method is
174 cultural heritage, and should be avoided.
175 Returns the body of the field. When this field is structured, it
177 will be stripped from everything what is behind the first semi-
178 color (";"). In any case, the string is unfolded. Whether the
179 field is structured is defined by isStructured().
180 $obj->folded
182 Returns the folded version of the whole header. When the header is
183 shorter than the wrap length, a list of one line is returned.
184 Otherwise more lines will be returned, all but the first starting
185 with at least one blank. See also foldedBody() to get the same
186 information without the field's name.
187 In scalar context, the lines are delived into one string, which is
189 a little faster because that's the way they are stored
190 internally...
191 example:
193 my @lines = $field->folded;
195 print $field->folded;
196 print scalar $field->folded; # faster
197 $obj->foldedBody([BODY])
199 Returns the body as a set of lines. In scalar context, this will be
200 one line containing newlines. Be warned about the newlines when
201 you do pattern-matching on the result of thie method.
202 The optional BODY argument changes the field's body. The folding
204 of the argument must be correct.
205 $obj->stripCFWS([STRING])
207 Mail::Message::Field->stripCFWS([STRING])
208 Remove the comments and folding white spaces from the STRING.
210 Without string and only as instance method, the unfoldedBody() is
211 being stripped and returned.
212 WARNING: This operation is only allowed for structured header
214 fields (which are defined by the various RFCs as being so. You
215 don't want parts within braces which are in the Subject header line
216 to be removed, to give an example.
217 $obj->unfoldedBody([BODY, [WRAP]])
219 Returns the body as one single line, where all folding information
220 (if available) is removed. This line will also NOT end on a new-
221 line.
222 The optional BODY argument changes the field's body. The right
224 folding is performed before assignment. The WRAP may be specified
225 to enforce a folding size.
226 example:
228 my $body = $field->unfoldedBody;
230 print "$field"; # via overloading
231 Access to the content
233 $obj->addresses
234 Returns a list of Mail::Address objects, which represent the e-mail
235 addresses found in this header line.
236 example:
238 my @addr = $message->head->get('to')->addresses;
240 my @addr = $message->to;
241 $obj->attribute(NAME [, VALUE])
243 Get the value of an attribute, optionally after setting it to a new
244 value. Attributes are part of some header lines, and hide
245 themselves in the comment field. If the attribute does not exist,
246 then "undef" is returned. The attribute is still encoded.
247 example:
249 my $field = Mail::Message::Field->new(
251 'Content-Type: text/plain; charset="us-ascii"');
252 print $field->attribute('charset');
254 # --> us-ascii
255 print $field->attribute('bitmap') || 'no'
257 # --> no
258 $field->atrribute(filename => '/tmp/xyz');
260 $field->print;
261 # --> Content-Type: text/plain; charset="us-ascii";
262 # filename="/tmp/xyz"
263 # Automatically folded, and no doubles created.
264 $obj->attributes
266 Returns a list of key-value pairs, where the values are not yet
267 decoded.
268 example:
270 my %attributes = $head->get('Content-Disposition')->attributes;
272 $obj->comment([STRING])
274 Returns the unfolded comment (part after a semi-colon) in a
275 structureed header-line. optionally after setting it to a new
276 STRING first. When "undef" is specified as STRING, the comment is
277 removed. Whether the field is structured is defined by
278 isStructured().
279 The comment part of a header field often contains "attributes".
281 Often it is preferred to use attribute() on them.
282 $obj->study
284 Study the header field in detail: turn on the full parsing and
285 detailed understanding of the content of the fields.
286 Mail::Message::Field::Fast and Mail::Message::Field::Fast objects
287 will be transformed into any Mail::Message::Field::Full object.
288 example:
290 my $subject = $msg->head->get('subject')->study;
292 my $subject = $msg->head->study('subject'); # same
293 my $subject = $msg->study('subject'); # same
294 $obj->toDate([TIME])
296 Mail::Message::Field->toDate([TIME])
297 Convert a timestamp into an rfc2822 compliant date format. This
299 differs from the default output of "localtime" in scalar context.
300 Without argument, the "localtime" is used to get the current time.
301 TIME can be specified as one numeric (like the result of "time()")
302 and as list (like produced by c<localtime()> in list context).
303 Be sure to have your timezone set right, especially when this
305 script runs automatically.
306 example:
308 my $now = time;
310 Mail::Message::Field->toDate($now);
311 Mail::Message::Field->toDate(time);
312 Mail::Message::Field->toDate(localtime);
314 Mail::Message::Field->toDate; # same
315 # returns someting like:
316 # Wed, 28 Aug 2002 10:40:25 +0200
317 $obj->toInt
319 Returns the value which is related to this field as integer. A
320 check is performed whether this is right.
321 Other methods
323 $obj->dateToTimestamp(STRING)
324 Mail::Message::Field->dateToTimestamp(STRING)
325 Convert a STRING which represents and RFC compliant time string
327 into a timestamp like is produced by the "time" function.
328 Internals
330 $obj->consume(LINE | (NAME,BODY|OBJECTS))
331 Accepts a whole field LINE, or a pair with the field's NAME and
332 BODY. In the latter case, the BODY data may be specified as array
333 of OBJECTS which are stringified. Returned is a nicely formatted
334 pair of two strings: the field's name and a folded body.
335 This method is called by new(), and usually not by an application
337 program. The details about converting the OBJECTS to a field
338 content are explained in "Specifying field data".
339 $obj->defaultWrapLength([LENGTH])
341 Any field from any header for any message will have this default
342 wrapping. This is maintained in one global variable. Without a
343 specified LENGTH, the current value is returned. The default is
344 78.
345 $obj->fold(NAME, BODY, [MAXCHARS])
347 Mail::Message::Field->fold(NAME, BODY, [MAXCHARS])
348 Make the header field with NAME fold into multiple lines. Wrapping
350 is performed by inserting newlines before a blanks in the BODY,
351 such that no line exceeds the MAXCHARS and each line is as long as
352 possible.
353 The RFC requests for folding on nice spots, but this request is
355 mainly ignored because it would make folding too slow.
356 $obj->setWrapLength([LENGTH])
358 Force the wrapping of this field to the specified LENGTH
359 characters. The wrapping is performed with fold() and the results
360 stored within the field object.
361 example: refolding the field
363 $field->setWrapLength(99);
365 $obj->stringifyData(STRING|ARRAY|OBJECTS)
367 This method implements the translation of user supplied objects
368 into ascii fields. The process is explained in "Specifying field
369 data".
370 $obj->unfold(STRING)
372 The reverse action of fold(): all lines which form the body of a
373 field are joined into one by removing all line terminators (even
374 the last). Possible leading blanks on the first line are removed
375 as well.
376 Error handling
378 $obj->AUTOLOAD
379 See "Error handling" in Mail::Reporter
380 $obj->addReport(OBJECT)
382 See "Error handling" in Mail::Reporter
383 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
385 Mail::Message::Field->defaultTrace([LEVEL]|[LOGLEVEL,
386 TRACELEVEL]|[LEVEL, CALLBACK])
387 See "Error handling" in Mail::Reporter
389 $obj->errors
391 See "Error handling" in Mail::Reporter
392 $obj->log([LEVEL [,STRINGS]])
394 Mail::Message::Field->log([LEVEL [,STRINGS]])
395 See "Error handling" in Mail::Reporter
397 $obj->logPriority(LEVEL)
399 Mail::Message::Field->logPriority(LEVEL)
400 See "Error handling" in Mail::Reporter
402 $obj->logSettings
404 See "Error handling" in Mail::Reporter
405 $obj->notImplemented
407 See "Error handling" in Mail::Reporter
408 $obj->report([LEVEL])
410 See "Error handling" in Mail::Reporter
411 $obj->reportAll([LEVEL])
413 See "Error handling" in Mail::Reporter
414 $obj->trace([LEVEL])
416 See "Error handling" in Mail::Reporter
417 $obj->warnings
419 See "Error handling" in Mail::Reporter
420 Cleanup
422 $obj->DESTROY
423 See "Cleanup" in Mail::Reporter
424 $obj->inGlobalDestruction
426 See "Cleanup" in Mail::Reporter
427
429 Field syntax
430 Folding fields
431 Fields which are long can be folded to span more than one line. The
433 real limit for lines in messages is only at 998 characters, however
434 such long lines are not easy to read without support of an application.
435 Therefore rfc2822 (which defines the message syntax) specifies
436 explicitly that field lines can be re-formatted into multiple sorter
437 lines without change of meaning, by adding new-line characters to any
438 field before any blank or tab.
439 Usually, the lines are reformatted to create lines which are 78
441 characters maximum. Some applications try harder to fold on nice spots,
442 like before attributes. Especially the "Received" field is often
443 manually folded into some nice layout. In most cases however, it is
444 preferred to produce lines which are as long as possible but max 78.
445 BE WARNED that all fields can be subjected to folding, and that you
447 usually want the unfolded value.
448 Structured fields
450 The rfc2822 describes a large number of header fields explicitly.
452 These fields have a defined meaning. For some of the fields, like the
453 "Subject" field, the meaning is straight forward the contents itself.
454 These fields are the Unstructured Fields.
455 Other fields have a well defined internal syntax because their content
457 is needed by e-mail applications. For instance, the "To" field contains
458 addresses which must be understood by all applications in the same way.
459 These are the Structured Fields, see isStructured().
460 Comments in fields
462 Stuctured fields can contain comments, which are pieces of text
464 enclosed in parenthesis. These comments can be placed close to
465 anywhere in the line and must be ignored be the application. Not all
466 applications are capable of handling comments correctly in all
467 circumstances.
468 Fields are stored in the header of a message, which are represented by
470 Mail::Message::Head objects. A field is a combination of a name, body,
471 and attributes. Especially the term "body" is cause for confusion:
472 sometimes the attributes are considered to be part of the body.
473 The name of the field is followed by a colon ("":"", not preceded by
475 blanks, but followed by one blank). Each attribute is preceded by a
476 separate semi-colon ("";""). Names of fields are case-insensitive and
477 cannot contain blanks.
478 Getting a field
480 Using get() field
481 The "get()" interface is copied from other Perl modules which can
483 handle e-mail messages. Many applications which simply replace
484 Mail::Internet objects by Mail::Message objects will work without
485 modification.
486 There is more than one get method. The exact results depend on which
488 get you use. When Mail::Message::get() is called, you will get the
489 unfolded, stripped from comments, stripped from attributes contents of
490 the field as string. Character-set encodings will still be in the
491 string. If the same fieldname appears more than once in the header,
492 only the last value is returned.
493 When Mail::Message::Head::get() is called in scalar context, the last
495 field with the specified name is returned as field object. This object
496 strinigfies into the unfolded contents of the field, including
497 attributes and comments. In list context, all appearances of the field
498 in the header are returned as objects.
499 BE WARNED that some lines seem unique, but are not according to the
501 official rfc. For instance, "To" fields can appear more than once. If
502 your program calls "get('to')" in scalar context, some information is
503 lost.
504 Using study() field
506 As the name "study" already implies, this way of accessing the fields
508 is much more thorough but also slower. The "study" of a field is like
509 a "get", but provides easy access to the content of the field and
510 handles character-set decoding correctly.
511 The Mail::Message::study() method will only return the last field with
513 that name as object. Mail::Message::Head::study() and
514 Mail::Message::Field::study() return all fields when used in list
515 context.
516 Using resent groups
518 Some fields belong together in a group of fields. For instance, a set
520 of lines is used to define one step in the mail transport process.
521 Each step adds a "Received" line, and optionally some "Resent-*" lines
522 and "Return-Path". These groups of lines shall stay together and in
523 order when the message header is processed.
524 The "Mail::Message::Head::ResentGroup" object simplifies the access to
526 these related fields. These resent groups can be deleted as a whole,
527 or correctly constructed.
528 As many programs as there are handling e-mail, as many variations on
530 accessing the header information are requested. Be careful which way
531 you access the data: read the variations described here and decide
532 which solution suites your needs best.
533 The field's data
535 Access to the field
536 · string()
538 Returns the text of the body exactly as will be printed to file
540 when print() is called, so name, main body, and attributes.
541 · foldedBody()
543 Returns the text of the body, like string(), but without the name
545 of the field.
546 · unfoldedBody()
548 Returns the text of the body, like foldedBody(), but then with all
550 new-lines removed. This is the normal way to get the content of
551 unstructured fields. Character-set encodings will still be in
552 place. Fields are stringified into their unfolded representation.
553 · stripCFWS()
555 Returns the text of structured fields, where new-lines and comments
557 are removed from the string. This is a good start for parsing the
558 field, for instance to find e-mail addresses in them.
559 · Mail::Message::Field::Full::decodedBody()
561 Studied fields can produce the unfolded text decoded into utf8
563 strings. This is an expensive process, but the only correct way to
564 get the field's data. More useful for people who are not living in
565 ASCII space.
566 · Studied fields
568 Studied fields have powerful methods to provide ways to access and
570 produce the contents of (structured) fields exactly as the involved
571 rfcs prescribe.
572 Using simplified field access
574 Some fields are accessed that often that there are support methods to
576 provide simplified access. All these methods are called upon a message
577 directly.
578 Specifying field data
580 Field data can be anything, strongly dependent on the type of field at
582 hand. If you decide to contruct the fields very carefully via some
583 Mail::Message::Field::Full extension (like via
584 Mail::Message::Field::Addresses objects), then you will have protection
585 build-in. However, you can bluntly create any Mail::Message::Field
586 object based on some data.
587 When you create a field, you may specify a string, object, or an array
589 of strings and objects. On the moment, objects are only used to help
590 the construction on e-mail addresses, however you may add some of your
591 own.
592 The following rules (implemented in stringifyData()) are obeyed given
594 the argument is:
595 · a string
597 The string must be following the (complicated) rules of the
599 rfc2822, and is made field content as specified. When the string
600 is not terminated by a new-line ("\n") it will be folded according
601 to the standard rules.
602 · a Mail::Address object
604 The most used Perl object to parse and produce address lines. This
606 object does not understand character set encodings in phrases.
607 · a Mail::Identity object
609 As part of the User::Identity distribution, this object has full
611 understanding of the meaning of one e-mail address, related to a
612 person. All features defined by rfc2822 are implemented.
613 · a User::Identity object
615 A person is specified, which may have more than one
617 Mail::Identity's defined. Some methods, like
618 Mail::Message::reply() and Mail::Message::forward() try to select
619 the right e-mail address smart (see their method descriptions), but
620 in other cases the first e-mail address found is used.
621 · a User::Identity::Collection::Emails object
623 All Mail::Identity objects in the collection will be included in
625 the field as a group carying the name of the collection.
626 · any other object
628 For all other objects, the stringification overload is used to
630 produce the field content.
631 · an ARRAY
633 You may also specify an array with a mixture of any of the above.
635 The elements will be joined as comma-separated list. If you do not
636 want comma's inbetween, you will have to process the array
637 yourself.
638 There are many ways to get the fields info as object, and there are
640 also many ways to process this data within the field.
641 Field class implementation
643 For performance reasons only, there are three types of fields: the
644 fast, the flexible, and the full understander:
645 · Mail::Message::Field::Fast
647 "Fast" objects are not derived from a "Mail::Reporter". The
649 consideration is that fields are so often created, and such a small
650 objects at the same time, that setting-up a logging for each of the
651 objects is relatively expensive and not really useful. The fast
652 field implementation uses an array to store the data: that will be
653 faster than using a hash. Fast fields are not easily inheritable,
654 because the object creation and initiation is merged into one
655 method.
656 · Mail::Message::Field::Flex
658 The flexible implementation uses a hash to store the data. The
660 new() and "init" methods are split, so this object is extensible.
661 · Mail::Message::Field::Full
663 With a full implementation of all applicable RFCs (about 5), the
665 best understanding of the fields is reached. However, this comes
666 with a serious memory and performance penalty. These objects are
667 created from fast or flex header fields when study() is called.
668
670 Warning: Field content is not numerical: $content
671 The numeric value of a field is requested (for instance the "Lines"
672 or "Content-Length" fields should be numerical), however the data
673 contains weird characters.
674 Warning: Illegal character in field name $name
676 A new field is being created which does contain characters not
677 permitted by the RFCs. Using this field in messages may break
678 other e-mail clients or transfer agents, and therefore mutulate or
679 extinguish your message.
680 Error: Package $package does not implement $method.
682 Fatal error: the specific package (or one of its superclasses) does
683 not implement this method where it should. This message means that
684 some other related classes do implement this method however the
685 class at hand does not. Probably you should investigate this and
686 probably inform the author of the package.
687
689 This module is part of Mail-Box distribution version 2.097, built on
690 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
691
693 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
694 ChangeLog.
695 This program is free software; you can redistribute it and/or modify it
697 under the same terms as Perl itself. See
698 http://www.perl.com/perl/misc/Artistic.html
699perl v5.12.3 2011-01-26 Mail::Message::Field(3)