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

NAME

6       Mail::Header - manipulate MIME headers
7

SYNOPSIS

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

DESCRIPTION

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

METHODS

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

SEE ALSO

188       This module is part of the MailTools distribution,
189       http://perl.overmeer.net/mailtools/.
190

AUTHORS

192       The MailTools bundle was developed by Graham Barr.  Later, Mark
193       Overmeer took over maintenance without commitment to further
194       development.
195
196       Mail::Cap by Gisle Aas <aas@oslonett.no>.  Mail::Field::AddrList by
197       Peter Orbaek <poe@cit.dk>.  Mail::Mailer and Mail::Send by Tim Bunce
198       <Tim.Bunce@ig.co.uk>.  For other contributors see ChangeLog.
199

LICENSE

201       Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2007 Mark
202       Overmeer <perl@overmeer.net>.
203
204       This program is free software; you can redistribute it and/or modify it
205       under the same terms as Perl itself.  See
206       http://www.perl.com/perl/misc/Artistic.html
207
208
209
210perl v5.16.3                      2012-12-21                   Mail::Header(3)
Impressum