.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.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.  \*(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-
.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" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Header 3pm"
.TH Header 3pm "2021-01-07" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Text::Header \- RFC 822/2068 "header" and "unheader" functions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&   use Text::Header;     # header and unheader exported
\&
\&   # Construct headers similar to CGI.pm and HTTP::Headers
\&
\&   @HEADERS = header(content_type => \*(Aqtext/html\*(Aq,
\&                     author => \*(AqNathan Wiger\*(Aq,
\&                     last_modified => $date,
\&                     accept => [qw(text/html text/plain)]);
\&
\&   # The above produces the array:
\&
\&   @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");
\&
\&   # Can also construct SMTP headers to format mail
\&
\&   @mail_headers = header(from => \*(AqNathan Wiger <nate@sun.com>\*(Aq,
\&                          to => \*(Aqperl5\-porters@perl.org\*(Aq);
\&   
\&   print $MAIL @mail_headers, "\enKeep up the great work!\en";
\&
\&   # 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!
.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 822\s0 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\*(Aqs the first letter of each tag token and lc\*(Aqs the
\&      rest, also converting _\*(Aqs to \-\*(Aqs 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
.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 => \*(Aqtext/html\*(Aq,
\&                     accept => \*(Aqtext/plain\*(Aq);
.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\*(Aqs the entire tag name, converting \-\*(Aqs to _\*(Aqs
\&
\&   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
.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 => \*(Aqtext/html\*(Aq,
\&       author => \*(AqNathan Wiger\*(Aq,
\&       last_modified => \*(AqWed Sep 27 13:31:06 PDT 2000\*(Aq,
\&       accept => \*(Aqtext/html, text/plain\*(Aq
\&   );
.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 822\s0 (\s-1SMTP\s0 Headers) and \s-1RFC 2068\s0 (\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.