- NAME
- SYNOPSIS
- DESCRIPTION
- METHODS

- header
- header_words
- split_words
- contains
- join_words
- delete_header_word
- delete_header
- format_headers
- clear_headers

- SEE ALSO
- MAINTAINER
- COPYRIGHT
- VERSION

# NAME

GT::WWW::http::Header - Module for GT::WWW::http request/response headers.

# SYNOPSIS

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.

# DESCRIPTION

This module provides an easy to use yet powerful header retrieval/manipulation object suitable for most HTTP headers.

# METHODS

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.

## header

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]
            ]
        );

## header_words

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" }

## split_words

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.

## contains

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

`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.

## delete_header_word

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

## delete_header

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.

## format_headers

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.

## clear_headers

This deletes all headers.

# SEE ALSO

the GT::WWW::http manpage the GT::WWW manpage RFC 2616: http://www.ietf.org/rfc/rfc2616.txt

# MAINTAINER

Jason Rhinelander

# COPYRIGHT

Copyright (c) 2004 Gossamer Threads Inc. All Rights Reserved. http://www.gossamer-threads.com/

# VERSION

Revision: $Id: Header.pm,v 1.8 2004/02/17 01:33:08 jagerman Exp $