Mail::SPF::Record - Abstract base class for SPF records

    use Mail::SPF::v1::Record;

    my $record = Mail::SPF::v1::Record->new_from_string("v=spf1 a mx -all");

    use Mail::SPF::v2::Record;

    my $record = Mail::SPF::v2::Record->new(
        scopes      => ['mfrom', 'pra'],
        terms       => [
            Mail::SPF::Mech::A->new(),
            Mail::SPF::Mech::MX->new(),
            Mail::SPF::Mech::All->new(qualifier => '-')
        ],
        global_mods => [
            Mail::SPF::Mod::Exp->new(domain_spec => 'spf-exp.example.com')
        ]
    );

#
# Mail::SPF::Record
# Abstract base class for SPF records.
#
# (C) 2005-2008 Julian Mehnle <julian@mehnle.net>
#     2005      Shevek <cpan@anarres.org>
# $Id: Record.pm 50 2008-08-17 21:28:15Z Julian Mehnle $
#
##############################################################################

package Mail::SPF::Record;

use warnings;
use strict;

use utf8;  # Hack to keep Perl 5.6 from whining about /[\p{}]/.

use base 'Mail::SPF::Base';

use overload
    '""'        => 'stringify',
    fallback    => 1;

use Error ':try';

use constant TRUE   => (0 == 0);
use constant FALSE  => not TRUE;

use constant default_qualifier      => '+';

use constant results_by_qualifier   => {
    ''  => 'pass',
    '+' => 'pass',
    '-' => 'fail',
    '~' => 'softfail',
    '?' => 'neutral'
};

# Interface:
##############################################################################

# Implementation:
##############################################################################

sub new {
    my ($self, %options) = @_;
    $self->class ne __PACKAGE__
        or throw Mail::SPF::EAbstractClass;
    $self = $self->SUPER::new(%options);
    $self->{parse_text} = $self->{text} if not defined($self->{parse_text});
    $self->{terms}       ||= [];
    $self->{global_mods} ||= {};
    return $self;
}

sub new_from_string {
    my ($self, $text, %options) = @_;
    $self = $self->new(%options, text => $text);
    $self->parse();
    return $self;
}

sub parse {
    my ($self) = @_;
    defined($self->{parse_text})
        or throw Mail::SPF::ENothingToParse('Nothing to parse for record');
    $self->parse_version_tag();
    $self->parse_term() while length($self->{parse_text});
    $self->parse_end();
    return;
}

sub parse_version_tag {
    my ($self) = @_;
    if (not $self->{parse_text} =~ s/^${\$self->version_tag_pattern}(?:\x20+|$)//) {
        throw Mail::SPF::EInvalidRecordVersion(
            "Not a '" . $self->version_tag . "' record: '" . $self->text . "'");
    }
}

sub parse_term {
    my ($self) = @_;
    if (
        $self->{parse_text} =~ s/
                        ^
                        (
                                ${\Mail::SPF::Mech->qualifier_pattern}?
                              (${\Mail::SPF::Mech->name_pattern})
                                [^\x20]*
                        )
                        (?: \x20+ | $ )
                //x
    ) {
        # Looks like a mechanism:
        my ($mech_text, $mech_name) = ($1, lc($2));
        my $mech_class = $self->mech_classes->{$mech_name};
        throw Mail::SPF::EInvalidMech("Unknown mechanism type '$mech_name' in '" . $self->version_tag . "' record")
            if not defined($mech_class);
        my $mech = $mech_class->new_from_string($mech_text);
        push(@{$self->{terms}}, $mech);
    }
    elsif (
        $self->{parse_text} =~ s/
                        ^
                        (
                              (${\Mail::SPF::Mod->name_pattern}) =
                                [^\x20]*
                        ) 
                        (?: \x20+ | $ )
                //x
    ) {
        # Looks like a modifier:
        my ($mod_text, $mod_name) = ($1, lc($2));
        my $mod_class = $self->mod_classes->{$mod_name};
        if (defined($mod_class)) {
            # Known modifier.
            my $mod = $mod_class->new_from_string($mod_text);
            if ($mod->isa('Mail::SPF::GlobalMod')) {
                # Global modifier.
                not defined($self->{global_mods}->{$mod_name}) or
                    throw Mail::SPF::EDuplicateGlobalMod("Duplicate global modifier '$mod_name' encountered");
                $self->{global_mods}->{$mod_name} = $mod;
            }
            elsif ($mod->isa('Mail::SPF::PositionalMod')) {
                # Positional modifier, queue normally:
                push(@{$self->{terms}}, $mod);
            }
            else {
                # Huh?  This should not happen.
            }
        }
        else {
            # Unknown modifier.
            my $mod = Mail::SPF::UnknownMod->new_from_string($mod_text);
            push(@{$self->{terms}}, $mod);
        }
    }
    else {
        throw Mail::SPF::EJunkInRecord("Junk encountered in record '" . $self->text . "'");
    }
    return;
}

sub parse_end {
    my ($self) = @_;
    throw Mail::SPF::EJunkInRecord("Junk encountered in record '" . $self->text . "'")
        if $self->{parse_text} ne '';
    delete($self->{parse_text});
    return;
}

sub text {
    my ($self) = @_;
    defined($self->{text})
        or throw Mail::SPF::ENoUnparsedText;
    return $self->{text};
}

sub scopes {
    my ($self) = @_;
    return @{$self->{scopes}};
}

sub terms {
    my ($self) = @_;
    return @{$self->{terms}};
}

sub global_mods {
    my ($self) = @_;
    return sort { $a->precedence <=> $b->precedence } values(%{$self->{global_mods}});
}

sub global_mod {
    my ($self, $mod_name) = @_;
    return $self->{global_mods}->{$mod_name};
}

sub stringify {
    my ($self) = @_;
    return join(' ', $self->version_tag, $self->terms, $self->global_mods);
}

sub eval {
    my ($self, $server, $request) = @_;
    
    defined($server)
        or throw Mail::SPF::EOptionRequired('Mail::SPF server object required for record evaluation');
    defined($request)
        or throw Mail::SPF::EOptionRequired('Request object required for record evaluation');
    
    try {
        foreach my $term ($self->terms) {
            if ($term->isa('Mail::SPF::Mech')) {
                # Term is a mechanism.
                my $mech = $term;
                if ($mech->match($server, $request)) {
                    my $result_name  = $self->results_by_qualifier->{$mech->qualifier};
                    my $result_class = $server->result_class($result_name);
                    my $result = $result_class->new($server, $request, "Mechanism '$term' matched");
                    $mech->explain($server, $request, $result);
                    $result->throw();
                }
            }
            elsif ($term->isa('Mail::SPF::PositionalMod')) {
                # Term is a positional modifier.
                my $mod = $term;
                $mod->process($server, $request);
            }
            elsif ($term->isa('Mail::SPF::UnknownMod')) {
                # Term is an unknown modifier.  Ignore it (RFC 4408, 6/3).
            }
            else {
                # Invalid term object encountered:
                throw Mail::SPF::EUnexpectedTermObject(
                    "Unexpected term object '$term' encountered");
            }
        }
        
        # Default result when "falling off" the end of the record (RFC 4408, 4.7/1):
        $server->throw_result('neutral-by-default', $request,
            'Default neutral result due to no mechanism matches');
    }
    catch Mail::SPF::Result with {
        my ($result) = @_;
        
        # Process global modifiers in ascending order of precedence:
        foreach my $global_mod ($self->global_mods) {
            $global_mod->process($server, $request, $result);
        }
        
        $result->throw();
    };
}

TRUE;