The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

AKXLIX / Sisimai-v5.3.0 / lib / Sisimai / Mail.pm 

            

              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
—
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165

              
package Sisimai::Mail;
use v5.26;
use strict;
use warnings;
use Class::Accessor::Lite (
    'new' => 0,
    'ro'  => [
        'path', # [String] path to mbox or Maildir/
        'kind', # [String] Data type: mailbox, maildir, stdin, or memory
    ],
    'rw'  => [
        'data', # [Sisimai::Mail::[Mbox,Maildir,Memory,STDIO] Object
    ]
);
sub new {
    # Constructor of Sisimai::Mail
    # @param    [String] argv1  Path to mbox or Maildir/
    # @return   [Sisimai::Mail] Object
    #           [Undef]         The argument is wrong
    my $class = shift;
    my $argv1 = shift;
    my $klass = undef;
    my $loads = 'Sisimai/Mail/';
    my $param = { 'kind' => '', 'data' => undef, 'path' => $argv1 };
    # The argumenet is a mailbox or a Maildir/.
    if( -f $argv1 ) {
        # The argument is a file, it is an mbox or email file in Maildir/
        $klass  = __PACKAGE__.'::Mbox';
        $loads .= 'Mbox.pm';
        $param->{'kind'} = 'mailbox';
        $param->{'path'} = $argv1;
    } elsif( -d $argv1 ) {
        # The agument is not a file, it is a Maildir/
        $klass  = __PACKAGE__.'::Maildir';
        $loads .= 'Maildir.pm';
        $param->{'kind'} = 'maildir';
    } else {
        # The argumen1 neither a mailbox nor a Maildir/.
        if( ref($argv1) eq 'GLOB' || $argv1 eq 'STDIN' ) {
            # Read from STDIN
            $klass  = __PACKAGE__.'::STDIN';
            $loads .= 'STDIN.pm';
            $param->{'kind'} = 'stdin';
        } elsif( ref($argv1) eq 'SCALAR' ) {
            # Read from a variable as a scalar reference
            $klass  = __PACKAGE__.'::Memory';
            $loads .= 'Memory.pm';
            $param->{'kind'} = 'memory';
            $param->{'path'} = 'MEMORY';
        }
    }
    return undef unless $klass;
    require $loads;
    $param->{'data'} = $klass->new($argv1);
    return bless($param, __PACKAGE__);
}
sub read {
    # Alias method of Sisimai::Mail::*->read()
    # @return   [String] Contents of mbox/Maildir
    my $self = shift;
    return undef unless ref $self->{'data'};
    return $self->{'data'}->read;
}
1;
__END__
=encoding utf-8
=head1 NAME
Sisimai::Mail - Handler of Mbox/Maildir for reading each mail.
=head1 SYNOPSIS
    use Sisimai::Mail;
    my $mailbox = Sisimai::Mail->new('/var/mail/root');
    while( my $r = $mailbox->read ) {
        print $r;
    }
    my $maildir = Sisimai::Mail->new('/home/neko/Maildir/cur');
    while( my $r = $maildir->read ) {
        print $r;
    }
    my $mailtxt = 'From Mailer-Daemon ...';
    my $mailobj = Sisimai::Mail->new(\$mailtxt);
    while( my $r = $mailobj->read ) {
        print $r;
    }
=head1 DESCRIPTION
C<Sisimai::Mail> is a handler for reading a UNIX mbox, a Maildir, or any email message input from
C<STDIN> variable. It is a wrapper class of the following child classes:
    * Sisimai::Mail::Mbox
    * Sisimai::Mail::Maildir
    * Sisimai::Mail::STDIN
    * Sisimai::Mail::Memory
=head1 CLASS METHODS
=head2 C<B<new(I<path to mbox|Maildir/>)>>
C<new()> method is a constructor of C<Sisimai::Mail>
    my $mailbox = Sisimai::Mail->new('/var/mail/root');
    my $maildir = Sisimai::Mail->new('/home/nyaa/Maildir/cur');
    my $mailtxt = 'From Mailer-Daemon ...';
    my $mailobj = Sisimai::Mail->new(\$mailtxt);
=head1 INSTANCE METHODS
=head2 C<B<path()>>
C<path()> method returns the path to the mbox or the Maildir.
    print $mailbox->path;   # /var/mail/root
=head2 C<B<kind()>>
C<kind()> method returns the name of the data type
    print $mailbox->kind;   # mailbox or maildir, stdin, or memory.
=head2 C<B<mail()>>
C<mail()> method returns the C<Sisimai::Mail::Mbox> object or the C<Sisimai::Mail::Maildir> object.
    my $o = $mailbox->mail;
    print ref $o;   # Sisimai::Mail::Mbox
=head2 C<B<read()>>
C<read()> method works as an iterator for reading each email in the mbox or the Maildir. It calls
C<Sisimai::Mail::Mbox->read()> or C<Sisimai::Mail::Maildir->read> methods.
    my $mailbox = Sisimai::Mail->new('/var/mail/neko');
    while( my $r = $mailbox->read ) {
        print $r;   # print each email in /var/mail/neko
    }
=head1 AUTHOR
azumakuniyuki
=head1 COPYRIGHT
Copyright (C) 2014-2016,2018-2021,2024 azumakuniyuki, All rights reserved.
=head1 LICENSE
This software is distributed under The BSD 2-Clause License.
=cut