blib/lib/Data/Search.pm

filter: Statementstmt 18.0% 13 / 72 Branchbran 0.0% 0 / 72 Conditioncond 0.0% 0 / 69 MC/DCmcdc 0.0% 0 / 37 Subroutinesub 50.0% 3 / 6 Podpod 50.0% 1 / 2 totaltotal 6.5% 17 / 258 CC 64 SCAR 70.2
CC
64
Cov
6%
_datasearch
1722.0
datasearch
342.0
get_args
56.0
CRAP 1118.2
↑ Summary
1 package Data::Search;
2 1 ▶use 5.005;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
5 1 require Exporter;
6 1 our $VERSION = '0.03';
7 1 our @ISA = qw(Exporter);
8 1 our @EXPORT= qw(datasearch);
9  
10 =head1 NAME
11  
12 Data::Search - Data structure search
13  
14 =head1 SYNOPSIS
15  
16 use Data::Search;
17  
18 $data = { ... };
19 @results = datasearch( data => $data, search => 'values',
20 find => qr/string/, return => 'hashcontainer' );
21  
22 =head1 DESCRIPTION
23  
24 =head2 datasearch - Search data structures
25  
26 This function allows you to search arbitrarily large/complex
27 data structures for particular elements.
28 You can search hash keys, or hash/array values, for a number/string
29 or regular expression.
30 The datasearch function can return either the found hash keys, the found
31 values (which could be data structures themselves) or the container
32 of the key or value (which is always going to be a data structure)
33  
34 By default, hash keys are searched, and the corresponding values are returned.
35 To search hash or array values, specify SEARCH => 'values'.
36 To search both values and keys, specify SEARCH => 'all'.
37  
38 To find an exact match of a string, set FIND => 'string'. To use a regular
39 expression use the qr operator: FIND => qr/^name.*/i
40 FIND may also be a 2 element array, to search for a key-value pair.
41  
42 To return the hash keys found (or the hash keys corresponding to
43 searched values), specify RETURN => 'keys'.
44 To return both keys and values specify RETURN => 'all'.
45  
46 You can also return the data structure containing the found key/value.
47  
48 To do that, specify RETURN => 'container'. This will return the immediate
49 container, either a hash or an array reference. You can also choose to
50 get the closest hash container (even if the value was inside an array)
51 by specifying RETURN => 'hashcontainer'.
52  
53 Similarly, you can return the closest array container (even though the
54 value found was a hash value or hash key) by specifying
55 RETURN => 'arraycontainer'
56  
57 Also, you can get an outer container by doing RETURN => 'container:xyz'
58 in which case the container returned would be a structure pointed to
59 by key xyz (if found to contain the search element somewhere inside it).
60 Please see the examples at the end of this document.
61  
62 ARGUMENTS
63 The following arguments are accepted (case-insensitively).
64 The only mandatory arguments are DATA and FIND.
65  
66 data => Reference of structure to search
67 search => What elements to search: keys|values|all (default: keys)
68 find => Look for: string | qr/regex/ | [ key => value ]
69 return => What to return: keys|values|all|
70 container|hashcontainer|arraycontainer|container:key_name
71
72 RETURN VALUES
73  
74 Returns a list of matching elements (could be strings or references
75 to internal parts (hashes/arrays) of the data structure.
76  
77 EXAMPLES
78  
79 my @results = datasearch( data => $ref, find => 'name' );
80 That will return all values pointed to by hash keys called 'name'
81  
82 my @results = datasearch( data => $ref, search => 'values',
83 find => qr/alex/i, return => 'key' );
84 That will return all keys that point to strings that match "alex"
85 case insensitively.
86  
87 my @results = datasearch( data => $ref, search => 'keys',
88 find => qr/_id$/, return => 'all' );
89 That will return all keys that end with "_id", and all values
90 pointed to by those keys.
91  
92 my @results = datasearch( data => $ref, return => 'container:myrecord',
93 find => [ suffix => 'Jr' ] )
94 That implies search=>'all', searches for a key 'suffix'
95 that has value 'Jr', and returns any matching hashes pointed to by a key
96 named myrecord (even if suffix is deep inside those hashes)
97  
98 =cut
99  
100 0 ▶sub datasearch {
Subroutine datasearch: not called CC=18 SCAR=58.3
Pod documented
101 0 my $args = get_args( [qw(FIND SEARCH RETURN DATA)], @_ );
102  
103 0 ▶ die "FIND argument is required" unless defined $args->{FIND};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args->{"FIND"} 0 0 0
104 0 ▶ die "DATA argument is required" unless defined $args->{DATA};
Branch: 1 branch
BranchTrueFalseTotal
unless defined $args->{"DATA"} 0 0 0
105  
106 my $sk = 1 if !$args->{SEARCH} || $args->{SEARCH} =~ /key|all/
107 0 ▶ or ref($args->{FIND}) eq 'ARRAY';
Branch: 1 branch
BranchTrueFalseTotal
if not $args->{"SEARCH"} or $args->{"SEARCH"} =~ /key|all/ or ref $args->{"FIND"} eq "ARRAY" 0 0 0
Condition0%0/6
not $args->{"SEARCH"} or $args->{"SEARCH"} =~ /key|all/ or ref $args->{"FIND"} eq "ARRAY"
l!l&&r!l&&!r
000
not $args->{"SEARCH"} or $args->{"SEARCH"} =~ /key|all/
l!l&&r!l&&!r
000
MC/DC0%0/3
not $args->{"SEARCH"} or $args->{"SEARCH"} =~ /key|all/ or ref $args->{"FIND"} eq "ARRAY"
not $args->{"SEARCH"} $args->{"SEARCH"} =~ /key|all/ ref $args->{"FIND"} eq "ARRAY"
Truth table0%0/4
not(A) or B or C
A= not $args->{"SEARCH"}B= $args->{"SEARCH"} =~ /key|all/C= ref $args->{"FIND"} eq "ARRAY"
ABCresult
1XX1
01X1
0011
0000
108 0 ▶ my $sv = 1 if $args->{SEARCH} && $args->{SEARCH} =~ /value|all/;
Branch: 1 branch
BranchTrueFalseTotal
if $args->{"SEARCH"} and $args->{"SEARCH"} =~ /value|all/ 0 0 0
Condition0%0/3
$args->{"SEARCH"} and $args->{"SEARCH"} =~ /value|all/
!ll&&!rl&&r
000
MC/DC0%0/2
$args->{"SEARCH"} and $args->{"SEARCH"} =~ /value|all/
$args->{"SEARCH"} $args->{"SEARCH"} =~ /value|all/
Truth table0%0/3
A and B
A= $args->{"SEARCH"}B= $args->{"SEARCH"} =~ /value|all/
ABresult
0X0
100
111
109  
110 0 ▶ my $rv = 1 if !$args->{RETURN} || $args->{RETURN} =~ /value|all/;
Branch: 1 branch
BranchTrueFalseTotal
if not $args->{"RETURN"} or $args->{"RETURN"} =~ /value|all/ 0 0 0
Condition0%0/3
not $args->{"RETURN"} or $args->{"RETURN"} =~ /value|all/
l!l&&r!l&&!r
000
MC/DC0%0/2
not $args->{"RETURN"} or $args->{"RETURN"} =~ /value|all/
not $args->{"RETURN"} $args->{"RETURN"} =~ /value|all/
Truth table0%0/3
not(A) or B
A= not $args->{"RETURN"}B= $args->{"RETURN"} =~ /value|all/
ABresult
1X1
011
000
111 0 ▶ my $rk = 1 if $args->{RETURN} && $args->{RETURN} =~ /key|all/;
Branch: 1 branch
BranchTrueFalseTotal
if $args->{"RETURN"} and $args->{"RETURN"} =~ /key|all/ 0 0 0
Condition0%0/3
$args->{"RETURN"} and $args->{"RETURN"} =~ /key|all/
!ll&&!rl&&r
000
MC/DC0%0/2
$args->{"RETURN"} and $args->{"RETURN"} =~ /key|all/
$args->{"RETURN"} $args->{"RETURN"} =~ /key|all/
Truth table0%0/3
A and B
A= $args->{"RETURN"}B= $args->{"RETURN"} =~ /key|all/
ABresult
0X0
100
111
112 my $rc = $args->{RETURN} && $args->{RETURN} =~ /container/
113 0 ▶ ? $args->{RETURN} : 0;
Branch: 1 branch
BranchTrueFalseTotal
$args->{'RETURN'} && $args->{'RETURN'} =~ /container/ ? : 0 0 0
Condition0%0/3
$args->{"RETURN"} and $args->{"RETURN"} =~ /container/
!ll&&!rl&&r
000
MC/DC0%0/2
$args->{"RETURN"} and $args->{"RETURN"} =~ /container/
$args->{"RETURN"} $args->{"RETURN"} =~ /container/
Truth table0%0/3
A and B
A= $args->{"RETURN"}B= $args->{"RETURN"} =~ /container/
ABresult
0X0
100
111
114  
115 0 my (@results, @refs, $container);
116 0 @results = _datasearch( $args->{DATA}, $args->{FIND}, $sk, $sv, $rv, $rk,
117 $rc, \@refs, undef, undef, undef, 0 );
118  
119 0 my @unique;
120 0 foreach my $p ( @results ) { # Weed out duplicate references
121 0 ▶ push @unique, $p unless ref($p) and grep { ref && $_ == $p } @unique;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $p and grep {ref $_ and $_ == $p;} @unique 0 0 0
Condition0%0/6
ref $p and grep {ref $_ and $_ == $p;} @unique
!ll&&!rl&&r
000
ref $_ && $_ == $p
!ll&&!rl&&r
000
MC/DC0%0/2
ref $p and grep {ref $_ and $_ == $p;} @unique
ref $p grep {ref $_ and $_ == $p;} @unique
MC/DC0%0/2
ref $_ && $_ == $p
ref $_ $_ == $p
Truth table0%0/3
A and B
A= ref $pB= grep {ref $_ and $_ == $p;} @unique
ABresult
0X0
100
111
Truth table0%0/3
A && B
A= ref $_B= $_ == $p
ABresult
0X0
100
111
122 }
123 0 return @unique;
124 } ## end sub datasearch
125  
126 # Internal recursive function called by datasearch
127 0 ▶sub _datasearch {
Subroutine _datasearch: not called CC=41 SCAR=74.5
128 0 my ($p, $f, $sk, $sv, $rv, $rk, $rc, $refs, $container, $key, $rr, $depth)
129 = @_;
130 # print "DEPTH IN=$depth\n";
131 0 my ($root) = $rc =~ /:(.+)/;
132 0 ▶ if ( ref($p) ) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $p) 0 0 0
133 0 ▶ if ( grep { $p == $_ } @$refs ) {
Branch: 1 branch
BranchTrueFalseTotal
if (grep {$p == $_;} @$refs) 0 0 0
134 0 warn "Skipping duplicate reference to $p";
135 0 return;
136 }
137 0 push @$refs, $p;
138 }
139  
140 0 my @results;
141 0 ▶ if ( ref($p) && $p =~ /HASH/ ) {
Branch: 3 branches
BranchTrueFalseTotal
if (ref $p and $p =~ /HASH/) { } 0 0 0
elsif (ref $p and $p =~ /ARRAY/) { } 0 0 0
elsif (not ref $p and defined $p and $sv and ref $f eq 'Regexp' && $p =~ /$f/ || $p eq $f) { } 0 0 0
Condition0%0/3
ref $p and $p =~ /HASH/
!ll&&!rl&&r
000
MC/DC0%0/2
ref $p and $p =~ /HASH/
ref $p $p =~ /HASH/
Truth table0%0/3
A and B
A= ref $pB= $p =~ /HASH/
ABresult
0X0
100
111
142 0 ▶ $container = $p unless $rc =~ /array/;
Branch: 1 branch
BranchTrueFalseTotal
unless $rc =~ /array/ 0 0 0
143 0 foreach my $k ( keys %$p ) {
144 0 ▶ $rr = $p->{$k} if $root && $root eq $k;
Branch: 1 branch
BranchTrueFalseTotal
if $root and $root eq $k 0 0 0
Condition0%0/3
$root and $root eq $k
!ll&&!rl&&r
000
MC/DC0%0/2
$root and $root eq $k
$root $root eq $k
Truth table0%0/3
A and B
A= $rootB= $root eq $k
ABresult
0X0
100
111
145 0 ▶ my ($f1, $f2) = ref($f) eq 'ARRAY' ? ($f->[0], $f->[1]) : $f;
Branch: 1 branch
BranchTrueFalseTotal
ref $f eq 'ARRAY' ? : 0 0 0
146 0 ▶ if ( $sk and ref($f1) eq 'Regexp' && $k =~ /$f1/ || $k eq $f1 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($sk and ref $f1 eq "Regexp" && $k =~ /$f1/ || $k eq $f1) 0 0 0
Condition0%0/9
$sk and ref $f1 eq "Regexp" && $k =~ /$f1/ || $k eq $f1
!ll&&!rl&&r
000
ref $f1 eq "Regexp" and $k =~ /$f1/ or $k eq $f1
l!l&&r!l&&!r
000
ref $f1 eq "Regexp" and $k =~ /$f1/
!ll&&!rl&&r
000
MC/DC0%0/4
$sk and ref $f1 eq "Regexp" && $k =~ /$f1/ || $k eq $f1
$sk ref $f1 eq "Regexp" $k =~ /$f1/ $k eq $f1
Truth table0%0/6
A and B and C or D
A= $skB= ref $f1 eq "Regexp"C= $k =~ /$f1/D= $k eq $f1
ABCDresult
0XXX0
10X00
11000
111X1
10X11
11011
147 0 ▶ if ( ! defined $f2 or
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $f2 or (ref $f2 eq "Regexp" and $p->{$k} =~ /$f2/ or $p->{$k} eq $f2)) 0 0 0
Condition0%0/9
not defined $f2 or (ref $f2 eq "Regexp" and $p->{$k} =~ /$f2/ or $p->{$k} eq $f2)
l!l&&r!l&&!r
000
ref $f2 eq "Regexp" and $p->{$k} =~ /$f2/ or $p->{$k} eq $f2
l!l&&r!l&&!r
000
ref $f2 eq "Regexp" and $p->{$k} =~ /$f2/
!ll&&!rl&&r
000
MC/DC0%0/4
not defined $f2 or (ref $f2 eq "Regexp" and $p->{$k} =~ /$f2/ or $p->{$k} eq $f2)
not defined $f2 ref $f2 eq "Regexp" $p->{$k} =~ /$f2/ $p->{$k} eq $f2
Truth table0%0/6
not(A) or B and C or D
A= not defined $f2B= ref $f2 eq "Regexp"C= $p->{$k} =~ /$f2/D= $p->{$k} eq $f2
ABCDresult
1XXX1
011X1
00X11
01011
00X00
01000
148 ref($f2) eq 'Regexp' && $p->{$k} =~ /$f2/
149 || $p->{$k} eq $f2 ) {
150 0 ▶ if ( $rc ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rc) { } 0 0 0
151 0 ▶ if ( $root ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($root) { } 0 0 0
152 0 ▶ push @results, $rr if $rr;
Branch: 1 branch
BranchTrueFalseTotal
if $rr 0 0 0
153 } else {
154 0 push @results, $container;
155 }
156 } else {
157 0 ▶ push @results, $k if $rk;
Branch: 1 branch
BranchTrueFalseTotal
if $rk 0 0 0
158 0 ▶ push @results, $p->{$k} if $rv;
Branch: 1 branch
BranchTrueFalseTotal
if $rv 0 0 0
159 }
160 }
161 }
162 0 ▶ if ( my @r = _datasearch( $p->{$k}, $f, $sk, $sv, $rv, $rk,
Branch: 1 branch
BranchTrueFalseTotal
if (my(@r) = _datasearch($p->{$k}, $f, $sk, $sv, $rv, $rk, $rc, $refs, $container, $k, $rr, $depth + 1)) 0 0 0
163 $rc, $refs, $container, $k, $rr, $depth+1 ) ) {
164 0 push @results, @r;
165 }
166 }
167 ▶ } elsif ( ref($p) && $p =~ /ARRAY/ ) {
Condition0%0/3
ref $p and $p =~ /ARRAY/
!ll&&!rl&&r
000
MC/DC0%0/2
ref $p and $p =~ /ARRAY/
ref $p $p =~ /ARRAY/
Truth table0%0/3
A and B
A= ref $pB= $p =~ /ARRAY/
ABresult
0X0
100
111
168 0 ▶ $container = $p unless $rc =~ /hash/;
Branch: 1 branch
BranchTrueFalseTotal
unless $rc =~ /hash/ 0 0 0
169 0 foreach ( @$p ) {
170 0 ▶ if ( my @r = _datasearch( $_, $f, $sk, $sv, $rv, $rk,
Branch: 1 branch
BranchTrueFalseTotal
if (my(@r) = _datasearch($_, $f, $sk, $sv, $rv, $rk, $rc, $refs, $container, $key, $rr, $depth + 1)) 0 0 0
171 $rc, $refs, $container, $key, $rr, $depth+1 ) ) {
172 0 push @results, @r;
173 }
174 }
175 ▶ } elsif ( !ref($p) && defined $p && $sv and
Condition0%0/15
not ref $p and defined $p and $sv and ref $f eq "Regexp" && $p =~ /$f/ || $p eq $f
!ll&&!rl&&r
000
not ref $p and defined $p and $sv
!ll&&!rl&&r
000
not ref $p and defined $p
!ll&&!rl&&r
000
ref $f eq "Regexp" and $p =~ /$f/ or $p eq $f
l!l&&r!l&&!r
000
ref $f eq "Regexp" and $p =~ /$f/
!ll&&!rl&&r
000
MC/DC0%0/6
not ref $p and defined $p and $sv and ref $f eq "Regexp" && $p =~ /$f/ || $p eq $f
not ref $p defined $p $sv ref $f eq "Regexp" $p =~ /$f/ $p eq $f
Truth table0%0/8
not(A) and B and C and D and E or F
A= not ref $pB= defined $pC= $svD= ref $f eq "Regexp"E= $p =~ /$f/F= $p eq $f
ABCDEFresult
0XXXXX0
10XXXX0
110XXX0
1110X00
1111000
11111X1
1110X11
1111011
176 ref($f) eq 'Regexp' && $p =~ /$f/ || $p eq $f ) {
177 0 ▶ if ( $rc ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($rc) { } 0 0 0
178 0 ▶ if ( $root ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($root) { } 0 0 0
179 0 ▶ push @results, $rr if $rr;
Branch: 1 branch
BranchTrueFalseTotal
if $rr 0 0 0
180 } else {
181 0 push @results, $container;
182 }
183 } else {
184 0 ▶ push @results, $p if $rv;
Branch: 1 branch
BranchTrueFalseTotal
if $rv 0 0 0
185 0 ▶ push @results, $key if $rk && defined $key;
Branch: 1 branch
BranchTrueFalseTotal
if $rk and defined $key 0 0 0
Condition0%0/3
$rk and defined $key
!ll&&!rl&&r
000
MC/DC0%0/2
$rk and defined $key
$rk defined $key
Truth table0%0/3
A and B
A= $rkB= defined $key
ABresult
0X0
100
111
186 }
187 }
188 # print "DEPTH OUT=$depth\n";
189 0 return @results;
190 } ## end sub datasearch
191  
192 # Return a hash of named parameters (keys converted to upper case)
193 0 ▶sub get_args {
Subroutine get_args: not called CC=7 SCAR=40.3
Pod undocumented
194 # Called as get_args(@_) or as get_args( [arg, arg2...], @_ )
195 0 ▶ my $valid_arg_list = ( ref($_[0]) eq 'ARRAY' ? shift : '' );
Branch: 1 branch
BranchTrueFalseTotal
ref $_[0] eq 'ARRAY' ? : 0 0 0
196  
197 0 ▶ die "get_args got odd number of arguments"
Branch: 1 branch
BranchTrueFalseTotal
unless @_ / 2 == int @_ / 2 0 0 0
198 unless (@_/2 == int(@_/2));
199  
200 0 my $args;
201 0 ▶ for ( my $n = 0 ; $n < $#_ ; $n += 2 ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($n < $#_) 0 0 0
202 0 $args->{ uc $_[$n] } = $_[ $n + 1 ];
203 }
204  
205 # Do argument checking, if list of valid arguments was given
206 0 ▶ if ($valid_arg_list) {
Branch: 1 branch
BranchTrueFalseTotal
if ($valid_arg_list) 0 0 0
207 0 foreach my $arg (keys %$args) {
208 0 ▶ die "get_args: Argument \"$arg\" is invalid"
Branch: 1 branch
BranchTrueFalseTotal
unless grep /^\Q$arg\E$/, @$valid_arg_list 0 0 0
209 unless grep (/^\Q$arg\E$/, @$valid_arg_list);
210 }
211 }
212 0 return $args;
213 }
214  
215 1 1;
216  
↑ Summary