NAME
Text::Header - RFC 822/2068 `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");
# 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, "\nKeep 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
Note that a list is always joined into a comma-delimited string. To
insert multiple separate headers, simply call `header' with multiple
args:
push @out, header(accept => 'text/html',
accept => 'text/plain');
This would create multiple "Accept:" lines.
Note that unlike `CGI.pm', the `header' function provided here does not
provide any intelligent defaults. If called as:
@out_headers = header;
It will return an empty list. This allows `header' to be more general
pupose, so it can provide SMTP and other headers as well. You can also
use it as a generic text formatting tool, hence the reason it's under
the `Text::' hierarchy.
The `unheader' function works in exactly the opposite direction from
`header', pulling apart headers and returning a list. `unheader':
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 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 Perl 6 proposal at http://dev.perl.org/rfc/333.html
This module is designed to be fully compliant with the internet
standards RFC 822 (SMTP Headers) and RFC 2068 (HTTP Headers).
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.