1HTTP::Headers(3)      User Contributed Perl Documentation     HTTP::Headers(3)
2
3
4

NAME

6       HTTP::Headers - Class encapsulating HTTP Message headers
7

VERSION

9       version 6.18
10

SYNOPSIS

12        require HTTP::Headers;
13        $h = HTTP::Headers->new;
14
15        $h->header('Content-Type' => 'text/plain');  # set
16        $ct = $h->header('Content-Type');            # get
17        $h->remove_header('Content-Type');           # delete
18

DESCRIPTION

20       The "HTTP::Headers" class encapsulates HTTP-style message headers.  The
21       headers consist of attribute-value pairs also called fields, which may
22       be repeated, and which are printed in a particular order.  The field
23       names are cases insensitive.
24
25       Instances of this class are usually created as member variables of the
26       "HTTP::Request" and "HTTP::Response" classes, internal to the library.
27
28       The following methods are available:
29
30       $h = HTTP::Headers->new
31           Constructs a new "HTTP::Headers" object.  You might pass some
32           initial attribute-value pairs as parameters to the constructor.
33           E.g.:
34
35            $h = HTTP::Headers->new(
36                  Date         => 'Thu, 03 Feb 1994 00:00:00 GMT',
37                  Content_Type => 'text/html; version=3.2',
38                  Content_Base => 'http://www.perl.org/');
39
40           The constructor arguments are passed to the "header" method which
41           is described below.
42
43       $h->clone
44           Returns a copy of this "HTTP::Headers" object.
45
46       $h->header( $field )
47       $h->header( $field => $value )
48       $h->header( $f1 => $v1, $f2 => $v2, ... )
49           Get or set the value of one or more header fields.  The header
50           field name ($field) is not case sensitive.  To make the life easier
51           for perl users who wants to avoid quoting before the => operator,
52           you can use '_' as a replacement for '-' in header names.
53
54           The header() method accepts multiple ($field => $value) pairs,
55           which means that you can update several fields with a single
56           invocation.
57
58           The $value argument may be a plain string or a reference to an
59           array of strings for a multi-valued field. If the $value is
60           provided as "undef" then the field is removed.  If the $value is
61           not given, then that header field will remain unchanged.
62
63           The old value (or values) of the last of the header fields is
64           returned.  If no such field exists "undef" will be returned.
65
66           A multi-valued field will be returned as separate values in list
67           context and will be concatenated with ", " as separator in scalar
68           context.  The HTTP spec (RFC 2616) promises that joining multiple
69           values in this way will not change the semantic of a header field,
70           but in practice there are cases like old-style Netscape cookies
71           (see HTTP::Cookies) where "," is used as part of the syntax of a
72           single field value.
73
74           Examples:
75
76            $header->header(MIME_Version => '1.0',
77                            User_Agent   => 'My-Web-Client/0.01');
78            $header->header(Accept => "text/html, text/plain, image/*");
79            $header->header(Accept => [qw(text/html text/plain image/*)]);
80            @accepts = $header->header('Accept');  # get multiple values
81            $accepts = $header->header('Accept');  # get values as a single string
82
83       $h->push_header( $field => $value )
84       $h->push_header( $f1 => $v1, $f2 => $v2, ... )
85           Add a new field value for the specified header field.  Previous
86           values for the same field are retained.
87
88           As for the header() method, the field name ($field) is not case
89           sensitive and '_' can be used as a replacement for '-'.
90
91           The $value argument may be a scalar or a reference to a list of
92           scalars.
93
94            $header->push_header(Accept => 'image/jpeg');
95            $header->push_header(Accept => [map "image/$_", qw(gif png tiff)]);
96
97       $h->init_header( $field => $value )
98           Set the specified header to the given value, but only if no
99           previous value for that field is set.
100
101           The header field name ($field) is not case sensitive and '_' can be
102           used as a replacement for '-'.
103
104           The $value argument may be a scalar or a reference to a list of
105           scalars.
106
107       $h->remove_header( $field, ... )
108           This function removes the header fields with the specified names.
109
110           The header field names ($field) are not case sensitive and '_' can
111           be used as a replacement for '-'.
112
113           The return value is the values of the fields removed.  In scalar
114           context the number of fields removed is returned.
115
116           Note that if you pass in multiple field names then it is generally
117           not possible to tell which of the returned values belonged to which
118           field.
119
120       $h->remove_content_headers
121           This will remove all the header fields used to describe the content
122           of a message.  All header field names prefixed with "Content-" fall
123           into this category, as well as "Allow", "Expires" and
124           "Last-Modified".  RFC 2616 denotes these fields as Entity Header
125           Fields.
126
127           The return value is a new "HTTP::Headers" object that contains the
128           removed headers only.
129
130       $h->clear
131           This will remove all header fields.
132
133       $h->header_field_names
134           Returns the list of distinct names for the fields present in the
135           header.  The field names have case as suggested by HTTP spec, and
136           the names are returned in the recommended "Good Practice" order.
137
138           In scalar context return the number of distinct field names.
139
140       $h->scan( \&process_header_field )
141           Apply a subroutine to each header field in turn.  The callback
142           routine is called with two parameters; the name of the field and a
143           single value (a string).  If a header field is multi-valued, then
144           the routine is called once for each value.  The field name passed
145           to the callback routine has case as suggested by HTTP spec, and the
146           headers will be visited in the recommended "Good Practice" order.
147
148           Any return values of the callback routine are ignored.  The loop
149           can be broken by raising an exception ("die"), but the caller of
150           scan() would have to trap the exception itself.
151
152       $h->flatten()
153           Returns the list of pairs of keys and values.
154
155       $h->as_string
156       $h->as_string( $eol )
157           Return the header fields as a formatted MIME header.  Since it
158           internally uses the "scan" method to build the string, the result
159           will use case as suggested by HTTP spec, and it will follow
160           recommended "Good Practice" of ordering the header fields.  Long
161           header values are not folded.
162
163           The optional $eol parameter specifies the line ending sequence to
164           use.  The default is "\n".  Embedded "\n" characters in header
165           field values will be substituted with this line ending sequence.
166

CONVENIENCE METHODS

168       The most frequently used headers can also be accessed through the
169       following convenience methods.  Most of these methods can both be used
170       to read and to set the value of a header.  The header value is set if
171       you pass an argument to the method.  The old header value is always
172       returned.  If the given header did not exist then "undef" is returned.
173
174       Methods that deal with dates/times always convert their value to system
175       time (seconds since Jan 1, 1970) and they also expect this kind of
176       value when the header value is set.
177
178       $h->date
179           This header represents the date and time at which the message was
180           originated. E.g.:
181
182             $h->date(time);  # set current date
183
184       $h->expires
185           This header gives the date and time after which the entity should
186           be considered stale.
187
188       $h->if_modified_since
189       $h->if_unmodified_since
190           These header fields are used to make a request conditional.  If the
191           requested resource has (or has not) been modified since the time
192           specified in this field, then the server will return a "304 Not
193           Modified" response instead of the document itself.
194
195       $h->last_modified
196           This header indicates the date and time at which the resource was
197           last modified. E.g.:
198
199             # check if document is more than 1 hour old
200             if (my $last_mod = $h->last_modified) {
201                 if ($last_mod < time - 60*60) {
202                     ...
203                 }
204             }
205
206       $h->content_type
207           The Content-Type header field indicates the media type of the
208           message content. E.g.:
209
210             $h->content_type('text/html');
211
212           The value returned will be converted to lower case, and potential
213           parameters will be chopped off and returned as a separate value if
214           in an array context.  If there is no such header field, then the
215           empty string is returned.  This makes it safe to do the following:
216
217             if ($h->content_type eq 'text/html') {
218                # we enter this place even if the real header value happens to
219                # be 'TEXT/HTML; version=3.0'
220                ...
221             }
222
223       $h->content_type_charset
224           Returns the upper-cased charset specified in the Content-Type
225           header.  In list context return the lower-cased bare content type
226           followed by the upper-cased charset.  Both values will be "undef"
227           if not specified in the header.
228
229       $h->content_is_text
230           Returns TRUE if the Content-Type header field indicate that the
231           content is textual.
232
233       $h->content_is_html
234           Returns TRUE if the Content-Type header field indicate that the
235           content is some kind of HTML (including XHTML).  This method can't
236           be used to set Content-Type.
237
238       $h->content_is_xhtml
239           Returns TRUE if the Content-Type header field indicate that the
240           content is XHTML.  This method can't be used to set Content-Type.
241
242       $h->content_is_xml
243           Returns TRUE if the Content-Type header field indicate that the
244           content is XML.  This method can't be used to set Content-Type.
245
246       $h->content_encoding
247           The Content-Encoding header field is used as a modifier to the
248           media type.  When present, its value indicates what additional
249           encoding mechanism has been applied to the resource.
250
251       $h->content_length
252           A decimal number indicating the size in bytes of the message
253           content.
254
255       $h->content_language
256           The natural language(s) of the intended audience for the message
257           content.  The value is one or more language tags as defined by RFC
258           1766.  Eg. "no" for some kind of Norwegian and "en-US" for English
259           the way it is written in the US.
260
261       $h->title
262           The title of the document.  In libwww-perl this header will be
263           initialized automatically from the <TITLE>...</TITLE> element of
264           HTML documents.  This header is no longer part of the HTTP
265           standard.
266
267       $h->user_agent
268           This header field is used in request messages and contains
269           information about the user agent originating the request.  E.g.:
270
271             $h->user_agent('Mozilla/5.0 (compatible; MSIE 7.0; Windows NT 6.0)');
272
273       $h->server
274           The server header field contains information about the software
275           being used by the originating server program handling the request.
276
277       $h->from
278           This header should contain an Internet e-mail address for the human
279           user who controls the requesting user agent.  The address should be
280           machine-usable, as defined by RFC822.  E.g.:
281
282             $h->from('King Kong <king@kong.com>');
283
284           This header is no longer part of the HTTP standard.
285
286       $h->referer
287           Used to specify the address (URI) of the document from which the
288           requested resource address was obtained.
289
290           The "Free On-line Dictionary of Computing" as this to say about the
291           word referer:
292
293                <World-Wide Web> A misspelling of "referrer" which
294                somehow made it into the {HTTP} standard.  A given {web
295                page}'s referer (sic) is the {URL} of whatever web page
296                contains the link that the user followed to the current
297                page.  Most browsers pass this information as part of a
298                request.
299
300                (1998-10-19)
301
302           By popular demand "referrer" exists as an alias for this method so
303           you can avoid this misspelling in your programs and still send the
304           right thing on the wire.
305
306           When setting the referrer, this method removes the fragment from
307           the given URI if it is present, as mandated by RFC2616.  Note that
308           the removal does not happen automatically if using the header(),
309           push_header() or init_header() methods to set the referrer.
310
311       $h->www_authenticate
312           This header must be included as part of a "401 Unauthorized"
313           response.  The field value consist of a challenge that indicates
314           the authentication scheme and parameters applicable to the
315           requested URI.
316
317       $h->proxy_authenticate
318           This header must be included in a "407 Proxy Authentication
319           Required" response.
320
321       $h->authorization
322       $h->proxy_authorization
323           A user agent that wishes to authenticate itself with a server or a
324           proxy, may do so by including these headers.
325
326       $h->authorization_basic
327           This method is used to get or set an authorization header that use
328           the "Basic Authentication Scheme".  In array context it will return
329           two values; the user name and the password.  In scalar context it
330           will return "uname:password" as a single string value.
331
332           When used to set the header value, it expects two arguments.  E.g.:
333
334             $h->authorization_basic($uname, $password);
335
336           The method will croak if the $uname contains a colon ':'.
337
338       $h->proxy_authorization_basic
339           Same as authorization_basic() but will set the "Proxy-
340           Authorization" header instead.
341

NON-CANONICALIZED FIELD NAMES

343       The header field name spelling is normally canonicalized including the
344       '_' to '-' translation.  There are some application where this is not
345       appropriate.  Prefixing field names with ':' allow you to force a
346       specific spelling.  For example if you really want a header field name
347       to show up as "foo_bar" instead of "Foo-Bar", you might set it like
348       this:
349
350         $h->header(":foo_bar" => 1);
351
352       These field names are returned with the ':' intact for
353       $h->header_field_names and the $h->scan callback, but the colons do not
354       show in $h->as_string.
355

AUTHOR

357       Gisle Aas <gisle@activestate.com>
358
360       This software is copyright (c) 1994-2017 by Gisle Aas.
361
362       This is free software; you can redistribute it and/or modify it under
363       the same terms as the Perl 5 programming language system itself.
364
365
366
367perl v5.26.3                      2018-06-05                  HTTP::Headers(3)
Impressum