GT::WWW::http::Header - Module for GT::WWW::http request/response headers.
Typically:
# Assuming $www is a GT::WWW::http object my $request_header = $www->header;
# Set a header: $request_header->header('Some-Http-Header' => 'Header value');
# After making a request: my $response_header = $www->response->header; # -- or -- my $response_header = $response->header; # $response is the return of, e.g. $www->get
Much more advanced headers can be set and determined, using the various methods available as described below.
This module provides an easy to use yet powerful header retrieval/manipulation object suitable for most HTTP headers.
First, a note about the methods described which add/change/delete headers: such methods should only be called on a request header, and only before making a request. Although nothing prevents you from making changes to the request header after having made the request, or from changing the headers of a response header object, such behaviour should be considered very bad practise and is strongly discouraged.
This is the most commonly used method as it is used both to add and retrieve headers, depending on its usage. The examples below assume the following header:
Date: Sun, 12 Jan 2003 08:21:21 GMT Server: Apache Keep-Alive: timeout=15, max=100 Connection: Keep-Alive Content-Type: text/html Content-Encoding: gzip Content-Length: 3215 X-Foo: bar1 X-Foo: bar2, bar3
With no arguments, a list of all the header names is returned. Given the example, the following list would be returned:
('Date', 'Server', 'Keep-Alive', 'Connection', 'Content-Type', 'Content-Encoding', 'Content-Length', 'X-Foo', 'X-Foo')
With a single argument, a list of value(s)
for headers of that name are
returned. In scalar context, only the first value is returned. In list
context, a list of all values is returned. Note that the header named passed
in is case-insensitive.
my $server = $header->header('server'); # returns 'Apache' my $foo = $header->header('X-Foo'); # returns 'bar1' my @foo = $header->header('x-Foo'); # returns ('bar1', 'bar2, bar3')
Finally, when more than one argument is provided, header values are set. At its simplest level, it takes a list of key => value pairs (NOT a hash, since duplicate keys are possible) of headers to set. So, to set the headers 'Server' and 'Content-Length' above at once, you could call:
$header->header(Server => 'Apache', 'Content-Length' => 3215);
Or, if you prefer:
$header->header(Server => 'Apache'); $header->header('Content-Length' => 3215);
Note that the order in which headers are added is preserved, for times when the order of headers is important.
WARNING: Before reading the below information, you should first know that it
describes advanced usage of the header()
method and requires have a grasp of
the intricacies of HTTP headers; the following is _not_ required knowledge for
typical GT::WWW use.
Consider the above Keep-Alive header an example. Instead of specifying:
$header->header('Keep-Alive' => 'timeout=15, max=100');
you could alternately write it as:
$header->header('Keep-Alive' => [timeout => 15, max => 100]);
This allows you a more pragmatic approach when you already have some sort of
data structure of the header options. You can go a step further with this, by
specifying undef
as the value:
# Set the second X-Foo header in the example: $header->header('X-Foo' => [bar2 => undef, bar3 => undef]);
header()
also allows you to set values such as:
image/gif;q=0.2
As can be seen in this example:
Accept: image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1
To do so, specify the suboption value as another array reference. The first element of the array reference is usually undef, while the remaining are the k=v pairs in the segment. So, in the above header, the 'image/gif;q=0.2' section would be specified as:
'image/gif' => [undef, q => 0.2]
(If a segment such as ``foo=bar;bar=foo'' is ever needed, the undef
would be
changed to "bar"
.)
So, piecing it all together, the Accept header shown above could be specified like this:
$header->header( Accept => [ 'image/png' => undef, 'image/jpeg' => undef, 'image/gif' => [undef, q => 0.2], '*/*' => [undef, q => 0.1] ] );
When you need to see it a header value contains a particular ``word'', this method is the one to use. As an example, consider this header:
X-Foo: bar, bar2, bar3
In order to determine whether or not ``bar2'' has been specified as an X-Foo value, you could attempt some sort of regex - or you could just call this method. The return value splits up the header in such a way as to be useful to determine the exact information contained within the header.
The method takes a case-insensitive header name, just like the single-argument form of header().
A even-numbered hash-like list is always returned - though each element of that list depends on the content of the header. First of all, if the header specified does not exist, you'll get an empty list back.
Assuming that the header does exist, it will first be broken up by ,
.
The even-indexed (0, 2, 4, ...) elements of the list are the keys, while the odd numbered elements are the values associated with those keys - or undef if there is no value (as above; an example with values is shown below).
So, using the above X-Foo header example, calling this method with 'X-Foo'
as an argument would give you back the list:
(bar => undef, bar2 => undef, bar3 => undef)
Getting a little more complicated, consider the following header:
X-Foo: bar, bar2=foo, bar3
Because of the ``=foo'' part, the list returned would now be:
(bar => undef, bar2 => "foo", bar3 => undef)
Quoting of values is also permitted, so the following would be parsed correctly
with '1;2,3=4"5\6'
being the value of bar2:
X-Foo: bar, bar2="1;2,3=4\"5\\6", bar3
Getting more complicated, this method also handles complex values containing more than one piece of information. A good example of this is in content type weighting used by most browsers. As a real life example (generated by the Phoenix web browser):
Accept: video/x-mng,image/png,image/jpeg,image/gif;q=0.2,*/*;q=0.1
Working that into the X-Foo example, consider this header:
X-Foo: bar, bar2=foo, bar3;foo1=24;foo2=10
In this case, the value for bar3 will become an array reference to handle the multiple pieces of information in the third part:
(bar => undef, bar2 => "foo", bar3 => [undef, foo1 => 24, foo2 => 10])
(If you've read the advanced section of the header()
documentation, and this looks familiar, you're right - the return value of this
function, if put in an array reference, is completely compatible with a
header()
value.)
The undef
value at the beginning of the array reference is rarely anything other
than undef
, but it could be, if a header such as this were encountered:
X-Foo: bar=foo,foo1=10
That would return:
(bar => ["foo", foo1 => 10])
One additional thing to note is that header_words()
returns the header words
for all matching headers. Thus if the following two headers were set:
X-Foo: bar, bar2=foo X-Foo: bar3
You would get the same return as if this header was set (shown above):
X-Foo: bar, bar2=foo, bar3
A good example usage of this is for a file download. To get the filename, you would do something like:
my %cd = $header->header_words('Content-Disposition'); my $filename; if ($cd{filename}) { $filename = $cd{filename} } else { $filename = "unknown" }
This can be called as object method, class method, or function - it takes a
single argument, a string, which it proceeds to split up as described for the
above header_words()
method. Note that this knows nothing about header names -
it simply knows how to break a header value into the above format.
This method is used internally by header_words(), but can be used separately if desired.
This method takes two arguments: a header, and a header word. It returns true if the header word passed is found in the header specified. For example, the following would return true:
$header->contains('X-Foo' => 'bar2')
for any of these headers:
X-Foo: bar2 X-Foo: bar, bar2, bar3 X-Foo: bar, bar2=10, bar3 X-Foo: bar, bar2=10;q=0.3, bar3
but not for either of these:
X-Foo: bar, bar3=bar2 X-Foo: bar, bar3;bar2=10
join_words()
does the opposite of split_words(). That is, it takes a value such
as might be returned by split_words(), and joins it up properly, quoting if
necessary. This is called internally when creating the actual header, and can
be called separately at a method or function if desired.
This takes a header and header word, and proceeds to remove any occurances of the header word from the header specified.
After calling:
$header->delete_header_word('X-Foo', 'bar2');
this header:
X-Foo: bar, bar2;foo=bar, bar3
would become:
X-Foo: bar, bar3
This takes a list of header names. The headers specified are completely removed.
=head2 replace_header
This 2 or more arguments in exactly the same way as header(), however all the specified headers are deleted (assuming they exist) before being readded.
This returns a properly formatted (lines are CRLF delimited) header. If you
use the header as a string (i.e. "$header"
), this method will be internally
called, and so generally does not need to be called directly.
The returned string has the final blank line that identifies the end of the header.
This deletes all headers.
the GT::WWW::http manpage the GT::WWW manpage RFC 2616: http://www.ietf.org/rfc/rfc2616.txt
Jason Rhinelander
Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/
Revision: $Id: Header.pm,v 1.8 2004/02/17 01:33:08 jagerman Exp $