NAME

Hash::Search - Search and return hash keys using regular expressions

SYNOPSIS

  use Hash::Search;
  my $hs = new Hash::Search;
  my %hashlist = (
    "one" => "orange", "two" => "banana", "three" => "apple",
    "four" => "pear", "five" => "pineapple"
  );
  $hs->hash_search("e\$", %hashlist);
  my %hashresult = $hs->hash_search_resultdata;
  my $hashresult_count = $hs->hash_search_resultcount;
  print $hashresult_count . " result(s) found: ";
  foreach my $hash_key (keys %hashresult){
    print $hash_key . " ";
  }

DESCRIPTION

This module allows a search to be made on a hash based on a regular expressions pattern based on the name of the key and returns the results as a seperate hash. It also keeps a count of how many matches have been made.

Creating an instance

Before Hash::Search can be used, an instance of Hash::Search must be created.

  use Hash::Search;
  $hs = new Hash::Search;

Finding keys in a hash

  $hs->hash_search("p\$", %hash);

The hash_search subroutine requires two parameters, one is a regular expression used for searching the names of keys and another for the hash itself.

If a blank expression has been specified or an empty hash is given then a warning (carp) message is written and the subroutine promptly returns.

hash_search can also be used in a if statement so that it can process information depending if hash_search finds matches or not.

Getting the results data

  %results = $hs->hash_search_resultdata;

The value returned from hash_search_resultdata will be a hash. If no matches have been found then it will return an empty hash.

Getting the count of results

  $searchresults = $hs->hash_search_resultcount;
  print "Matches found: " . $searchresults;
        
  print "Number of results returned: " . $hs->hash_search_resultcount;

The value returned from hash_search_resultcount will be a scalar value.

EXAMPLES

Using Hash::Search with CGI

  use CGI qw(:standard);
  use Hash::Search;

  my $q = new CGI;
  my $hs = new Hash::Search;

  my %formdata = $q->Vars;
  $hs->hash_search("^prefix_", %formdata);
  my %resultdata = $hs->hash_search_resultdata;

Using Hash::Search with CGI::Lite

  use CGI::Lite;
  use Hash::Search;

  my $cgi = new CGI::Lite;
  my $hs = new Hash::Search;
  my %formdata = $cgi->parse_form_data;
  $hs->hash_search("^prefix_", %formdata);
  my %resultdata = $hs->hash_search_resultdata; 

CAVEATS / KNOWN BUGS

If an invalid regular expression is given to hash_search then the script will not run and will give the line number at the point where the regular expression is used in this module as there doesn't appear to be a relatively straight forward way of checking if the regular expression itself is valid or not prior to it being used.

This is currently a perl module that is at the alpha development stage and as such things in this module can change which may break your scripts in the future.

SEE ALSO

Carp, CGI and CGI::Lite

AUTHOR

Steve Brokenshire, <sbrokenshire@xestia.co.uk>

COPYRIGHT AND LICENSE

Copyright (C) 2009 by Steve Brokenshire

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

cpanm Hash::Search

perl -MCPAN -e shell
install Hash::Search