SYNOPSIS
use Data::Seek;
my $hash = {...};
my $seeker = Data::Seek->new(data => $hash);
my $result = $seeker->search(...);
my $data = $result->data;
DESCRIPTION
Data::Seek is used for querying complex data structures. This module
allows you to select and return specific node(s) in a hierarchical data
structure using a simple and intuitive query syntax. The results can be
returned as a list of values, or as a hash object in the same shape as
the original.
CONCEPT
The follow is a short and simple overview of the strategy and syntax
used by Data::Seek to query complex data structures. The overall idea
behind Data::Seek is to flatten/fold the data structure, reduce it by
applying a series patterns, then, unflatten/unfold and operate on the
new data structure. The introspection strategy is to flatten the data
structure producing a non-hierarchical data structure where its keys
represent endpoints (using dot-notation and colons to separate (and
denote) nested hash keys and array indices respectively) within the
structure.
ENCODING
During the processing of flattening a data structure with nested data,
the following data structure would be converted into a collection of
endpoint/value pairs.
{
'id' => 12345,
'patient' => {
'name' => {
'first' => 'Bob',
'last' => 'Bee'
}
},
'medications' => [{
'aceInhibitors' => [{
'name' => 'lisinopril',
'strength' => '10 mg Tab',
'dose' => '1 tab',
'route' => 'PO',
'sig' => 'daily',
'pillCount' => '#90',
'refills' => 'Refill 3'
}],
'antianginal' => [{
'name' => 'nitroglycerin',
'strength' => '0.4 mg Sublingual Tab',
'dose' => '1 tab',
'route' => 'SL',
'sig' => 'q15min PRN',
'pillCount' => '#30',
'refills' => 'Refill 1'
}],
}]
}
Given the aforementioned data structure, the following would be the
resulting flattened structure comprised of endpoint/value pairs.
{
'id' => 12345,
'medications:0.aceInhibitors:0.dose' => '1 tab',
'medications:0.aceInhibitors:0.name' => 'lisinopril',
'medications:0.aceInhibitors:0.pillCount' => '#90',
'medications:0.aceInhibitors:0.refills' => 'Refill 3',
'medications:0.aceInhibitors:0.route' => 'PO',
'medications:0.aceInhibitors:0.sig' => 'daily',
'medications:0.aceInhibitors:0.strength' => '10 mg Tab',
'medications:0.antianginal:0.dose' => '1 tab',
'medications:0.antianginal:0.name' => 'nitroglycerin',
'medications:0.antianginal:0.pillCount' => '#30',
'medications:0.antianginal:0.refills' => 'Refill 1',
'medications:0.antianginal:0.route' => 'SL',
'medications:0.antianginal:0.sig' => 'q15min PRN',
'medications:0.antianginal:0.strength' => '0.4 mg Sublingual Tab',
'patient.name.first' => 'Bob'
'patient.name.last' => 'Bee',
}
This structure provides the endpoint strings which will be matched
against using the querying strategy.
QUERYING
During the processing of querying the data structure, the criteria
(query expressions) are converted into a series of regular expressions
to be applied sequentially, filtering/reducing the endpoints and
producing a data set of matching nodes or throwing an exception
explaining the search failure.
* Node Expression
my $result = $seeker->search(...);
# given "id"
{ id => 12345 }
The node expression is a part of a criterion, which preforms an exact
match against a node in the data structure. It is a string which can
contain letters, numbers, and/or underscores.
* Step Expression
my $result = $seeker->search(...);
# given "patient.name.first"
{ patient => { name => { first => "Bob" } } }
# given "patient.name.last"
{ patient => { name => { last => "Bee" } } }
The step expression is a criterion, or part of a criterion, made up
of one or more node expressions separated using the period character,
which matches against nodes in the data structure. It is a string
which can contain letters, numbers, and/or underscores, separated
using periods.
* Index Expression
my $result = $seeker->search(...);
# given "medications:0.aceInhibitors:0.dose"
{ medications => [{ aceInhibitors => [{ dose => "1 tab" }] }] }
# given "medications:0.aceInhibitors:0.name"
{ medications => [{ aceInhibitors => [{ name => "lisinopril" }] }], }
# given "medications:0.aceInhibitors:0.pillCount"
{ medications => [{ aceInhibitors => [{ pillCount => "#90" }] }] }
The index expression is a criterion, or part of a criterion, having a
node expressions suffixed with a colon followed by a number denoting
that it should only match an array which has an index corresponding
to the numeric portion of the suffix. It is a string which can
contain letters, numbers, and/or underscores, suffixed with a
semi-colon followed by a number.
* Iterator Expression
my $result = $seeker->search(...);
# given "@medications.@aceInhibitors.dose"
{ medications => [{ aceInhibitors => [{ dose => "1 tab" }] }] }
# given "@medications.@aceInhibitors.name"
{ medications => [{ aceInhibitors => [{ name => "lisinopril" }] }], }
# given "@medications.@aceInhibitors.pillCount"
{ medications => [{ aceInhibitors => [{ pillCount => "#90" }] }] }
The iteration expression is a criterion, or part of a criterion,
having a node expressions preceded by an "at" character denoting that
the node expression should match all nodes in the data structure
which are mapped to array objects. It is a string which can contain
letters, numbers, and/or underscores, preceded by a single ampersand
character.
* Wildcard Expression
my $result = $seeker->search(...);
# given "*"
{ id => 12345 }
# given "*.*.first"
{ patient => { name => { first => "Bob" } } }
# given "*.*.last"
{ patient => { name => { last => "Bee" } } }
# given "patient.*.first"
{ patient => { name => { first => "Bob" } } }
# given "patient.*.last"
{ patient => { name => { last => "Bee" } } }
# given "@*.@*.pillCount"
{
medications => [{
aceInhibitors => [{ pillCount => "#90" }],
antianginal => [{ pillCount => "#30" }],
}],
}
The wildcard expression is a criterion, or part of a criterion, which
matches against a single node having a single "star" character match
and represent one node expression. It is a string which can contain
letters, numbers, underscores, and/or a single star character.
* Greedy-Wildcard Expression
my $result = $seeker->search(...);
# given "**.first"
{ patient => { name => { first => "Bob" } } }
# given "**.last"
{ patient => { name => { last => "Bee" } } }
# given "patient.**"
{ patient => { name => { first => "Bob", last => "Bee" } } }
# given "medications**.pillCount"
{
medications => [{
aceInhibitors => [{ pillCount => "#90" }],
antianginal => [{ pillCount => "#30" }],
}],
}
The greedy-wildcard expression is a criterion, or part of a
criterion, which matches against any multitude of nodes having a
double "star" character match and represent one or more of any
character. It is a string which can contain letters, numbers,
underscores, and/or a double star character.
$seeker->data;
$seeker->data({...});
The data structure to be introspected, must be a hash reference, which
is coerced into a Data::Object::Hash object.
$seeker->ignore;
$seeker->ignore(1);
Bypass exceptions thrown when a criterion is invalid or no data matches
can be found. This attribute must be an integer, which is coerced into
a Data::Object::Integer object.
my $search = $seeker->search('id', 'person.name.*');
Prepare a search object to use the supplied criteria and return a
search object. Introspection is triggered when the result method is
enacted. See Data::Seek::Search for usage information.
POD ERRORS
Hey! The above document had some coding errors, which are explained
below:
Around line 225:
Unknown directive: =attr
Around line 233:
Unknown directive: =attr
Around line 242:
Unknown directive: =method