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. Fo 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
Does not handle circular data structures properly. Does not have regex-like operators like '?', '*', '+'. Should probably incorporate 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
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.01. $Revision: 1.1 $
AUTHOR
Kurt A. Stephens <kurtstephens@acm.org>