Mail::Header(3pm)

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

AUTHORS

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

LICENSE

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

NAME

SYNOPSIS

DESCRIPTION

METHODS

SEE ALSO

AUTHORS

LICENSE