blib/lib/IMAP/BodyStructure.pm

filter: Statementstmt 95.0% 192 / 202 Branchbran 87.8% 72 / 82 Conditioncond 51.5% 17 / 33 MC/DCmcdc 31.2% 5 / 16 Subroutinesub 93.1% 27 / 29 Podpod 100% 8 / 8 totaltotal 86.7% 321 / 370 CC 56 SCAR 17.8
CC
56
Cov
89%
charset
14.1
_part_at
11.0
_get_bodystructure
10.0
CRAP 6.0
↑ Summary
1 package IMAP::BodyStructure;
2 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
3  
4 =head1 NAME
5  
6 IMAP::BodyStructure - IMAP4-compatible BODYSTRUCTURE and ENVELOPE parser
7  
8 =head1 SYNOPSIS
9
10 use IMAP::BodyStructure;
11  
12 # $imap is a low-level IMAP-client with an ability to fetch items
13 # by message uids
14  
15 my $bs = new IMAP::BodyStructure
16 $imap->imap_fetch($msg_uid,
17 'BODYSTRUCTURE', 1)->[0]->{BODYSTRUCTURE};
18  
19 print "[UID:$msg_uid] message is in Russian. Sure.\n"
20 if $bs->charset =~ /(?:koi8-r|windows-1251)/i;
21  
22 my $part = $bs->part_at('1.3');
23 $part->type =~ m#^image/#
24 and print "The 3rd part is an image named \""
25 . $part->filename . "\"\n";
26  
27 =head1 DESCRIPTION
28  
29 An IMAP4-compatible IMAP server MUST include a full MIME-parser which
30 parses the messages inside IMAP mailboxes and is accessible via
31 BODYSTRUCTURE fetch item. This module provides a Perl interface to
32 parse the output of IMAP4 MIME-parser. Hope no one will have problems
33 with parsing this doc.
34  
35 It is a rather straightforward C<m/\G.../gc>-style parser and is
36 therefore much, much faster then the venerable L<Mail::IMAPClient::BodyStructure>
37 which is based on a L<Parse::RecDescent> grammar. I believe it is also
38 more correct when parsing nested multipart C<message/rfc822> parts. See
39 testsuite if interested.
40  
41 I'd also like to emphasize that I<this module does not contain IMAP4
42 client!> You will need to employ one from CPAN, there are many. A
43 section with examples of getting to a BODYSTRUCTURE fetch item with
44 various Perl IMAP clients available on CPAN would greatly
45 enhance this document.
46  
47 =head1 INTERFACE
48  
49 =cut
50  
51 2 ▶use 5.005;
Subroutine BEGIN: called CC=1 SCAR=0.0
52  
53 2 ▶use vars qw/$VERSION/;
Subroutine BEGIN: called CC=1 SCAR=0.0
54  
55 2 $VERSION = '1.03';
56  
57 sub _get_envelope($\$);
58 sub _get_bodystructure(\$;$$);
59 sub _get_npairs(\$);
60 sub _get_ndisp(\$);
61 sub _get_nstring(\$);
62 sub _get_lang(\$);
63  
64 =head2 METHODS
65  
66 =over 4
67  
68 =item new($)
69  
70 The constructor does most of the work here. It initializes the
71 hierarchial data structure representing all the message parts and their
72 properties. It takes one argument which should be a string returned
73 by IMAP server in reply to a FETCH command with BODYSTRUCTURE item.
74  
75 All the parts on all the levels are represented by IMAP::BodyStructure
76 objects and that enables the uniform access to them. It is a direct
77 implementation of the Composite Design Pattern.
78  
79 =cut
80  
81 2 ▶use fields qw/type encoding size disp params parts desc bodystructure
Subroutine BEGIN: called CC=1 SCAR=0.0
82 2 part_id cid textlines md5 lang loc envelope/;
83  
84 13 ▶sub new {
Subroutine new: called CC=2 SCAR=7.4
Pod documented
85 13 my $class = shift;
86 13 ▶ $class = ref $class || $class;
Condition33%1/3
ref $class || $class
l!l&&r!l&&!r
0130
MC/DC0%0/2
ref $class || $class
ref $class $class
Truth table33%1/3
A || B
A= ref $classB= $class
ABresult
1X1
011
000
87 13 my $imap_str= shift;
88  
89 13 return _get_bodystructure($imap_str, $class);
90 }
91  
92 =item type()
93  
94 Returns the MIME type of the part. Expect something like C<text/plain>
95 or C<application/octet-stream>.
96  
97 =item encoding()
98  
99 Returns the MIME encoding of the part. This is usually one of '7bit',
100 '8bit', 'base64' or 'quoted-printable'.
101  
102 =item size()
103  
104 Returns the size of the part in octets. It is I<NOT> the size of the
105 data in the part, which may be encoded as quoted-printable leaving us
106 without an obvious method of calculating the exact size of original
107 data.
108  
109 =cut
110  
111 2 for my $field (qw/type encoding size/) {
112 2 ▶ no strict 'refs';
Subroutine BEGIN: called CC=1 SCAR=0.0
113 123 ▶ *$field = sub { return $_[0]->{$field} };
Subroutine __ANON__: called CC=1 SCAR=0.0
114 }
115  
116 =item disp()
117  
118 Returns the content-disposition of the part. One of 'inline' or
119 'attachment', usually. Defaults to inline, but you should remember
120 that if there IS a disposition but you cannot recognize it than act as
121 if it's 'attachment'. And use case-insensitive comparisons.
122  
123 =cut
124  
125 2 ▶sub disp {
Subroutine disp: called CC=3 SCAR=12.0
Pod documented
126 2 my $self = shift;
127  
128 2 ▶ return $self->{disp} ? $self->{disp}->[0] || 'inline' : 'inline';
Branch: 1 branch
BranchTrueFalseTotal
$self->{'disp'} ? : 2 0 2
Condition50%1/2
$self->{"disp"}[0] or "inline"
l!l
20
MC/DC0%0/1
$self->{"disp"}[0] or "inline"
$self->{"disp"}[0]
Truth table50%1/2
A
A= $self->{"disp"}[0]
Aresult
11
00
129 }
130  
131 =item charset()
132  
133 Returns the charset of the part OR the charset of the first nested
134 part. This looks like a good heuristic really. Charset is something
135 resembling 'UTF-8', 'US-ASCII', 'ISO-8859-13' or 'KOI8-R'. The standard
136 does not say it should be uppercase, by the way.
137  
138 Can be undefined.
139  
140 =cut
141  
142 2 ▶sub charset {
Subroutine charset: called CC=5 SCAR=26.5
Pod documented
143 2 my $self = shift;
144  
145 # get charset from params OR dive into the first part
146 return $self->{params}->{charset}
147 0 ▶ || ($self->{parts} && @{$self->{parts}} && $self->{parts}->[0]->charset)
Condition18%2/11
$self->{'params'}{'charset'} || $self->{'parts'} && @{$self->{'parts'};} && $self->{'parts'}[0]->charset || undef
l!l
20
$self->{"params"}{"charset"} or $self->{"parts"} and @{$self->{"parts"};} and $self->{"parts"}[0]->charset
l!l&&r!l&&!r
200
$self->{"parts"} and @{$self->{"parts"};} and $self->{"parts"}[0]->charset
!ll&&!rl&&r
000
$self->{"parts"} and @{$self->{"parts"};}
!ll&&!rl&&r
000
MC/DC0%0/4
$self->{'params'}{'charset'} || $self->{'parts'} && @{$self->{'parts'};} && $self->{'parts'}[0]->charset || undef
$self->{"params"}{"charset"} $self->{"parts"} @{$self->{"parts"};} $self->{"parts"}[0]->charset
Truth table20%1/5
A or B and C and D
A= $self->{"params"}{"charset"}B= $self->{"parts"}C= @{$self->{"parts"};}D= $self->{"parts"}[0]->charset
ABCDresult
1XXX1
01111
00XX0
010X0
01100
148 || undef; # please oh please, no '' or '0' charsets
149 }
150  
151 =item filename()
152  
153 Returns the filename specified as a part of Content-Disposition
154 header.
155  
156 Can be undefined.
157  
158 =cut
159  
160 2 ▶sub filename {
Subroutine filename: called CC=1 SCAR=0.0
Pod documented
161 2 my $self = shift;
162  
163 2 return $self->{disp}->[1]->{filename};
164 }
165  
166 =item description()
167  
168 Returns the description of the part.
169  
170 =cut
171  
172 0 ▶sub description {
Subroutine description: not called CC=1 SCAR=6.9
Pod documented
173 0 my $self = shift;
174  
175 0 return $self->{desc};
176 }
177  
178 =item parts(;$)
179  
180 This sub acts differently depending on whether you pass it an
181 argument or not.
182  
183 Without any arguments it returns a list of parts in list context and
184 the number in scalar context.
185  
186 Specifying a scalar argument allows you to get an individual part with
187 that index.
188  
189 I<Remember, all the parts I talk here about are not actual message data, files
190 etc. but IMAP::BodyStructure objects containing information about the
191 message parts which was extracted from parsing BODYSTRUCTURE IMAP
192 response!>
193  
194 =cut
195  
196 14 ▶sub parts {
Subroutine parts: called CC=3 SCAR=11.2
Pod documented
197 14 my $self = shift;
198 14 my $arg = shift;
199  
200 14 ▶ if (defined $arg) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $arg) { } 13 1 14
201 13 return $self->{parts}->[$arg];
202 } else {
203 0 ▶ return wantarray ? @{$self->{parts}} : scalar @{$self->{parts}};
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 0 1 1
204 }
205 }
206  
207 =item part_at($)
208  
209 This method returns a message part by its path. A path to a part in
210 the hierarchy is a dot-separated string of part indices. See L</SYNOPSIS> for
211 an example. A nested C<message/rfc822> does not add a hierarchy level
212 UNLESS it is a single part of another C<message/rfc822> part (with no
213 C<multipart/*> levels in between). Instead, it has an additional
214 C<.TEXT> part which refers to the internal IMAP::BodyStructure object.
215 Look, here is an outline of an example message structure with part
216 paths alongside each part.
217  
218 multipart/mixed 1
219 text/plain 1.1
220 application/msword 1.2
221 message/rfc822 1.3
222 multipart/alternative 1.3.TEXT
223 text/plain 1.3.1
224 multipart/related 1.3.2
225 text/html 1.3.2.1
226 image/png 1.3.2.2
227 image/png 1.3.2.3
228  
229 This is a text email with two attachments, one being an MS Word document,
230 and the other is itself a message (probably a forward) which is composed in a
231 graphical MUA and contains two alternative representations, one
232 plain text fallback and one HTML with images (bundled as a
233 C<multipart/related>).
234  
235 Another one with several levels of C<message/rfc822>. This one is hard
236 to compose in a modern MUA, however.
237  
238 multipart/mixed 1
239 text/plain 1.1
240 message/rfc822 1.2
241 message/rfc822 1.2.TEXT
242 text/plain 1.2.1
243  
244 =cut
245  
246 33 ▶sub part_at {
Subroutine part_at: called CC=1 SCAR=0.0
Pod documented
247 33 my $self = shift;
248 33 my $path = shift;
249  
250 33 return $self->_part_at(split /\./, $path);
251 }
252  
253 77 ▶sub _part_at {
Subroutine _part_at: called CC=11 SCAR=24.0
254 77 my $self = shift;
255 77 my @parts = @_;
256  
257 77 ▶ return $self unless @parts; # (cond ((null? l) s)
Branch: 1 branch
BranchTrueFalseTotal
unless @parts 17 60 77
258  
259 60 my $part_num = shift @parts; # (car l)
260  
261 60 ▶ if ($self->type =~ /^multipart\//) {
Branch: 2 branches
BranchTrueFalseTotal
if ($self->type =~ m[^multipart/]) { } 33 27 60
elsif ($self->type eq 'message/rfc822') { } 22 5 27
262 33 ▶ if (exists $self->{parts}->[$part_num - 1]) {
Branch: 1 branch
BranchTrueFalseTotal
if (exists $self->{'parts'}[$part_num - 1]) { } 27 6 33
263 27 return $self->{parts}->[$part_num - 1]->_part_at(@parts);
264 } else {
265 6 return;
266 }
267 } elsif ($self->type eq 'message/rfc822') {
268 22 ▶ return $self->{bodystructure} if $part_num eq 'TEXT';
Branch: 1 branch
BranchTrueFalseTotal
if $part_num eq "TEXT" 4 18 22
269  
270 18 ▶ if ($self->{bodystructure}->type =~ m{^ multipart/ | ^ message/rfc822 \z}xms) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'bodystructure'}->type =~ m[^ multipart/ | ^ message/rfc822 \z]msx) { } 12 6 18
271 12 return $self->{bodystructure}->_part_at($part_num, @parts);
272 } else {
273 6 ▶ return $part_num == 1 ? $self->{bodystructure}->_part_at(@parts) : undef;
Branch: 1 branch
BranchTrueFalseTotal
$part_num == 1 ? : 5 1 6
274 }
275 } else {
276 # there's no included parts in single non-rfc822 parts
277 # so if you still want one you get undef
278 5 ▶ if ($part_num && $part_num ne '1' || @parts) {
Branch: 1 branch
BranchTrueFalseTotal
if ($part_num and $part_num ne '1' or @parts) { } 3 2 5
Condition83%5/6
$part_num and $part_num ne 1 or @parts
l!l&&r!l&&!r
212
$part_num and $part_num ne 1
!ll&&!rl&&r
032
MC/DC66%2/3
$part_num and $part_num ne 1 or @parts
$part_num $part_num ne 1 @parts
Truth table60%3/5
A and B or C
A= $part_numB= $part_num ne 1C= @parts
ABCresult
11X1
0X11
1011
0X00
1000
279 3 return;
280 } else {
281 2 return $self;
282 }
283 }
284 }
285  
286 =item part_path()
287  
288 Returns the part path to the current part.
289  
290 =back
291  
292 =head2 DATA MEMBERS
293  
294 These are additional pieces of information returned by IMAP server and
295 parsed. They are rarely used, though (and rarely defined too, btw), so
296 I chose not to provide access methods for them.
297  
298 =over 4
299  
300 =item params
301  
302 This is a hashref of MIME parameters. The only interesting param is
303 charset and there's a shortcut method for it.
304  
305 =item lang
306  
307 Content language.
308  
309 =item loc
310  
311 Content location.
312  
313 =item cid
314  
315 Content ID.
316  
317 =item md5
318  
319 Content MD5. No one seems to bother with calculating and it is usually
320 undefined.
321  
322 =back
323  
324 B<cid> and B<md5> members exist only in singlepart parts.
325  
326 =cut
327  
328 0 ▶sub part_path {
Subroutine part_path: not called CC=1 SCAR=6.9
Pod documented
329 0 my $self = shift;
330  
331 0 return $self->{part_id};
332 }
333  
334 7 ▶sub _get_envelope($\$) {
Subroutine _get_envelope: called CC=1 SCAR=0.0
335 7 eval "$_[0]::Envelope->new(\$_[1])";
336 }
337  
338 66 ▶sub _get_bodystructure(\$;$$) {
Subroutine _get_bodystructure: called CC=10 SCAR=23.0
339 66 my $str = shift;
340 66 ▶ my $class = shift || __PACKAGE__;
Condition50%1/2
shift() || __PACKAGE__
l!l
660
MC/DC0%0/1
shift() || __PACKAGE__
shift()
Truth table50%1/2
A
A= shift()
Aresult
11
00
341 66 my $id = shift;
342  
343 66 my __PACKAGE__ $bs = fields::new($class);
344 66 ▶ $bs->{part_id} = $id || 1; # !defined $id --> top-level message
Condition100%2/2
$id || 1
l!l
5313
MC/DC100%1/1
$id || 1
$id
Truth table100%2/2
A
A= $id
Aresult
11
00
345 # and single-part has one part with part_id 1
346  
347 66 ▶ my $id_prefix = $id ? "$id." : '';
Branch: 1 branch
BranchTrueFalseTotal
$id ? : 53 13 66
348  
349 66 ▶ $$str =~ m/\G\s*(?:\(BODYSTRUCTURE\s*)?\(/gc
Branch: 1 branch
BranchTrueFalseTotal
$$str =~ /\G\s*(?:\(BODYSTRUCTURE\s*)?\(/cg or return 0 53 13 66
350 or return 0;
351  
352 53 $bs->{parts} = [];
353 53 ▶ if ($$str =~ /\G(?=\()/gc) {
Branch: 1 branch
BranchTrueFalseTotal
if ($$str =~ /\G(?=\()/cg) { } 13 40 53
354 # multipart
355 13 $bs->{type} = 'multipart/';
356 13 my $part_id = 1;
357 13 $id_prefix =~ s/\.?TEXT//;
358 13 ▶ while (my $part_bs = _get_bodystructure($$str, $class, $id_prefix . $part_id++)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $part_bs = &_get_bodystructure(\$$str, $class, $id_prefix . $part_id++)) 33 13 46
359 33 push @{$bs->{parts}}, $part_bs;
360 }
361  
362 13 $bs->{type} .= lc(_get_nstring($$str));
363 13 $bs->{params} = _get_npairs($$str);
364 13 $bs->{disp} = _get_ndisp($$str);
365 13 $bs->{lang} = _get_lang($$str);
366 13 $bs->{loc} = _get_nstring($$str);
367 } else {
368 40 $bs->{type} = lc (_get_nstring($$str) . '/' . _get_nstring($$str));
369 40 $bs->{params} = _get_npairs($$str);
370 40 $bs->{cid} = _get_nstring($$str);
371 40 $bs->{desc} = _get_nstring($$str);
372 40 $bs->{encoding} = _get_nstring($$str);
373 40 $bs->{size} = _get_nstring($$str);
374  
375 40 ▶ if ($bs->{type} eq 'message/rfc822') {
Branch: 2 branches
BranchTrueFalseTotal
if ($bs->{'type'} eq 'message/rfc822') { } 7 33 40
elsif ($bs->{'type'} =~ m[^text/]) { } 23 10 33
376 7 $bs->{envelope} = _get_envelope($class, $$str);
377 7 ▶ if ($id_prefix =~ s/\.?TEXT//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($id_prefix =~ s/\.?TEXT//) { } 1 6 7
378 1 $bs->{bodystructure} = _get_bodystructure($$str, $class, $id_prefix . '1');
379 } else {
380 6 $bs->{bodystructure} = _get_bodystructure($$str, $class, $id_prefix . 'TEXT');
381 }
382 7 $bs->{textlines} = _get_nstring($$str);
383 } elsif ($bs->{type} =~ /^text\//) {
384 23 $bs->{textlines} = _get_nstring($$str);
385 }
386  
387 40 $bs->{md5} = _get_nstring($$str);
388 40 $bs->{disp} = _get_ndisp($$str);
389 40 $bs->{lang} = _get_lang($$str);
390 40 $bs->{loc} = _get_nstring($$str);
391 }
392  
393 53 $$str =~ m/\G\s*\)/gc;
394  
395 53 return $bs;
396 }
397  
398 53 ▶sub _get_ndisp(\$) {
Subroutine _get_ndisp: called CC=3 SCAR=11.1
399 53 my $str = shift;
400  
401 53 $$str =~ /\G\s+/gc;
402  
403 53 ▶ if ($$str =~ /\GNIL/gc) {
Branch: 2 branches
BranchTrueFalseTotal
if ($$str =~ /\GNIL/cg) { } 23 30 53
elsif ($$str =~ /\G\s*\(/cg) { } 30 0 30
404 23 return undef;
405 } elsif ($$str =~ m/\G\s*\(/gc) {
406 30 my @disp;
407  
408 30 $disp[0] = _get_nstring($$str);
409 30 $disp[1] = _get_npairs($$str);
410  
411 30 $$str =~ m/\G\s*\)/gc;
412 30 return \@disp;
413 }
414
415 0 return 0;
416 }
417  
418 83 ▶sub _get_npairs(\$) {
Subroutine _get_npairs: called CC=4 SCAR=13.9
419 83 my $str = shift;
420  
421 83 $$str =~ /\G\s+/gc;
422  
423 83 ▶ if ($$str =~ /\GNIL/gc) {
Branch: 2 branches
BranchTrueFalseTotal
if ($$str =~ /\GNIL/cg) { } 27 56 83
elsif ($$str =~ /\G\s*\(/cg) { } 56 0 56
424 27 return undef;
425 } elsif ($$str =~ m/\G\s*\(/gc) {
426 56 my %r;
427 56 while ('fareva') {
428 114 my ($key, $data) = (_get_nstring($$str), _get_nstring($$str));
429 114 ▶ $key or last;
Branch: 1 branch
BranchTrueFalseTotal
$key or last 58 56 114
430  
431 58 $r{$key} = $data;
432 }
433  
434 56 $$str =~ m/\G\s*\)/gc;
435 56 return \%r;
436 }
437
438 0 return 0;
439 }
440  
441 791 ▶sub _get_nstring(\$) {
Subroutine _get_nstring: called CC=5 SCAR=16.1
442 791 my $str = $_[0];
443  
444 # nstring = string / nil
445 # nil = "NIL"
446 # string = quoted / literal
447 # quoted = DQUOTE *QUOTED-CHAR DQUOTE
448 # QUOTED-CHAR = <any TEXT-CHAR except quoted-specials> /
449 # "\" quoted-specials
450 # quoted-specials = DQUOTE / "\"
451 # literal = "{" number "}" CRLF *CHAR8
452 # ; Number represents the number of CHAR8s
453  
454 # astring = 1*(any CHAR except "(" / ")" / "{" / SP / CTL / list-wildcards / quoted-specials)
455  
456 791 $$str =~ /\G\s+/gc;
457  
458 791 ▶ if ($$str =~ /\GNIL/gc) {
Branch: 4 branches
BranchTrueFalseTotal
if ($$str =~ /\GNIL/cg) { } 206 585 791
elsif ($$str =~ /\G(\"(?>[^\\\"]*(?:\\.[^\\\"]*)*)\")/cg) { } 343 242 585
elsif ($$str =~ /\G\{(\d+)\}\r\n/cg) { } 5 237 242
elsif ($$str =~ /\G([^"\(\)\{ \%\*\"\\\x00-\x1F]+)/cg) { } 71 166 237
459 206 return undef;
460 } elsif ($$str =~ m/\G(\"(?>[^\\\"]*(?:\\.[^\\\"]*)*)\")/gc) { # delimited re ala Regexp::Common::delimited + (?>...)
461 343 return _unescape($1);
462 } elsif ($$str =~ /\G\{(\d+)\}\r\n/gc) {
463 5 my $pos = pos($$str);
464 5 my $data = substr $$str, $pos, $1;
465 5 pos($$str) = $pos + $1;
466 5 return $data;
467 } elsif ($$str =~ /\G([^"\(\)\{ \%\*\"\\\x00-\x1F]+)/gc) {
468 71 return $1;
469 }
470  
471 166 return 0;
472 }
473  
474 53 ▶sub _get_lang(\$) {
Subroutine _get_lang: called CC=4 SCAR=13.9
475 53 my $str = $_[0];
476  
477 # body-fld-lang = nstring / "(" string *(SP string) ")"
478  
479 53 ▶ if ($$str =~ m/\G\s*\(/gc) {
Branch: 1 branch
BranchTrueFalseTotal
if ($$str =~ /\G\s*\(/cg) 1 52 53
480 1 my @a;
481 1 while ('fareva') {
482 3 my $data = _get_nstring($$str);
483 3 ▶ $data or last;
Branch: 1 branch
BranchTrueFalseTotal
$data or last 2 1 3
484  
485 2 push @a, $data;
486 }
487  
488 1 $$str =~ m/\G\s*\)/gc;
489 1 return \@a;
490 }
491  
492 52 ▶ if (my $data = _get_nstring($$str)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $data = &_get_nstring(\$$str)) 1 51 52
493 1 return [$data];
494 }
495  
496 51 return [];
497 }
498  
499 343 ▶sub _unescape {
Subroutine _unescape: called CC=1 SCAR=0.0
500 343 my $str = shift;
501  
502 343 $str =~ s/^"//;
503 343 $str =~ s/"$//;
504 343 $str =~ s/\\\"/\"/g;
505 343 $str =~ s/\\\\/\\/g;
506  
507 343 return $str;
508 }
509  
510 =over 4
511  
512 =item get_enveleope($)
513  
514 Parses a string into IMAP::BodyStructure::Envelope object. See below.
515  
516 =back
517  
518 =head2 IMAP::BodyStructure::Envelope CLASS
519  
520 Every message on an IMAP server has an envelope. You can get it
521 using ENVELOPE fetch item or, and this is relevant, from BODYSTRUCTURE
522 response in case there are some nested messages (parts with type of
523 C<message/rfc822>). So, if we have a part with such a type then the
524 corresponding IMAP::BodyStructure object always has
525 B<envelope> data member which is, in turn, an object of
526 IMAP::BodyStructure::Envelope.
527  
528 You can of course use this satellite class on its own, this is very
529 useful when generating meaningful message lists in IMAP folders.
530  
531 =cut
532  
533 package IMAP::BodyStructure::Envelope;
534  
535 sub _get_nstring(\$); # proto
536  
537 2 *_get_nstring = \&IMAP::BodyStructure::_get_nstring;
538  
539 sub _get_naddrlist(\$);
540 sub _get_naddress(\$);
541  
542 2 ▶use vars qw/@envelope_addrs/;
Subroutine BEGIN: called CC=1 SCAR=0.0
543 2 @envelope_addrs = qw/from sender reply_to to cc bcc/;
544  
545 =head2 METHODS
546  
547 =over 4
548  
549 =item new($)
550  
551 The constructor create Envelope object from string which should be an
552 IMAP server respone to a fetch with ENVELOPE item or a substring of
553 BODYSTRUCTURE response for a message with message/rfc822 parts inside.
554  
555 =back
556  
557 =head2 DATA MEMBERS
558  
559 =over 4
560  
561 =item date
562  
563 Date of the message as specified in the envelope. Not the IMAP
564 INTERNALDATE, be careful!
565  
566 =item subject
567  
568 Subject of the message, may be RFC2047 encoded, of course.
569  
570 =item message_id
571  
572 =item in_reply_to
573  
574 Message-IDs of the current message and the message in reply to which
575 this one was composed.
576  
577 =item to, from, cc, bcc, sender, reply_to
578  
579 These are the so called address-lists or just arrays of addresses.
580 Remember, a message may be addressed to lots of people.
581  
582 Each address is a hash of four elements:
583  
584 =over 4
585  
586 =item name
587  
588 The informal part, "A.U.Thor" from "A.U.Thor, <a.u.thor@somewhere.com>"
589  
590 =item sroute
591  
592 Source-routing information, not used. (By the way, IMAP4r1 spec was
593 born after the last email address with sroute passed away.)
594  
595 =item account
596  
597 The part before @.
598  
599 =item host
600  
601 The part after @.
602  
603 =item full
604  
605 The full address for display purposes.
606  
607 =back
608  
609 =back
610  
611 =cut
612  
613 2 ▶use fields qw/from sender reply_to to cc bcc date subject in_reply_to message_id/;
Subroutine BEGIN: called CC=1 SCAR=0.0
614  
615 7 ▶sub new(\$) {
Subroutine new: called CC=3 SCAR=11.0
616 7 my $class = shift;
617 7 my $str = shift;
618
619 7 ▶ $$str =~ m/\G\s*(?:\(ENVELOPE)?\s*\(/gc
Branch: 1 branch
BranchTrueFalseTotal
$$str =~ /\G\s*(?:\(ENVELOPE)?\s*\(/cg or return 0 7 0 7
620 or return 0;
621  
622 7 my __PACKAGE__ $self = fields::new($class);
623  
624 7 $self->{'date'} = _get_nstring($$str);
625 7 $self->{'subject'} = _get_nstring($$str);
626  
627 7 foreach my $header (@envelope_addrs) {
628 42 $self->{$header} = _get_naddrlist($$str);
629 }
630  
631 7 $self->{'in_reply_to'} = _get_nstring($$str);
632 7 $self->{'message_id'} = _get_nstring($$str);
633  
634 7 $$str =~ m/\G\s*\)/gc;
635  
636 7 return $self;
637 }
638  
639 32 ▶sub _get_naddress(\$) {
Subroutine _get_naddress: called CC=5 SCAR=16.4
640 32 my $str = shift;
641  
642 32 ▶ if ($$str =~ /\GNIL/gc) {
Branch: 2 branches
BranchTrueFalseTotal
if ($$str =~ /\GNIL/cg) { } 0 32 32
elsif ($$str =~ /\G\s*\(/cg) { } 16 16 32
643 0 return undef;
644 } elsif ($$str =~ m/\G\s*\(/gc) {
645 16 my %addr = (
646 name => _get_nstring($$str),
647 sroute => _get_nstring($$str),
648 account => _get_nstring($$str),
649 host => _get_nstring($$str),
650 );
651 $addr{address} = ($addr{account}
652 16 ▶ ? "$addr{account}@" . ($addr{host} || '')
Branch: 1 branch
BranchTrueFalseTotal
$addr{'account'} ? : 16 0 16
Condition100%2/2
$addr{'host'} || ''
l!l
133
MC/DC100%1/1
$addr{'host'} || ''
$addr{'host'}
Truth table100%2/2
A
A= $addr{'host'}
Aresult
11
00
653 : '');
654  
655 16 $addr{full} = _format_address($addr{name}, $addr{address});
656  
657 16 $$str =~ m/\G\s*\)/gc;
658 16 return \%addr;
659 }
660 16 return 0;
661 }
662  
663 42 ▶sub _get_naddrlist(\$) {
Subroutine _get_naddrlist: called CC=4 SCAR=13.9
664 42 my $str = shift;
665
666 42 $$str =~ /\G\s+/gc;
667  
668 42 ▶ if ($$str =~ /\GNIL/gc) {
Branch: 2 branches
BranchTrueFalseTotal
if ($$str =~ /\GNIL/cg) { } 26 16 42
elsif ($$str =~ /\G\s*\(/cg) { } 16 0 16
669 26 return undef;
670 } elsif ($$str =~ m/\G\s*\(/gc) {
671 16 my @addrs = ();
672 16 ▶ while (my $addr = _get_naddress($$str)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $addr = &_get_naddress(\$$str)) 16 16 32
673 16 push @addrs, $addr;
674 }
675  
676 16 $$str =~ m/\G\s*\)/gc;
677 16 return \@addrs;
678 }
679 0 return 0;
680 }
681  
682 2 my $rfc2822_atext = q(a-zA-Z0-9!#$%&'*+/=?^_`{|}~-); # simple non-interpolating string (think apostrophs)
683 2 my $rfc2822_atom = qr/[$rfc2822_atext]+/; # straight from rfc2822
684  
685 2 ▶use constant EMPTY_STR => q{};
Subroutine BEGIN: called CC=1 SCAR=0.0
686 16 ▶sub _format_address {
Subroutine _format_address: called CC=7 SCAR=19.9
687 16 my ($phrase, $email) = @_;
688  
689 16 ▶ if (defined $phrase && $phrase ne EMPTY_STR) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $phrase and $phrase ne '') { } 13 3 16
Condition66%2/3
defined $phrase and $phrase ne ""
!ll&&!rl&&r
3013
MC/DC50%1/2
defined $phrase and $phrase ne ""
defined $phrase $phrase ne ""
Truth table66%2/3
A and B
A= defined $phraseB= $phrase ne ""
ABresult
0X0
100
111
690 13 ▶ if ($phrase !~ /^ \s* " [^"]+ " \s* \z/xms) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($phrase =~ /^ \s* " [^"]+ " \s* \z/msx) 13 0 13
691 # $phrase is not already quoted
692  
693 13 $phrase =~ s/ (["\\]) /\\$1/xmsg;
694  
695 13 ▶ if ($phrase !~ m/^ \s* $rfc2822_atom (?: \s+ $rfc2822_atom)* \s* \z/xms) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($phrase =~ /^ \s* $rfc2822_atom (?: \s+ $rfc2822_atom)* \s* \z/msx) 3 10 13
696 3 $phrase = qq{"$phrase"};
697 }
698 }
699  
700 13 ▶ return $email ? "$phrase <$email>" : $phrase;
Branch: 1 branch
BranchTrueFalseTotal
$email ? : 13 0 13
701 } else {
702 3 ▶ return $email || '';
Condition50%1/2
$email || ''
l!l
30
MC/DC0%0/1
$email || ''
$email
Truth table50%1/2
A
A= $email
Aresult
11
00
703 }
704 }
705  
706 2 1;
707  
708 __END__
↑ Summary