Courriel::Headers - The headers for an email part

       This class supports the following methods:

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

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

       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.

       Dave Rolsky <autarch@urth.org>

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

       This is free software, licensed under:

         The Artistic License 2.0 (GPL Compatible)

       The full text of the license can be found in the LICENSE file included with this distribution.

perl v5.32.1                                       2021-08-22                             Courriel::Headers(3pm)

       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:

       •   Content-Type

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

       •   Content-Disposition

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

       Courriel::Headers - The headers for an email part

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

       The source code repository for Courriel can be found at <https://github.com/houseabsolute/Courriel>.

       Bugs may be submitted at <https://github.com/houseabsolute/Courriel/issues>.

       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".

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

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

       version 0.49