clean up documentation

add error examples

modify Mail::Bounce::$module return "hints" to caller (Mail::Bounce class).

8 files changed, 158 insertions, 60 deletions

diff --git a/fml/lib/Mail/Bounce.pm b/fml/lib/Mail/Bounce.pm
index 07f42256..09e06ca0 100644
--- a/fml/lib/Mail/Bounce.pm
+++ b/fml/lib/Mail/Bounce.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: Bounce.pm,v 1.9 2001/07/29 15:06:50 fukachan Exp $
+# $FML: Bounce.pm,v 1.10 2001/07/29 15:08:36 fukachan Exp $
 #
 
 package Mail::Bounce;
@@ -51,6 +51,40 @@ For non DSN pattern,
 try to analyze it by using modules in C<Mail::Bounce::> 
 which can recognize MTA specific and domian specific patterns.
 
+For example,
+
+  Mail::Bounce
+      
+                $msg
+              --------> Mail::Bounce::DSN::analyze()
+              <--------
+               $result
+
+returned C<$result> provides the following information:
+
+    $result = {
+	address1 => {
+	    Original-Recipient => 'rfc822; addr',
+	    Final-Recipient    => 'rfc822; addr',
+	    Diagnostic-Code    => 'reason ...',
+	    Action             => 'failed',
+	    Status             => '4.0.0',
+	    hints              => ... which module matches ...,
+	},
+
+	address2 => {
+	    Original-Recipient => 'rfc822; addr',
+	    Final-Recipient    => 'rfc822; addr',
+	    Diagnostic-Code    => 'reason ...',
+	    Action             => 'failed',
+	    Status             => '4.0.0',
+	    hints              => ... which module matches ...,
+	},
+
+	...
+    };
+
+
 =head1 METHODS
 
 =head2 C<new()>
@@ -168,6 +202,21 @@ sub reason
 }
 
 
+sub hints
+{
+    my ($self, $addr) = @_;
+    $self->{ _result }->{ $addr }->{ 'hints' };
+}
+
+
+=head2 C<look_like_japanese(string)>
+
+return 1 if C<string> looks Japanese one in JIS/SJIS/EUC code.
+return 0 unless.
+
+=cut
+
+
 my $RE_SJIS_C = '[\201-\237\340-\374][\100-\176\200-\374]';
 my $RE_SJIS_S = "($RE_SJIS_C)+";
 my $RE_EUC_C  = '[\241-\376][\241-\376]';
@@ -184,15 +233,6 @@ my @REGEXP = (
 	      $RE_JOUT,
 	      );
 
-
-=head2 C<look_like_japanese(string)>
-
-return 1 if C<string> looks Japanese one.
-return 0 unless.
-
-=cut
-
-
 sub look_like_japanese
 {
     my ($self, $buf) = @_;
diff --git a/fml/lib/Mail/Bounce/DSN.pm b/fml/lib/Mail/Bounce/DSN.pm
index 1a5efcd9..dc30464c 100644
--- a/fml/lib/Mail/Bounce/DSN.pm
+++ b/fml/lib/Mail/Bounce/DSN.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: DSN.pm,v 1.5 2001/04/12 11:44:54 fukachan Exp $
+# $FML: DSN.pm,v 1.6 2001/04/12 14:07:40 fukachan Exp $
 #
 
 
@@ -25,24 +25,58 @@ Mail::Bounce::DSN - DSN error message format parser
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
-
- $result = {
-      addr => {
-             Original-Recipient => 'rfc822; addr'
-             Final-Recipient    => 'rfc822; addr'
-             Diagnostic-Code    => 'reason ...'
-             Action             => 'failed'
-             Status             => '4.0.0'
-          }
-      }
+See C<Mail::Bounce> for more details.
 
-=head1 METHODS
+=head1 DESCRIPTION
 
-=head2 C<new()>
+See C<Mail::Bounce> for more details.
+
+=head1 ERROR EXAMPLE
+
+   From: MAILER-DAEMON@ahodori.fml.org (Mail Delivery System)
+   Subject: Undelivered Mail Returned to Sender
+   To: fml-help-admin@ffs.fml.org
+   MIME-Version: 1.0
+   Content-Type: multipart/report; report-type=delivery-status;
+   	boundary="C687D866E0.986737575/ahodori.fml.org"
+   Message-Id: <20010408134615.F1DD786658@ahodori.fml.org>
+   
+   This is a MIME-encapsulated message.
+   
+   --C687D866E0.986737575/ahodori.fml.org
+   Content-Description: Notification
+   Content-Type: text/plain
+   
+   This is the Postfix program at host ahodori.fml.org.
+
+       ... reason ...
+   
+   --C687D866E0.986737575/ahodori.fml.org
+   Content-Description: Delivery error report
+   Content-Type: message/delivery-status
+   
+   Reporting-MTA: dns; ahodori.fml.org
+   Arrival-Date: Sun, 25 Mar 2001 22:34:15 +0900 (JST)
+   
+   Final-Recipient: rfc822; rudo@nuinui.net
+   Action: failed
+   Status: 4.0.0
+   Diagnostic-Code: X-Postfix; connect to sv.nuinui.net[210.161.170.173]:
+       Connection refused
+   
+   --C687D866E0.986737575/ahodori.fml.org
+   Content-Description: Undelivered Message
+   Content-Type: message/rfc822
+   
+       ... original message ...
+   
+   -- rudo's mabuachi
+   
+   --C687D866E0.986737575/ahodori.fml.org--
 
 =cut
 
+
 sub analyze
 {
     my ($self, $msg, $result) = @_;
@@ -95,6 +129,7 @@ sub _parse_dsn_format
 	     'Action', 'Status', 'Diagnostic-Code') {
 	    $result->{ $addr }->{ $_ } = $header->get($_) || undef;
 	}
+	$result->{ $addr }->{ 'hints' } = 'DSN';
     }
 }
 
diff --git a/fml/lib/Mail/Bounce/Exim.pm b/fml/lib/Mail/Bounce/Exim.pm
index a6999445..f44e7dc8 100644
--- a/fml/lib/Mail/Bounce/Exim.pm
+++ b/fml/lib/Mail/Bounce/Exim.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: Exim.pm,v 1.1 2001/04/10 14:34:19 fukachan Exp $
+# $FML: Exim.pm,v 1.2 2001/04/11 15:51:55 fukachan Exp $
 #
 
 
@@ -20,20 +20,13 @@ Mail::Bounce::Exim - Exim error message format parser
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
+See C<Mail::Bounce> for more details.
 
+=head1 DESCRIPTION
 
- $result = {
-      addr => {
-             Original-Recipient => 'rfc822; addr'
-             Final-Recipient    => 'rfc822; addr'
-             Diagnostic-Code    => 'reason ...'
-             Action             => 'failed'
-             Status             => '4.0.0'
-          }
-      }
+See C<Mail::Bounce> for more details.
 
-=head1 Exim Error Formats
+=head1 ERROR EXAMPLE
 
  Received: from fukachan by eriko.fml.org with local (Exim 2.04 #5)
         id 11fxjP-0005MW-00
@@ -44,10 +37,6 @@ Mail::Bounce::Exim - Exim error message format parser
  Subject: Mail delivery failed: returning message to sender
  Message-Id: <E11fxjP-0005MW-00@eriko.fml.org>
 
-=head1 METHODS
-
-=head2 C<new()>
-
 =cut
 
 
@@ -68,6 +57,7 @@ sub analyze
 	$addr =~ s/\s*$//;
 	$result->{ $addr }->{ 'Final-Recipient' } = $addr;
 	$result->{ $addr }->{ 'Status' }          = '5.x.y';
+	$result->{ $addr }->{ 'hints' }           = 'exim';
     }
 }
 
diff --git a/fml/lib/Mail/Bounce/GOO.pm b/fml/lib/Mail/Bounce/GOO.pm
index dddd8b11..d22c7913 100644
--- a/fml/lib/Mail/Bounce/GOO.pm
+++ b/fml/lib/Mail/Bounce/GOO.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: GOO.pm,v 1.2 2001/04/11 15:51:55 fukachan Exp $
+# $FML: GOO.pm,v 1.1 2001/04/11 16:36:19 fukachan Exp $
 #
 
 
@@ -20,17 +20,26 @@ Mail::Bounce::GOO - GOO error message format parser
 
 =head1 SYNOPSIS
 
-=head1 DESCRIPTION
+See C<Mail::Bounce> for more details.
 
-=head1 GOO Error Formats
+=head1 DESCRIPTION
 
+See C<Mail::Bounce> for more details.
 
-=head1 METHODS
+=head1 GOO Error Formats
 
-=head2 C<new()>
+   To: nospam-ml-admin@ffs.fml.org
+   Subject: [goo mail] Rejecting your mail to user@mail.goo.ne.jp
+   X-SMType: Notification
+   Message-Id: <E12pMyv-0003Q7-00@mail.goo.ne.jp>
+   Date: Wed, 10 May 2000 12:16:17 +0900
+   X-UIDL: 326069d2d4e53c677fa3443428c80788
+   
+     ... Japanese message ...
 
 =cut
 
+
 sub analyze
 {
     my ($self, $msg, $result) = @_;
@@ -45,6 +54,7 @@ sub analyze
 	    $addr =~ s/\s*$//;
 	    $result->{ $addr }->{ 'Final-Recipient' } = $addr;
 	    $result->{ $addr }->{ 'Status' }          = '5.x.y';
+	    $result->{ $addr }->{ 'hints' }           = 'goo.ne.jp';
 	}
     }
 }
diff --git a/fml/lib/Mail/Bounce/Postfix19991231.pm b/fml/lib/Mail/Bounce/Postfix19991231.pm
index 20ce4b8e..a19d0060 100644
--- a/fml/lib/Mail/Bounce/Postfix19991231.pm
+++ b/fml/lib/Mail/Bounce/Postfix19991231.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: Postfix19991231.pm,v 1.7 2001/05/20 12:19:59 fukachan Exp $
+# $FML: Postfix19991231.pm,v 1.8 2001/05/27 14:27:56 fukachan Exp $
 #
 
 
@@ -28,11 +28,25 @@ See C<Mail::Bounce> for more details.
 
 sub class used in C<Mail::Bounce>.
 
-=head1 METHODS
-
-=head2 C<analyze($msg, $result)>
-
-See C<Mail::Bounce> for more details.
+=head1 ERROR FORMAT
+
+   Date: Fri, 29 Jan 1999 15:05:06 +0900 (JST)
+   From: MAILER-DAEMON@fml.org (Mail Delivery System)
+   Subject: Undelivered Mail Returned to Sender
+   To: fukachan@fml.org
+   Message-Id: <19990129060506.816AD5B33D@katri.fml.org>
+   
+   This is the Postfix program at host katri.fml.org.
+
+       ... reason ...    
+   
+   	--- Delivery error report follows ---
+   
+   <rudo@nuinui.net>: mail to command is restricted
+   
+   	--- Undelivered message follows ---
+   
+   ... original message ...
 
 =cut
 
@@ -122,6 +136,7 @@ sub _parse_address
 	$addr = $self->address_clean_up($self, $addr);
 	$result->{ $addr }->{ 'Diagnostic-Code' } = $reason;
 	$result->{ $addr }->{ 'Status' }          = '5.x.y';
+	$result->{ $addr }->{ 'hints' }           = 'postfix 19991231 style';
     }
 }
 
diff --git a/fml/lib/Mail/Bounce/Qmail.pm b/fml/lib/Mail/Bounce/Qmail.pm
index 20d1b183..2f80798b 100644
--- a/fml/lib/Mail/Bounce/Qmail.pm
+++ b/fml/lib/Mail/Bounce/Qmail.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: Qmail.pm,v 1.1 2001/04/09 15:56:52 fukachan Exp $
+# $FML: Qmail.pm,v 1.2 2001/04/10 11:52:59 fukachan Exp $
 #
 
 
@@ -29,12 +29,9 @@ format), as describbed in
 
     http://cr.yp.to/proto/qsbmf.txt
 
-=head1 METHODS
-
-=head2 C<new()>
-
 =cut
 
+
 sub analyze
 {
     my ($self, $msg, $result) = @_;
@@ -72,6 +69,7 @@ sub analyze
 
 			$result->{ $addr }->{ 'Diagnostic-Code' } = $reason;
 			$result->{ $addr }->{ 'Status' }          = $status;
+			$result->{ $addr }->{ 'hints' }           = 'qmail';
 		    }
 		} 
 	    }
diff --git a/fml/lib/Mail/Bounce/SimpleMatch.pm b/fml/lib/Mail/Bounce/SimpleMatch.pm
index 88c445b1..9f2180c2 100644
--- a/fml/lib/Mail/Bounce/SimpleMatch.pm
+++ b/fml/lib/Mail/Bounce/SimpleMatch.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: SimpleMatch.pm,v 1.19 2001/05/31 11:02:33 fukachan Exp $
+# $FML: SimpleMatch.pm,v 1.20 2001/07/29 15:08:36 fukachan Exp $
 #
 
 
@@ -254,6 +254,7 @@ sub _address_match
 		if ($addr) {
 		    $result->{ $addr }->{ 'Final-Recipient' } = $addr;
 		    $result->{ $addr }->{ 'Status'}           = '5.x.y';
+		    $result->{ $addr }->{ 'hints' }           = $mta_type;
 		}
 	    }
 
@@ -262,6 +263,7 @@ sub _address_match
 		if ($addr) {
 		    $result->{ $addr }->{ 'Final-Recipient' } = $addr;
 		    $result->{ $addr }->{ 'Status'}           = '5.x.y';
+		    $result->{ $addr }->{ 'hints' }           = $mta_type;
 		}
 	    }
 	}
diff --git a/fml/lib/Mail/Bounce/Smtpfeed.pm b/fml/lib/Mail/Bounce/Smtpfeed.pm
index bf25deef..9be7ef9f 100644
--- a/fml/lib/Mail/Bounce/Smtpfeed.pm
+++ b/fml/lib/Mail/Bounce/Smtpfeed.pm
@@ -4,7 +4,7 @@
 #   All rights reserved. This program is free software; you can
 #   redistribute it and/or modify it under the same terms as Perl itself. 
 #
-# $FML: Smtpfeed.pm,v 1.1 2001/04/10 14:34:19 fukachan Exp $
+# $FML: Smtpfeed.pm,v 1.1 2001/04/10 16:02:07 fukachan Exp $
 #
 
 
@@ -20,13 +20,20 @@ Mail::Bounce::Smtpfeed - Smtpfeed error message format parser
 
 =head1 SYNOPSIS
 
+See C<Mail::Bounce> for more details.
+
 =head1 DESCRIPTION
 
+See C<Mail::Bounce> for more details.
+
 =head1 Smtpfeed Error Formats
 
-=head1 METHODS
+"smtpfeed -1 -F" sends the mail with the header rewriting of To:
+header field. It will include
+
+  To: (original recipient in envelope at ADDRESS) <ADDRESS>
 
-=head2 C<new()>
+at the header somewhere in the error message.
 
 =cut
 
@@ -57,6 +64,7 @@ sub analyze
     # set up return buffer
     $result->{ $addr }->{ 'Final-Recipient' } = $addr;
     $result->{ $addr }->{ 'Status' }          = '5.x.y';
+    $result->{ $addr }->{ 'hints' }           = 'smtpfeed';
 }
 
 =head1 AUTHOR