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::MoreUtils
    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.

    `-and'
        This is a (deprecated) synonym for `-all'.

    `-or'
        This is a (deprecated) synonym for `-any'.

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

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

    or

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

    The values for special keys can be either a hash or array reference. But
    note that hash references only allow strings as keys, and that keys must
    be unique.

    You can use regular expressions for matching keys. For example,

      -any => [
        qr/xyz/ => $rule,
      ]

    will match if there is any key that matches the regular expression has a
    corresponding value which matches the `$rule'.

    You can also use

      -and => [
        qr/xyz/ => $rule,
      ]

    to match if all keys that match the regular expression have
    corresponding values which match the `$rule'.

    You can also use functions to match keys. For example,

      -or => [
        sub { $_[0] > 10 } => $rule,
      ]

AUTHOR
    Robert Rothenberg, `<rrwo at cpan.org>'

LICENSE AND COPYRIGHT
    Copyright 2014 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