Courriel::Headers(3pm)					User Contributed Perl Documentation				    Courriel::Headers(3pm)

NAME

       Courriel::Headers - The headers for an email part

VERSION

       version 0.29

SYNOPSIS

	   my $email = Courriel->parse( text => ... );
	   my $headers = $email->headers;

	   print "$_
" for $headers->get('Received');

DESCRIPTION

       This class represents the headers of an email.

       Any sub part of an email can have its own headers, so every part has an associated object representing its headers. This class makes no
       distinction between top-level headers and headers for a sub part.

       Each individual header name/value pair is represented internally by a Courriel::Header object. Some headers have their own special
       subclass. These are:

       o   Content-Type

	   This is stored as a Courriel::Header::ContentType object.

       o   Content-Disposition

	   This is stored as a Courriel::Header::Disposition object.

API

       This class supports the following methods:

   Courriel::Headers->parse( ... )
       This method creates a new object by parsing a string. It accepts the following parameters:

       o   text

	   The text to parse. This can either be a plain scalar or a reference to a scalar. If you pass a reference, the underlying scalar may be
	   modified.

       o   line_sep

	   The line separator. This default to a "
", but you can change it if necessary. Note that this only affects parsing, header objects
	   are always output with RFC-compliant line endings.

       Header parsing unfolds folded headers, and decodes any MIME-encoded values as described in RFC 2047. Parsing also decodes header attributes
       encoded as described in RFC 2231.

   Courriel::Headers->new( headers => [ ... ] )
       This method creates a new object. It accepts one parameter, "headers", which should be an array reference of header names and values.

       A given header key can appear multiple times.

       This object does not (yet, perhaps) enforce RFC restrictions on repetition of certain headers.

       Header order is preserved, per RFC 5322.

   $headers->get($name)
       Given a header name, this returns a list of the Courriel::Header objects found for the header. Each occurrence of the header is returned as
       a separate object.

   $headers->get_values($name)
       Given a header name, this returns a list of the string values found for the header. Each occurrence of the header is returned as a separate
       string.

   $headers->add( $name => $value )
       Given a header name and value, this adds the headers to the object. If any of the headers already have values in the object, then new
       values are added after the existing values, rather than at the end of headers.

       The value can be provided as a string or a Courriel::Header object.

   $headers->unshift( $name => $value )
       This is like "add()", but this pushes the headers onto the front of the internal headers array. This is useful if you are adding "Received"
       headers, which per RFC 5322, should always be added at the top of the headers.

       The value can be provided as a string or a Courriel::Header object.

   $headers->remove($name)
       Given a header name, this removes all instances of that header from the object.

   $headers->replace( $name => $value )
       A shortcut for calling "remove()" and "add()".

       The value can be provided as a string or a Courriel::Header object.

   $headers->as_string( skip => ...., charset => ... )
       This returns a string representing the headers in the object. The values will be folded and/or MIME-encoded as needed.

       The "skip" parameter should be an array reference containing the name of headers that should be skipped. This parameter is optional, and
       the default is to include all headers.

       The "charset" parameter specifies what character set to use for MIME-encoding non-ASCII values. This defaults to "utf8". The charset name
       must be one recognized by the Encode module.

       MIME encoding is always done using the "B" (Base64) encoding, never the "Q" encoding.

   $headers->stream_to( output => $output, skip => ...., charset => ... )
       This method will send the stringified headers to the specified output.

       See the "as_string()" method for documentation on the "skip" and "charset" parameters.

ROLES

       This class does the "Courriel::Role::Streams" role.

AUTHOR

       Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

       This software is Copyright (c) 2012 by Dave Rolsky.

       This is free software, licensed under:

	 The Artistic License 2.0 (GPL Compatible)

perl v5.14.2							    2012-03-07						    Courriel::Headers(3pm)