.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Mail::SPF::Record 3" .TH Mail::SPF::Record 3 2024-09-01 "perl v5.40.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME Mail::SPF::Record \- Abstract base class for SPF records .SH VERSION .IX Header "VERSION" version 3.20240827 .SH SYNOPSIS .IX Header "SYNOPSIS" .SS "Creating a record from a string" .IX Subsection "Creating a record from a string" .Vb 1 \& use Mail::SPF::v1::Record; \& \& my $record = Mail::SPF::v1::Record\->new_from_string("v=spf1 a mx \-all"); .Ve .SS "Creating a record synthetically" .IX Subsection "Creating a record synthetically" .Vb 1 \& use Mail::SPF::v2::Record; \& \& my $record = Mail::SPF::v2::Record\->new( \& scopes => [\*(Aqmfrom\*(Aq, \*(Aqpra\*(Aq], \& terms => [ \& Mail::SPF::Mech::A\->new(), \& Mail::SPF::Mech::MX\->new(), \& Mail::SPF::Mech::All\->new(qualifier => \*(Aq\-\*(Aq) \& ], \& global_mods => [ \& Mail::SPF::Mod::Exp\->new(domain_spec => \*(Aqspf\-exp.example.com\*(Aq) \& ] \& ); .Ve .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBMail::SPF::Record\fR is an abstract base class for SPF records. It cannot be instantiated directly. Create an instance of a concrete sub-class instead. .SS Constructor .IX Subsection "Constructor" The following constructors are provided: .IP "\fBnew(%options)\fR: returns \fIMail::SPF::Record\fR" 4 .IX Item "new(%options): returns Mail::SPF::Record" Creates a new SPF record object. .Sp \&\f(CW%options\fR is a list of key/value pairs representing any of the following options: .RS 4 .IP \fBtext\fR 4 .IX Item "text" A \fIstring\fR denoting the unparsed text of the record. .IP \fBscopes\fR 4 .IX Item "scopes" A reference to an \fIarray\fR of \fIstring\fRs denoting the scopes that are covered by the record (see the description of the \f(CW\*(C`scope\*(C'\fR option of Mail::SPF::Request's \f(CW\*(C`new\*(C'\fR constructor). .IP \fBterms\fR 4 .IX Item "terms" A reference to an \fIarray\fR of \fIMail::SPF::Term\fR (i.e. \fIMail::SPF::Mech\fR or \&\fIMail::SPF::Mod\fR) objects that make up the record. \fIMail::SPF::GlobalMod\fR objects must not be included here, but should be specified using the \&\f(CW\*(C`global_mods\*(C'\fR option instead. .IP \fBglobal_mods\fR 4 .IX Item "global_mods" A reference to an \fIarray\fR of \fIMail::SPF::GlobalMod\fR objects that are global modifiers of the record. .RE .RS 4 .RE .ie n .IP "\fBnew_from_string($text, \fR\fB%options\fR\fB)\fR: returns \fIMail::SPF::Record\fR; throws \fIMail::SPF::ENothingToParse\fR, \fIMail::SPF::EInvalidRecordVersion\fR, \fIMail::SPF::ESyntaxError\fR" 4 .el .IP "\fBnew_from_string($text, \fR\f(CB%options\fR\fB)\fR: returns \fIMail::SPF::Record\fR; throws \fIMail::SPF::ENothingToParse\fR, \fIMail::SPF::EInvalidRecordVersion\fR, \fIMail::SPF::ESyntaxError\fR" 4 .IX Item "new_from_string($text, %options): returns Mail::SPF::Record; throws Mail::SPF::ENothingToParse, Mail::SPF::EInvalidRecordVersion, Mail::SPF::ESyntaxError" Creates a new SPF record object by parsing the string and any options given. .SS "Class methods" .IX Subsection "Class methods" The following class methods are provided: .IP "\fBversion_tag_pattern\fR: returns \fIRegexp\fR" 4 .IX Item "version_tag_pattern: returns Regexp" \&\fIAbstract\fR. Returns a regular expression that matches a legal version tag. .Sp This method is abstract and must be implemented by sub-classes of Mail::SPF::Record. .IP "\fBdefault_qualifier\fR: returns \fIstring\fR" 4 .IX Item "default_qualifier: returns string" Returns the default qualifier, i.e. \fB'+'\fR. .IP "\fBresults_by_qualifier\fR: returns \fIhash\fR of \fIstring\fR" 4 .IX Item "results_by_qualifier: returns hash of string" Returns a reference to a hash that maps qualifiers to result codes as follows: .Sp .Vb 6 \& Qualifier | Result code \& \-\-\-\-\-\-\-\-\-\-\-+\-\-\-\-\-\-\-\-\-\-\-\-\- \& + | pass \& \- | fail \& ~ | softfail \& ? | neutral .Ve .SS "Instance methods" .IX Subsection "Instance methods" The following instance methods are provided: .IP "\fBtext\fR: returns \fIstring\fR; throws \fIMail::SPF::ENoUnparsedText\fR" 4 .IX Item "text: returns string; throws Mail::SPF::ENoUnparsedText" Returns the unparsed text of the record. Throws a \fIMail::SPF::ENoUnparsedText\fR exception if the record was created synthetically instead of being parsed, and no text was provided. .IP "\fBversion_tag\fR: returns \fIstring\fR" 4 .IX Item "version_tag: returns string" \&\fIAbstract\fR. Returns the version tag of the record. .Sp This method is abstract and must be implemented by sub-classes of Mail::SPF::Record. .IP "\fBscopes\fR: returns \fIlist\fR of \fIstring\fR" 4 .IX Item "scopes: returns list of string" Returns a list of the scopes that are covered by the record. See the description of the "new" constructor's \f(CW\*(C`scopes\*(C'\fR option. .IP "\fBterms\fR: returns \fIlist\fR of \fIMail::SPF::Term\fR" 4 .IX Item "terms: returns list of Mail::SPF::Term" Returns a list of the terms that make up the record, excluding any global modifiers, which are returned by the \f(CW\*(C`global_mods\*(C'\fR method. See the description of the "new" constructor's \f(CW\*(C`terms\*(C'\fR option. .IP "\fBglobal_mods\fR: returns \fIlist\fR of \fIMail::SPF::GlobalMod\fR" 4 .IX Item "global_mods: returns list of Mail::SPF::GlobalMod" Returns a list of the global modifiers of the record, ordered ascending by modifier precedence. See the description of the "new" constructor's \&\f(CW\*(C`global_mods\*(C'\fR option. .IP "\fBglobal_mod($mod_name)\fR: returns \fIMail::SPF::GlobalMod\fR" 4 .IX Item "global_mod($mod_name): returns Mail::SPF::GlobalMod" Returns the global modifier of the given name if it is present in the record. Returns \fBundef\fR otherwise. Use this method if you wish to retrieve a specific global modifier as opposed to getting all of them. .IP "\fBstringify\fR: returns \fIstring\fR" 4 .IX Item "stringify: returns string" Returns the record's version tag and terms (including the global modifiers) formatted as a string. You can simply use a Mail::SPF::Record object as a string for the same effect, see "OVERLOADING". .ie n .IP "\fBeval($server, \fR\fB$request\fR\fB)\fR: throws \fIMail::SPF::Result\fR" 4 .el .IP "\fBeval($server, \fR\f(CB$request\fR\fB)\fR: throws \fIMail::SPF::Result\fR" 4 .IX Item "eval($server, $request): throws Mail::SPF::Result" Evaluates the SPF record in the context of the request parameters represented by the given \fIMail::SPF::Request\fR object. The given \fIMail::SPF::Server\fR object is used for performing DNS look-ups. Throws a \fIMail::SPF::Result\fR object matching the outcome of the evaluation; see Mail::SPF::Result. See RFC 4408, 4.6 and 4.7, for the exact algorithm used. .SH OVERLOADING .IX Header "OVERLOADING" If a Mail::SPF::Record object is used as a \fIstring\fR, the \f(CW\*(C`stringify\*(C'\fR method is used to convert the object into a string. .SH "SEE ALSO" .IX Header "SEE ALSO" Mail::SPF, Mail::SPF::v1::Record, Mail::SPF::v2::Record, Mail::SPF::Term, Mail::SPF::Mech, Mail::SPF::Mod .PP .PP For availability, support, and license information, see the README file included with Mail::SPF. .SH AUTHORS .IX Header "AUTHORS" Julian Mehnle , Shevek