Text::Header: Rfc 822/2068 \*(c`header\*(c' and \*(c`unheader\*(c' 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");

# Can also construct SMTP headers to format mail

@mail_headers = header(from => 'Nathan Wiger <[email protected]>', to => '[email protected]');

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

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

From: Nathan Wiger <[email protected]> To: [email protected]

Keep up the great work!

DESCRIPTION

This module provides two new functions, \*(C`header\*(C' and \*(C`unheader\*(C', which provide general-purpose \s-1RFC\s0 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 \*(C`CGI.pm\*(C' and \*(C`HTTP::Headers\*(C', so that users familiar with these interfaces will feel at home with these functions. As shown above, the \*(C`headers\*(C' 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

Note that a list is always joined into a comma-delimited string. To insert multiple separate headers, simply call \*(C`header\*(C' with multiple args:

push @out, header(accept => 'text/html', accept => 'text/plain');

This would create multiple \*(L"Accept:\*(R" lines.

Note that unlike \*(C`CGI.pm\*(C', the \*(C`header\*(C' function provided here does not provide any intelligent defaults. If called as:

@out_headers = header;

It will return an empty list. This allows \*(C`header\*(C' to be more general pupose, so it can provide \s-1SMTP\s0 and other headers as well. You can also use it as a generic text formatting tool, hence the reason it's under the \*(C`Text::\*(C' hierarchy.

The \*(C`unheader\*(C' function works in exactly the opposite direction from \*(C`header\*(C', pulling apart headers and returning a list. \*(C`unheader\*(C':

1. lc's the entire tag name, converting -'s to _'s

2. Separates each tag based on the colon delimiter, chomping newlines.

3. Returns a list of tag/value pairs for easy assignment to a hash

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 \s-1HTTP\s0 \*(C`Date:\*(C' 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 \*(C`unheader\*(C' function will respect line wrapping, as seen in \s-1SMTP\s0 headers. It will simply join the lines and return the value, so that:

%mail = unheader("To: Nathan Wiger <[email protected]>, [email protected]");

Would return:

$mail{to} = "Nathan Wiger <[email protected]>, [email protected]"

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

@out = header unheader @in;

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

Text::Header (3pm)

SYNOPSIS

DESCRIPTION

REFERENCES

AUTHOR