.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28)
.\"
.\" 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
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    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 turned on, 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
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Mail::SPF::Result 3pm"
.TH Mail::SPF::Result 3pm "2014-06-29" "perl v5.18.2" "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::Result \- SPF result class
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
For the general usage of \fIMail::SPF::Result\fR objects in code that calls
Mail::SPF, see Mail::SPF.  For the detailed interface of \fIMail::SPF::Result\fR
and its derivatives, see below.
.SS "Throwing results"
.IX Subsection "Throwing results"
.Vb 3
\&    package Mail::SPF::Foo;
\&    use Error \*(Aq:try\*(Aq;
\&    use Mail::SPF::Result;
\&
\&    sub foo {
\&        if (...) {
\&            $server\->throw_result(\*(Aqpass\*(Aq, $request)
\&        }
\&        else {
\&            $server\->throw_result(\*(Aqpermerror\*(Aq, $request, \*(AqInvalid foo\*(Aq);
\&        }
\&    }
.Ve
.SS "Catching results"
.IX Subsection "Catching results"
.Vb 3
\&    package Mail::SPF::Bar;
\&    use Error \*(Aq:try\*(Aq;
\&    use Mail::SPF::Foo;
\&
\&    try {
\&        Mail::SPF::Foo\->foo();
\&    }
\&    catch Mail::SPF::Result with {
\&        my ($result) = @_;
\&        ...
\&    };
.Ve
.SS "Using results"
.IX Subsection "Using results"
.Vb 7
\&    my $result_name     = $result\->name;
\&    my $result_code     = $result\->code;
\&    my $request         = $result\->request;
\&    my $local_exp       = $result\->local_explanation;
\&    my $authority_exp   = $result\->authority_explanation
\&        if $result\->can(\*(Aqauthority_explanation\*(Aq);
\&    my $spf_header      = $result\->received_spf_header;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
An object of class \fBMail::SPF::Result\fR represents the result of an \s-1SPF\s0
request.
.PP
There is usually no need to construct an \s-1SPF\s0 result object directly using the
\&\f(CW\*(C`new\*(C'\fR constructor.  Instead, use the \f(CW\*(C`throw\*(C'\fR class method to signal to the
calling code that a definite \s-1SPF\s0 result has been determined.  In other words,
use Mail::SPF::Result and its derivatives just like exceptions.  See Error
or \*(L"eval\*(R" in perlfunc for how to handle exceptions in Perl.
.SS "Constructor"
.IX Subsection "Constructor"
The following constructor is provided:
.ie n .IP "\fBnew($server, \fB$request\fB)\fR: returns \fIMail::SPF::Result\fR" 4
.el .IP "\fBnew($server, \f(CB$request\fB)\fR: returns \fIMail::SPF::Result\fR" 4
.IX Item "new($server, $request): returns Mail::SPF::Result"
.PD 0
.ie n .IP "\fBnew($server, \fB$request\fB, \f(BI$text\fB)\fR: returns \fIMail::SPF::Result\fR" 4
.el .IP "\fBnew($server, \f(CB$request\fB, \f(CB$text\fB)\fR: returns \fIMail::SPF::Result\fR" 4
.IX Item "new($server, $request, $text): returns Mail::SPF::Result"
.PD
Creates a new \s-1SPF\s0 result object and associates the given \fIMail::SPF::Server\fR
and \fIMail::SPF::Request\fR objects with it.  An optional result text may be
specified.
.SS "Class methods"
.IX Subsection "Class methods"
The following class methods are provided:
.ie n .IP "\fBthrow($server, \fB$request\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.el .IP "\fBthrow($server, \f(CB$request\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.IX Item "throw($server, $request): throws Mail::SPF::Result"
.PD 0
.ie n .IP "\fBthrow($server, \fB$request\fB, \f(BI$text\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.el .IP "\fBthrow($server, \f(CB$request\fB, \f(CB$text\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.IX Item "throw($server, $request, $text): throws Mail::SPF::Result"
.PD
Throws a new \s-1SPF\s0 result object, associating the given \fIMail::SPF::Server\fR and
\&\fIMail::SPF::Request\fR objects with it.  An optional result text may be
specified.
.Sp
\&\fINote\fR:  Do not write code invoking \f(CW\*(C`throw\*(C'\fR on \fIliteral\fR result class names
as this would ignore any derivative result classes provided by \fBMail::SPF\fR
extension modules.  Invoke the \f(CW\*(C`throw_result\*(C'\fR
method on a \fIMail::SPF::Server\fR object instead.
.IP "\fBname\fR: returns \fIstring\fR" 4
.IX Item "name: returns string"
\&\fIAbstract\fR.  Returns the result name of the result class (or object).  For
classes of the \fIMail::SPF::Result::*\fR hierarchy, this roughly corresponds to
the trailing part of the class name.  For example, returns \f(CW\*(C`neutral\-by\-default\*(C'\fR
if invoked on \fIMail::SPF::Result::NeutralByDefault\fR.  Also see the \*(L"code\*(R"
method.  This method may also be used as an instance method.
.Sp
This method must be implemented by sub-classes of Mail::SPF::Result for which
the result \fIname\fR differs from the result \fIcode\fR.
.IP "\fBclass\fR: returns \fIclass\fR" 4
.IX Item "class: returns class"
.PD 0
.IP "\fBclass($name)\fR: returns \fIclass\fR" 4
.IX Item "class($name): returns class"
.PD
Maps the given result name to the corresponding \fIMail::SPF::Result::*\fR class,
or returns the result base class (the class on which it is invoked) if no
result name is given.  If an unknown result name is specified, returns
\&\fBundef\fR.
.IP "\fBisa_by_name($name)\fR: returns \fIboolean\fR" 4
.IX Item "isa_by_name($name): returns boolean"
If the class (or object) on which this method is invoked represents the given
result name (or a derivative name), returns \fBtrue\fR.  Returns \fBfalse\fR
otherwise.  This method may also be used as an instance method.
.Sp
For example, \f(CW\*(C`Mail::SPF::Result::NeutralByDefault\->isa_by_name(\*(Aqneutral\*(Aq)\*(C'\fR
returns \fBtrue\fR.
.IP "\fBcode\fR: returns \fIstring\fR" 4
.IX Item "code: returns string"
\&\fIAbstract\fR.  Returns the basic \s-1SPF\s0 result code (\f(CW"pass"\fR, \f(CW"fail"\fR,
\&\f(CW"softfail"\fR, \f(CW"neutral"\fR, \f(CW"none"\fR, \f(CW"error"\fR, \f(CW"permerror"\fR,
\&\f(CW"temperror"\fR) of the result class on which it is invoked.  All valid result
codes are valid result names as well, the reverse however does not apply.  This
method may also be used as an instance method.
.Sp
This method is abstract and must be implemented by sub-classes of
Mail::SPF::Result.
.IP "\fBis_code($code)\fR: returns \fIboolean\fR" 4
.IX Item "is_code($code): returns boolean"
If the class (or object) on which this method is invoked represents the given
result code, returns \fBtrue\fR.  Returns \fBfalse\fR otherwise.  This method may
also be used as an instance method.
.Sp
\&\fINote\fR:  The \*(L"isa_by_name\*(R" method provides a superset of this method's
functionality.
.IP "\fBreceived_spf_header_name\fR: returns \fIstring\fR" 4
.IX Item "received_spf_header_name: returns string"
Returns \fB'Received\-SPF'\fR as the field name for \f(CW\*(C`Received\-SPF\*(C'\fR header fields.
This method should be overridden by \fBMail::SPF\fR extension modules that provide
non-standard features (such as local policy) with the capacity to dilute the
purity of \s-1SPF\s0 results, in order not to deceive users of the header field into
mistaking it as an indication of a natural \s-1SPF\s0 result.
.SS "Instance methods"
.IX Subsection "Instance methods"
The following instance methods are provided:
.IP "\fBthrow\fR: throws \fIMail::SPF::Result\fR" 4
.IX Item "throw: throws Mail::SPF::Result"
.PD 0
.ie n .IP "\fBthrow($server, \fB$request\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.el .IP "\fBthrow($server, \f(CB$request\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.IX Item "throw($server, $request): throws Mail::SPF::Result"
.ie n .IP "\fBthrow($server, \fB$request\fB, \f(BI$text\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.el .IP "\fBthrow($server, \f(CB$request\fB, \f(CB$text\fB)\fR: throws \fIMail::SPF::Result\fR" 4
.IX Item "throw($server, $request, $text): throws Mail::SPF::Result"
.PD
Re-throws an existing \s-1SPF\s0 result object.  If \fIMail::SPF::Server\fR and
\&\fIMail::SPF::Request\fR objects are specified, associates them with the result
object, replacing the prior server and request objects.  If a result text is
specified as well, overrides the prior result text.
.IP "\fBserver\fR: returns \fIMail::SPF::Server\fR" 4
.IX Item "server: returns Mail::SPF::Server"
Returns the Mail::SPF server object that produced the result at hand.
.IP "\fBrequest\fR: returns \fIMail::SPF::Request\fR" 4
.IX Item "request: returns Mail::SPF::Request"
Returns the \s-1SPF\s0 request that led to the result at hand.
.IP "\fBtext\fR: returns \fIstring\fR" 4
.IX Item "text: returns string"
Returns the text message of the result object.
.IP "\fBstringify\fR: returns \fIstring\fR" 4
.IX Item "stringify: returns string"
Returns the result's name and text message formatted as a string.  You can
simply use a Mail::SPF::Result object as a string for the same effect, see
\&\*(L"\s-1OVERLOADING\*(R"\s0.
.IP "\fBlocal_explanation\fR: returns \fIstring\fR; throws \fIMail::SPF::EDNSError\fR, \fIMail::SPF::EInvalidMacroString\fR" 4
.IX Item "local_explanation: returns string; throws Mail::SPF::EDNSError, Mail::SPF::EInvalidMacroString"
Returns a locally generated explanation for the result.
.Sp
The local explanation is prefixed with the authority domain whose sender policy
is responsible for the result.  If the responsible sender policy referred to
another domain's policy (using the \f(CW\*(C`include\*(C'\fR mechanism or the \f(CW\*(C`redirect\*(C'\fR
modifier), that other domain which is \fIdirectly\fR responsible for the result is
also included in the local explanation's head.  For example:
.Sp
.Vb 1
\&    example.com: <local\-explanation>
.Ve
.Sp
The authority domain \f(CW\*(C`example.com\*(C'\fR's sender policy is directly responsible for
the result.
.Sp
.Vb 1
\&    example.com ... other.example.org: <local\-explanation>
.Ve
.Sp
The authority domain \f(CW\*(C`example.com\*(C'\fR (directly or indirectly) referred to the
domain \f(CW\*(C`other.example.org\*(C'\fR, whose sender policy then led to the result.
.IP "\fBreceived_spf_header\fR: returns \fIstring\fR" 4
.IX Item "received_spf_header: returns string"
Returns a string containing an appropriate \f(CW\*(C`Received\-SPF\*(C'\fR header field for the
result object.  The header field is not line-wrapped and contains no trailing
newline character.
.SH "OVERLOADING"
.IX Header "OVERLOADING"
If a Mail::SPF::Result object is used as a \fIstring\fR, the \*(L"stringify\*(R" method
is used to convert the object into a string.
.SH "RESULT CLASSES"
.IX Header "RESULT CLASSES"
The following result classes are provided:
.IP "\(bu" 4
\&\fIMail::SPF::Result::Pass\fR
.IP "\(bu" 4
\&\fIMail::SPF::Result::Fail\fR
.IP "\(bu" 4
\&\fIMail::SPF::Result::SoftFail\fR
.IP "\(bu" 4
\&\fIMail::SPF::Result::Neutral\fR
.RS 4
.IP "\(bu" 4
\&\fIMail::SPF::Result::NeutralByDefault\fR
.Sp
This is a special case of the \f(CW\*(C`neutral\*(C'\fR result that is thrown as a default
when \*(L"falling off\*(R" the end of the record during evaluation.  See \s-1RFC 4408,
4.7.\s0
.RE
.RS 4
.RE
.IP "\(bu" 4
\&\fIMail::SPF::Result::None\fR
.IP "\(bu" 4
\&\fIMail::SPF::Result::Error\fR
.RS 4
.IP "\(bu" 4
\&\fIMail::SPF::Result::PermError\fR
.IP "\(bu" 4
\&\fIMail::SPF::Result::TempError\fR
.RE
.RS 4
.RE
.PP
The following result classes have additional functionality:
.IP "\fIMail::SPF::Result::Fail\fR" 4
.IX Item "Mail::SPF::Result::Fail"
The following additional instance method is provided:
.RS 4
.IP "\fBauthority_explanation\fR: returns \fIstring\fR; throws \fIMail::SPF::EDNSError\fR, \fIMail::SPF::EInvalidMacroString\fR" 4
.IX Item "authority_explanation: returns string; throws Mail::SPF::EDNSError, Mail::SPF::EInvalidMacroString"
Returns the authority domain's explanation for the result.  Be aware that the
authority domain may be a malicious party and thus the authority explanation
should not be trusted blindly.  See \s-1RFC 4408, 10.5,\s0 for a detailed discussion
of this issue.
.RE
.RS 4
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Mail::SPF, Mail::SPF::Server, Error, \*(L"eval\*(R" in perlfunc
.PP
<http://tools.ietf.org/html/rfc4408>
.PP
For availability, support, and license information, see the \s-1README\s0 file
included with Mail::SPF.
.SH "AUTHORS"
.IX Header "AUTHORS"
Julian Mehnle <julian@mehnle.net>