Email::...entType(3)

🌸 NAME 🌸

okay so bestie, this is the Email::MIME::ContentType page — aka the one your manpage header truncates to Email::...entType(3) because terminal width is a hater. It's a User Contributed Perl Documentation situation, and it's literally about parsing and building a MIME Content-Type or Content-Disposition header. 💌

💖 VERSION 💖

version 1.028 — yes, that's the exact version, no cap. ✨

✨ SYNOPSIS ✨

okay so here's the group-chat demo. Copy-paste energy, but keep the code exactly as it is:

  use Email::MIME::ContentType;

  # Content-Type: text/plain; charset="us-ascii"; format=flowed
  my $ct = 'text/plain; charset="us-ascii"; format=flowed';
  my $data = parse_content_type($ct);

  $data = {
    type       => "text",
    subtype    => "plain",
    attributes => {
      charset => "us-ascii",
      format  => "flowed"
    }
  };

  my $ct_new = build_content_type($data);
  # text/plain; charset=us-ascii; format=flowed

  # Content-Type: application/x-stuff;
  #  title*0*=us-ascii'en'This%20is%20even%20more%20;
  #  title*1*=%2A%2A%2Afun%2A%2A%2A%20;
  #  title*2="isn't it!"
  my $ct = q(application/x-stuff;
   title*0*=us-ascii'en'This%20is%20even%20more%20;
   title*1*=%2A%2A%2Afun%2A%2A%2A%20;
   title*2="isn't it!");
  my $data = parse_content_type($ct);

  $data = {
    type       => "application",
    subtype    => "x-stuff",
    attributes => {
      title => "This is even more ***fun*** isn't it!"
    }
  };

  # Content-Disposition: attachment; filename=genome.jpeg;
  #   modification-date="Wed, 12 Feb 1997 16:29:51 -0500"
  my $cd = q(attachment; filename=genome.jpeg;
    modification-date="Wed, 12 Feb 1997 16:29:51 -0500");
  my $data = parse_content_disposition($cd);

  $data = {
    type       => "attachment",
    attributes => {
      filename            => "genome.jpeg",
      "modification-date" => "Wed, 12 Feb 1997 16:29:51 -0500"
    }
  };

  my $cd_new = build_content_disposition($data);
  # attachment; filename=genome.jpeg; modification-date="Wed, 12 Feb 1997 16:29:51 -0500"

Look at that. parse_content_type gives you the hashref-shaped data; build_content_type puts it back into header form. Same deal for parse_content_disposition and build_content_disposition. 🫶

🐚 PERL VERSION 🐚

This library should run on perls released even a long time ago. It should work on any version of perl released in the last five years.

Although it may work on older versions of perl, no guarantee is made that the minimum required version will not be increased. The version may be increased for any reason, and there is no promise that patches will be accepted to lower the minimum required perl. ⭐

🧚 FUNCTIONS 🧚

🧚 parse_content_type 🧚

• exported by default — yes bestie, it's just there.
• parses email content type headers according to section 5.1 of RFC 2045 and also RFC 2231 (Character Set and Parameter Continuations).
• returns a hash as above, with entries for the "type", the "subtype", and a hash of "attributes".
• For backward compatibility with a really unfortunate misunderstanding of RFC 2045 by the early implementors of this module, "discrete" and "composite" are also present in the returned hashref, with the values of "type" and "subtype" respectively.

🐚 parse_content_disposition 🐚

• exported by default — same energy.
• parses email Content-Disposition headers according to RFC 2183 and RFC 2231.
• returns a hash as above, with entries for the "type", and a hash of "attributes".

🎀 build_content_type 🎀

• exported by default — it's in the group chat too.
• builds email Content-Type header according to RFC 2045 and RFC 2231.
• takes a hash as above, with entries for the "type", the "subtype", and optionally also a hash of "attributes".
• returns a string representing Content-Type header.
• Non-ASCII attributes are encoded to UTF-8 according to Character Set section of RFC 2231.
• Attribute which has more than 78 ASCII characters is split into more attributes according to Parameter Continuations of RFC 2231.
• For compatibility reasons with clients which do not support RFC 2231, output string contains also a truncated ASCII version of any too long or non-ASCII attribute.
• Encoding to ASCII is done via Text::Unidecode module.
• This behavior can cause confusion by 2231-compatible MIME implementations, and can be disabled by setting $Email::MIME::ContentType::STRICT to true.

🦋 build_content_disposition 🦋

• exported by default — yes queen.
• builds email Content-Disposition header according to RFC 2182 and RFC 2231.
• takes a hash as above, with entries for the "type", and optionally also a hash of "attributes".
• returns a string representing Content-Disposition header.
• Non-ASCII or too long attributes are handled in the same way like in build_content_type function.

⚠️ WARNINGS ⚠️

okay bestie, warning time. This is not a valid content-type header, according to both RFC 1521 and RFC 2045:

  Content-Type: type/subtype;

If a semicolon appears, a parameter must. Like, a semicolon is not a vibe on its own.

parse_content_type will carp if it encounters a header of this type, but you can suppress this carp by setting $Email::MIME::ContentType::STRICT_PARAMS to a false value.

Please consider localizing this assignment! (for real, localize it 💅)

Same applies for parse_content_disposition.

👑 AUTHORS 👑

• Simon Cozens — <simon@cpan.org>
• Casey West — <casey@geeknest.com>
• Ricardo Signes — <cpan@semiotic.systems>

🌈 CONTRIBUTORS 🌈

• Matthew Green — <mrg@eterna.com.au>
• Pali — <pali@cpan.org>
• Ricardo Signes — <rjbs@semiotic.systems>
• Thomas Szukala — <ts@abusix.com>

🎀 COPYRIGHT AND LICENSE 🎀

This software is copyright (c) 2004 by Simon Cozens.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

that's the whole page, bestie. this one came from perl v5.42.0, dated 2023-01-09, and the footer's truncated Email::...entType(3) is just the manual name being extra. go parse something cute 💅✨