---
name: "Text::Header"
section: "3pm"
platform: "linux"
package: "libtext-header-perl"
version: "1.03+pristine-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Text::Header"
---

# Text::Header(3pm)

RFC 822/2068 "header" and "unheader" functions

## NAME

Text::Header - RFC 822/2068 "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");
   # 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, "\nKeep 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
```

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.

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

```
    @out_headers = header;
```

It will return an empty list. This allows `"header"` to be more general pupose, so it can provide SMTP and other headers as well. You can also use it as a generic text formatting tool, hence the reason it's under the `"Text::"` hierarchy.

The `"unheader"` function works in exactly the opposite direction from `"header"`, pulling apart headers and returning a list. `"unheader"`:

```
   1. lc's the entire tag name, converting -'s to _'s
   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
```

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 Perl 6 proposal at http://dev.perl.org/rfc/333.html

This module is designed to be fully compliant with the internet standards RFC 822 (SMTP Headers) and RFC 2068 (HTTP Headers).

## 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.