MHonArc/RFC822.pm untested

filter: Statementstmt 0.0% 0 / 106 Branchbran 0.0% 0 / 60 Conditioncond 0.0% 0 / 12 MC/DCmcdc 0.0% 0 / 8 Subroutinesub 0.0% 0 / 8 Podpod 0.0% 0 / 5 totaltotal 0.0% 0 / 199 CC 31 SCAR 46.7
CC
31
Cov
0%
first_route_addr
182.0
tokenise
132.0
first_addr_spec
30.0
CRAP 106.5
1 ##---------------------------------------------------------------------------##
2 ## File:
3 ## $Id: RFC822.pm,v 1.4 2011/01/02 08:42:32 ehood Exp $
4 ## Author:
5 ## Earl Hood earl@earlhood.com
6 ## Module adapted to Perl 5 from Perl 4 library:
7 ## rfc822.pl -- A perl package to manipulate RFC822 mail headers
8 ## A. P. Barrett <barrett@ee.und.ac.za>, June 1993
9 ## Revision: 1.1 Date: 1993/06/28 11:28:18
10 ##
11 ## Description:
12 ## Module to handle parsing of RFC 822 mail header strings.
13 ##---------------------------------------------------------------------------##
14 ## Copyright (C) 1993 A. P. Barrett
15 ## Copyright (C) 1997,2003 Earl Hood, earl@earlhood.com
16 ##
17 ## This program is free software; you can redistribute it and/or modify
18 ## it under the terms of the GNU General Public License as published by
19 ## the Free Software Foundation; either version 2 of the License, or
20 ## (at your option) any later version.
21 ##
22 ## This program is distributed in the hope that it will be useful,
23 ## but WITHOUT ANY WARRANTY; without even the implied warranty of
24 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
25 ## GNU General Public License for more details.
26 ##
27 ## You should have received a copy of the GNU General Public License
28 ## along with this program; if not, write to the Free Software
29 ## Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
30 ## 02111-1307, USA
31 ##---------------------------------------------------------------------------##
32  
33 package MHonArc::RFC822;
34  
35 use strict;
36 use Exporter ();
37 use vars qw( @ISA @EXPORT @EXPORT_OK $VERSION );
38  
39 @ISA = qw ( Exporter );
40 $VERSION = '2.6.24';
41  
42 @EXPORT = ();
43 @EXPORT_OK = qw(
44 &tokenise
45 &untokenise
46 &uncomment
47 &first_route_addr
48 &first_addr_spec
49 );
50  
51 ##---------------------------------------------------------------------------##
52 ## Synopsis:
53 ## use MHonArc::RFC822;
54 ##
55 ## # sample input
56 ## $string = 'Joe (Random) User <@route:"j.r.l"@host.com>';
57 ##
58 ##---------------------------------------------------------------------------##
59 ## @toks = MHonArc::RFC822::tokenise($string);
60 ##
61 ## Convert string to tokens.
62 ## In an array context, returns:
63 ## ('Joe', '(Random)', 'User', '<', '@', 'route', ':',
64 ## '"j.r.l"', '@', 'host', '.', 'com', '>')
65 ## Not intended for use in a scalar context, but would return:
66 ## 'Joe(Random)User<@route:"j.r.l"@host.com>'
67 ##
68 ##---------------------------------------------------------------------------##
69 ## $newstring = MHonArc::RFC822::untokenise(@toks);
70 ##
71 ## Convert tokens to string with minimum white space.
72 ## Not intended for use in an array context.
73 ## In a scalar context, returns:
74 ## 'Joe(Random)User<@route:"j.r.l"@host.com>'
75 ##
76 ##---------------------------------------------------------------------------##
77 ## @newtoks = MHonArc::RFC822::uncomment($string);
78 ## @newtoks = MHonArc::RFC822::uncomment(@toks);
79 ## $newstring = MHonArc::RFC822::uncomment($string);
80 ## $newstring = MHonArc::RFC822::uncomment(@toks);
81 ##
82 ## Remove comments.
83 ## In an array context, returns:
84 ## ('Joe', 'User', '<', '@', 'route', ':',
85 ## '"j.r.l"', '@', 'host', '.', 'com', '>')
86 ## In a scalar context, returns:
87 ## 'Joe User<@route:"j.r.l"@host.com>'
88 ##
89 ##---------------------------------------------------------------------------##
90 ## @newtoks = MHonArc::RFC822::first_route_addr($string);
91 ## @newtoks = MHonArc::RFC822::first_route_addr(@toks);
92 ## $newstring = MHonArc::RFC822::first_route_addr($string);
93 ## $newstring = MHonArc::RFC822::first_route_addr(@toks);
94 ##
95 ## Obtain first route-addr or addr-spec.
96 ##
97 ## In an array context, returns:
98 ## ('<', '@', 'route', ':',
99 ## '"j.r.l"', '@', 'host', '.', 'com', '>')
100 ## In a scalar context, returns:
101 ## '<@route:"j.r.l"@host.com>'
102 ##
103 ##---------------------------------------------------------------------------##
104 ## @newtoks = MHonArc::RFC822::first_addr_spec($string);
105 ## @newtoks = MHonArc::RFC822::first_addr_spec(@toks);
106 ## $newstring = MHonArc::RFC822::first_addr_spec($string);
107 ## $newstring = MHonArc::RFC822::first_addr_spec(@toks);
108 ##
109 ## Obtain first addr-spec.
110 ## In an array context, returns:
111 ## ('"j.r.l"', '@', 'host', '.', 'com')
112 ## In a scalar context, returns:
113 ## '"j.r.l"@host.com'
114 ##---------------------------------------------------------------------------##
115  
116 ## Define some variables to help us write regexps.
117 my $self_delimiters = '<>@,;:.'; # use /[$self_delimiters]/
118 my $specials = $self_delimiters . '()\\\\"\\[\\]'; # use /[$specials]/
119 my $quoted_pair = '\\\\.'; # use /$quoted_pair/
120 my $qp_or_bs_end = $quoted_pair . '|\\\\$'; # use /$qp_or_bs_end/
121  
122 ##---------------------------------------------------------------------------##
123 ## Tokenise, per RFC 822.
124 ##
125 ## As an extension, allows atoms to contain quoted pairs.
126 ## The last output token might contain an unterminated quoted pair,
127 ## comment, domain literal or quoted string.
128 ## Other output tokens might contain solitary unmatched special characters.
129 ##
130 ## Input is a single string.
131 ## In an array context, output is a list of tokens.
132 ## In a scalar context, output is a single string (not very useful).
133  
134 sub tokenise {
135 local $_ = shift;
136 my (@outtoks);
137 my ($firstchar);
138 my ($comment, $comment_depth);
139  
140 while (s/^\s*(\S)/$firstchar = $1/e) {
141 if ($firstchar =~ /[$self_delimiters]/o) {
142 # a special character as a self-delimiting token.
143 s/^(.)//;
144 push(@outtoks, $1);
145 } elsif ($firstchar eq '"') {
146 # a quoted string.
147 # XXX we don't prohibit bare CR.
148 s/^(\"(?:$qp_or_bs_end|[^\\"])*(?:\"|\Z))//o;
149 push(@outtoks, $1);
150 } elsif ($firstchar eq '[') {
151 # a domain literal.
152 # XXX we don't prohibit bare CR or '['.
153 s/^(\[(?:$qp_or_bs_end|[^\\\]])*(?:\]|$))//o;
154 push(@outtoks, $1);
155 } elsif ($firstchar eq '(') {
156 # a comment.
157 do {
158 s/^(([^()]*)([()]|$))//;
159 $comment .= $1;
160 if ($3 eq '') {
161 # XXX error recovery for unterminated comment
162 warn "Unterminated comment: $comment\n";
163 $comment_depth = 0;
164 } elsif (substr($2, -1, 1) eq '\\') {
165 # quoted comment delim, ignore
166 } elsif ($3 eq '(') {
167 ++$comment_depth;
168 } elsif ($3 eq ')') {
169 --$comment_depth;
170 } else {
171 # Should not get here
172 warn "Internal error: expecting (' or ')' but got: $3\n";
173 $comment_depth = 0;
174 }
175 } until ($comment_depth == 0);
176 push(@outtoks, $comment);
177 } elsif ($firstchar ne '\\' && $firstchar =~ /[$specials]/o) {
178 # an illegal special character.
179 s/^(.)//;
180 push(@outtoks, $1);
181 } else {
182 # should be an atom, which is not allowed to contain
183 # special characters or control characters.
184 # we have already checked for all special chars except
185 # controls and backslash.
186 # XXX we don't check for controls.
187 # XXX we allow a quoted-pair as part of an atom.
188 s/^(($qp_or_bs_end|[^\s$specials])+)//o;
189 push(@outtoks, $1);
190 }
191 }
192  
193 # return result
194 wantarray ? @outtoks : &untokenise(@outtoks);
195 }
196  
197 ##---------------------------------------------------------------------------##
198 ## Convert a list of tokens to a single string.
199 ##
200 ## Just pastes the tokens together, with blanks where they are essential.
201 ##
202 ## Input is a list of tokens.
203 ## Output is a single string.
204  
205 sub untokenise {
206 my ($token, $prevtok);
207 my ($prev, $this);
208 my $result = '';
209  
210 foreach $token (@_) {
211 # Do we need a space?
212 # A space is essential when both the left and right tokens
213 # are either atoms or quoted strings.
214 # XXX - Spaces are desirable in some other places, but for
215 # now it's too difficult to worry about that. It's
216 # context-dependent anyway -- for example, we sometimes
217 # want spaces after ':' and ',', but not when they appear
218 # inside a route-addr. The tokener has no business knowing
219 # about such details.
220 if ($result ne '') {
221 $prev = substr($prevtok, $[, 1);
222 $this = substr($token, $[, 1);
223 if ( ($this eq '"' || $this !~ /[$specials]/o)
224 && ($prev eq '"' || $prev !~ /[$specials]/o)) {
225 $result .= ' ';
226 }
227 }
228 $result .= $token;
229 $prevtok = $token;
230 }
231  
232 # return result
233 $result;
234 }
235  
236 ##---------------------------------------------------------------------------##
237 ## Delete comments.
238 ##
239 ## Input can be a single string or a list of tokens.
240 ## In an array context, output is a list of tokens.
241 ## In a scalar context, output is a single string.
242  
243 sub uncomment {
244 my (@intoks) = @_;
245 my (@outtoks);
246 my ($token);
247  
248 # tokenise the input if we were given a single string
249 @intoks = &tokenise($intoks[$[]) if $#intoks le $[;
250  
251 # delete comment tokens
252 @outtoks = grep (/^[^(]/, @intoks);
253  
254 # return result
255 wantarray ? @outtoks : &untokenise(@outtoks);
256 }
257  
258 ##---------------------------------------------------------------------------##
259 ## Try to extract a single RFC-822 route-addr or addr-spec from a
260 ## list of addresses.
261 ##
262 ## Returns the first route-addr or addr-spec if there are several
263 ## (for example, if the input is a comma-separated list)..
264 ## Garbage in, garbage out.
265 ##
266 ## Input can be a single string or a list of tokens.
267 ## In an array context, output is a list of tokens.
268 ## In a scalar context, output is a single string.
269  
270 sub first_route_addr {
271 my (@intoks) = @_;
272 my (@outtoks);
273 my ($token, $firstchar);
274 my ($state) = 'start';
275  
276 # tokenise the input if we were given a single string
277 @intoks = &tokenise($intoks[$[]) if $#intoks le $[;
278  
279 foreach $token (@intoks) {
280 $firstchar = substr($token, 0, 1);
281 if ($firstchar eq '(') {
282 # ignore comments
283 next;
284 } elsif ($firstchar eq '<') {
285 # '<' is start of route-addr.
286 # discard what came before.
287 $state = 'routeaddr';
288 @outtoks = ($token);
289 } elsif ($firstchar eq ':') {
290 # ':' might be end of phrase for a group,
291 # or might be end of route and start of addr-spec in route-addr.
292 if ($state eq 'routeaddr') {
293 push(@outtoks, $token);
294 } else {
295 $state = 'start';
296 @outtoks = ();
297 }
298 } elsif ($firstchar eq ',') {
299 # ',' might be a separator between addresses
300 # or might be part of a route inside a route-addr.
301 if ($state eq 'routeaddr') {
302 push(@outtoks, $token);
303 } else {
304 $state = 'start';
305 last if $#outtoks ge $[; # we got what we wanted
306 }
307 } elsif ($firstchar eq '>') {
308 # '>' is end of route-addr
309 push(@outtoks, $token);
310 $state = 'end';
311 last; # we got what we wanted
312 } elsif ($firstchar eq ';') {
313 # ';' is end of group
314 $state = 'end';
315 last if $#outtoks ge $[; # we got what we wanted
316 } else {
317 # accumulate valid tokens.
318 push(@outtoks, $token);
319 }
320 }
321  
322 # return result
323 wantarray ? @outtoks : &untokenise(@outtoks);
324 }
325  
326 ##---------------------------------------------------------------------------##
327 ## Try to extract a single RFC-822 addr-spec from a list of addresses.
328 ##
329 ## Returns the first addr-spec if there are several.
330 ## Garbage in, garbage out.
331 ##
332 ## Input can be a single string or a list of tokens.
333 ## In an array context, output is a list of tokens.
334 ## In a scalar context, output is a single string.
335  
336 sub first_addr_spec {
337 my (@intoks) = @_;
338 my ($token);
339 my ($i, $startpos, $endpos);
340  
341 # Get the first route-addr or addr-spec
342 @intoks = &first_route_addr(@intoks);
343  
344 # if starts with '<' then it was a route-addr.
345 # Keep the stuff between the last ':' (if any) and the first '>'.
346 if ($intoks[$[] eq '<') {
347 $startpos = $[ + 1; # skip the initial '<'
348 $endpos = $#intoks; # don't yet know if there is a final '>'
349 foreach $i ($startpos .. $endpos) {
350 $token = $intoks[$i];
351 if ($token eq '>') {
352 $endpos = $i - 1;
353 last;
354 } elsif ($token eq ':') {
355 $startpos = $i + 1;
356 }
357 }
358 }
359 # if it didn't start with '<' then it was an addr-spec
360 else {
361 $startpos = $[;
362 $endpos = $#intoks;
363 }
364  
365 # return result
366 wantarray
367 ? @intoks[$startpos .. $endpos]
368 : &untokenise(@intoks[$startpos .. $endpos]);
369 }
370  
371 ##---------------------------------------------------------------------------##
372 1;