NAME

Hash::Match - match contents of a hash against rules

REQUIREMENTS

This module requires Perl v5.10 or newer, and the following non-core modules:

List::AllUtils

namespace::autoclean

SYNOPSIS

  use Hash::Match;

  my $m = Hash::Match->new( rules => { key => qr/ba/ } );

  $m->( { key => 'foo' } ); # returns false
  $m->( { key => 'bar' } ); # returns true
  $m->( { foo => 'bar' } ); # returns false

  my $n = Hash::Match->new( rules => {
     -any => [ key => qr/ba/,
               key => qr/fo/,
             ],
  } )

  $n->( { key => 'foo' } ); # returns true

DESCRIPTION

This module allows you to specify complex matching rules for the contents of a hash.

METHODS

new

  my $m = Hash::Match->new( rules => $rules );

Returns a function that matches a hash reference against the $rules, e.g.

  if ( $m->( \%hash ) ) { ... }

Rules

The rules can be a hash or array reference of key-value pairs, e.g.

  {
    k_1 => 'string',    # k_1 eq 'string'
    k_2 => qr/xyz/,     # k_2 =~ qr/xyz/
    k_3 => sub { ... }, # k_3 exists and sub->($hash->{k_3}) is true
  }

For a hash reference, all keys in the rule must exist in the hash and match the criteria specified by the rules' values.

For an array reference, some (any) key must exist and match the criteria specified in the rules.

You can specify more complex rules using special key names:

-all

  {
    -all => $rules,
  }

All of the $rules must match, where $rules is an array or hash reference.

-any

  {
    -any => $rules,
  }

Any of the $rules must match.

-notall

  {
    -notall => $rules,
  }

Not all of the $rules can match (i.e., at least one rule must fail).

-notany

  {
    -any => $rules,
  }

None of the $rules can match.

Note that rules can be specified arbitrarily deep, e.g.

  {
    -any => [
       -all => { ... },
       -all => { ... },
    ],
  }

or

  {
    -all => [
       -any => [ ... ],
       -any => [ ... ],
    ],
  }

SEE ALSO

The following modules have similar functionality:

Data::Match

Data::Search

AUTHOR

Robert Rothenberg, <rrwo at cpan.org>

Contributors

Mohammad S Anwar

ACKNOWLEDGEMENTS

Foxtons, Ltd.

LICENSE AND COPYRIGHT

Copyright 2017 Robert Rothenberg.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

cpanm Hash::Match

perl -MCPAN -e shell
install Hash::Match