/ 
Data-Match-0.02
River stage one • 1 direct dependent • 2 total dependents
/ Data::Match

NAME

Data::Match - Complex data structure pattern matching

SYNOPSIS

use Data::Match qw(:all);

my ($match, $results) = match($structure, $pattern);

DESCRIPTION

Data::Match provides extensible complex perl data structure searching and matching.

EXPORT

None are exported by default.  C<:func> exports C<match> and C<matches>, C<:pat> exports all the pattern element generators below, C<:all> exports C<:func> and C<:pat>.

PATTERNS

A data pattern is a complex data structure that possibly matches another complex data structure. For example:

matches([ 1, 2 ], [ 1, 2 ]); # is true

matches([ 1, 2, 3 ], [ 1, ANY, 2 ]); # is true

ANY matches anything, including an undefined value.

my $results = matches([ 1, 2, 1 ], [ BIND('x'), ANY, BIND('x') ]); # is true.

BIND($name) matches anything and remembers each match and its position with every BIND($name) in $result-{'BIND'}{$name}>. If BIND($name) is not the same as the first value bound to BIND($name) it does not match. For example:

my $results = matches([ 1, 2, 3 ], [ BIND('x'), 2, BIND('x') ]); # is false: 3 != 1

COLLECT($name) is similar to BIND but does not compare first bound values.

REST matches all remaining elements of an array or hash.

matches([ 1, 2, 3 ], [ 1, REST() ]); # is true.
matches({ 'a'=>1, 'b'=>1 }, { 'b'=>1, REST() => REST() }); # is true

FIND searches at all depths for matching subpatterns.

matches([ 1, [ 1, 2 ], 3], FIND(COLLECT('x', [ 1, REST() ])); # is true.

See the test script t/t1.t in the package distribution for more pattern examples.

MATCH COLLECTIONS

When a BIND or COLLECT matches a datum an entry is collect in $result-{BIND}> and $result-{COLLECT}>, respectively.

Each entry for the binding name is a hash containing 'v', 'p' and 'ps' lists. 'v' is a list of the value at each match. 'p' is a list describing where the corresponding match was found based on the root of the searchat each match. 'ps' is a list of code strings that describes where the match was for each match.

CAVEATS

Blessed structures are not traversed. Circular data structures are not handled properly. Does not have regex-like operators like '?', '*', '+'. Should probably have interfaces to Data::DRef and Data::Walker.

STATUS

If you find this to be useful please contact the author. This is beta software; all APIs, semantics and behavors are subject to change.

INTERNALS

This section describes the components of this module.

_match_ARRAY

Internal recursive match routine. Assumes $results is initialized.

_match_HASH

Internal recursive match routine. Assumes $results is initialized.

_match_SCALAR

Internal recursive match routine. Assumes $results is initialized.

_match

Internal recursive match routine. Assumes $results is initialized.

%match_opts

Default options for match.

match

Matches a structure against a pattern. In a list context, return both the match success and results; in a scalar context returns the results hash if match succeeded or undef.

my ($matched, $results) = match($thing, $p);
$results = match($thing, $p);

matches

Same as match in scalar context.

match_path_get

Returns the value pointing to the location for the match path in the root.

my $results = matches($thing, FIND(BIND('x', [ 'x', REST ])));
my $x = match_path_get($thing, $results->{'BIND'}{'x'}{'path'}[0]);

The above example returns.

match_path_set

Returns the value pointing to the location for the match path in the root.

my $results = matches($thing, FIND(BIND('x', [ 'x', REST ])));
match_path_set($thing, $results->{'BIND'}{'x'}{'path'}[0], 'y');

The above example replaces the first array found that starts with 'x' with 'y';

match_path_ref

Returns a scalar ref pointing to the location for the match path in the root.

my $results = matches($thing, FIND(BIND('x', [ 'x', REST ])));
my $ref = match_path_ref($thing, $results->{'BIND'}{'x'}{'path'}[0]);
$$ref = 'y';

The above example replaces the first array that starts with 'x' with 'y';

match_path_str

Returns a perl expression that will generate code to point to the element of the path.

VERSION

Version 0.02, $Revision: 1.5 $.

AUTHOR

Kurt A. Stephens <kurtstephens@acm.org>

SEE ALSO

perl, Data::Compare, Data::Dumper, Data::DRef, Data::Walker.