Update the release notes and README files for the new callback feature …

…#399
sisimai · Jul 12, 2020 · 98ffded · 98ffded
1 parent 865294f
commit 98ffded
Show file tree

Hide file tree

Showing 3 changed files with 121 additions and 20 deletions.
diff --git a/ChangeLog.md b/ChangeLog.md
@@ -20,6 +20,9 @@ v4.25.7p4
   - Remove unused method `Sisimai::Rhost->list` #396
   - Implement `Sisimai::Rhost::Cox` for parsing bounce mails returned from Cox:
     https://cox.com/. Thanks to @meir-w #398
+  - Callback feature for each email file in Maildir/ #399
+    - `Sisimai->make` receives a hook method at `c___` argument
+    - `Sisimai::Mail->hook` runs the hook method
 
 v4.25.7
 --------------------------------------------------------------------------------

diff --git a/README-JA.md b/README-JA.md
@@ -166,6 +166,7 @@ my $j = Sisimai->dump('/path/to/mbox', 'delivered' => 1);
 
 Callback feature
 -------------------------------------------------------------------------------
+### メールヘッダと本文に対して
 Sisimai 4.19.0から`Sisimai->make()`と`Sisimai->dump()`にコードリファレンスを
 引数`hook`に指定できるコールバック機能が実装されました。
 `hook`に指定したサブルーチンによって処理された結果は`Sisimai::Data->catch`
@@ -174,21 +175,69 @@ Sisimai 4.19.0から`Sisimai->make()`と`Sisimai->dump()`にコードリファ
 ```perl
 #! /usr/bin/env perl
 use Sisimai;
-my $callbackto = sub {
-    my $emdata = shift;
-    my $caught = { 'x-mailer' => '', 'queue-id' => '' };
+my $code = sub {
+    my $args = shift;               # (*Hash)
+    my $head = $args->{'headers'};  # (*Hash)  Email headers
+    my $body = $args->{'message'};  # (String) Message body
+    my $adds = { 'x-mailer' => '', 'queue-id' => '' };
+
+    if( $body =~ m/^X-Postfix-Queue-ID:\s*(.+)$/m ) {
+        $adds->{'queue-id'} = $1;
+    }
+
+    $adds->{'x-mailer'} = $head->{'x-mailer'} || '';
+    return $adds;
+};
+my $data = Sisimai->make('/path/to/mbox', 'hook' => $code);
+my $json = Sisimai->dump('/path/to/mbox', 'hook' => $code);
+
+print $data->[0]->catch->{'x-mailer'};    # "Apple Mail (2.1283)"
+print $data->[0]->catch->{'queue-id'};    # "43f4KX6WR7z1xcMG"
+```
+
+### 各メールのファイルに対して
+Sisimai 4.25.8からは`Sisimai->make()`と`Sisimai->dump()`の両メソッドで`c___`引数
+にコードリファレンスを渡せるようになりました。`c___`に渡されたコードリファレンス
+は解析したメールのファイルごとに呼び出されます。
 
-    if( $emdata->{'message'} =~ m/^X-Postfix-Queue-ID:\s*(.+)$/m ) {
-        $caught->{'queue-id'} = $1;
+```perl
+my $path = '/path/to/maildir';
+my $code = sub {
+    my $args = shift;           # (*Hash)
+    my $kind = $args->{'kind'}; # (String)  Sisimai::Mail->kind
+    my $mail = $args->{'mail'}; # (*String) Entire email message
+    my $path = $args->{'path'}; # (String)  Sisimai::Mail->path
+    my $sisi = $args->{'sisi'}; # (*Array)  List of Sisimai::Data
+
+    for my $e ( @$sisi ) {
+        # Insert custom fields into the parsed results
+        $e->{'catch'} ||= {};
+        $e->{'catch'}->{'size'} = length $$mail;
+        $e->{'catch'}->{'kind'} = ucfirst $kind;
+
+        if( $$mail =~ /^Return-Path: (.+)$/m ) {
+            # Return-Path: <MAILER-DAEMON>
+            $e->{'catch'}->{'return-path'} = $1;
+        }
+
+        # Append X-Sisimai-Parsed: header and save into other path
+        my $a = sprintf("X-Sisimai-Parsed: %d\n", scalar @$sisi);
+        my $p = sprintf("/path/to/another/directory/sisimai-%s.eml", $e->token);
+        my $f = IO::File->new($p, 'w');
+        my $v = $$mail; $v =~ s/^(From:.+)$/$a$1/m;
+        print $f $v; $f->close;
     }
 
-    $caught->{'x-mailer'} = $emdata->{'headers'}->{'x-mailer'} || '';
-    return $caught;
+    # Remove the email file in Maildir/ after parsed
+    unlink $path if $kind eq 'maildir';
+
+    # Need to not return a value
 };
-my $data = Sisimai->make('/path/to/mbox', 'hook' => $callbackto);
-my $json = Sisimai->dump('/path/to/mbox', 'hook' => $callbackto);
 
-print $data->[0]->catch->{'x-mailer'};    # Apple Mail (2.1283)
+my $list = Sisimai->make($path, 'c___' => $code);
+print $list->[0]->{'catch'}->{'size'};          # 2202
+print $list->[0]->{'catch'}->{'kind'};          # "Maildir"
+print $list->[0]->{'catch'}->{'return-path'};   # "<MAILER-DAEMON>"
 ```
 
 コールバック機能のより詳細な使い方は

diff --git a/README.md b/README.md
@@ -172,28 +172,77 @@ my $j = Sisimai->dump('/path/to/mbox', 'delivered' => 1);
 
 Callback feature
 -------------------------------------------------------------------------------
+### For email headers and the body
 Beginning with Sisimai 4.19.0, `make()` and `dump()` methods of Sisimai accept
 a sub routine reference in `hook` argument for setting a callback method and
 getting the results generated by the method via `Sisimai::Data->catch` method.
 
 ```perl
 #! /usr/bin/env perl
 use Sisimai;
-my $callbackto = sub {
-    my $emdata = shift;
-    my $caught = { 'x-mailer' => '', 'queue-id' => '' };
+my $code = sub {
+    my $args = shift;               # (*Hash)
+    my $head = $args->{'headers'};  # (*Hash)  Email headers
+    my $body = $args->{'message'};  # (String) Message body
+    my $adds = { 'x-mailer' => '', 'queue-id' => '' };
+
+    if( $body =~ m/^X-Postfix-Queue-ID:\s*(.+)$/m ) {
+        $adds->{'queue-id'} = $1;
+    }
+
+    $adds->{'x-mailer'} = $head->{'x-mailer'} || '';
+    return $adds;
+};
+my $data = Sisimai->make('/path/to/mbox', 'hook' => $code);
+my $json = Sisimai->dump('/path/to/mbox', 'hook' => $code);
+
+print $data->[0]->catch->{'x-mailer'};    # "Apple Mail (2.1283)"
+print $data->[0]->catch->{'queue-id'};    # "43f4KX6WR7z1xcMG"
+```
+
+### For each email file
+Beginning from v4.25.8, `c___` argument is available at `Sisimai->make()` and
+`Sisimai->dump()` meethod for callback feature. The argument `c___` receives a
+callback method for each email file like the following:
 
-    if( $emdata->{'message'} =~ m/^X-Postfix-Queue-ID:\s*(.+)$/m ) {
-        $caught->{'queue-id'} = $1;
+```perl
+my $path = '/path/to/maildir';
+my $code = sub {
+    my $args = shift;           # (*Hash)
+    my $kind = $args->{'kind'}; # (String)  Sisimai::Mail->kind
+    my $mail = $args->{'mail'}; # (*String) Entire email message
+    my $path = $args->{'path'}; # (String)  Sisimai::Mail->path
+    my $sisi = $args->{'sisi'}; # (*Array)  List of Sisimai::Data
+
+    for my $e ( @$sisi ) {
+        # Insert custom fields into the parsed results
+        $e->{'catch'} ||= {};
+        $e->{'catch'}->{'size'} = length $$mail;
+        $e->{'catch'}->{'kind'} = ucfirst $kind;
+
+        if( $$mail =~ /^Return-Path: (.+)$/m ) {
+            # Return-Path: <MAILER-DAEMON>
+            $e->{'catch'}->{'return-path'} = $1;
+        }
+
+        # Append X-Sisimai-Parsed: header and save into other path
+        my $a = sprintf("X-Sisimai-Parsed: %d\n", scalar @$sisi);
+        my $p = sprintf("/path/to/another/directory/sisimai-%s.eml", $e->token);
+        my $f = IO::File->new($p, 'w');
+        my $v = $$mail; $v =~ s/^(From:.+)$/$a$1/m;
+        print $f $v; $f->close;
     }
 
-    $caught->{'x-mailer'} = $emdata->{'headers'}->{'x-mailer'} || '';
-    return $caught;
+    # Remove the email file in Maildir/ after parsed
+    unlink $path if $kind eq 'maildir';
+
+    # Need to not return a value
 };
-my $data = Sisimai->make('/path/to/mbox', 'hook' => $callbackto);
-my $json = Sisimai->dump('/path/to/mbox', 'hook' => $callbackto);
 
-print $data->[0]->catch->{'x-mailer'};    # Apple Mail (2.1283)
+my $list = Sisimai->make($path, 'c___' => $code);
+print $list->[0]->{'catch'}->{'size'};          # 2202
+print $list->[0]->{'catch'}->{'kind'};          # "Maildir"
+print $list->[0]->{'catch'}->{'return-path'};   # "<MAILER-DAEMON>"
 ```
 
 More information about the callback feature is available at