Constructors¶

The following constructors are provided:

new(%options): returns Mail::SPF::Mech

Abstract. Creates a new SPF record mechanism object.

%options is a list of key/value pairs representing any of the following options:

new_from_string($text, %options): returns Mail::SPF::Mech; throws Mail::SPF::ENothingToParse, Mail::SPF::EInvalidMech

Abstract. Creates a new SPF record mechanism object by parsing the string and any options given.

Class methods¶

The following class methods are provided:

default_qualifier: returns string

Returns the default qualifier, i.e. '+'.

default_ipv4_prefix_length: returns integer

Returns the default IPv4 network prefix length, i.e. 32.

default_ipv6_prefix_length: returns integer

Returns the default IPv6 network prefix length, i.e. 128.

qualifier_pattern: returns Regexp

Returns a regular expression that matches any legal mechanism qualifier, i.e. '+', '-', '~', or '?'.

name: returns string

Abstract. Returns the name of the mechanism.

This method is abstract and must be implemented by sub-classes of Mail::SPF::Mech.

name_pattern: returns Regexp

Returns a regular expression that matches any legal mechanism name.

Instance methods¶

The following instance methods are provided:

text: returns string; throws Mail::SPF::ENoUnparsedText

Returns the unparsed text of the mechanism. Throws a Mail::SPF::ENoUnparsedText exception if the mechanism was created synthetically instead of being parsed, and no text was provided.

qualifier: returns string

Returns the qualifier of the mechanism. See the description of the "new" constructor's "qualifier" option.

params: returns string

Abstract. Returns the mechanism's parameters formatted as a string.

A sub-class of Mail::SPF::Mech does not have to implement this method if it supports no parameters.

stringify: returns string

Formats the mechanism's qualifier, name, and parameters as a string and returns it. (A qualifier that matches the default of '+' is omitted.) You can simply use a Mail::SPF::Mech object as a string for the same effect, see "OVERLOADING".

domain($server, $request): returns string

Returns the target domain of the mechanism. Depending on whether the mechanism does have an explicit "domain_spec" parameter, this is either the macro-expanded "domain_spec" parameter, or the request's authority domain (see "authority_domain" in Mail::SPF::Request) otherwise. Both a Mail::SPF::Server and a Mail::SPF::Request object are required for resolving the target domain.

match($server, $request): returns boolean; throws Mail::SPF::Result::Error

Abstract. Checks whether the mechanism matches the parameters of the given request (see Mail::SPF::Request) and returns true if it does, or false otherwise. In any case, takes both a Mail::SPF::Server and a Mail::SPF::Request object.

This method is abstract and must be implemented by sub-classes of Mail::SPF::Mech.

match_in_domain($server, $request): returns boolean; throws Mail::SPF::Result::Error

match_in_domain($server, $request, $domain): returns boolean; throws Mail::SPF::Result::Error

Checks whether the mechanism's target domain name (that is, any of its DNS "A" or "AAAA" records) matches the given request's IP address (see "ip_address" in Mail::SPF::Request), and returns true if it does, or false otherwise. If an explicit domain is specified, it is used instead of the mechanism's target domain. The mechanism's IP network prefix lengths are respected when matching DNS address records against the request's IP address. See RFC 4408, 5, for the exact algorithm used.

This method exists mainly for the convenience of sub-classes of Mail::SPF::Mech.

explain($server, $request, $result)

Locally generates an explanation for why the mechanism caused the given result, and stores it in the given request object's state.

There is no need to override this method in sub-classes. See the "explanation_template" method.

explanation_template($server, $request, $result): returns string

Returns a macro string template for a locally generated explanation for why the mechanism caused the given result object.

Sub-classes should either define an "explanation_templates_by_result_code" hash constant with their own templates, or override this method.