Email-MIME-Kit

 view release on metacpan or  search on metacpan

Changes  view on Meta::CPAN

        - add some docs on cid_for (thanks, Kaitlyn Parkhurst!)

3.000005  2016-09-20 11:22:25-04:00 America/New_York
        - set up kit_reader and manifest_reader with a helper attribute instead
          of the weird and rarely-seen Moose "initializer" system

3.000004  2016-08-03 22:48:27-04:00 America/New_York
        - require a newer Email::MIME so we can rely on the header_raw method

3.000003  2016-08-03 09:08:35-04:00 America/New_York
        - manifest.json is now properly decoded while being read, so
          UTF-8 strings in the manifest.json are treated the same way as
          \u.... sequences.  If you had been doubly-UTF-8-encoding your
          manifest.json to work around this bug, your code is now broken
          because my code is now fixed.

3.000002  2015-02-19 11:02:14-05:00 America/New_York
        - immutabilize more classes

3.000001  2014-12-01 14:10:12-05:00 America/New_York
          [BREAKING CHANGES]
        - content read from disk (templates, for example) is now decoded
          as UTF-8 if and only if the content type for which it is being used
          is text/*
        - for more information on this change, consult the "ENCODING" section
          of the documentation for Email::MIME::Kit

          [BUG FIXES]
        - non-text parts are no longer padded with CRLFs

2.102015  2014-11-02 08:59:04-05:00 America/New_York
        - read kit entries in binary mode for the sake of Win32 (thanks,

lib/Email/MIME/Kit.pm  view on Meta::CPAN

#pod In general, "it should all just work" ... starting in version v3.
#pod
#pod Email::MIME::Kit assumes that any file read for the purpose of becoming a
#pod C<text/*>-type part is encoded in UTF-8.  It will decode them and work with
#pod their contents as text strings.  Renderers will be passed text strings to
#pod render, and so on.  This, further, means that strings passed to the C<assemble>
#pod method for use in rendering should also be text strings.
#pod
#pod In older versions of Email::MIME::Kit, files read from disk were read in raw
#pod mode and then handled as octet strings.  Meanwhile, the manifest's contents
#pod (and, thus, any templates stored as strings in the manifest) were decoded into
#pod text strings.  This could lead to serious problems.  For example: the
#pod F<manifest.json> file might contain:
#pod
#pod   "header": [
#pod     { "Subject": "Message for [% customer_name %]" },
#pod     ...
#pod   ]
#pod
#pod ...while a template on disk might contain:
#pod

lib/Email/MIME/Kit.pm  view on Meta::CPAN

#pod
#pod =cut

has source => (is => 'ro', required => 1);

has manifest => (reader => 'manifest', writer => '_set_manifest');

my @auto_attrs = (
  [ manifest_reader => ManifestReader => JSON => [ 'read_manifest' ] ],
  [ kit_reader      => KitReader      => Dir  => [ 'get_kit_entry',
                                                   'get_decoded_kit_entry' ] ],
);

for my $tuple (@auto_attrs) {
  my ($attr, $role, $default, $handles) = @$tuple;

  my $seed = "_${attr}_seed";
  my $base_ns  = "Email::MIME::Kit::$role";
  my $role_pkg = "Email::MIME::Kit::Role::$role";

  has $seed => (

lib/Email/MIME/Kit.pm  view on Meta::CPAN

In general, "it should all just work" ... starting in version v3.

Email::MIME::Kit assumes that any file read for the purpose of becoming a
C<text/*>-type part is encoded in UTF-8.  It will decode them and work with
their contents as text strings.  Renderers will be passed text strings to
render, and so on.  This, further, means that strings passed to the C<assemble>
method for use in rendering should also be text strings.

In older versions of Email::MIME::Kit, files read from disk were read in raw
mode and then handled as octet strings.  Meanwhile, the manifest's contents
(and, thus, any templates stored as strings in the manifest) were decoded into
text strings.  This could lead to serious problems.  For example: the
F<manifest.json> file might contain:

  "header": [
    { "Subject": "Message for [% customer_name %]" },
    ...
  ]

...while a template on disk might contain:

lib/Email/MIME/Kit/Assembler/Standard.pm  view on Meta::CPAN

  $self->_assemble_from_string(
    $self->manifest->{body},
    $stash,
  );
}

sub _assemble_from_kit {
  my ($self, $stash) = @_;

  my $type   = $self->manifest->{attributes}{content_type} || 'text/plain';
  my $method = $type =~ m{^text/} ? 'get_decoded_kit_entry' : 'get_kit_entry';

  my $body_ref = $self->kit->$method($self->manifest->{path});

  $self->_assemble_from_string($$body_ref, $stash);
}

sub _assemble_mp_alt {
  my ($self, $stash) = @_;

  my %attr = %{ $self->manifest->{attributes} || {} };

lib/Email/MIME/Kit/Role/KitReader.pm  view on Meta::CPAN

#pod =head1 IMPLEMENTING
#pod
#pod This role also performs L<Email::MIME::Kit::Role::Component>.
#pod
#pod Classes implementing this role must provide a C<get_kit_entry> method.  It will
#pod be called with one parameter, the name of a path to an entry in the kit.  It
#pod should return a reference to a scalar holding the contents (as octets) of the
#pod named entry.  If no entry is found, it should raise an exception.
#pod
#pod A method called C<get_decoded_kit_entry> is provided.  It behaves like
#pod C<get_kit_entry>, but assumes that the entry for that name is stored in UTF-8
#pod and will decode it to text before returning.
#pod
#pod =cut

requires 'get_kit_entry';

sub get_decoded_kit_entry {
  my ($self, $name) = @_;
  my $content_ref = $self->get_kit_entry($name);

  require Encode;
  my $decoded = Encode::decode('utf-8', $$content_ref);
  return \$decoded;
}

no Moose::Role;
1;

__END__

=pod

=encoding UTF-8

lib/Email/MIME/Kit/Role/KitReader.pm  view on Meta::CPAN

=head1 IMPLEMENTING

This role also performs L<Email::MIME::Kit::Role::Component>.

Classes implementing this role must provide a C<get_kit_entry> method.  It will
be called with one parameter, the name of a path to an entry in the kit.  It
should return a reference to a scalar holding the contents (as octets) of the
named entry.  If no entry is found, it should raise an exception.

A method called C<get_decoded_kit_entry> is provided.  It behaves like
C<get_kit_entry>, but assumes that the entry for that name is stored in UTF-8
and will decode it to text before returning.

=head1 AUTHOR

Ricardo Signes <cpan@semiotic.systems>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2023 by Ricardo Signes.