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.44
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. In
62           addition to being a string, $value may be something that
63           stringifies.
64
65           The old value (or values) of the last of the header fields is
66           returned.  If no such field exists "undef" will be returned.
67
68           A multi-valued field will be returned as separate values in list
69           context and will be concatenated with ", " as separator in scalar
70           context.  The HTTP spec (RFC 2616) promises that joining multiple
71           values in this way will not change the semantic of a header field,
72           but in practice there are cases like old-style Netscape cookies
73           (see HTTP::Cookies) where "," is used as part of the syntax of a
74           single field value.
75
76           Examples:
77
78            $header->header(MIME_Version => '1.0',
79                            User_Agent   => 'My-Web-Client/0.01');
80            $header->header(Accept => "text/html, text/plain, image/*");
81            $header->header(Accept => [qw(text/html text/plain image/*)]);
82            @accepts = $header->header('Accept');  # get multiple values
83            $accepts = $header->header('Accept');  # get values as a single string
84
85       $h->push_header( $field => $value )
86       $h->push_header( $f1 => $v1, $f2 => $v2, ... )
87           Add a new field value for the specified header field.  Previous
88           values for the same field are retained.
89
90           As for the header() method, the field name ($field) is not case
91           sensitive and '_' can be used as a replacement for '-'.
92
93           The $value argument may be a scalar or a reference to a list of
94           scalars.
95
96            $header->push_header(Accept => 'image/jpeg');
97            $header->push_header(Accept => [map "image/$_", qw(gif png tiff)]);
98
99       $h->init_header( $field => $value )
100           Set the specified header to the given value, but only if no
101           previous value for that field is set.
102
103           The header field name ($field) is not case sensitive and '_' can be
104           used as a replacement for '-'.
105
106           The $value argument may be a scalar or a reference to a list of
107           scalars.
108
109       $h->remove_header( $field, ... )
110           This function removes the header fields with the specified names.
111
112           The header field names ($field) are not case sensitive and '_' can
113           be used as a replacement for '-'.
114
115           The return value is the values of the fields removed.  In scalar
116           context the number of fields removed is returned.
117
118           Note that if you pass in multiple field names then it is generally
119           not possible to tell which of the returned values belonged to which
120           field.
121
122       $h->remove_content_headers
123           This will remove all the header fields used to describe the content
124           of a message.  All header field names prefixed with "Content-" fall
125           into this category, as well as "Allow", "Expires" and
126           "Last-Modified".  RFC 2616 denotes these fields as Entity Header
127           Fields.
128
129           The return value is a new "HTTP::Headers" object that contains the
130           removed headers only.
131
132       $h->clear
133           This will remove all header fields.
134
135       $h->header_field_names
136           Returns the list of distinct names for the fields present in the
137           header.  The field names have case as suggested by HTTP spec, and
138           the names are returned in the recommended "Good Practice" order.
139
140           In scalar context return the number of distinct field names.
141
142       $h->scan( \&process_header_field )
143           Apply a subroutine to each header field in turn.  The callback
144           routine is called with two parameters; the name of the field and a
145           single value (a string).  If a header field is multi-valued, then
146           the routine is called once for each value.  The field name passed
147           to the callback routine has case as suggested by HTTP spec, and the
148           headers will be visited in the recommended "Good Practice" order.
149
150           Any return values of the callback routine are ignored.  The loop
151           can be broken by raising an exception ("die"), but the caller of
152           scan() would have to trap the exception itself.
153
154       $h->flatten()
155           Returns the list of pairs of keys and values.
156
157       $h->as_string
158       $h->as_string( $eol )
159           Return the header fields as a formatted MIME header.  Since it
160           internally uses the "scan" method to build the string, the result
161           will use case as suggested by HTTP spec, and it will follow
162           recommended "Good Practice" of ordering the header fields.  Long
163           header values are not folded.
164
165           The optional $eol parameter specifies the line ending sequence to
166           use.  The default is "\n".  Embedded "\n" characters in header
167           field values will be substituted with this line ending sequence.
168

CONVENIENCE METHODS

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

NON-CANONICALIZED FIELD NAMES

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

AUTHOR

359       Gisle Aas <gisle@activestate.com>
360
362       This software is copyright (c) 1994 by Gisle Aas.
363
364       This is free software; you can redistribute it and/or modify it under
365       the same terms as the Perl 5 programming language system itself.
366
367
368
369perl v5.36.0                      2023-01-20                  HTTP::Headers(3)
Impressum