<html><head><title>DBD::TreeData</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" >
</head>
<body class='pod'>
<!--
generated by Pod::Simple::HTML v3.20,
using Pod::Simple::PullParser v3.20,
under Perl v5.016000 at Wed Feb 27 21:45:25 2013 GMT.
If you want to change this HTML document, you probably shouldn't do that
by changing it directly. Instead, see about changing the calling options
to Pod::Simple::HTML, and/or subclassing Pod::Simple::HTML,
then reconverting this document from the Pod source.
When in doubt, email the author of Pod::Simple::HTML for advice.
See 'perldoc Pod::Simple::HTML' for more info.
-->
<!-- start doc -->
<a name='___top' class='dummyTopAnchor' ></a>
<h1><a class='u'
name="NAME"
>NAME</a></h1>
<p>DBD::TreeData - DBI driver for any abstract hash/array tree</p>
<h1><a class='u'
name="SYNOPSIS"
>SYNOPSIS</a></h1>
<pre> use DBI;
use JSON::Any;
use LWP::Simple;
# Example JSON object
my $json = get 'http://maps.googleapis.com/maps/api/geocode/json?address=1600+Pennsylvania+Ave+NW,+20500&region=us&language=en&sensor=false';
my $obj = JSON::Any->jsonToObj($json);
my $dbh = DBI->connect('dbi:TreeData:', '', '', {
tree_table_name => 'geocode',
tree_data => $obj,
});
# Informational dump
use Data::Dump;
dd ($dbh->table_info->fetchall_arrayref);
dd (map { [ @{$_}[2 .. 6] ] } @{
$dbh->column_info('','','','')->fetchall_arrayref
});
# DBIC dump
use DBIx::Class::Schema::Loader 'make_schema_at';
make_schema_at(
'My::Schema', {
debug => 1,
dump_directory => './lib',
},
[ 'dbi:TreeData:geocode', '', '', { tree_data => $obj } ],
);</pre>
<h1><a class='u'
name="DESCRIPTION"
>DESCRIPTION</a></h1>
<p>DBD::TreeData provides a DBI driver to translate any sort of tree-based data set (encapsulated in a Perl object) into a flat set of tables, complete with real SQL functionality. This module utilizes <a href="http://search.cpan.org/perldoc?DBD%3A%3AAnyData" class="podlinkpod"
>DBD::AnyData</a> to create the new tables, which uses <a href="http://search.cpan.org/perldoc?SQL%3A%3AStatement" class="podlinkpod"
>SQL::Statement</a> to support the SQL parsing. (Any caveats with those modules likely applies here.)</p>
<p>This module can be handy to translate JSON, XML, YAML, and many other tree formats to be used in class sets like <a href="http://search.cpan.org/perldoc?DBIx%3A%3AClass" class="podlinkpod"
>DBIx::Class</a>. Unlike <a href="http://search.cpan.org/perldoc?DBD%3A%3AAnyData" class="podlinkpod"
>DBD::AnyData</a>, the format of the data doesn't have to be pre-flattened, and will be spread out into multiple tables.</p>
<p>Also, this driver fully supports all of the <code>*_info</code> methods, making it ideal to shove into modules like <a href="http://search.cpan.org/perldoc?DBIx%3A%3AClass%3A%3ASchema%3A%3ALoader" class="podlinkpod"
>DBIx::Class::Schema::Loader</a>. (The <code>table_info</code> and <code>column_info</code> filters use REs with begin/end bounds pre-set.)</p>
<h1><a class='u'
name="CONNECT_ATTRIBUTES"
>CONNECT ATTRIBUTES</a></h1>
<h2><a class='u'
name="tree_data"
>tree_data</a></h2>
<p>The actual tree object. Of course, this attribute is required.</p>
<h2><a class='u'
name="tree_table_name"
>tree_table_name</a></h2>
<p>The name of the starting table. Not required, but recommended. If not specified, defaults to 'tree_data', or the value of the driver DSN string (after the <code>dbi:TreeData:</code> part).</p>
<h2><a class='u'
name="tree_debug"
>tree_debug</a></h2>
<p>Boolean. Print debug information while translating the tree.</p>
<h2><a class='u'
name="tree_rename_tables"
>tree_rename_tables</a></h2>
<p>Hashref of table names. If you don't like the name of an auto-created table, you can rename them while the database is being built. Within the hashref, the keys/values are the old/new names, respectively.</p>
<h1><a class='u'
name="TRANSLATION_BEHAVIOR"
>TRANSLATION BEHAVIOR</a></h1>
<p>The tree translation into flat tables is done using a recursive descent algorithm. It starts with a check of the current node's reference type, which dictates how it interprets the children. The goal is to create a fully <a href="http://en.wikipedia.org/wiki/Fourth_normal_form" class="podlinkurl"
>4NF</a> database from the tree.</p>
<p>Arrays are interpreted as a list of rows, and typically get rolled up into "group" tables. Hashes are interpreted as a list of column names and values. Non-references are considered values. Scalar refs and VStrings are de-referenced first. Other types of refs are processed as best as possible, but the driver will complain. (Code ref blocks are currently NOT executed and discarded.)</p>
<p>Nested arrays will create nested group tables with different suffixes, like <code>matrix</code>, <code>cube</code>, and <code>hypercube</code>. If it has to go beyond that (and you really shouldn't have structures like that), it'll start complaining (sarcastically).</p>
<p>In almost all cases, the table name is derived from a previous key. Table names also use <a href="http://search.cpan.org/perldoc?Lingua%3A%3AEN%3A%3AInflect%3A%3APhrase" class="podlinkpod"
>Lingua::EN::Inflect::Phrase</a> to create pluralized names. Primary IDs will have singular names with a <code>_id</code> suffix.</p>
<p>For example, this tree:</p>
<pre> address_components => [
{
long_name => 1600,
short_name => 1600,
types => [ "street_number" ]
},
{
long_name => "President's Park",
short_name => "President's Park",
types => [ "establishment" ]
},
{
long_name => "Pennsylvania Avenue Northwest",
short_name => "Pennsylvania Ave NW",
types => [ "route" ]
},
{
long_name => "Washington",
short_name => "Washington",
types => [ "locality", "political" ]
},
... etc ...,
],</pre>
<p>Would create the following tables:</p>
<pre> <main_table>
address_component_groups
address_components
type_groups
types</pre>
<p>In this case, <code>address_components</code> has most of the columns and data, but it also has a tie to an ID of <code>address_component_groups</code>.</p>
<p>Since <code>types</code> points to an array, it will have its own dedicated table. That table would have data like:</p>
<pre> type_id │ type
════════╪════════════════
1 │ street_number
2 │ establishment
3 │ route
4 │ locality
5 │ political
... │ ...</pre>
<p>Most of the <code>type_groups</code> table would be a 1:1 match. However, the last component entry has more than one value in the <code>types</code> array, so the <code>type_group_id</code> associated to that component would have multiple entries (4 & 5). Duplicate values are also tracked, so that IDs are reused.</p>
<h1><a class='u'
name="CAVEATS"
>CAVEATS</a></h1>
<h2><a class='u'
name="DBI_/_DBD::AnyData_Conflict"
>DBI / DBD::AnyData Conflict</a></h2>
<p>As of the time of this writing, the latest version of <a href="http://search.cpan.org/perldoc?DBI" class="podlinkpod"
>DBI</a> (1.623) and the latest version of <a href="http://search.cpan.org/perldoc?DBD%3A%3AAnyData" class="podlinkpod"
>DBD::AnyData</a> (0.110) do not work together. Since TreeData relies on <a href="http://search.cpan.org/perldoc?DBD%3A%3AAnyData" class="podlinkpod"
>DBD::AnyData</a> for table creation, you will need to downgrade to <a href="http://search.cpan.org/perldoc?DBI" class="podlinkpod"
>DBI</a> 1.622 to use this driver, until a new version of <a href="http://search.cpan.org/perldoc?DBD%3A%3AAnyData" class="podlinkpod"
>DBD::AnyData</a> comes out.</p>
<h1><a class='u'
name="AVAILABILITY"
>AVAILABILITY</a></h1>
<p>The project homepage is <a href="https://github.com/SineSwiper/DBD-TreeData/wiki" class="podlinkurl"
>https://github.com/SineSwiper/DBD-TreeData/wiki</a>.</p>
<p>The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <a href="http://www.perl.com/CPAN/" class="podlinkurl"
>http://www.perl.com/CPAN/</a> to find a CPAN site near you, or see <a href="https://metacpan.org/module/DBD::TreeData/" class="podlinkurl"
>https://metacpan.org/module/DBD::TreeData/</a>.</p>
<h1><a class='u'
name="SUPPORT"
>SUPPORT</a></h1>
<h2><a class='u'
name="Internet_Relay_Chat"
>Internet Relay Chat</a></h2>
<p>You can get live help by using IRC ( Internet Relay Chat ). If you don't know what IRC is, please read this excellent guide: <a href="http://en.wikipedia.org/wiki/Internet_Relay_Chat" class="podlinkurl"
>http://en.wikipedia.org/wiki/Internet_Relay_Chat</a>. Please be courteous and patient when talking to us, as we might be busy or sleeping! You can join those networks/channels and get help:</p>
<ul>
<li>irc.perl.org
<p>You can connect to the server at 'irc.perl.org' and join this channel: #dbi then talk to this person for help: SineSwiper.</p>
</li>
</ul>
<h2><a class='u'
name="Bugs_/_Feature_Requests"
>Bugs / Feature Requests</a></h2>
<p>Please report any bugs or feature requests via <a href="http://search.cpan.org/perldoc?GitHub" class="podlinkpod"
><a href="https://github.com/SineSwiper/DBD-TreeData/issues" class="podlinkurl"
>https://github.com/SineSwiper/DBD-TreeData/issues</a></a>.</p>
<h1><a class='u'
name="AUTHOR"
>AUTHOR</a></h1>
<p>Brendan Byrd <BBYRD@CPAN.org></p>
<h1><a class='u'
name="COPYRIGHT_AND_LICENSE"
>COPYRIGHT AND LICENSE</a></h1>
<p>This software is Copyright (c) 2013 by Brendan Byrd.</p>
<p>This is free software, licensed under:</p>
<pre> The Artistic License 2.0 (GPL Compatible)</pre>
<!-- end doc -->
</body></html>