The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.

NAME

Data::PatternCompare - Module to match data to pattern.

SYNOPSIS

Create a comparator object.

    use Data::PatternCompare;

    my $cmp = Data::PatternCompare->new;

You can match Perl data structure to pattern like so:

    my $data = [1, 2, { name => "cono" }];
    my $pattern = [1, 2, { name => $Data::PatternCompare::any }];

    if ($cmp->pattern_match($data, $pattern)) {
        print "Matched";
    }

If you have array of patterns, you can sort them from stricter to wider like so:

    my @array_of_patterns = ( ... );

    my @sorted = sort { $cmp->compare_pattern($a, $b) } @array_of_patterns;

DESCRIPTION

This module provides to you functionality of matching Perl data structures to patterns. Could be used for some kind of multi method dispatching.

This module is far from high performance.

FUNCTIONS

import_to($pkg, @export_list)

This function imports functions @export_list in defined package $pkg. Available functions: any and empty.

METHODS

import()

By default module does not export anything. You can export 2 functions: any and empty.

e.g. use Data::PatternCompare qw(any empty);

new( epsilon => 0.01 )

It is a constructor. Currently takes only one parameter: epsilon for float comparison. Floats are equal if true the following statement: abs(float1 - float2) < epsilon. Returns instance of the Data::PatternCompare class.

pattern_match($data, $pattern) : Boolean

This method takes 2 arguments, Perl data structure and pattern. Returns true if data matches to pattern.

Pattern can contain special objects of class Data::PatternCompare::Any, you can refer to instance of this class simply using $Data::PatternCompare::any variable.

$Data::PatterCompare::any can be used to match any value.

So call pattern_match( DATA, $Data::PatternCompare::any) will match any data: Integers, Strings, Objects, ...

Because of nature of matching method you can't match empty arrays (zero sized array patterns can match any amount of data). @Data::PatternCompare::empty array was defined. It's also exported via function empty. It matches only zero sized arrays.

compare_pattern($pattern_a, $pattern_b) : Integer

This method takes 2 pattern as an arguments and return Integer value like any other comparator does.

    return_value < 0 - means that $pattern_a more strict than $pattern_b
                   0 - pattern are equal to each others
    0 < return_value - $pattern_a wider than $pattern_b

Simple type

What stricter/wider means?

If we take 2 following patterns:

1. 42
2. $Data::PatternCompare::any

The second one is more wide. If we represent patterns as a set of values, that means that second pattern contain first one. In another words: 42 is a member of Set any.

Array

Before matching values inside of the array, length of array is taking into consideration. Arrays with bigger length are more strict.

This rule applies because we consider: pattern_match([42, 1], [42]) as true value. Because of this @Data::PatternCompare::empty array was created.

You can define empty array pattern like so: [ @Data::PatternCompare::empty] .

Empty (not zero sized) arrays will take precedense over any other arrays.

Hash

The same rules as for the Array. The bigger size of the hash treats as stricter.

e.g.:

    $cmp->compare_pattern({ qw|a b c d| }, { qw|a b| }) # -1

To define empty hash pattern you can use following code:

    $pattern = { @Data::PatternCompare::empty };

Be careful with the following example:

    $cmp->compare_pattern(
        { a => $Data::PatternCompare::any, b => 42 },
        { a => 42, b => $Data::PatternCompare::any }
    );

Result of the code above is unpredicted. It depends on in what order keys will be returned by the keys() function.

eq_pattern($pattern_a, $pattern_b) : Boolean

This method takes 2 arguments. Returns true if 2 patterns are strictly equal to each others.

The main differece to compare_pattern() == 0 is that 42 != 43. $Data::PatterCompare::any and @Data::PatternCompare::empty matched only to the same object.

AUTHOR

cono <cono@cpan.org>

COPYRIGHT

Copyright 2014 - cono

LICENSE

Artistic v2.0

SEE ALSO