NAME
    Text::Header - provide RFC 822 `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",
                   "\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, "Keep 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 

       4. Appends a singular newline as the last element of
          the list

    Note that unlike `CGI.pm', the `header' function provided here does not
    provide any intelligent defaults. If called as:

        @out_headers = header;

    It would create a single-element list consisting of "\n". This allows
    `header' to be more general pupose, so it can provide SMTP and other
    headers as well.

    The `unheader' function works in exactly the opposite direction from
    `header', pulling apart headers and returning a list. 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 complete Perl 6 proposal at http://dev.perl.org/rfc/

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.