/ 
Data-Matcher-0.0002
/ Data::Matcher

NAME

Data::Matcher - simple matching on perl data structures and moose objects

VERSION

version 0.0002

SYNOPSIS

use Data::Matcher;

# Usage: matcher \%rules|\@rules, $data;

# keys foo bar and baz are in %data;
matcher [ -keys => 1, -all => 1, qw(foo bar baz) ], \%data;

# substring of keys foo bar and baz are in %data;
matcher [ -keys => 1, -substr => 1, -and => 1, qw(foo bar baz) ], \%data;

# substring of values foo bar and baz are in %data;
matcher [ -noKeys => 1, -noExact => 1, -all => 1, qw(foo bar baz) ], \%data;

# a key foo that has a value "bar"
matcher { foo => "bar" }, \%data;

# -regex => 1,  treats the keys and the values as regular expressions
matcher { -regex => 1, "foo.*" => "bar?" }, \%data;
# -regex was added for config storage (makes it serializable)

# ensures $data is an array reference where the first value matches the
# regex qw/^foo?$/
matcher [ -typeConstraint => 'ArrayRef',  -indexed => 1, qr/^foo?$/ ], $data;

my $match = matcher {
    -all => 1,
    foo => qr/foo|bar/,
    bar => 2,
    baz => [ -all => 1, -typeConstraint => 'ArrayRef', qw( foo bar bat ) ],
    bat => {
        -flags => [qw/regex all only/],
        'hey|hi' => qr/(?:wo)?man/,
        '(?:yo)\s+wut' => qr/up.*/
    }
}, {
    foo => "bar",
    bar => 2,
    baz => [ "bat", "bar", "foo" ],
    bat => {
        hey => "man",
        wut => "up",
    }
};

# OOP interface

# defaults to 'and' for matching. Can be changed in rules
my $rule = new Data::Matcher::Rule( 'and' => 1 );

# parses rule. sets global flags. initialized subrule objects
$rule->parse([ -indexed, qw(foo bar baz) ]);

my $match1 = $rule->match( $data1 );
my $match2 = $rule->match( $data2 );
...

# clear rules
$rule->clear_rules;
# Note: parse() adds rules

# add a rule
$rule->parse( qr/[a-z]+/ );
# do more matching
my $match3 = $rule->match( $data3 );

DESCRIPTION

This module gives you an interface to search perl data structures. It also understand IO::Handle types and Moose objects.

Rules

The rules passed to matcher() can be either an array reference, hash reference, regexp reference or string. If you specify a regexp or string, they will be converted to an array reference.

The type of data you specify is used in deciding matching heuristics. Here is a chart that covers the behavior:

+-----------------------------------------------------------------------------+
| Flag       | Rule   | Data    | Explination                                 |
+------------+--------+---------+---------------------------------------------+
| -keys      | Array  | Hash    | Matches values of Rule to keys of Data      |
| -noKeys    | Array  | Hash    | Matches values of Rule to values of Data    |
| -keys      | Array  | Array   | No effect                                   |
| -noKeys    | Array  | Array   | No effect                                   |
| -keys      | Hash   | Hash    | Matches keys of Rule to keys of Data        |
| -noKeys    | Hash   | Hash    | Matches keys and values of both hashes      |
| -keys      | Hash   | Array   | Matches keys of Rule against Array values   |
| -noKeys    | Hash   | Array   | Matches values of Rule against Array values |
| -indexed   | Hash   | Array   | No effect                                   |
| -noIndexed | Hash   | Array   | No effect                                   |
| -indexed   | Hash   | Hash    | No effect                                   |
| -noIndexed | Hash   | Hash    | No effect                                   |
| -indexed   | Array  | Array   | Matches Rule to Data array in index order   |
| -noIndexed | Array  | Array   | Matches Rule to Data in any order           |
+-----------------------------------------------------------------------------+

Sub-Rules

Any array or hash references found will be converted into Data::Matcher::Rule objects. For example:

# this will match an array with values ( foo and bar and ( baz or bat ) )
# it will also match a hash with keys ( foo and bar and ( baz or bat ) )
matcher [
    -all => 1, qw(foo bar),
    [ -all => 0, qw(baz bat) ]
], $data;
# Notes
#   1. The second -all above is not needed as Data::Matcher::Rule defaults to 0
#   2. To prevent the above from matching a hash as well as an array use:
#      -typeConstraint => 'ArrayRef'


matcher {
    -typeConstraint => 'HashRef',
    -all => 1,
    foo => 1,
    bar => [
        -typeConstraint => 'ArrayRef',
        -all => 1,
        qw(bar bat)
    ]
}, $data;

Flags

There are two methods to enable/disable flags in the parsing options. The first way is with -flags and -noFlags. These allow you to pass in an array ref of flags to enable/disble.

-flags => [qw(list of flags to enable)]
# turns on the flags 'keys' and 'only'
matcher [ -flags => [ qw( keys only ) ], qw(stuff) ], $data;
-noFlags => [qw(list of flags to disable)]
# turns off the flags 'index' and 'all'
matcher [ -noFlags => [ qw( index all ), qw(stuff) ], $data

The other method is passing in the flags one at a time. Flags always start with a dash. The value in that case will be a boolean.

# turns on the flags 'keys' and 'only'
matcher [ -keys => 1, -only => 1, qw(stuff) ], $data;

# turns off the flags 'index' and 'all'
matcher [ -indexed => 0, -all => 1, qw(stuff) ], $data

List Flags

These flags control how lists are matched.

-indexed => 0|1 default 0

This flag is only valid when matching against an array and will be ignored if set while matching a hash.

This flag causes the matcher to perform tests in order, starting from index zero in the matching array and in the data array. Flags are not counted when finding the index, only rules that can match. This does not enforce any limits on the number of elements in the data we are matching, see -only for that. For example:

#  Will not match
matcher [ -indexed => 1, qw(foo bar baz) ], [ qw( bar baz foo ) ];

#  Will match
matcher [ qw(foo bar baz) ], [ qw( bar baz foo ) ];

#  Will match
matcher [ -indexed => 1, qw(foo bar baz) ], [ qw( foo bar baz ) ];

#  Will match
matcher [ -indexed => 1, qw(foo bar baz) ], [ qw( foo bar baz bat ) ];

#  Will not match, bat is index 0, foo is matching on index 0
matcher [ -indexed => 1, qw(foo bar baz) ], [ qw( bat foo bar baz ) ];
-all => 0|1 default 0

This flag turns matching into an AND process. All rules must match, including sub-rules and type constraints. For example:

# matches (order isn't important, see -indexed for that)
matcher [ -all => 1, qw(you there) ], [ qw(there you are) ];

# no match, both 'you' and 'these' must match
matcher [ -all => 1, qw(you there) ], [ qw(you) ];

Also aliased:

-any => 0|1

turns on -all when true

-and => 0|1

turns on -all when true

-or => 0|1

turns off -all when true

-only => 0|1 default 0

This flag adds an additional test after matching. It ensure that the number of elements in the array are the same as the number of tests we've performed. For example:

# will not match
matcher [ -only => 1, qw(foo bar) ], [ qw(foo bar baz) ];

# will match
matcher [ -only => 0, qw(foo bar) ], [ qw(bar) ]; # only need one match

Also aliased:

-noOnly => 0|1
-keys => 0|1

For array matching a hash, this check the keys of the hash

-noKeys => 0|1

turns off -keys when true

-values => 0|1

turns off -keys when true

-noValues => 0|1

turns on -keys when true

String Flags

These flags determine what type of match is attempted when Data::Matcher encounters a string in matching rules.

NB: These flags change how both keys and values are treated if you specified a hash as matching rules.

substr => 0|1

All strings encountered in rules will be matched using substr().

# Will match foobly
matcher [ -substr => 1, 'foo' ], $data;
mooseType => 0|1

All strings encountered in rules will be coerced into Moose::Meta::Constraint objects. If the rule can not be coerced and use warnings; is set, a warning will be issued.

# checks if $data has an array ref in it.
matcher [ -mooseType => 1, "ArrayRef" ], $data;
regex => 0|1

All strings encountered is rules are treated as regular expressions.

# match anything starting with foo
matcher [ -regex => 1, "^foo.*" ], $data;

Global Flags

These are flags that, when present, are set for the whole instance instead of just the context they are in. In other words, it's the same as setting them on the object it's self before calling $obj->parse(). For example the following are equivalent:

Data::Matcher::Rule->new( typeConstraint => 'HashRef' )
                   ->parse( { foo => 1 } )
                   ->match( $data )

Data::Matcher::Rule->new
                   ->parse( { -typeConstraint => 'HashRef', foo => 1 } )
                   ->match( $data )
-typeConstraint => DMTypeConstraint

This allows you to check the type of data being matched on for the current Rule. If set to a string, this will be coerced into a Moose::Meta::TypeConstraint via "Type Constraint Constructors" in Moose::Util::TypeConstraints.

Moose

From the Moose documentation Moose is an extension of the Perl 5 object system. Moose is involved in Data::Matcher in three ways.

Moose objects can be matched upon. They are treated like a hash. Keys are the attribute accessor names and values are the return of calling the accessor. Attributes are called as late as possible using Tie::MooseObject internally.

Moose type constraints can be passed in for matching options. You can also tell Data::Matcher to treat all strings as Moose type constraints in the current context. This is a parsing option you can enable and disable it from within the matching options with -mooseType => 1|0. See "String Options" in Data::Matcher, Moose::Util::TypeConstraints and Moose::Meta::TypeConstraint.

EXPORTS

matcher($rules, $data)

Expects matching rules as the first argument and the data to match against as the second.

AUTHOR

Scott Beck <scottbeck@gmail.com>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Scott Beck.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.