Mail::Header(3pm)

1Mail::Header(3)       User Contributed Perl Documentation      Mail::Header(3)
2
3
4

NAME

6       Mail::Header - manipulate MIME headers
7

INHERITANCE

SYNOPSIS

10        use Mail::Header;
11
12        my $head = Mail::Header->new;
13        my $head = Mail::Header->new( \*STDIN );
14        my $head = Mail::Header->new( [<>], Modify => 0);
15

DESCRIPTION

17       Read, write, create, and manipulate MIME headers, the leading part of
18       each modern e-mail message, but also used in other protocols like HTTP.
19       The fields are kept in Mail::Field objects.
20
21       Be aware that the header fields each have a name part, which shall be
22       treated case-insensitive, and a content part, which may be folded over
23       multiple lines.
24
25       Mail::Header does not always follow the RFCs strict enough, does not
26       help you with character encodings.  It does not use weak references
27       where it could (because those did not exist when the module was
28       written) which costs some performance and make the implementation a
29       little more complicated.  The Mail::Message::Head implementation is
30       much newer and therefore better.
31

METHODS

33   Constructors
34       $obj->dup
35
36           Create a duplicate of the current object.
37
38       $obj->new([ARG], [OPTIONS])
39
40       Mail::Header->new([ARG], [OPTIONS])
41
42           ARG may be either a file descriptor (reference to a GLOB) or a
43           reference to an array. If given the new object will be initialized
44           with headers either from the array of read from the file
45           descriptor.
46
47           OPTIONS is a list of options given in the form of key-value pairs,
48           just like a hash table. Valid options are
49
50            Option    --Default
51            FoldLength  79
52            MailFrom    'KEEP'
53            Modify      true
54
55           . FoldLength => INTEGER
56
57               The default length of line to be used when folding header
58               lines.  See fold_length().
59
60           . MailFrom => 'IGNORE'|'COERCE'|'KEEP'|'ERROR'
61
62               See method mail_from().
63
64           . Modify => BOOLEAN
65
66               If this value is true then the headers will be re-formatted,
67               otherwise the format of the header lines will remain unchanged.
68
69   "Fake" constructors
70       Be warned that the next constructors all require an already created
71       header object, of which the original content will be destroyed.
72
73       $obj->empty
74
75           Empty an existing "Mail::Header" object of all lines.
76
77       $obj->extract(ARRAY)
78
79           Extract a header from the given array into an existing Mail::Header
80           object. "extract" will modify this array.  Returns the object that
81           the method was called on.
82
83       $obj->header([ARRAY])
84
85           "header" does multiple operations. First it will extract a header
86           from the ARRAY, if given. It will then reformat the header (if
87           reformatting is permitted), and finally return a reference to an
88           array which contains the header in a printable form.
89
90       $obj->header_hashref([HASH])
91
92           As header(), but it will eventually set headers from a hash
93           reference, and it will return the headers as a hash reference.
94
95           example:
96
97            $fields->{From} = 'Tobias Brox <tobix@cpan.org>';
98            $fields->{To}   = ['you@somewhere', 'me@localhost'];
99            $head->header_hashref($fields);
100
101       $obj->read(FILEHANDLE)
102
103           Read a header from the given file descriptor into an existing
104           Mail::Header object.
105
106   Accessors
107       $obj->fold_length([TAG], [LENGTH])
108
109           Set the default fold length for all tags or just one. With no
110           arguments the default fold length is returned. With two arguments
111           it sets the fold length for the given tag and returns the previous
112           value. If only "LENGTH" is given it sets the default fold length
113           for the current object.
114
115           In the two argument form "fold_length" may be called as a static
116           method, setting default fold lengths for tags that will be used by
117           all "Mail::Header" objects. See the "fold" method for a description
118           on how "Mail::Header" uses these values.
119
120       $obj->mail_from('IGNORE'|'COERCE'|'KEEP'|'ERROR')
121
122           This specifies what to do when a `From ' line is encountered.
123           Valid values are "IGNORE" - ignore and discard the header, "ERROR"
124           - invoke an error (call die), "COERCE" - rename them as Mail-From
125           and "KEEP" - keep them.
126
127       $obj->modify([VALUE])
128
129           If "VALUE" is false then "Mail::Header" will not do any automatic
130           reformatting of the headers, other than to ensure that the line
131           starts with the tags given.
132
133   Processing
134       $obj->add(TAG, LINE [, INDEX])
135
136           Add a new line to the header. If TAG is "undef" the the tag will be
137           extracted from the beginning of the given line. If INDEX is given,
138           the new line will be inserted into the header at the given point,
139           otherwise the new line will be appended to the end of the header.
140
141       $obj->as_string
142
143           Returns the header as a single string.
144
145       $obj->cleanup
146
147           Remove any header line that, other than the tag, only contains
148           whitespace
149
150       $obj->combine(TAG [, WITH])
151
152           Combine all instances of TAG into one. The lines will be joined
153           together WITH, or a single space if not given. The new item will be
154           positioned in the header where the first instance was, all other
155           instances of TAG will be removed.
156
157       $obj->count(TAG)
158
159           Returns the number of times the given atg appears in the header
160
161       $obj->delete(TAG [, INDEX ])
162
163           Delete a tag from the header. If an INDEX id is given, then the Nth
164           instance of the tag will be removed. If no INDEX is given, then all
165           instances of tag will be removed.
166
167       $obj->fold([LENGTH])
168
169           Fold the header. If LENGTH is not given, then "Mail::Header" uses
170           the following rules to determine what length to fold a line.
171
172       $obj->get(TAG [, INDEX])
173
174           Get the text from a line. If an INDEX is given, then the text of
175           the Nth instance will be returned. If it is not given the return
176           value depends on the context in which "get" was called. In an array
177           context a list of all the text from all the instances of the TAG
178           will be returned. In a scalar context the text for the first
179           instance will be returned.
180
181           The lines are unfolded, but still terminated with a new-line (see
182           "chomp")
183
184       $obj->print([FILEHANDLE])
185
186           Print the header to the given file descriptor, or "STDOUT" if no
187           file descriptor is given.
188
189       $obj->replace(TAG, LINE [, INDEX ])
190
191           Replace a line in the header.  If TAG is "undef" the the tag will
192           be extracted from the beginning of the given line. If INDEX is
193           given the new line will replace the Nth instance of that tag,
194           otherwise the first instance of the tag is replaced. If the tag
195           does not appear in the header then a new line will be appended to
196           the header.
197
198       $obj->tags
199
200           Returns an array of all the tags that exist in the header. Each tag
201           will only appear in the list once. The order of the tags is not
202           specified.
203
204       $obj->unfold([TAG])
205
206           Unfold all instances of the given tag so that they do not spread
207           across multiple lines. If "TAG" is not given then all lines are
208           unfolded.
209
210           The unfolding process is wrong but (for compatibility reasons) will
211           not be repaired: only one blank at the start of the line should be
212           removed, not all of them.
213

AUTHORS

219       The MailTools bundle was developed by Graham Barr.  Later, Mark
220       Overmeer took over maintenance without commitment to further
221       development.
222
223       Mail::Cap by Gisle Aas <aas@oslonett.no>.  Mail::Field::AddrList by
224       Peter Orbaek <poe@cit.dk>.  Mail::Mailer and Mail::Send by Tim Bunce
225       <Tim.Bunce@ig.co.uk>.  For other contributors see ChangeLog.
226

LICENSE

228       Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2007 Mark
229       Overmeer <perl@overmeer.net>.
230
231       This program is free software; you can redistribute it and/or modify it
232       under the same terms as Perl itself.  See
233       http://www.perl.com/perl/misc/Artistic.html
234
235
236
237perl v5.10.1                      2008-07-29                   Mail::Header(3)