File Coverage

blib/lib/Data/Cleaner.pm

Criterion	Covered	Total	%
statement	93	106	87.7
branch	16	26	61.5
condition	5	15	33.3
subroutine	25	34	73.5
pod	26	26	100.0
total	165	207	79.7

package Data::Cleaner;

use 5.010000;
use strict;
use warnings;
use Time::Local;

use constant ENCODING         => 'UTF-8';
use constant DATE_FORMAT      => '%d-%m-%Y';
use constant TIME_FORMAT      => '%X %z';
use constant DATE_TIME_FORMAT => DATE_FORMAT.' '.TIME_FORMAT;

our $VERSION = 0.0.2;

#
# Main methods
#

sub new {

    my ($class, %options) = @_;
    my $self = {};
    %{$self} = %options;

    my $typemodule = ucfirst(lc($self->{'type'}));
    my $namespace  = 'Data::Cleaner::'.$typemodule;
    my $usemodule  = 'Data/Cleaner/'.$typemodule.'.pm';
    require $usemodule;

    $self->{'encoding'}       = ENCODING         unless (defined $self->{'encoding'});
    $self->{'dateFormat'}     = DATE_FORMAT      unless (defined $self->{'dateFormat'});
    $self->{'timeFormat'}     = TIME_FORMAT      unless (defined $self->{'timeFormat'});
    $self->{'dateTimeFormat'} = DATE_TIME_FORMAT unless (defined $self->{'dateTimeFormat'});
    $self->{'enumOptions'}    = []               unless (defined $self->{'enumOptions'});
    unless (defined $self->{'tz'}) {
        $self->{'tz'} = sprintf '%+05d', (100 * ((timegm(localtime) - timelocal(localtime)) / (3600)));
    }

    #
    # Each of the three main methods (validate, format and fix), is a
    # reference to a subroutine in a datatype submodule. Each datatype
    # module is a black box - they all have the same inputs and outputs.
    #
    # Submodules also have their own defaults which get loaded by the
    # constructor (defaults can be overwritten using set_default).
    #

    eval('push @{$self->{\'_validate\'}}, \\\&'.$namespace.'::_validate');
    eval('$self->{\'_fix\'} = \\\&'.$namespace.'::_fix');
    eval('$self->{\'_format\'} = \\\&'.$namespace.'::_format');
    unless (defined $self->{'default'}) {
        eval('$self->{\'default\'} = $'.$namespace.'::DEFAULT');
    }
    $self->{'_ns'} = $namespace;

    bless $self, $class;
    return $self;

}

sub load {

    #
    # Loads an item of data into the object as 'raw' data without
    # attempting validation. Useful if only fix and/or format will
    # be used.
    #

    my ($self, $value) = @_;
    $self->{'_raw'} = $value;

}

sub validate {

    #
    # A proxy for Data::Cleaner::::_validate
    # Updates the '_pass', '_raw' and '_processTime' properties
    #
    # The '_validate' property is an array of subroutine references
    # allowing the addition of further tests (with order preserved).
    #

    my ($self, $value) = @_;
    return undef unless (defined $value || defined $self->{'_raw'});

    my $start = time;

    $self->{'_raw'}  = $value if (defined $value);
    $self->{'_pass'} = undef;
    $self->{'_processTime'} = undef;

    foreach my $test (@{$self->{'_validate'}}) {

        my $out = ${$test}->($self, $self->{'_raw'});

        if (defined $out) {
            $self->{'_pass'} = 1;
            $self->{'_raw'}  = $out;
        } else {
            $self->{'_pass'} = 0;
            $self->{'_raw'}  = $value || $self->{'_raw'};
            last;
        }

    }

    $self->{'_processTime'} = time - $start;
    return $self->{'_pass'};

}

sub reset {

    #
    # Definitive method of flushing previous data from the
    # object before reuse (not usually required, since the validate
    # function does the same thing whenever data is loaded as an
    # argument)
    #

    my $self = $_[0];
    $self->{'_raw'}         = undef;
    $self->{'_pass'}        = undef;
    $self->{'_processTime'} = undef;

}

sub format {

    #
    # A proxy for Data::Cleaner::::_format
    # Updates the '_raw' and '_processTime' properties
    #

    my $self = $_[0];
    my $start = time;
    $self->{'_raw'} = ${$self->{'_format'}}->($self, $self->{'_raw'});
    $self->{'_processTime'} = time - $start;
    return $self->{'_raw'};

}

sub fix {

    #
    # A proxy for Data::Cleaner::::_fix
    # Updates the '_raw' and '_processTime' properties
    #

    my $self = $_[0];
    my $start = time;
    $self->{'_raw'} = ${$self->{'_fix'}}->($self, $self->{'_raw'});
    $self->{'_processTime'} = time - $start;

}

sub add_test {

    #
    # Appends a test subroutine reference to $self->{'_validate'}
    #

    if (ref($_[1]) && ref($_[1]) eq 'REF') {
        push @{$_[0]->{'_validate'}}, $_[1];
    }

}

sub set_format {

    #
    # Replaces the default format subroutine reference in
    # $self->{'_format'}
    #

    if (ref($_[1]) && ref($_[1]) eq 'REF') {
        $_[0]->{'_format'} = $_[1];
    }

}

sub set_fix {

    #
    # Replaces the default fix subroutine reference in
    # $self->{'_fix'}
    #

    if (ref($_[1]) && ref($_[1]) eq 'REF') {
        $_[0]->{'_fix'} = $_[1];
    }

}

#
# Helper methods - get property value
#

sub is_valid {

    #
    # Reports whether or not the input data passed [all stages of] validation
    #

    return $_[0]->{'_pass'};

}

sub get_raw {

    #
    # Returns the data item in raw (pre-processed) form
    #

    return $_[0]->{'_raw'};

}

sub get_default {

    #
    # Returns the default value for the type
    #

    return $_[0]->{'default'};

}

sub get_type {

    #
    # Returns the type setting for the object
    #

    return $_[0]->{'type'};

}

sub get_encoding {

    #
    # Returns the encoding the module expects all input data to be encoded in
    #

    return $_[0]->{'encoding'};

}

sub get_timezone {

    #
    # Returns the timezone +/-nnnn
    # By default this is calculated by the constructor as the difference
    # between GMT (UTC) and localtime. Can be overridden
    #

    return $_[0]->{'tz'};

}

sub get_datetime_format {

    #
    # Returns the datetime formatting (uses time2str convention)
    #

    return $_[0]->{'dateTimeFormat'};

}

sub get_date_format {

    #
    # Returns the date formatting (uses time2str convention)
    #

    return $_[0]->{'dateFormat'};

}

sub get_time_format {

    #
    # Returns the time format (uses time2str convention)
    #

    return $_[0]->{'timeFormat'};

}

sub get_enum_options {

    #
    # Returns the defined enum options in an array
    #

    return $_[0]->{'enumOptions'};

}

#
# Helper methods - set property value
#

sub set_default {

    #
    # Sets a new default value for the type
    #

    $_[0]->{'default'} = $_[1];

}

sub set_encoding {

    #
    # Sets the encoding to be used for processing all text input
    #

    $_[0]->{'encoding'} = $_[1];

}

sub set_timezone {

    #
    # Sets a timezone to override the default for formatting of date and time values
    # Can be +/-nnnn or a 3-letter code
    #

    $_[0]->{'tz'} = $_[1];

}

sub set_datetime_format {

    #
    # Set datetime formatting (uses time2str convention)
    #

    $_[0]->{'dateTimeFormat'} = $_[1];

}

sub set_date_format {

    #
    # Set date formatting (uses time2str convention)
    #

    $_[0]->{'dateFormat'} = $_[1];

}

sub set_time_format {

    #
    # Set time formatting (uses time2str convention)
    #

    $_[0]->{'timeFormat'} = $_[1];

}

sub set_enum_options {

    #
    # Sets the defined enum options
    #

    $_[0]->{'enumOptions'} = $_[1];

}

1;

__END__