Mail::Box::Tie::ARRAY(3pm)

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

DETAILS

120       Folder tied as array
121
122       Limitations
123
124       This module implements "TIEARRAY", "FETCH", "STORE", "FETCHSIZE",
125       "STORESIZE", "DELETE", "PUSH", and "DESTROY".
126
127       This module does not implement all other methods as described in the
128       Tie::Array documentation, because the real array of messages is not
129       permitted to shrink or be mutilated.
130

LICENSE

136       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
137       ChangeLog.
138
139       This program is free software; you can redistribute it and/or modify it
140       under the same terms as Perl itself.  See
141       http://www.perl.com/perl/misc/Artistic.html
142
143
144
145perl v5.8.8                       2007-03-25          Mail::Box::Tie::ARRAY(3)

NAME

SYNOPSIS

DESCRIPTION

METHODS

DETAILS

SEE ALSO

LICENSE