1Mail::Box::Tie::ARRAY(3U)ser Contributed Perl DocumentatiMoanil::Box::Tie::ARRAY(3)
2
3
4

NAME

6       Mail::Box::Tie::ARRAY - access an existing message folder as array
7

SYNOPSIS

9        use Mail::Box::Manager;
10        my $mgr    = Mail::Box::Manager->new;
11        my $folder = $mgr->open(folder => 'inbox');
12
13        use Mail::Box::Tie::ARRAY;
14        tie my(@inbox), 'Mail::Box::Tie::ARRAY', $folder;
15
16        # deprecated, but works too
17        use Mail::Box::Tie;
18        tie my(@inbox), 'Mail::Box::Tie', $folder;
19
20        foreach (@inbox) {print $_->short}
21        print $_->print foreach @inbox;
22        my $emails = @inbox;
23
24        print $inbox[3];
25        print scalar @inbox;
26        push @inbox, Mail::Box::Message->new(...);
27        delete $inbox[6];
28        print $inbox[0]->head->get('status');
29
30        my $folder = tied @inbox;
31        untie @inbox;
32

DESCRIPTION

34       Certainly when you look at a folder as a list of messages, it is
35       logical to access the folder through an array.
36
37       Not all operations on arrays are supported.  Actually, most functions
38       which would reduce the size of the array are modified instead to mark
39       messages for deletion.
40
41       Examples what you cannot do:
42
43        shift/unshift/pop/splice @inbox;
44

METHODS

46   Constructors
47       TIEARRAY('Mail::Box::Tie::ARRAY', FOLDER)
48           Create the tie on an existing folder.
49
50           example: tie an array to a folder
51
52            my $mgr   = Mail::Box::Manager->new;
53            my $inbox = $mgr->new(folder => $ENV{MAIL});
54            tie my(@inbox), 'Mail::Box::Tie::Array', ref $inbox, $inbox;
55
56   Tied Interface
57       $obj->DELETE()
58           Flag a message to be removed.  Be warned that the message stays in
59           the folder, and is not removed before the folder is written.
60
61           example:
62
63            delete $inbox[5];
64            $inbox[5]->delete;   #same
65
66       $obj->FETCH($index)
67           Get the message which is at the indicated location in the list of
68           messages contained in this folder.  Deleted messages will be
69           returned as "undef".
70
71           example:
72
73            print $inbox[3];     # 4th message in the folder
74            print @inbox[3,0];   # 4th and first of the folder
75            print $inbox[-1];    # last message
76
77       $obj->FETCHSIZE()
78           Return the total number of messages in a folder.  This is called
79           when the folder-array is used in scalar context, for instance.
80
81           example:
82
83            if(@inbox > 10)    # contains more than 10 messages?
84            my $nrmsgs = @inbox;
85
86       $obj->PUSH(@messages)
87           Add @messages to the end of the folder.
88
89           example:
90
91               push @inbox, $newmsg;
92
93       $obj->STORE($index, $message)
94           Random message replacement is not permitted --doing so would
95           disturb threads etc.  An error occurs if you try to do this. The
96           only thing which is allowed is to store a message at the first free
97           index at the end of the folder (which is also achievable with
98           PUSH()).
99
100           example:
101
102            $inbox[8] = $add;
103            $inbox[-1] = $add;
104            push @inbox, $add;
105
106       $obj->STORESIZE($length)
107           Sets all messages behind from $length to the end of folder to be
108           deleted.
109

DETAILS

111   Folder tied as array
112       Limitations
113
114       This module implements "TIEARRAY", "FETCH", "STORE", "FETCHSIZE",
115       "STORESIZE", "DELETE", "PUSH", and "DESTROY".
116
117       This module does not implement all other methods as described in the
118       Tie::Array documentation, because the real array of messages is not
119       permitted to shrink or be mutilated.
120

SEE ALSO

122       This module is part of Mail-Box distribution version 3.009, built on
123       August 18, 2020. Website: http://perl.overmeer.net/CPAN/
124

LICENSE

126       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
127       ChangeLog.
128
129       This program is free software; you can redistribute it and/or modify it
130       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
131
132
133
134perl v5.34.0                      2021-07-22          Mail::Box::Tie::ARRAY(3)
Impressum