SPF/Mod.pm

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