MboxParser.pm

filter: Statementstmt 68.8% 183 / 266 Branchbran 55.9% 66 / 118 Conditioncond 67.3% 33 / 49 MC/DCmcdc 53.5% 15 / 28 Subroutinesub 81.4% 22 / 27 Podpod 53.3% 8 / 15 totaltotal 65.0% 327 / 503 CC 78 SCAR 45.2
CC
78
Cov
65%
open
308.8
get_messages_old
16.1
next_message_old
13.0
CRAP 91.9
↑ Summary MboxParser/Mail.pm »
1 # Mail::MboxParser - object-oriented access to UNIX-mailboxes
2 #
3 # Copyright (C) 2001 Tassilo v. Parseval
4 # This program is free software; you can redistribute it and/or
5 # modify it under the same terms as Perl itself.
6  
7 # Version: $Id: MboxParser.pm,v 1.54 2002/03/01 09:34:39 parkerpine Exp $
8  
9 package Mail::MboxParser;
10  
11 18 require 5.004;
12  
13 18 ▶use base 'Mail::MboxParser::Base';
Subroutine BEGIN: called CC=1 SCAR=0.0
14  
15 # ----------------------------------------------------------------
16  
17 =head1 NAME
18  
19 Mail::MboxParser - read-only access to UNIX-mailboxes
20  
21 =head1 SYNOPSIS
22  
23 use Mail::MboxParser;
24  
25 my $parseropts = {
26 enable_cache => 1,
27 enable_grep => 1,
28 cache_file_name => 'mail/cache-file',
29 };
30 my $mb = Mail::MboxParser->new('some_mailbox',
31 decode => 'ALL',
32 parseropts => $parseropts);
33  
34 # -----------
35
36 # slurping
37 for my $msg ($mb->get_messages) {
38 print $msg->header->{subject}, "\n";
39 $msg->store_all_attachments(path => '/tmp');
40 }
41  
42 # iterating
43 while (my $msg = $mb->next_message) {
44 print $msg->header->{subject}, "\n";
45 # ...
46 }
47  
48 # we forgot to do something with the messages
49 $mb->rewind;
50 while (my $msg = $mb->next_message) {
51 # iterate again
52 # ...
53 }
54  
55 # subscripting one message after the other
56 for my $idx (0 .. $mb->nmsgs - 1) {
57 my $msg = $mb->get_message($idx);
58 }
59  
60 =head1 DESCRIPTION
61  
62 This module attempts to provide a simplified access to standard UNIX-mailboxes.
63 It offers only a subset of methods to get 'straight to the point'. More
64 sophisticated things can still be done by invoking any method from MIME::Tools
65 on the appropriate return values.
66  
67 Mail::MboxParser has not been derived from Mail::Box and thus isn't acquainted
68 with it in any way. It, however, incorporates some invaluable hints by the
69 author of Mail::Box, Mark Overmeer.
70  
71 =head1 METHODS
72  
73 See also the section ERROR-HANDLING much further below.
74  
75 More to that, see the relevant manpages of Mail::MboxParser::Mail,
76 Mail::MboxParser::Mail::Body and Mail::MboxParser::Mail::Convertable for a
77 description of the methods for these objects.
78  
79 =cut
80  
81 18 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
82 18 ▶use Mail::MboxParser::Mail;
Subroutine BEGIN: called CC=1 SCAR=0.0
83 18 ▶use File::Temp qw/tempfile/;
Subroutine BEGIN: called CC=1 SCAR=0.0
84 18 ▶use Symbol;
Subroutine BEGIN: called CC=1 SCAR=0.0
85 18 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
86 18 ▶use IO::Seekable;
Subroutine BEGIN: called CC=1 SCAR=0.0
87  
88 18 ▶use base qw(Exporter);
Subroutine BEGIN: called CC=1 SCAR=0.0
89 18 ▶use vars qw($VERSION @EXPORT @ISA);
Subroutine BEGIN: called CC=1 SCAR=0.0
90 18 $VERSION = "0.55";
91 18 @EXPORT = qw();
92 18 @ISA = qw(Mail::MboxParser::Base);
93  
94 use constant
95 0 ▶ HAVE_MSGPARSER => eval { require Mail::Mbox::MessageParser; 1 } || 0;
Subroutine BEGIN: called CC=2 SCAR=7.4
Condition50%1/2
eval { do { require Mail::Mbox::MessageParser; 1 } } || 0
l!l
018
MC/DC0%0/1
eval { do { require Mail::Mbox::MessageParser; 1 } } || 0
eval { do { require Mail::Mbox::MessageParser; 1 } }
Truth table50%1/2
A
A= eval { do { require Mail::Mbox::MessageParser; 1 } }
Aresult
11
00
96
97 18 my $from_date = qr/^From (.*)\d{4}\015?$/;
98 18 my $empty_line = qr/^\015?$/;
99  
100 # ----------------------------------------------------------------
101  
102 =over 4
103  
104 =item B<new(mailbox, options)>
105  
106 =item B<new(scalar-ref, options)>
107  
108 =item B<new(array-ref, options)>
109  
110 =item B<new(filehandle, options)>
111  
112 This creates a new MboxParser-object opening the specified 'mailbox' with
113 either absolute or relative path.
114  
115 new() can also take a reference to a variable containing the mailbox either as
116 one string (reference to a scalar) or linewise (reference to an array), or a
117 filehandle from which to read the mailbox.
118  
119 The following option(s) may be useful. The value in brackets below the key is
120 the default if none given.
121  
122 key: | value: | description:
123 ==========|============|===============================
124 decode | 'NEVER' | never decode transfer-encoded
125 (NEVER) | | data
126 |------------|-------------------------------
127 | 'BODY' | will decode body into a human-
128 | | readable format
129 |------------|-------------------------------
130 | 'HEADER' | will decode header fields if
131 | | any is encoded
132 |------------|-------------------------------
133 | 'ALL' | decode any data
134 ==========|============|===============================
135 uudecode | 1 | enable extraction of uuencoded
136 (0) | | attachments in MIME::Parser
137 |------------|-------------------------------
138 | 0 | uuencoded attachments are
139 | | treated as plain body text
140 ==========|============|===============================
141 newline | 'UNIX' | UNIXish line-endings
142 (AUTO) | | ("\n" aka \012)
143 |------------|-------------------------------
144 | 'WIN' | Win32 line-endings
145 | | ("\n\r" aka \012\015)
146 |------------|-------------------------------
147 | 'AUTO' | try to do autodetection
148 |------------|-------------------------------
149 | custom | a user-given value for totally
150 | | borked mailboxes
151 ==========|============|===============================
152 oldparser | 1 | uses the old (and slower)
153 (0) | | parser (but guaranteed to show
154 | | the old behaviour)
155 |------------|-------------------------------
156 | 0 | uses Mail::Mbox::MessageParser
157 ==========|============|===============================
158 parseropts| | see "Specifying parser opts"
159 | | below
160 ==========|============|===============================
161  
162 The I<newline> option comes in handy if you have a mbox-file that happens to
163 not conform to the rules of your operating-system's character semantics one way
164 or another. One such scenario: You are using the module under Win but
165 deliberately have mailboxes with UNIX-newlines (or the other way round). If you
166 do not give this option, 'AUTO' is assumed and some basic tests on the mailbox
167 are performed. This autoedection is of course not capable of detecting cases
168 where you use something like '#DELIMITER' as line-ending. It can as to yet only
169 distinguish between UNIX and Win32ish newlines. You may be lucky and it even
170 works for Macintoshs. If you have more extravagant wishes, pass a costum value:
171  
172 my $mb = new Mail::MboxParser ("mbox", newline => '#DELIMITER');
173  
174 You can't use regexes here since internally this relies on the $/ var
175 ($INPUT_RECORD_SEPERATOR, that is).
176
177 When passing either a scalar-, array-ref or \*STDIN as first-argument, an
178 anonymous tmp-file is created to hold the data. This procedure is hidden away
179 from the user so there is no need to worry about it. Since a tmp-file acts just
180 like an ordinary mailbox-file you don't need to be concerned about loss of data
181 or so once you have been walking through the mailbox-data. No data will be lost
182 and it'll all be fine and smooth.
183  
184 =back
185  
186 =head2 Specifying parser options
187  
188 When available, the module will use C<Mail::Mbox::MessageParser> to do the
189 parsing. To get the most speed out of it, you can tweak some of its options.
190 Arguably, you even have to do that in order to make it use caching. Options for
191 the parser are given via the I<parseropts> switch that expects a reference to a
192 hash as values. The values you can specify are:
193  
194 =over 8
195  
196 =item enable_cache
197  
198 When set to a true value, caching is used B<but only> if you gave
199 I<cache_file_name>. There is no default value here!
200  
201 =item cache_file_name
202  
203 The file used for caching. This option is mandatory if I<enable_cache> is true.
204  
205 =item enable_grep
206  
207 When set to a true value (which is the default), the extern grep(1) is used to
208 speed up parsing. If your system does not provide a usable grep implementation,
209 it silently falls back to the pure Perl parser.
210  
211 =back
212  
213 When the module was unable to create a C<Mail::Mbox::MessageParser> object, it
214 will fall back to the old parser in the hope that the construction of the
215 object then succeeds.
216  
217 =cut
218  
219 17 ▶sub init (@) {
Subroutine init: called CC=3 SCAR=12.3
Pod undocumented
220 17 my ($self, @args) = @_;
221  
222 17 ▶ if (@args == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args == 0) 0 17 17
223 0 croak <<EOC;
224 Error: open needs either a filename, a filehande (as glob-ref) or a
225 (scalar/array)-referece variable as first argument.
226 EOC
227 }
228
229 # we need odd number of arguments
230 17 ▶ if ((@args % 2) == 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (@args % 2 == 0) 0 17 17
231 0 croak <<EOC;
232 Error: open() can never have an even number of arguments.
233 See 'perldoc Mail::MboxParser' on how to call it.
234 EOC
235 }
236 17 $self->open(@args);
237  
238 17 $self;
239 }
240  
241 # ----------------------------------------------------------------
242  
243 =over 4
244  
245 =item B<open(source, options)>
246  
247 Takes exactly the same arguments as new() does just that it can be used to
248 change the characteristics of a mailbox on the fly.
249  
250 =back
251  
252 =cut
253  
254 17 ▶sub open (@) {
Subroutine open: called CC=29 SCAR=57.3
Pod documented
255 17 my ($self, @args) = @_;
256
257 17 local *_;
258  
259 17 my $source = shift @args;
260
261 17 $self->{CONFIG} = { @args };
262 17 $self->{CURR_POS} = 0;
263  
264 17 my ($file_name, $old_filepos);
265
266 # supposedly a filename
267 17 ▶ if (! ref $source) {
Branch: 2 branches
BranchTrueFalseTotal
if (not ref $source) { } 17 0 17
elsif (ref $source eq 'GLOB' and seek $source, 0, 1) { } 0 0 0
268 17 ▶ if (! -f $source) {
Branch: 1 branch
BranchTrueFalseTotal
unless (-f $source) 0 17 17
269 0 croak <<EOC;
270 Error: The filename you passed to open() does not refer to an existing file
271 EOC
272 }
273 17 my $handle = gensym;
274 17 ▶ open $handle, "<$source" or
Branch: 1 branch
BranchTrueFalseTotal
CORE::open $handle, "<$source" or croak("Error: Could not open $source for reading: $!") 17 0 17
275 croak "Error: Could not open $source for reading: $!";
276 17 $self->{READER} = $handle;
277 17 $file_name = $source;
278 }
279  
280 # a filehandle
281 ▶ elsif (ref $source eq 'GLOB' && seek $source, 0, SEEK_CUR) {
Condition0%0/3
ref $source eq "GLOB" and seek $source, 0, 1
!ll&&!rl&&r
000
MC/DC0%0/2
ref $source eq "GLOB" and seek $source, 0, 1
ref $source eq "GLOB" seek $source, 0, 1
Truth table0%0/3
A and B
A= ref $source eq "GLOB"B= seek $source, 0, 1
ABresult
0X0
100
111
282 0 $old_filepos = tell $source;
283 0 $self->{READER} = $source;
284 }
285
286 # else
287 else {
288 0 ▶ (my $fh, $file_name) = tempfile(UNLINK => 1) or croak <<EOC;
Branch: 1 branch
BranchTrueFalseTotal
(my $fh, $file_name) = tempfile("UNLINK", 1) or croak("Error: Could not create temporary file. This is very weird ($!).\n") 0 0 0
289 Error: Could not create temporary file. This is very weird ($!).
290 EOC
291 0 ▶ if (ref $source eq 'SCALAR') { print $fh ${$source} }
Branch: 3 branches
BranchTrueFalseTotal
if (ref $source eq 'SCALAR') { } 0 0 0
elsif (ref $source eq 'ARRAY') { } 0 0 0
elsif (ref $source eq 'GLOB') { } 0 0 0
292 0 elsif (ref $source eq 'ARRAY') { print $fh @{$source} }
293 0 ▶ elsif (ref $source eq 'GLOB') { print $fh $_ while <$source> }
Branch: 1 branch
BranchTrueFalseTotal
defined($_ = readline $source) and do { print $fh $_ } 0 0 0
294 0 seek $fh, 0, SEEK_SET;
295 0 $self->{READER} = $fh;
296 }
297  
298 17 ▶ if ($self->{CONFIG}->{oldparser} or ! HAVE_MSGPARSER
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'CONFIG'}{'oldparser'} or !0 or not defined $file_name) { } 17 0 17
Condition60%3/5
or not defined $file_name
l!l&&r!l&&!r
1700
$self->{"CONFIG"}{"oldparser"} or
l!l
89
MC/DC0%0/2
or not defined $file_name
$self->{"CONFIG"}{"oldparser"} not defined $file_name
Truth table33%1/3
A or not(B)
A= $self->{"CONFIG"}{"oldparser"}B= not defined $file_name
ABresult
1X1
011
000
299 or ! defined $file_name) {
300 17 binmode $self->{READER};
301 17 local $^W = 0;
302 17 *get_messages = \&get_messages_old;
303 17 *get_message = \&get_message_old;
304 17 *next_message = \&next_message_old;
305
306 17 $self->{CONFIG}->{join_string} = "";
307 } else {
308 0 local $^W = 0;
309 0 *get_messages = \&get_messages_new;
310 0 *get_message = \&get_message_new;
311 0 *next_message = \&next_message_new;
312  
313 0 $self->{CONFIG}->{join_string} = "\n";
314 # check sanity of arguments and capabilities of system:
315 # clean options accordingly
316 0 ▶ my $opts = delete($self->{CONFIG}->{parseropts}) || {enable_grep => 1};
Condition0%0/2
delete $self->{'CONFIG'}{'parseropts'} || {'enable_grep', 1}
l!l
00
MC/DC0%0/1
delete $self->{'CONFIG'}{'parseropts'} || {'enable_grep', 1}
delete $self->{'CONFIG'}{'parseropts'}
Truth table0%0/2
A
A= delete $self->{'CONFIG'}{'parseropts'}
Aresult
11
00
317 0 ▶ $opts->{enable_grep} = 1 if ! exists $self->{enable_grep};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"enable_grep"} 0 0 0
318  
319 0 ▶ if ($opts->{enable_grep}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opts->{"enable_grep"}) 0 0 0
320 0 eval { require Mail::Mbox::MessageParser::Grep };
321 0 ▶ delete $opts->{enable_grep} if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
322 }
323 0 ▶ if ($opts->{enable_cache}) {
Branch: 1 branch
BranchTrueFalseTotal
if ($opts->{"enable_cache"}) 0 0 0
324 0 ▶ delete $opts->{enable_cache} if ! exists $opts->{cache_file_name};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $opts->{"cache_file_name"} 0 0 0
325 0 eval { require Mail::Mbox::MessageParser::Cache };
326 0 ▶ delete $opts->{enable_cache} if $@;
Branch: 1 branch
BranchTrueFalseTotal
if $@ 0 0 0
327 }
328  
329 Mail::Mbox::MessageParser::SETUP_CACHE(
330 { file_name => $opts->{cache_file_name} }
331 0 ▶ ) if $opts->{enable_cache};
Branch: 1 branch
BranchTrueFalseTotal
if $opts->{"enable_cache"} 0 0 0
332
333 0 ▶ $opts->{enable_cache} ||= 0;
Condition0%0/2
$opts->{"enable_cache"} ||= 0
l!l
00
MC/DC0%0/1
$opts->{"enable_cache"} ||= 0
$opts->{"enable_cache"}
Truth table0%0/2
A
A= $opts->{"enable_cache"}
Aresult
11
00
334 0 $opts->{file_handle} = $self->{READER};
335 0 $opts->{file_name} = $file_name;
336 0 ▶ if (not ref($self->{PARSER} = Mail::Mbox::MessageParser->new($opts))) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref($self->{"PARSER"} = "Mail::Mbox::MessageParser"->new($opts))) 0 0 0
337 # when Mail::Mbox::MessageParser object could not be created,
338 # try to fall back to the old parser
339 0 my %opt = @args;
340 0 $opt{ oldparser } = 1;
341 0 delete $opt{ parseropts };
342 # $source could be a GLOB which we need to rewind
343 # if it isn't, the BLOCK-eval should catch it.
344 0 eval { seek $source, $old_filepos, SEEK_SET };
345 0 return Mail::MboxParser->new($source, %opt);
346 }
347 }
348  
349 # do line-ending stuff
350 17 ▶ if (! exists $self->{CONFIG}->{newline}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"CONFIG"}{"newline"}) 17 0 17
351 17 $self->{CONFIG}->{newline} = 'AUTO';
352 }
353
354 17 my $nl = $self->{CONFIG}->{newline};
355 0 ▶ if ($nl eq 'UNIX') { $self->{NL} = "\012" }
Branch: 3 branches
BranchTrueFalseTotal
if ($nl eq 'UNIX') { } 0 17 17
elsif ($nl eq 'WIN') { } 0 17 17
elsif ($nl eq 'AUTO') { } 17 0 17
356 0 elsif ($nl eq 'WIN') { $self->{NL} = "\015\012" }
357 17 elsif ($nl eq 'AUTO') { $self->{NL} = $self->_detect_nl }
358 0 else { $self->{NL} = $nl }
359 17 $Mail::MboxParser::Mail::NL = $self->{NL};
360  
361 17 ▶ seek $self->{READER}, 0, SEEK_SET if ! $self->{PARSER};
Branch: 1 branch
BranchTrueFalseTotal
unless $self->{"PARSER"} 17 0 17
362 17 return;
363 }
364  
365 # ----------------------------------------------------------------
366  
367 =over 4
368  
369 =item B<get_messages>
370  
371 Returns an array containing all messages in the mailbox respresented as
372 Mail::MboxParser::Mail objects. This method is _minimally_ quicker than
373 iterating over the mailbox using C<next_message> but eats much more memory.
374 Memory-usage will grow linearly for each new message detected since this method
375 creates a huge array containing all messages. After creating this array, it
376 will be returned.
377  
378 =back
379  
380 =cut
381  
382 0 ▶sub get_messages_new() {
Subroutine get_messages_new: not called CC=2 SCAR=17.9
Pod undocumented
383 0 my $self = shift;
384  
385 0 my $nl = $self->{NL};
386 0 my @messages;
387 0 my $p = $self->parser;
388 0 $p->reset;
389  
390 0 ▶ while (! $p->end_of_file) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($p->end_of_file) 0 0 0
391 0 my $mailref = $p->read_next_email;
392 0 my ($header, $body) = split /$nl$nl/, $$mailref, 2;
393 push @messages,
394 Mail::MboxParser::Mail->new([ split(/$nl/, $header), '' ],
395 [ split /$nl/, $body ],
396 0 $self->{CONFIG});
397 }
398 0 $p->reset;
399 0 return @messages;
400 }
401
402 9 ▶sub get_messages_old() {
Subroutine get_messages_old: called CC=16 SCAR=27.8
Pod undocumented
403 9 my $self = shift;
404  
405 9 local $/ = $self->{NL};
406  
407 9 my ($in_header, $in_body) = (0, 0);
408 9 my $header;
409 9 my (@header, @body);
410 9 my $h = $self->{READER};
411  
412 9 my $got_header;
413  
414 my @messages;
415  
416 9 seek $h, 0, SEEK_SET;
417 9 local *_;
418 9 ▶ while (<$h>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $h)) 7354 9 7363
419  
420 # entering header
421 7354 ▶ if (!$in_body && /$from_date/) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $in_body and /$from_date/) 9 7345 7354
Condition100%3/3
not $in_body and /$from_date/
!ll&&!rl&&r
491624299
MC/DC100%2/2
not $in_body and /$from_date/
not $in_body /$from_date/
Truth table100%3/3
not(A) and B
A= not $in_bodyB= /$from_date/
ABresult
0X0
100
111
422 9 ($in_header, $in_body) = (1, 0);
423 9 $got_header = 0;
424 }
425 # entering body
426 7354 ▶ if ($in_header && /$empty_line/) {
Branch: 1 branch
BranchTrueFalseTotal
if ($in_header and /$empty_line/) 73 7281 7354
Condition100%3/3
$in_header and /$empty_line/
!ll&&!rl&&r
4924235773
MC/DC100%2/2
$in_header and /$empty_line/
$in_header /$empty_line/
Truth table100%3/3
A and B
A= $in_headerB= /$empty_line/
ABresult
0X0
100
111
427 73 ($in_header, $in_body) = (0, 1);
428 73 $got_header = 1;
429 }
430  
431 # just before entering next mail-header or running
432 # out of data, store message in Mail-object
433 7354 ▶ if ((/$from_date/ || eof) && $got_header) {
Branch: 1 branch
BranchTrueFalseTotal
if (/$from_date/ || eof and $got_header) 73 7281 7354
Condition100%6/6
/$from_date/ || eof and $got_header
!ll&&!rl&&r
7272973
/$from_date/ or eof
l!l&&r!l&&!r
7397272
MC/DC100%3/3
/$from_date/ || eof and $got_header
/$from_date/ eof $got_header
Truth table80%4/5
A or B and C
A= /$from_date/B= eofC= $got_header
ABCresult
00X0
1X00
0100
1X11
0111
434 73 ▶ push @body, $_ if eof; # don't forget last line!!
Branch: 1 branch
BranchTrueFalseTotal
if eof 9 64 73
435 73 my $m = Mail::MboxParser::Mail->new([ @header ], [ @body ], $self->{CONFIG});
436 73 push @messages, $m;
437 73 ($in_header, $in_body) = (1, 0);
438 73 undef $header;
439 73 (@header, @body) = ();
440 73 $got_header = 0;
441 }
442 7354 ▶ if ($_) {
Branch: 1 branch
BranchTrueFalseTotal
if ($_) 7354 0 7354
443 7354 ▶ push @header, $_ if $in_header && !$got_header;
Branch: 1 branch
BranchTrueFalseTotal
if $in_header and not $got_header 2430 4924 7354
Condition66%2/3
$in_header and not $got_header
!ll&&!rl&&r
492402430
MC/DC50%1/2
$in_header and not $got_header
$in_header not $got_header
Truth table66%2/3
A and not(B)
A= $in_headerB= not $got_header
ABresult
0X0
100
111
444 7354 ▶ push @body, $_ if $in_body && $got_header;
Branch: 1 branch
BranchTrueFalseTotal
if $in_body and $got_header 4916 2438 7354
Condition66%2/3
$in_body and $got_header
!ll&&!rl&&r
243804916
MC/DC50%1/2
$in_body and $got_header
$in_body $got_header
Truth table66%2/3
A and B
A= $in_bodyB= $got_header
ABresult
0X0
100
111
445 }
446 }
447
448 9 ▶ if (exists $self->{CONFIG}->{decode}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{"CONFIG"}{"decode"}) 0 9 9
449 0 $Mail::MboxParser::Mail::Config->{decode} = $self->{CONFIG}->{decode};
450 }
451 9 return @messages;
452 }
453  
454 # ----------------------------------------------------------------
455  
456 =over 4
457  
458 =item B<get_message(n)>
459  
460 Returns the n-th message (first message has index 0) in a mailbox. Examine
461 C<$mb-E<gt>error> which contains an error-string if the message does not exist.
462 In this case, C<get_message> returns undef.
463  
464 =back
465  
466 =cut
467  
468 0 ▶sub get_message_new($) {
Subroutine get_message_new: not called CC=1 SCAR=6.9
Pod undocumented
469 0 my ($self, $num) = @_;
470 0 my $oldpos = tell $self->{READER};
471 0 my $msg = $self->get_message_old($num);
472 0 seek $self->{READER}, $oldpos, SEEK_SET;
473 0 return $msg;
474 }
475  
476 38 ▶sub get_message_old($) {
Subroutine get_message_old: called CC=3 SCAR=11.3
Pod undocumented
477 38 my ($self, $num) = @_;
478
479 38 local $/ = $self->{NL};
480
481 38 $self->reset_last;
482 38 ▶ $self->make_index if ! exists $self->{MSG_IDX};
Branch: 1 branch
BranchTrueFalseTotal
unless exists $self->{"MSG_IDX"} 6 32 38
483  
484 38 my $tmp_idx = $self->current_pos;
485 38 my $pos = $self->get_pos($num);
486
487 38 ▶ if (my $err = $self->error) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $err = $self->error) 0 38 38
488 0 $self->set_pos($tmp_idx);
489 0 $self->{LAST_ERR} = $err;
490 0 return;
491 }
492  
493 38 $self->set_pos($pos);
494 38 my $msg = $self->next_message_old;
495 38 $self->set_pos($tmp_idx);
496 38 return $msg;
497 }
498  
499 # ----------------------------------------------------------------
500  
501 =over 4
502  
503 =item B<next_message>
504  
505 This lets you iterate over a mailbox one mail after another. The great
506 advantage over C<get_messages> is the very low memory-comsumption. It will be
507 at a constant level throughout the execution of your script. Secondly, it
508 almost instantly begins spitting out Mail::MboxParser::Mail-objects since it
509 doesn't have to slurp in all mails before returing them.
510  
511 =back
512  
513 =cut
514  
515 0 ▶sub next_message_new() {
Subroutine next_message_new: not called CC=3 SCAR=24.8
Pod undocumented
516 0 my $self = shift;
517 0 $self->reset_last;
518 0 my $p = $self->parser;
519  
520 0 ▶ return undef if ref(\$p) eq 'SCALAR' or $p->end_of_file;
Branch: 1 branch
BranchTrueFalseTotal
if ref \$p eq "SCALAR" or $p->end_of_file 0 0 0
Condition0%0/3
ref \$p eq "SCALAR" or $p->end_of_file
l!l&&r!l&&!r
000
MC/DC0%0/2
ref \$p eq "SCALAR" or $p->end_of_file
ref \$p eq "SCALAR" $p->end_of_file
Truth table0%0/3
A or B
A= ref \$p eq "SCALAR"B= $p->end_of_file
ABresult
1X1
011
000
521  
522 0 seek $self->{READER}, $self->{CURR_POS}, SEEK_SET;
523 0 my $nl = $self->{NL};
524 0 my $mailref = $p->read_next_email;
525 0 my ($header, $body) = split /$nl$nl/, $$mailref, 2;
526 my $msg = Mail::MboxParser::Mail->new([ split(/$nl/, $header), '' ],
527 [ split /$nl/, $body ],
528 0 $self->{CONFIG});
529 0 $self->{CURR_POS} = $p->offset + $p->length;
530 0 return $msg;
531 }
532  
533 78 ▶sub next_message_old() {
Subroutine next_message_old: called CC=13 SCAR=25.6
Pod undocumented
534 78 my $self = shift;
535 78 $self->reset_last;
536  
537 78 local $/ = $self->{NL};
538  
539 78 my $h = $self->{READER};
540  
541 78 my ($in_header, $in_body) = (0, 0);
542 78 my $header;
543 78 my (@header, @body);
544  
545 78 my $got_header = 0;
546  
547 78 seek $h, $self->{CURR_POS}, SEEK_SET;
548  
549 # we need to force join_string to "" here because
550 # this method is also invoked by get_message_new():
551 78 my %newopts = %{ $self->{CONFIG} };
552 78 $newopts{ join_string } = '';
553  
554 78 local *_;
555 78 ▶ while (<$h>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $h)) 8158 4 8162
556  
557 8158 ▶ $got_header = 1 if eof($h) || /$empty_line/ and $in_header;
Branch: 1 branch
BranchTrueFalseTotal
if eof $h || /$empty_line/ and $in_header 74 8084 8158
Condition100%6/6
eof $h || /$empty_line/ and $in_header
!ll&&!rl&&r
6498158674
eof $h or /$empty_line/
l!l&&r!l&&!r
1416466498
MC/DC66%2/3
eof $h || /$empty_line/ and $in_header
eof $h /$empty_line/ $in_header
Truth table80%4/5
A or B and C
A= eof $hB= /$empty_line/C= $in_header
ABCresult
00X0
1X00
0100
1X11
0111
558  
559 8158 ▶ if (/$from_date/ || eof $h) {
Branch: 1 branch
BranchTrueFalseTotal
if (/$from_date/ or eof $h) 152 8006 8158
Condition100%3/3
/$from_date/ or eof $h
l!l&&r!l&&!r
138148006
MC/DC100%2/2
/$from_date/ or eof $h
/$from_date/ eof $h
Truth table100%3/3
A or B
A= /$from_date/B= eof $h
ABresult
1X1
011
000
560 152 ▶ push @body, $_ if eof $h;
Branch: 1 branch
BranchTrueFalseTotal
if eof $h 14 138 152
561 152 ▶ if (! $got_header) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $got_header) { } 78 74 152
562 78 ($in_header, $in_body) = (1, 0);
563 }
564 else {
565 74 $self->{CURR_POS} = tell($h) - length;
566 74 return Mail::MboxParser::Mail->new(\@header, \@body, \%newopts);
567 }
568 }
569  
570 8084 ▶ if (/$empty_line/ && $got_header) {
Branch: 1 branch
BranchTrueFalseTotal
if (/$empty_line/ and $got_header) 1642 6442 8084
Condition100%3/3
/$empty_line/ and $got_header
!ll&&!rl&&r
643841642
MC/DC100%2/2
/$empty_line/ and $got_header
/$empty_line/ $got_header
Truth table100%3/3
A and B
A= /$empty_line/B= $got_header
ABresult
0X0
100
111
571 1642 ($in_header, $in_body) = (0, 1);
572 1642 $got_header = 1;
573 }
574  
575 8084 ▶ push @header, $_ if $in_header;
Branch: 1 branch
BranchTrueFalseTotal
if $in_header 2480 5604 8084
576 8084 ▶ push @body, $_ if $in_body;
Branch: 1 branch
BranchTrueFalseTotal
if $in_body 5600 2484 8084
577
578 }
579 }
580  
581 # ----------------------------------------------------------------
582  
583 =over 4
584  
585 =item B<set_pos(n)>
586  
587 =item B<rewind>
588  
589 =item B<current_pos>
590  
591 These three methods deal with the position of the internal filehandle backening
592 the mailbox. Once you have iterated over the whole mailbox using
593 C<next_message> MboxParser has reached the end of the mailbox and you have to
594 do repositioning if you want to iterate again. You could do this with either
595 C<set_pos> or C<rewind>.
596  
597 $mb->rewind; # equivalent to
598 $mb->set_pos(0);
599  
600 C<current_pos> reveals the current position in the mailbox and can be used to
601 later return to this position if you want to do tricky things. Mark that
602 C<current_pos> does *not* return the current line but rather the current
603 character as returned by Perl's tell() function.
604
605 my $last_pos;
606 while (my $msg = $mb->next_message) {
607 # ...
608 if ($msg->header->{subject} eq 'I was looking for this') {
609 $last_pos = $mb->current_pos;
610 last; # bail out here and do something else
611 }
612 }
613
614 # ...
615 # ...
616
617 # now continue where we stopped:
618 $mb->set_pos($last_pos)
619 while (my $msg = $mb->next_message) {
620 # ...
621 }
622  
623 B<WARNING: > Be very careful with these methods when using the parser of
624 C<Mail::Mbox::MessageParser>. This parser maintains its own state and you
625 shouldn't expect it to always be in sync with the state of C<Mail::MboxParser>.
626 If you need some finer control over the parsing, better consider to use the
627 public interface as described in L<the manpage of
628 Mail::Mbox::MessageParser|Mail::Mbox::MessageParser>. Use C<parser()> to get
629 the underlying parser object.
630  
631 This however may expose you to the same problems turned around:
632 C<Mail::MboxParser> may loose its sync with its parser when you do that.
633  
634 Therefore: Just avoid any of the above for now and wait till
635 C<Mail::Mbox::MessageParser> has a stable interface.
636  
637 =back
638  
639 =cut
640  
641 76 ▶sub set_pos($) {
Subroutine set_pos: called CC=1 SCAR=0.0
Pod documented
642 76 my ($self, $pos) = @_;
643 76 $self->reset_last;
644 76 $self->{CURR_POS} = $pos;
645 }
646  
647 # ----------------------------------------------------------------
648  
649 0 ▶sub rewind() {
Subroutine rewind: not called CC=1 SCAR=6.9
Pod documented
650 0 my $self = shift;
651 0 $self->reset_last;
652 0 $self->set_pos(0);
653 }
654  
655 # ----------------------------------------------------------------
656  
657 40 ▶sub current_pos() {
Subroutine current_pos: called CC=1 SCAR=0.0
Pod documented
658 40 my $self = shift;
659 40 $self->reset_last;
660 40 return $self->{CURR_POS};
661 }
662  
663 # ----------------------------------------------------------------
664  
665 =over 4
666  
667 =item B<make_index>
668  
669 You can force the creation of a message-index with this method. The
670 message-index is a mapping between the index-number of a message (0 ..
671 $mb->nmsgs - 1) and the byte-position of the filehandle. This is usually done
672 automatically for you once you call C<get_message> hence the first call for a
673 particular message will be a little slower since the message-index first has to
674 be built. This is, however, done rather quickly.
675  
676 You can have a peek at the index if you are interested. The following produces
677 a nicely padded table (suitable for mailboxes up to 9.9999...GB ;-).
678
679 $mb->make_index;
680 for (0 .. $mb->nmsgs - 1) {
681 printf "%5.5d => %10.10d\n",
682 $_, $mb->get_pos($_);
683 }
684  
685 =back
686  
687 =cut
688  
689 6 ▶sub make_index() {
Subroutine make_index: called CC=3 SCAR=11.0
Pod documented
690 6 my $self = shift;
691  
692 6 local $/ = $self->{NL};
693
694 6 $self->reset_last;
695 6 my $h = $self->{READER};
696
697 6 seek $h, 0, SEEK_SET;
698
699 6 my $c = 0;
700  
701 6 local *_;
702 6 ▶ while (<$h>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $h)) 5442 6 5448
703 5442 ▶ $self->{MSG_IDX}->{$c} = tell($h) - length, $c++
Branch: 1 branch
BranchTrueFalseTotal
if /$from_date/ 54 5388 5442
704 if /$from_date/;
705 }
706 6 seek $h, 0, SEEK_SET;
707 }
708  
709 # ----------------------------------------------------------------
710  
711 =over 4
712  
713 =item B<get_pos(n)>
714  
715 This method takes the index-number of a certain message within the mailbox and
716 returns the corresponding position of the filehandle that represents that start
717 of the file.
718  
719 It is mainly used by C<get_message()> and you wouldn't really have to bother
720 using it yourself except for statistical purpose as demonstrated above along
721 with B<make_index>.
722  
723 =back
724  
725 =cut
726  
727 38 ▶sub get_pos($) {
Subroutine get_pos: called CC=3 SCAR=12.3
Pod documented
728 38 my ($self, $num) = @_;
729 38 $self->reset_last;
730 38 ▶ if (exists $self->{MSG_IDX}) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{'MSG_IDX'}) { } 38 0 38
731 38 ▶ if (! exists $self->{MSG_IDX}{$num}) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $self->{"MSG_IDX"}{$num}) 0 38 38
732 0 $self->{LAST_ERR} = "$num: No such message";
733 }
734 38 return $self->{MSG_IDX}{$num}
735 }
736 0 else { return }
737 }
738  
739 # ----------------------------------------------------------------
740  
741 =over 4
742  
743 =item B<nmsgs>
744  
745 Returns the number of messages in a mailbox. You could naturally also call
746 get_messages in scalar-context, but this one wont create new objects. It just
747 counts them and thus it is much quicker and wont eat a lot of memory.
748  
749 =back
750  
751 =cut
752  
753 14 ▶sub nmsgs() {
Subroutine nmsgs: called CC=6 SCAR=18.1
Pod documented
754 14 my $self = shift;
755  
756 14 local $/ = $self->{NL};
757  
758 0 ▶ if (not $self->{READER}) { return "No mbox opened" }
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"READER"}) 0 14 14
759 14 ▶ if (not $self->{NMSGS}) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($self->{"NMSGS"}) 12 2 14
760 12 my $h = $self->{READER};
761 12 seek $h, 0, SEEK_SET;
762 12 local *_;
763 12 ▶ while (<$h>) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $h)) 10884 12 10896
764 10884 ▶ $self->{NMSGS}++ if /$from_date/;
Branch: 1 branch
BranchTrueFalseTotal
if /$from_date/ 108 10776 10884
765 }
766 }
767 14 ▶ return $self->{NMSGS} || 0;
Condition50%1/2
$self->{'NMSGS'} || 0
l!l
140
MC/DC0%0/1
$self->{'NMSGS'} || 0
$self->{'NMSGS'}
Truth table50%1/2
A
A= $self->{'NMSGS'}
Aresult
11
00
768 }
769  
770 # ----------------------------------------------------------------
771  
772 =over 4
773  
774 =item B<parser>
775  
776 Returns the bare C<Mail::Mbox::MessageParser> object. If no such object exists
777 returns C<undef>.
778  
779 You can use this method to check whether the module actually uses the old or
780 new parser. If C<parser> returns a false value, it is using the old parsing
781 routines.
782  
783 =back
784  
785 =cut
786  
787 0 ▶sub parser { shift->{PARSER} }
Subroutine parser: not called CC=1 SCAR=6.9
Pod documented
788  
789 # ----------------------------------------------------------------
790  
791 17 ▶sub _detect_nl {
Subroutine _detect_nl: called CC=5 SCAR=16.1
792
793 17 my $self = shift;
794 17 my $h = $self->{READER};
795 17 my $newline;
796
797 17 seek $h, 0, SEEK_SET;
798 17 ▶ while (sysread $h, (my $c), 1) {
Branch: 1 branch
BranchTrueFalseTotal
if (sysread $h, my $c, 1) 48 0 48
799 48 ▶ if (ord($c) == 13) {
Branch: 2 branches
BranchTrueFalseTotal
if (ord $c == 13) { } 1 47 48
elsif (ord $c == 10) { } 16 31 47
800 1 $newline = "\015";
801 1 sysread $h, (my $next), 1;
802 1 ▶ $newline .= "\012" if ord($next) == 10;
Branch: 1 branch
BranchTrueFalseTotal
if ord $next == 10 1 0 1
803 1 last;
804 }
805 elsif (ord($c) == 10) {
806 16 $newline = "\012";
807 16 last;
808 }
809 }
810 17 return $newline;
811 }
812  
813 # ----------------------------------------------------------------
814  
815 17 ▶sub DESTROY {
Subroutine DESTROY: called CC=2 SCAR=7.1
816 17 my $self = shift;
817 17 $self->{NMSGS} = undef;
818 17 ▶ close $self->{READER} if defined $self->{READER};
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"READER"} 17 0 17
819 }
820  
821 # ----------------------------------------------------------------
822  
823 18 1;
824  
825 __END__
↑ Summary MboxParser/Mail.pm »