SPF/Mod.pm

filter: Statementstmt 78.5% 55 / 70 Branchbran 29.1% 7 / 24 Conditioncond 33.3% 1 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 76.4% 13 / 17 Podpod 16.6% 1 / 6 totaltotal 63.1% 77 / 122 CC 14 SCAR 15.4
CC
14
Cov
65%
parse_params
12.0
stringify
12.0
new
6.0
CRAP 4.7
« SPF/Record.pm ↑ Summary SPF/Exception.pm »
1 #
2 # Mail::SPF::Mod
3 # SPF record modifier class.
4 #
5 # (C) 2005-2012 Julian Mehnle <julian@mehnle.net>
6 # 2005 Shevek <cpan@anarres.org>
7 # $Id: Mod.pm 57 2012-01-30 08:15:31Z julian $
8 #
9 ##############################################################################
10  
11 package Mail::SPF::Mod;
12  
13 =head1 NAME
14  
15 Mail::SPF::Mod - SPF record modifier base class
16  
17 =head1 VERSION
18  
19 version 3.20261105
20  
21 =cut
22  
23 5 our $VERSION = '3.20261105'; # VERSION
24  
25 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
26 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
27  
28 5 ▶use utf8; # Hack to keep Perl 5.6 from whining about /[\p{}]/.
Subroutine BEGIN: called CC=1 SCAR=0.0
29  
30 5 ▶use base 'Mail::SPF::Term';
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 5 ▶use Mail::SPF::MacroString;
Subroutine BEGIN: called CC=1 SCAR=0.0
33  
34 5 ▶use constant TRUE => (0 == 0);
Subroutine BEGIN: called CC=1 SCAR=0.0
35 5 ▶use constant FALSE => not TRUE;
Subroutine BEGIN: called CC=1 SCAR=0.0
36  
37 5 ▶use constant name_pattern => qr/ ${\__PACKAGE__->SUPER::name_pattern} (?= = ) /x;
Subroutine BEGIN: called CC=1 SCAR=0.0
38  
39 =head1 DESCRIPTION
40  
41 An object of class B<Mail::SPF::Mod> represents a modifier within an SPF
42 record. Mail::SPF::Mod cannot be instantiated directly. Create an instance of
43 a concrete sub-class instead.
44  
45 =head2 Constructors
46  
47 The following constructors are provided:
48  
49 =over
50  
51 =item B<new(%options)>: returns I<Mail::SPF::Mod>
52  
53 I<Abstract>. Creates a new SPF record modifier object.
54  
55 %options is a list of key/value pairs representing any of the following
56 options:
57  
58 =over
59  
60 =item B<text>
61  
62 A I<string> denoting the unparsed text of the modifier.
63  
64 =item B<name>
65  
66 A I<string> denoting the name of the modifier. I<Required> if a generic
67 I<Mail::SPF::Mod> object (as opposed to a specific sub-class) is being
68 constructed.
69  
70 =item B<domain_spec>
71  
72 Either a plain I<string> or a I<Mail::SPF::MacroString> object denoting an
73 optional C<domain-spec> parameter of the mechanism.
74  
75 =back
76  
77 =cut
78  
79 6 ▶sub new {
Subroutine new: called CC=5 SCAR=17.8
Pod documented
80 6 my ($self, %options) = @_;
81 6 ▶ $self->class ne __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$self->class ne __PACKAGE__ or "Mail::SPF::EAbstractClass"->throw 6 0 6
82 or throw Mail::SPF::EAbstractClass;
83 6 $self = $self->SUPER::new(%options);
84 6 ▶ $self->{parse_text} = $self->{text} if not defined($self->{parse_text});
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->{"parse_text"} 6 0 6
85 $self->{domain_spec} = Mail::SPF::MacroString->new(text => $self->{domain_spec})
86 if defined($self->{domain_spec})
87 6 ▶ and not UNIVERSAL::isa($self->{domain_spec}, 'Mail::SPF::MacroString');
Branch: 1 branch
BranchTrueFalseTotal
if defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString") 0 6 6
Condition33%1/3
defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
!ll&&!rl&&r
600
MC/DC0%0/2
defined $self->{"domain_spec"} and not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
defined $self->{"domain_spec"} not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
Truth table33%1/3
A and not(B)
A= defined $self->{"domain_spec"}B= not UNIVERSAL::isa($self->{"domain_spec"}, "Mail::SPF::MacroString")
ABresult
0X0
100
111
88 6 return $self;
89 }
90  
91 =item B<new_from_string($text, %options)>: returns I<Mail::SPF::Mod>;
92 throws I<Mail::SPF::ENothingToParse>, I<Mail::SPF::EInvalidMod>
93  
94 I<Abstract>. Creates a new SPF record modifier object by parsing the string and
95 any options given.
96  
97 =back
98  
99 =head2 Class methods
100  
101 The following class methods are provided:
102  
103 =over
104  
105 =item B<name_pattern>: returns I<Regexp>
106  
107 Returns a regular expression that matches any legal modifier name.
108  
109 =back
110  
111 =head2 Instance methods
112  
113 The following instance methods are provided:
114  
115 =over
116  
117 =cut
118  
119 6 ▶sub parse {
Subroutine parse: called CC=2 SCAR=7.0
Pod undocumented
120 6 my ($self) = @_;
121 defined($self->{parse_text})
122 6 ▶ or throw Mail::SPF::ENothingToParse('Nothing to parse for modifier');
Branch: 1 branch
BranchTrueFalseTotal
defined $self->{"parse_text"} or "Mail::SPF::ENothingToParse"->throw("Nothing to parse for modifier") 6 0 6
123 6 $self->parse_name();
124 6 $self->parse_params(TRUE);
125 6 $self->parse_end();
126 6 return;
127 }
128  
129 6 ▶sub parse_name {
Subroutine parse_name: called CC=2 SCAR=7.2
Pod undocumented
130 6 my ($self) = @_;
131 6 ▶ if ($self->{parse_text} =~ s/^(${\$self->name_pattern})=//) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{'parse_text'} =~ s/^(${\$self->name_pattern;})=//) { } 6 0 6
132 6 $self->{name} = $1;
133 }
134 else {
135 0 throw Mail::SPF::EInvalidMod(
136 "Unexpected modifier name encountered in '" . $self->text . "'");
137 }
138 6 return;
139 }
140  
141 0 ▶sub parse_params {
Subroutine parse_params: not called CC=3 SCAR=24.8
Pod undocumented
142 0 my ($self, $required) = @_;
143 # Parse generic macro string of parameters text (should be overridden in sub-classes):
144 0 ▶ if ($self->{parse_text} =~ s/^(${\$self->macro_string_pattern})$//) {
Branch: 2 branches
BranchTrueFalseTotal
if ($self->{'parse_text'} =~ s/^(${\$self->macro_string_pattern;})$//) { } 0 0 0
elsif ($required) { } 0 0 0
145 0 $self->{params_text} = $1;
146 }
147 elsif ($required) {
148 0 throw Mail::SPF::EInvalidMacroString(
149 "Invalid macro string encountered in '" . $self->text . "'");
150 }
151 0 return;
152 }
153  
154 6 ▶sub parse_end {
Subroutine parse_end: called CC=2 SCAR=7.0
Pod undocumented
155 6 my ($self) = @_;
156 6 ▶ $self->{parse_text} eq ''
Branch: 1 branch
BranchTrueFalseTotal
$self->{"parse_text"} eq "" or "Mail::SPF::EJunkInTerm"->throw(q[Junk encountered in modifier '] . $self->text . q[']) 6 0 6
157 or throw Mail::SPF::EJunkInTerm("Junk encountered in modifier '" . $self->text . "'");
158 6 delete($self->{parse_text});
159 6 return;
160 }
161  
162 =item B<text>: returns I<string>; throws I<Mail::SPF::ENoUnparsedText>
163  
164 Returns the unparsed text of the modifier. Throws a
165 I<Mail::SPF::ENoUnparsedText> exception if the modifier was created
166 synthetically instead of being parsed, and no text was provided.
167  
168 =item B<name>: returns I<string>
169  
170 Returns the name of the modifier.
171  
172 =cut
173  
174 # Read-only accessor:
175 5 __PACKAGE__->make_accessor('name', TRUE);
176  
177 =item B<params>: returns I<string>
178  
179 I<Abstract>. Returns the modifier's parameters formatted as a string.
180  
181 A sub-class of Mail::SPF::Mod does not have to implement this method if it
182 supports no parameters, although this is highly unlikely.
183  
184 =item B<stringify>: returns I<string>
185  
186 Formats the modifier's name and parameters as a string and returns it. You can
187 simply use a Mail::SPF::Mod object as a string for the same effect, see
188 L<"OVERLOADING">.
189  
190 =cut
191  
192 0 ▶sub stringify {
Subroutine stringify: not called CC=3 SCAR=24.8
Pod undocumented
193 0 my ($self) = @_;
194 0 ▶ my $params = $self->can('params') ? $self->params : undef;
Branch: 1 branch
BranchTrueFalseTotal
$self->can('params') ? : 0 0 0
195 0 ▶ return sprintf(
Branch: 1 branch
BranchTrueFalseTotal
defined $params ? : 0 0 0
196 '%s=%s',
197 $self->name,
198 defined($params) ? $params : ''
199 );
200 }
201  
202 =item B<process>: throws I<Mail::SPF::Result>, I<Mail::SPF::Result::Error>,
203 I<Mail::SPF::Exception>
204  
205 I<Abstract>. Processes the modifier. What that means depends on the actual
206 implementation in sub-classes. See L</MODIFIER TYPES> below.
207  
208 This method is abstract and must be implemented by sub-classes of
209 Mail::SPF::Mod.
210  
211 =back
212  
213 =head1 MODIFIER TYPES
214  
215 There are different basic types of modifiers, which are described below. All
216 of them are provided by the B<Mail::SPF::Mod> module.
217  
218 =head2 Global modifiers - B<Mail::SPF::GlobalMod>
219  
220 B<SPFv1> (RFC 4408) only knows "global" modifiers. A global modifier may
221 appear anywhere in an SPF record, but only once. During evaluation of the
222 record, global modifiers are processed after the last mechanism has been
223 evaluated and an SPF result has been determined.
224  
225 =cut
226  
227 package Mail::SPF::GlobalMod;
228 5 our @ISA = 'Mail::SPF::Mod';
229  
230 6 ▶sub new {
Subroutine new: called CC=2 SCAR=7.1
231 6 my ($self, %options) = @_;
232 6 ▶ $self->class ne __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$self->class ne __PACKAGE__ or "Mail::SPF::EAbstractClass"->throw 6 0 6
233 or throw Mail::SPF::EAbstractClass;
234 6 return $self->SUPER::new(%options);
235 }
236  
237 =pod
238  
239 The following additional class method is provided by B<Mail::SPF::GlobalMod>:
240  
241 =over
242  
243 =item B<precedence>: returns I<real>
244  
245 I<Abstract>. Returns a I<real> number between B<0> and B<1> denoting the
246 precedence of the type of the global modifier. Global modifiers present in an
247 SPF record are processed in the order of their precedence values, B<0> meaning
248 "first".
249  
250 This method is abstract and must be implemented by sub-classes of
251 Mail::SPF::GlobalMod.
252  
253 =back
254  
255 The following specific instance method is provided by B<Mail::SPF::GlobalMod>:
256  
257 =over
258  
259 =item B<process($server, $request, $result)>: throws I<Mail::SPF::Result>
260  
261 I<Abstract>. Processes the modifier. What that means depends on the actual
262 implementation in sub-classes. Takes both a I<Mail::SPF::Server> and a
263 I<Mail::SPF::Request> object. As global modifiers are generally processed
264 I<after> an SPF result has already been determined, takes also the current
265 I<Mail::SPF::Result>. If the modifier wishes to modify the SPF result, it may
266 throw a different I<Mail::SPF::Result> object.
267  
268 This method is abstract and must be implemented by sub-classes of
269 Mail::SPF::GlobalMod.
270  
271 =back
272  
273 =head2 Positional modifiers - B<Mail::SPF::PositionalMod>
274  
275 B<Sender ID> (RFC 4406) introduces the concept of "positional" modifiers.
276 According to RFC 4406, a positional modifier must follow a mechanism and
277 applies to that, and only that, mechanism. However, because this definition is
278 not very useful, and because no positional modifiers have been defined based on
279 it as of yet, B<Mail::SPF> deviates from RFC 4406 as follows:
280  
281 A positional modifier may appear anywhere in an SPF record, and it is stateful,
282 i.e. it applies to all mechanisms and modifiers that follow it. Positional
283 modifiers are generally multiple, i.e. they may appear any number of times
284 throughout the record. During evaluation of the record, positional modifiers
285 are processed at exactly the time when they are encountered by the evaluator.
286 Consequently, all positional modifiers are processed before an SPF result is
287 determined.
288  
289 =cut
290  
291 package Mail::SPF::PositionalMod;
292 5 our @ISA = 'Mail::SPF::Mod';
293  
294 0 ▶sub new {
Subroutine new: not called CC=2 SCAR=17.9
295 0 my ($self, %options) = @_;
296 0 ▶ $self->class ne __PACKAGE__
Branch: 1 branch
BranchTrueFalseTotal
$self->class ne __PACKAGE__ or "Mail::SPF::EAbstractClass"->throw 0 0 0
297 or throw Mail::SPF::EAbstractClass;
298 0 return $self->SUPER::new(%options);
299 }
300  
301 =pod
302  
303 The following specific instance method is provided by
304 B<Mail::SPF::PositionalMod>:
305  
306 =over
307  
308 =item B<process($server, $request)>: throws I<Mail::SPF::Result::Error>, I<Mail::SPF::Exception>
309  
310 I<Abstract>. Processes the modifier. What that means depends on the actual
311 implementation in sub-classes. Takes both a I<Mail::SPF::Server> and a
312 I<Mail::SPF::Request> object. As global modifiers are generally processed
313 I<before> an SPF result has been determined, no result object is available to
314 the modifier. The modifier can (at least at this time) not directly modify the
315 final SPF result, however it may throw an exception to signal an error
316 condition.
317  
318 This method is abstract and must be implemented by sub-classes of
319 Mail::SPF::PositionalMod.
320  
321 =back
322  
323 =head2 Unknown modifiers - B<Mail::SPF::UnknownMod>
324  
325 Both B<SPFv1> and B<Sender ID> allow unknown modifiers to appear in SPF records
326 in order to allow new modifiers to be introduced without breaking existing
327 implementations. Obviously, unknown modifiers are neither global nor
328 positional, but they may appear any number of times throughout the record and
329 are simply ignored during evaluation of the record.
330  
331 =cut
332  
333 package Mail::SPF::UnknownMod;
334 5 our @ISA = 'Mail::SPF::Mod';
335  
336 =pod
337  
338 Also obviously, B<Mail::SPF::UnknownMod> does not support a C<process> method.
339  
340 The following specific instance method is provided by
341 B<Mail::SPF::UnknownMod>:
342  
343 =over
344  
345 =item B<params>: returns I<string>
346  
347 Returns the modifier's unparsed value as a string.
348  
349 =cut
350  
351 0 ▶sub params {
Subroutine params: not called CC=1 SCAR=6.9
352 0 my ($self) = @_;
353 0 return $self->{params_text};
354 }
355  
356 =back
357  
358 =cut
359  
360 package Mail::SPF::Mod;
361  
362 =head1 OVERLOADING
363  
364 If a Mail::SPF::Mod object is used as a I<string>, the C<stringify> method is
365 used to convert the object into a string.
366  
367 =head1 SEE ALSO
368  
369 L<Mail::SPF::Mod::Redirect>, L<Mail::SPF::Mod::Exp>
370  
371 L<Mail::SPF>, L<Mail::SPF::Record>, L<Mail::SPF::Term>
372  
373 L<http://tools.ietf.org/html/rfc4408>
374  
375 For availability, support, and license information, see the README file
376 included with Mail::SPF.
377  
378 =head1 AUTHORS
379  
380 Julian Mehnle <julian@mehnle.net>, Shevek <cpan@anarres.org>
381  
382 =cut
383  
384 5 TRUE;
« SPF/Record.pm ↑ Summary SPF/Exception.pm »