File Coverage

blib/lib/MIME/Visitor.pm

Criterion	Covered	Total	%
statement	30	32	93.7
branch	4	4	100.0
condition			n/a
subroutine	12	13	92.3
pod	5	5	100.0
total	51	54	94.4

use strict;
use warnings;
package MIME::Visitor 0.007;
# ABSTRACT: walk through MIME parts and do stuff (like rewrite)

use Encode;
use MIME::BodyMunger;

#pod =head1 SYNOPSIS
#pod
#pod   # This will reverse all lines in each text part, taking care of all encoding
#pod   # for you.
#pod
#pod   MIME::Visitor->rewrite_all_lines(
#pod     $mime_entity,
#pod     sub { chomp; $_ = reverse . "\n"; },
#pod   );
#pod
#pod =head1 DESCRIPTION
#pod
#pod MIME::Visitor provides a simple way to walk through the parts of a MIME
#pod message, taking action on each one.  In general, this is not a very complicated
#pod thing to do, but having it in one place is convenient.
#pod
#pod The most powerful feature of MIME::Visitor, though, is its methods for
#pod rewriting text parts.  These methods take care of character sets for you so
#pod that you can treat everything like text instead of worrying about content
#pod transfer encoding or character set encoding.
#pod
#pod At present, only MIME::Entity messages can be handled.  Other types will be
#pod added in the future.
#pod
#pod =method walk_parts
#pod
#pod   MIME::Visitor->walk_parts($root, sub { ... });
#pod
#pod This method calls the given code on every part of the given root message,
#pod including the root itself.
#pod
#pod =cut

sub walk_parts {
  my ($self, $root, $code) = @_;

  $code->($root);
  for my $part ($root->parts) {
    $self->walk_parts($part, $code);
  }
}

#pod =method walk_leaves
#pod
#pod   MIME::Visitor->walk_leaves($root, sub { ... });
#pod
#pod This method calls the given code on every leaf part of the given root message.
#pod It descends into multipart parts of the message without calling the callback on
#pod them.
#pod
#pod =cut

sub walk_leaves {
  my ($self, $root, $code) = @_;

  $self->walk_parts(
    $root,
    sub {
      return if $_[0]->is_multipart;
      $code->($_[0]);
    },
  );
}

#pod =method walk_text_leaves
#pod
#pod   MIME::Visitor->walk_text_leaves($root, sub { ... });
#pod
#pod This method behaves like C, but only calls the callback on parts
#pod with a content type of text/plain or text/html.
#pod
#pod =cut

sub walk_text_leaves {
  my ($self, $root, $code) = @_;
  $self->walk_leaves($root, sub {
    return unless $_[0]->effective_type =~ qr{\Atext/(?:html|plain)(?:$|;)}i;
    $code->($_[0]);
  });
}

#pod =method rewrite_parts
#pod
#pod   MIME::Visitor->rewrite_parts($root, sub { ... });
#pod
#pod This method walks the text leaves of the MIME message, rewriting the content of
#pod the parts.  For each text leaf, the callback is invoked like this:
#pod
#pod   $code->(\$content, $part);
#pod
#pod For more information, see L.
#pod
#pod =cut

sub rewrite_parts {
  my ($self, $root, $code) = @_;

  $self->walk_text_leaves($root, sub {
    my ($part) = @_;
    MIME::BodyMunger->rewrite_content($part, $code);
  });
}

#pod =method rewrite_all_lines
#pod
#pod   MIME::Visitor->rewrite_all_lines($root, sub { ... });
#pod
#pod This method behaves like C, but the callback is called for each
#pod line of each relevant part, rather than for the part's body as a whole.
#pod
#pod =cut

sub rewrite_all_lines {
  my ($self, $root, $code) = @_;

  $self->walk_text_leaves($root, sub {
    my ($part) = @_;
    MIME::BodyMunger->rewrite_lines($part, $code);
  });
}

#pod =head1 THANKS
#pod
#pod Thanks to Pobox.com and Listbox.com, who sponsored the development of this
#pod module.
#pod
#pod =cut

1;

__END__