TITLE

Add header and unheader funtions to core distribution

VERSION

   Maintainer: Nathan Wiger <nate@wiger.org>
   Date: 27 Sep 2000
   Last Modified: 29 Sep 2000
   Mailing List: perl6-stdlib@perl.org
   Number: 333
   Version: 2
   Status: Frozen

ABSTRACT

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

This RFC proposes that Perl include a simple function, 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 CGI.pm's version). It is also proposed that an unheader function be included which converts in the opposite direction.

NOTES ON FREEZE

Since this belongs in a module, and I've already written one, this RFC basically boils down to just making sure Text::Header (or an equivalent yet renamed module) ends up in the stdlib. These functions just need to be available for stuff like the use cgi pragma proposed in RFC 288.

Any additional technical concerns should be addressed towards improving the module itself.

DESCRIPTION

The header function works very similarly to CGI.pm and HTTP::Headers:

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

Note that unlike CGI.pm, the header function does not end the array with a singular "\n". The 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

This usage integrates very well with RFC 288 on improving the coupling between Perl and CGI apps. Note that a list is always joined into a comma-delimited string. To insert multiple separate headers, simply call header with multiple args:

   push @out, header(accept => 'text/html',
                     accept => 'text/plain');

This would create multiple "Accept:" lines.

Unlike CGI.pm, the header function would not provide any defaults. If called simply as:

   @HEADERS = header;

header will return an empty list. This allows header to be more general pupose, so it can provide SMTP and other headers as well:

   @mail_headers = header(from => 'nate@sun.com',
                          to => 'perl6-rfc@perl.org');
   print $MAIL @mail_headers, "\n", @content;

In addition, it is proposed that an unheader function be added as well. This function would convert in the opposite direction:

   1. lc the entire tag name converting -'s to _'s

   2. Separate each tag based on the colon delimiter,
      chomping newlines.

   3. Return a list of tag/value pairs for easy assignment
      to a hash

So, assuming the @HEADERS array above:

   %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

Since the two functions are inverses, this:

   @out = header unheader @in;

will result in @out being exactly equivalent to @in.

IMPLEMENTATION

Include Text::Header in the stdlib: http://www.perl.com/CPAN/modules/by-authors/id/N/NW/NWIGER/Text-Header-1.03.tar.gz

MIGRATION

This introduces new functionality, but its name does conflict with those using CGI.pm. However, using both CGI.pm and Text::Header at the same time would silly, so would probably not happen.

REFERENCES

RFC 288: First-Class CGI Support

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

CGI.pm by Lincoln Stein

HTTP::Headers by Gisle Aas

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