/ 
Text-Header-1.02
River stage zero No dependents
/ Text::Header

NAME

Text::Header - provide RFC 822 header and unheader functions

SYNOPSIS

use Text::Header;     # header and unheader exported

# Construct headers similar to CGI.pm and HTTP::Headers

@HEADERS = header(content_type => 'text/html',
                  author => 'Nathan Wiger',
                  last_modified => $date,
                  accept => [qw(text/html text/plain)]);

# The above produces the array:

@HEADERS = ("Content-Type: text/html\n",
            "Author: Nathan Wiger\n",
            "Last-Modified: Wed Sep 27 13:31:06 PDT 2000\n",
            "Accept: text/html, text/plain\n",
            "\n");

# Can also construct SMTP headers to format mail

@mail_headers = header(from => 'Nathan Wiger <nate@sun.com>',
                       to => 'perl5-porters@perl.org');

print $MAIL @mail_headers, "Keep up the great work!\n";

# The above would print this to the $MAIL handle:

From: Nathan Wiger <nate@sun.com>
To: perl5-porters@perl.org

Keep up the great work!

DESCRIPTION

This module provides two new functions, header and unheader, which provide general-purpose RFC 822 header construction and parsing. They do not provide any intelligent defaults of HTTP-specific methods. They are simply aimed at providing an easy means to address the mechanics of header parsing.

The output style is designed to mimic CGI.pm and HTTP::Headers, so that users familiar with these interfaces will feel at home with these functions. As shown above, the headers function automatically does the following:

1. uc's the first letter of each tag token and lc's the
   rest, also converting _'s to -'s automatically

2. Adds a colon separating each tag and its value, and
   exactly one newline after each one

3. Combines list elements into a comma-delimited
   string 

4. Appends a singular newline as the last element of
   the list

Note that unlike CGI.pm, the header function provided here does not provide any intelligent defaults. If called as:

@out_headers = header;

It would create a single-element list consisting of "\n". This allows header to be more general pupose, so it can provide SMTP and other headers as well.

The unheader function works in exactly the opposite direction from header, pulling apart headers and returning a list. So, assuming the @HEADERS array shown up top:

%myheaders = unheader(@HEADERS);

The hash %myheaders would have the following values:

%myheaders = (
    content_type => 'text/html',
    author => 'Nathan Wiger',
    last_modified => 'Wed Sep 27 13:31:06 PDT 2000'
    accept => 'text/html, text/plain');
);

Note that all keys are converted to lowercase, and their values have their newlines stripped. However, note that comma-separated fields are not split up on input. This cannot be done reliably because some fields, such as the HTTP Date: header, can contain commas even though they are not lists. Inferring this type of structure would require knowledge of content, and these functions are specifically designed to be content-independent.

The unheader function will respect line wrapping, as seen in SMTP headers. It will simply join the lines and return the value, so that:

%mail = unheader("To: Nathan Wiger <nate@sun.com>,
                          perl5-porters@perl.org");

Would return:

$mail{to} = "Nathan Wiger <nate@sun.com>, perl5-porters@perl.org"

Notice that multiple spaces between the comma separator have been condensed to a single space. Since the header and unheader functions are direct inverses, this call:

@out = header unheader @in;

Will result in @out being exactly equivalent to @in.

REFERENCES

This is designed as both a Perl 5 module and also a Perl 6 prototype. Please see the complete Perl 6 proposal at http://dev.perl.org/rfc/

AUTHOR

Copyright (c) 2000 Nathan Wiger <nate@sun.com>. All Rights Reserved.

This module is free software; you may copy this under the terms of the GNU General Public License, or the Artistic License, copies of which should have accompanied your Perl kit.