RFC 333 (v1) Add C<header> and C<unheader> funtions to core distribution

This and other RFCs are available on the web at
  http://dev.perl.org/rfc/

=head1 TITLE

Add C<header> and C<unheader> funtions to core distribution

=head1 VERSION

   Maintainer: Nathan Wiger <[email protected]>
   Date: 27 Sep 2000
   Mailing List: [email protected]
   Number: 333
   Version: 1
   Status: Developing

=head1 ABSTRACT

Many services use HTTP-style headers to pass information, including
HTTP, SMTP, and others. These headers, described in internet RFC 822
(see L<REFERENCES>), are a widely-accepted internet standard.

This RFC proposes that Perl include a simple function, C<header>, that
can be used to interact with these headers more easily. It is a
general-purpose formatting function that does not do any
content-specific handling (unlike C<CGI.pm>'s version). It is also
proposed that an C<unheader> function be included which converts in the
opposite direction.

=head1 DESCRIPTION

=head2 The functions

The C<header> function would work very similarly to C<CGI.pm>'s:

   @HEADERS = header(content_type => 'text/html',
                     author => 'Nathan Wiger',
                     last_modified => $date,
                     accept => [qw(text/html text/plain)]);

This would produce an array of the following:

   @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");

Notice that the last element is a "\n" by itself, providing the
necessary blank line separating headers and content. The C<header>
function would simply:

   1. uc the first letter of each tag token and lc the
      rest, also converting _'s to -'s automatically

   2. Add a colon separating each tag and its value,
      and exactly one newline after each one

   3. Combine list elements into a comma-delimited
      string 

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

This usage integrates very well with B<RFC 288> on improving the
coupling between Perl and CGI apps. Unlike C<CGI.pm>, however, the
C<header> function would B<not> provide any defaults. If called simply
as:

   @HEADERS = header;

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

   @mail_headers = header(from => '[email protected]',
                          to => '[email protected]');
   print $MAIL @mail_headers, @content;

In addition, it is proposed that an C<unheader> function be added as
well. This function would convert in the opposite direction. Assuming
the C<@HEADERS> array above:

   %myheaders = unheader(@HEADERS);

The hash C<%myvals> would have the following values:

   %myheaders = (
       content_type => 'text/html',
       author => 'Nathan Wiger',
       last_modified => 'Wed Sep 27 13:31:06 PDT 2000'
       accept => [qw(text/html text/plain)]);
   );

That is, the process that C<header> does is exactly reversed, including
stripping of trailing newlines, conversion to lowercase, and so forth.
So, this call:

   @out = header unheader @in;

Should result in C<@out> being exactly equivalent to C<@in>.

=head2 Location

These are such lightweight functions that their impact on core would be
negligible. As such, they could potentially be put directly into it,
since they are just formatting functions compliant with open standards.
Having to modify them is not seen as likely. Also, other RFC's, such as
B<RFC 288>, could well use this mechanism to automatically parse
incoming and outgoing headers. This could also be linked to the concept
of C<open http> proposed in B<RFC 14>. If functions such as C<merge> and
C<unmerge> go in, then it would seem logical to put C<header> and
C<unheader> in as well.

Nonetheless, it may be more appropriate to place these in a module that
is part of the core distribution. 

=head1 IMPLEMENTATION

A complete Perl 5 implementation can be found as Text::Header at:
http://www.perl.com/CPAN/modules/by-authors/id/N/NW/NWIGER/Text-Header-1.02.tar.gz

Provide a simple and more general-purpose version of C<CGI::header> and
C<HTTP::Headers>. Also provide an C<unheader> function that converts in
the opposite direction.

=head1 MIGRATION

This introduces new functionality, but its name does conflict with those
using C<CGI.pm>. Still, those who say C<use CGI;> should win, since the
imported function will overlap with the builtin one (assuming core
functions become true functions).

=head1 REFERENCES

RFC 288: First-Class CGI Support

RFC 14: Modify open() to support FileObjects and Extensibility

RFC 90: Arrays: merge() and unmerge()

C<CGI.pm> by Lincoln Stein

C<HTTP::Headers> by Gisle Aas

http://sunsite.auc.dk/RFC/rfc/rfc822.html