Debian Codegraph @

README

raw
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