NAME

Data::Search - Data structure search

SYNOPSIS

use Data::Search;

 $data = { ... };
 @results = datasearch( data => $data, search => 'values',
                        find => qr/string/, return => 'hashcontainer' );

DESCRIPTION

datasearch - Search data structures

This function allows you to search arbitrarily large/complex data structures for particular elements. You can search hash keys, or hash/array values, for a number/string or regular expression. The datasearch function can return either the found hash keys, the found values (which could be data structures themselves) or the container of the key or value (which is always going to be a data structure)

By default, hash keys are searched, and the corresponding values are returned. To search hash or array values, specify SEARCH => 'values'. To search both values and keys, specify SEARCH => 'all'.

To find an exact match of a string, set FIND => 'string'. To use a regular expression use the qr operator: FIND => qr/^name.*/i FIND may also be a 2 element array, to search for a key-value pair.

To return the hash keys found (or the hash keys corresponding to searched values), specify RETURN => 'keys'. To return both keys and values specify RETURN => 'all'.

You can also return the data structure containing the found key/value.

To do that, specify RETURN => 'container'. This will return the immediate container, either a hash or an array reference. You can also choose to get the closest hash container (even if the value was inside an array) by specifying RETURN => 'hashcontainer'.

Similarly, you can return the closest array container (even though the value found was a hash value or hash key) by specifying RETURN => 'arraycontainer'

Also, you can get an outer container by doing RETURN => 'container:xyz' in which case the container returned would be a structure pointed to by key xyz (if found to contain the search element somewhere inside it). Please see the examples at the end of this document.

ARGUMENTS The following arguments are accepted (case-insensitively). The only mandatory arguments are DATA and FIND.

 data   => Reference of structure to search
 search => What elements to search: keys|values|all (default: keys)
 find   => Look for: string | qr/regex/ | [ key => value ]
 return => What to return: keys|values|all|
             container|hashcontainer|arraycontainer|container:key_name
 

RETURN VALUES

Returns a list of matching elements (could be strings or references to internal parts (hashes/arrays) of the data structure.

EXAMPLES

 my @results = datasearch( data => $ref, find => 'name' );
That will return all values pointed to by hash keys called 'name'

 my @results = datasearch( data => $ref, search => 'values',
     find => qr/alex/i, return => 'key' );
That will return all keys that point to strings that match "alex"
case insensitively.

 my @results = datasearch( data => $ref, search => 'keys',
     find => qr/_id$/, return => 'all' );
That will return all keys that end with "_id", and all values
pointed to by those keys.

 my @results = datasearch( data => $ref, return => 'container:myrecord',
                 find => [ suffix => 'Jr' ] )
That implies search=>'all', searches for a key 'suffix'
that has value 'Jr', and returns any matching hashes pointed to by a key
named myrecord (even if suffix is deep inside those hashes)