.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.13
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
.\" expand to `' in nroff, nothing in troff, for use with C<>.
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Header 3"
.TH Header 3 "2003-12-23" "perl v5.8.2" "User Contributed Perl Documentation"
.SH "NAME"
Text::Header \- RFC 822/2068 \f(CW\*(C`header\*(C'\fR and \f(CW\*(C`unheader\*(C'\fR functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Text::Header;     # header and unheader exported
.Ve
.PP
.Vb 1
\&   # Construct headers similar to CGI.pm and HTTP::Headers
.Ve
.PP
.Vb 4
\&   @HEADERS = header(content_type => 'text/html',
\&                     author => 'Nathan Wiger',
\&                     last_modified => $date,
\&                     accept => [qw(text/html text/plain)]);
.Ve
.PP
.Vb 1
\&   # The above produces the array:
.Ve
.PP
.Vb 4
\&   @HEADERS = ("Content-Type: text/html\en",
\&               "Author: Nathan Wiger\en",
\&               "Last-Modified: Wed Sep 27 13:31:06 PDT 2000\en",
\&               "Accept: text/html, text/plain\en");
.Ve
.PP
.Vb 1
\&   # Can also construct SMTP headers to format mail
.Ve
.PP
.Vb 2
\&   @mail_headers = header(from => 'Nathan Wiger <nate@sun.com>',
\&                          to => 'perl5-porters@perl.org');
.Ve
.PP
.Vb 1
\&   print $MAIL @mail_headers, "\enKeep up the great work!\en";
.Ve
.PP
.Vb 1
\&   # The above would print this to the $MAIL handle:
.Ve
.PP
.Vb 2
\&   From: Nathan Wiger <nate@sun.com>
\&   To: perl5-porters@perl.org
.Ve
.PP
.Vb 1
\&   Keep up the great work!
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module provides two new functions, \f(CW\*(C`header\*(C'\fR and \f(CW\*(C`unheader\*(C'\fR,
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.
.PP
The output style is designed to mimic \f(CW\*(C`CGI.pm\*(C'\fR and \f(CW\*(C`HTTP::Headers\*(C'\fR,
so that users familiar with these interfaces will feel at home with
these functions. As shown above, the \f(CW\*(C`headers\*(C'\fR function automatically
does the following:
.PP
.Vb 2
\&   1. uc's the first letter of each tag token and lc's the
\&      rest, also converting _'s to -'s automatically
.Ve
.PP
.Vb 2
\&   2. Adds a colon separating each tag and its value, and
\&      exactly one newline after each one
.Ve
.PP
.Vb 2
\&   3. Combines list elements into a comma-delimited
\&      string
.Ve
.PP
Note that a list is always joined into a comma-delimited string. To
insert multiple separate headers, simply call \f(CW\*(C`header\*(C'\fR with multiple
args:
.PP
.Vb 2
\&   push @out, header(accept => 'text/html',
\&                     accept => 'text/plain');
.Ve
.PP
This would create multiple \*(L"Accept:\*(R" lines.
.PP
Note that unlike \f(CW\*(C`CGI.pm\*(C'\fR, the \f(CW\*(C`header\*(C'\fR function provided here
does not provide any intelligent defaults. If called as:
.PP
.Vb 1
\&    @out_headers = header;
.Ve
.PP
It will return an empty list. This allows \f(CW\*(C`header\*(C'\fR 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 \f(CW\*(C`Text::\*(C'\fR hierarchy.
.PP
The \f(CW\*(C`unheader\*(C'\fR function works in exactly the opposite direction from
\&\f(CW\*(C`header\*(C'\fR, pulling apart headers and returning a list. \f(CW\*(C`unheader\*(C'\fR:
.PP
.Vb 1
\&   1. lc's the entire tag name, converting -'s to _'s
.Ve
.PP
.Vb 2
\&   2. Separates each tag based on the colon delimiter,
\&      chomping newlines.
.Ve
.PP
.Vb 2
\&   3. Returns a list of tag/value pairs for easy assignment
\&      to a hash
.Ve
.PP
So, assuming the \f(CW@HEADERS\fR array shown up top:
.PP
.Vb 1
\&   %myheaders = unheader(@HEADERS);
.Ve
.PP
The hash \f(CW%myheaders\fR would have the following values:
.PP
.Vb 6
\&   %myheaders = (
\&       content_type => 'text/html',
\&       author => 'Nathan Wiger',
\&       last_modified => 'Wed Sep 27 13:31:06 PDT 2000',
\&       accept => 'text/html, text/plain'
\&   );
.Ve
.PP
Note that all keys are converted to lowercase, and their values have
their newlines stripped. However, note that comma-separated fields
are \fBnot\fR split up on input. This cannot be done reliably because
some fields, such as the \s-1HTTP\s0 \f(CW\*(C`Date:\*(C'\fR 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.
.PP
The \f(CW\*(C`unheader\*(C'\fR function will respect line wrapping, as seen in
\&\s-1SMTP\s0 headers. It will simply join the lines and return the value,
so that:
.PP
.Vb 2
\&   %mail = unheader("To: Nathan Wiger <nate@sun.com>,
\&                             perl5-porters@perl.org");
.Ve
.PP
Would return:
.PP
.Vb 1
\&   $mail{to} = "Nathan Wiger <nate@sun.com>, perl5-porters@perl.org"
.Ve
.PP
Notice that multiple spaces between the comma separator have been
condensed to a single space. Since the \f(CW\*(C`header\*(C'\fR and \f(CW\*(C`unheader\*(C'\fR
functions are direct inverses, this call:
.PP
.Vb 1
\&   @out = header unheader @in;
.Ve
.PP
Will result in \f(CW@out\fR being exactly equivalent to \f(CW@in\fR.
.SH "REFERENCES"
.IX Header "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
.PP
This module is designed to be fully compliant with the internet
standards \s-1RFC\s0 822 (\s-1SMTP\s0 Headers) and \s-1RFC\s0 2068 (\s-1HTTP\s0 Headers).
.SH "AUTHOR"
.IX Header "AUTHOR"
Copyright (c) 2000 Nathan Wiger <nate@sun.com>. All Rights Reserved.
.PP
This module is free software; you may copy this under the terms of
the \s-1GNU\s0 General Public License, or the Artistic License, copies of
which should have accompanied your Perl kit.