1Mail::Header(3) User Contributed Perl Documentation Mail::Header(3)
2
6 Mail::Header - manipulate MIME headers
7
9 use Mail::Header;
10 my $head = Mail::Header->new;
12 my $head = Mail::Header->new( \*STDIN );
13 my $head = Mail::Header->new( [<>], Modify => 0);
14
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 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 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
32 Constructors
33 $obj->dup()
34 Create a duplicate of the current object.
35 $obj->new( [$source], [%options] )
37 Mail::Header->new( [$source], [%options] )
38 The $source may be either a file descriptor (reference to a GLOB)
39 or a reference to an array. If given the new object will be
40 initialized with headers either from the array of read from the
41 file descriptor.
42 %options is a list of options given in the form of key-value pairs,
44 just like a hash table. Valid options are
45 -Option --Default
47 FoldLength 79
48 MailFrom 'KEEP'
49 Modify false
50 FoldLength => INTEGER
52 The default length of line to be used when folding header lines.
53 See fold_length().
54 MailFrom => 'IGNORE'|'COERCE'|'KEEP'|'ERROR'
56 See method mail_from().
57 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 "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 $obj->empty()
67 Empty an existing "Mail::Header" object of all lines.
68 $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 $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 $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 example:
85 $fields->{From} = 'Tobias Brox <tobix@cpan.org>';
87 $fields->{To} = ['you@somewhere', 'me@localhost'];
88 $head->header_hashref($fields);
89 $obj->read($fh)
91 Read a header from the given file descriptor into an existing
92 Mail::Header object.
93 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 for
100 the current object.
101 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 $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 $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 Processing
119 $obj->add( $tag, $line [, $index] )
120 Add a new line to the header. If $tag is "undef" 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 $obj->as_string()
126 Returns the header as a single string.
127 $obj->cleanup()
129 Remove any header line that, other than the tag, only contains
130 whitespace
131 $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
135 be positioned in the header where the first instance was, all other
136 instances of $tag will be removed.
137 $obj->count($tag)
139 Returns the number of times the given atg appears in the header
140 $obj->delete( $tag [, $index ] )
142 Delete a tag from the header. If an $index id is given, then the
143 Nth instance of the tag will be removed. If no $index is given,
144 then all instances of tag will be removed.
145 $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 $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 The lines are unfolded, but still terminated with a new-line (see
159 "chomp")
160 $obj->print( [$fh] )
162 Print the header to the given file descriptor, or "STDOUT" if no
163 file descriptor is given.
164 $obj->replace( $tag, $line [, $index ] )
166 Replace a line in the header. If $tag is "undef" the tag will be
167 extracted from the beginning of the given line. If $index is given
168 the new line will replace the Nth instance of that tag, otherwise
169 the first instance of the tag is replaced. If the tag does not
170 appear in the header then a new line will be appended to the
171 header.
172 $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 $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 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
188 This module is part of the MailTools distribution,
189 http://perl.overmeer.net/mailtools/.
190
192 The MailTools bundle was developed by Graham Barr. Later, Mark
193 Overmeer took over maintenance without commitment to further
194 development.
195 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
201 Copyrights 1995-2000 Graham Barr <gbarr@pobox.com> and 2001-2017 Mark
202 Overmeer <perl@overmeer.net>.
203 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
207perl v5.32.0 2020-07-28 Mail::Header(3)