about summary refs log tree commit homepage
diff options
context:
space:
mode:
authorEric Wong <e@yhbt.net>2020-05-16 22:53:53 +0000
committerEric Wong <e@yhbt.net>2020-05-17 06:58:26 +0000
commit9787fae1f7235bd790d1db6f0b513ce420c361bd (patch)
tree3c16023e9f1beae64a0848941159a25762f4b6de
parente60231148eb604a379033c69e8c4494eb1753783 (diff)
downloadpublic-inbox-9787fae1f7235bd790d1db6f0b513ce420c361bd.tar.gz
To avoid confusing future readers and users, recommend
PublicInbox::Eml in our Import POD and refer to PublicInbox::Eml
comments at the top of PublicInbox::MIME.

mime_load() confined to t/eml.t, since we won't be using
it anywhere else in our tests.
-rw-r--r--lib/PublicInbox/Import.pm22
-rw-r--r--lib/PublicInbox/MIME.pm4
-rw-r--r--lib/PublicInbox/TestCommon.pm10
-rw-r--r--t/eml.t6
4 files changed, 23 insertions, 19 deletions
diff --git a/lib/PublicInbox/Import.pm b/lib/PublicInbox/Import.pm
index fc61d062..792570c8 100644
--- a/lib/PublicInbox/Import.pm
+++ b/lib/PublicInbox/Import.pm
@@ -648,7 +648,10 @@ version 1.0
 
 =head1 SYNOPSIS
 
-        use Email::MIME;
+        use PublicInbox::Eml;
+        # PublicInbox::Eml exists as of public-inbox 1.5.0,
+        # Email::MIME was used in older versions
+
         use PublicInbox::Git;
         use PublicInbox::Import;
 
@@ -664,7 +667,7 @@ version 1.0
                 "Date: Thu, 01 Jan 1970 00:00:00 +0000\n" .
                 "Message-ID: <m\@example.org>\n".
                 "\ntest message";
-        my $parsed = Email::MIME->new($message);
+        my $parsed = PublicInbox::Eml->new($message);
         my $ret = $im->add($parsed);
         if (!defined $ret) {
                 warn "duplicate: ",
@@ -675,7 +678,7 @@ version 1.0
         $im->done;
 
         # to remove a message
-        my $junk = Email::MIME->new($message);
+        my $junk = PublicInbox::Eml->new($message);
         my ($mark, $orig) = $im->remove($junk);
         if ($mark eq 'MISSING') {
                 print "not found\n";
@@ -690,8 +693,8 @@ version 1.0
 
 =head1 DESCRIPTION
 
-An importer and remover for public-inboxes which takes L<Email::MIME>
-messages as input and stores them in a git repository as
+An importer and remover for public-inboxes which takes C<PublicInbox::Eml>
+or L<Email::MIME> messages as input and stores them in a git repository as
 documented in L<https://public-inbox.org/public-inbox-v1-format.txt>,
 except it does not allow duplicate Message-IDs.
 
@@ -709,7 +712,7 @@ Initialize a new PublicInbox::Import object.
 
 =head2 add
 
-        my $parsed = Email::MIME->new($message);
+        my $parsed = PublicInbox::Eml->new($message);
         $im->add($parsed);
 
 Adds a message to to the git repository.  This will acquire
@@ -720,12 +723,13 @@ is called, but L</remove> may be called on them.
 
 =head2 remove
 
-        my $junk = Email::MIME->new($message);
+        my $junk = PublicInbox::Eml->new($message);
         my ($code, $orig) = $im->remove($junk);
 
 Removes a message from the repository.  On success, it returns
 a ':'-prefixed numeric code representing the git-fast-import
-mark and the original messages as an Email::MIME object.
+mark and the original messages as a PublicInbox::Eml
+(or Email::MIME) object.
 If the message could not be found, the code is "MISSING"
 and the original message is undef.  If there is a mismatch where
 the "Message-ID" is matched but the subject and body do not match,
@@ -749,7 +753,7 @@ The mail archives are hosted at L<https://public-inbox.org/meta/>
 
 =head1 COPYRIGHT
 
-Copyright (C) 2016 all contributors L<mailto:meta@public-inbox.org>
+Copyright (C) 2016-2020 all contributors L<mailto:meta@public-inbox.org>
 
 License: AGPL-3.0+ L<http://www.gnu.org/licenses/agpl-3.0.txt>
 
diff --git a/lib/PublicInbox/MIME.pm b/lib/PublicInbox/MIME.pm
index 9077386a..831a3d19 100644
--- a/lib/PublicInbox/MIME.pm
+++ b/lib/PublicInbox/MIME.pm
@@ -4,7 +4,9 @@
 # The license for this file differs from the rest of public-inbox.
 #
 # We no longer load this in any of our code outside of maintainer
-# tests for compatibility.
+# tests for compatibility.  PublicInbox::Eml is favored throughout
+# our codebase for performance and safety reasons, though we maintain
+# Email::MIME-compatibility in mail injection and indexing code paths.
 #
 # It monkey patches the "parts_multipart" subroutine with patches
 # from Matthew Horsfall <wolfsage@gmail.com> at:
diff --git a/lib/PublicInbox/TestCommon.pm b/lib/PublicInbox/TestCommon.pm
index d952ee6d..79e597f5 100644
--- a/lib/PublicInbox/TestCommon.pm
+++ b/lib/PublicInbox/TestCommon.pm
@@ -9,15 +9,7 @@ use Fcntl qw(FD_CLOEXEC F_SETFD F_GETFD :seek);
 use POSIX qw(dup2);
 use IO::Socket::INET;
 our @EXPORT = qw(tmpdir tcp_server tcp_connect require_git require_mods
-        run_script start_script key2sub xsys xqx mime_load eml_load);
-
-sub mime_load ($) {
-        my ($path) = @_;
-        open(my $fh, '<', $path) or die "open $path: $!";
-        # test should've called: require_mods('Email::MIME')
-        require PublicInbox::MIME;
-        PublicInbox::MIME->new(\(do { local $/; <$fh> }));
-}
+        run_script start_script key2sub xsys xqx eml_load);
 
 sub eml_load ($) {
         my ($path, $cb) = @_;
diff --git a/t/eml.t b/t/eml.t
index b7f58ac7..1892b001 100644
--- a/t/eml.t
+++ b/t/eml.t
@@ -12,6 +12,12 @@ SKIP: {
 };
 use_ok $_ for @classes;
 
+sub mime_load ($) {
+        my ($path) = @_;
+        open(my $fh, '<', $path) or die "open $path: $!";
+        PublicInbox::MIME->new(\(do { local $/; <$fh> }));
+}
+
 {
         my $eml = PublicInbox::Eml->new(\(my $str = "a: b\n\nhi\n"));
         is($str, "hi\n", '->new modified body like Email::Simple');