| 1 |
NAME |
| 2 |
Text::Header - RFC 822/2068 `header' and `unheader' functions |
| 3 |
|
| 4 |
SYNOPSIS |
| 5 |
use Text::Header; # header and unheader exported |
| 6 |
|
| 7 |
# Construct headers similar to CGI.pm and HTTP::Headers |
| 8 |
|
| 9 |
@HEADERS = header(content_type => 'text/html', |
| 10 |
author => 'Nathan Wiger', |
| 11 |
last_modified => $date, |
| 12 |
accept => [qw(text/html text/plain)]); |
| 13 |
|
| 14 |
# The above produces the array: |
| 15 |
|
| 16 |
@HEADERS = ("Content-Type: text/html\n", |
| 17 |
"Author: Nathan Wiger\n", |
| 18 |
"Last-Modified: Wed Sep 27 13:31:06 PDT 2000\n", |
| 19 |
"Accept: text/html, text/plain\n"); |
| 20 |
|
| 21 |
# Can also construct SMTP headers to format mail |
| 22 |
|
| 23 |
@mail_headers = header(from => 'Nathan Wiger <[email protected]>', |
| 24 |
to => '[email protected]'); |
| 25 |
|
| 26 |
print $MAIL @mail_headers, "\nKeep up the great work!\n"; |
| 27 |
|
| 28 |
# The above would print this to the $MAIL handle: |
| 29 |
|
| 30 |
From: Nathan Wiger <[email protected]> |
| 31 |
To: [email protected] |
| 32 |
|
| 33 |
Keep up the great work! |
| 34 |
|
| 35 |
DESCRIPTION |
| 36 |
This module provides two new functions, `header' and `unheader', which |
| 37 |
provide general-purpose RFC 822 header construction and parsing. They do |
| 38 |
not provide any intelligent defaults of HTTP-specific methods. They are |
| 39 |
simply aimed at providing an easy means to address the mechanics of |
| 40 |
header parsing. |
| 41 |
|
| 42 |
The output style is designed to mimic `CGI.pm' and `HTTP::Headers', so |
| 43 |
that users familiar with these interfaces will feel at home with these |
| 44 |
functions. As shown above, the `headers' function automatically does the |
| 45 |
following: |
| 46 |
|
| 47 |
1. uc's the first letter of each tag token and lc's the |
| 48 |
rest, also converting _'s to -'s automatically |
| 49 |
|
| 50 |
2. Adds a colon separating each tag and its value, and |
| 51 |
exactly one newline after each one |
| 52 |
|
| 53 |
3. Combines list elements into a comma-delimited |
| 54 |
string |
| 55 |
|
| 56 |
Note that a list is always joined into a comma-delimited string. To |
| 57 |
insert multiple separate headers, simply call `header' with multiple |
| 58 |
args: |
| 59 |
|
| 60 |
push @out, header(accept => 'text/html', |
| 61 |
accept => 'text/plain'); |
| 62 |
|
| 63 |
This would create multiple "Accept:" lines. |
| 64 |
|
| 65 |
Note that unlike `CGI.pm', the `header' function provided here does not |
| 66 |
provide any intelligent defaults. If called as: |
| 67 |
|
| 68 |
@out_headers = header; |
| 69 |
|
| 70 |
It will return an empty list. This allows `header' to be more general |
| 71 |
pupose, so it can provide SMTP and other headers as well. You can also |
| 72 |
use it as a generic text formatting tool, hence the reason it's under |
| 73 |
the `Text::' hierarchy. |
| 74 |
|
| 75 |
The `unheader' function works in exactly the opposite direction from |
| 76 |
`header', pulling apart headers and returning a list. `unheader': |
| 77 |
|
| 78 |
1. lc's the entire tag name, converting -'s to _'s |
| 79 |
|
| 80 |
2. Separates each tag based on the colon delimiter, |
| 81 |
chomping newlines. |
| 82 |
|
| 83 |
3. Returns a list of tag/value pairs for easy assignment |
| 84 |
to a hash |
| 85 |
|
| 86 |
So, assuming the `@HEADERS' array shown up top: |
| 87 |
|
| 88 |
%myheaders = unheader(@HEADERS); |
| 89 |
|
| 90 |
The hash `%myheaders' would have the following values: |
| 91 |
|
| 92 |
%myheaders = ( |
| 93 |
content_type => 'text/html', |
| 94 |
author => 'Nathan Wiger', |
| 95 |
last_modified => 'Wed Sep 27 13:31:06 PDT 2000', |
| 96 |
accept => 'text/html, text/plain' |
| 97 |
); |
| 98 |
|
| 99 |
Note that all keys are converted to lowercase, and their values have |
| 100 |
their newlines stripped. However, note that comma-separated fields are |
| 101 |
not split up on input. This cannot be done reliably because some fields, |
| 102 |
such as the HTTP `Date:' header, can contain commas even though they are |
| 103 |
not lists. Inferring this type of structure would require knowledge of |
| 104 |
content, and these functions are specifically designed to be |
| 105 |
content-independent. |
| 106 |
|
| 107 |
The `unheader' function will respect line wrapping, as seen in SMTP |
| 108 |
headers. It will simply join the lines and return the value, so that: |
| 109 |
|
| 110 |
%mail = unheader("To: Nathan Wiger <[email protected]>, |
| 111 |
[email protected]"); |
| 112 |
|
| 113 |
Would return: |
| 114 |
|
| 115 |
$mail{to} = "Nathan Wiger <[email protected]>, [email protected]" |
| 116 |
|
| 117 |
Notice that multiple spaces between the comma separator have been |
| 118 |
condensed to a single space. Since the `header' and `unheader' functions |
| 119 |
are direct inverses, this call: |
| 120 |
|
| 121 |
@out = header unheader @in; |
| 122 |
|
| 123 |
Will result in `@out' being exactly equivalent to `@in'. |
| 124 |
|
| 125 |
REFERENCES |
| 126 |
This is designed as both a Perl 5 module and also a Perl 6 prototype. |
| 127 |
Please see the Perl 6 proposal at http://dev.perl.org/rfc/333.html |
| 128 |
|
| 129 |
This module is designed to be fully compliant with the internet |
| 130 |
standards RFC 822 (SMTP Headers) and RFC 2068 (HTTP Headers). |
| 131 |
|
| 132 |
AUTHOR |
| 133 |
Copyright (c) 2000 Nathan Wiger <[email protected]>. All Rights Reserved. |
| 134 |
|
| 135 |
This module is free software; you may copy this under the terms of the |
| 136 |
GNU General Public License, or the Artistic License, copies of which |
| 137 |
should have accompanied your Perl kit. |
| 138 |
|