Ron Savage > DBIx-Hash2Table-2.04 > DBIx::Hash2Table

Download:
DBIx-Hash2Table-2.04.tgz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 2.04   Source  

NAME ^

DBIx::Hash2Table - Save a hash into a database table

Synopsis ^

        #!/usr/bin/perl

        my(%entity)     = create_a_hash(...);
        my($dbh)        = DBI -> connect(...);
        my($table_name) = 'entity';

        # Cope with MySQL-specific SQL.
        eval{$dbh -> do("drop table if exists $table_name")};

        # Cope with non-existant table.
        eval{$dbh -> do("drop table $table_name")};

        my($sql) = "create table $table_name (id int, parent_id int, " .
                                "code char(5), name varchar(255), _url varchar(255) )";

        $dbh -> do($sql);

        DBIx::Hash2Table -> new
        (
                hash_ref   => \%entity,
                dbh        => $dbh,
                table_name => $table_name,
                columns    => ['id', 'parent_id', 'name'],
#               extras     => ['code']
#               extras     => ['_url', 'code']
#               extras     => ['code', '_url']
        ) -> insert();

Description ^

DBIx::Hash2Table is a pure Perl module.

This module saves a hash ref into an existing database table of at least 3 columns.

Each row in the table will consist of these 3 columns, at least: id (row number), parent's id, and the value of a hash key.

You specify the names of these 3 columns in the constructor's array ref parameter called columns.

I suggest you display the script examples/test-hash2table.pl in another window while reading the following.

In fact, you are strongly recommended to run the demo now, and examine the resultant database table, before reading further. Then, remove the comment '#' from one of lines 84 .. 86 and run it again.

In the hash ref being saved to the database, hash keys normally point to hash refs. This nested structure is preserved when the data is written to the table.

That is, the hash keys which point to hash refs become parents in the database, and keys within the hash ref being pointed to may become children of this parent.

I say 'may' because inside the hash ref you can have hash keys which are column names, and you can have hash keys which are just 'normal' hash keys, ie not column names.

If the nested hash key is a column name, then it should point to a non-ref, ie a number or a string. In that case, you can optionally have the value it points to written to the table.

You activate this feature by putting the names of the columns you wish to have saved in the database into the constructor's array ref parameter called extras.

In the example code, such a nested hash keys are called code, _run_mode and _url, and at lines 84 .. 86 you can control whether or not any or all of these values are written to the table.

If the nested hash key is not a column name, then it should point to a hash ref, and when its turn comes, it too will be written to the table.

In more detail, the 3 mandatory columns in each row of the database are:

Distributions ^

This module is available both as a Unix-style distro (*.tgz) and an ActiveState-style distro (*.ppd). The latter is shipped in a *.zip file.

See http://savage.net.au/Perl-modules.html for details.

See http://savage.net.au/Perl-modules/html/installing-a-module.html for help on unpacking and installing each type of distro.

Constructor and initialization ^

new(...) returns a DBIx::Hash2Table object.

This is the class's contructor.

Parameters:

Method: new(...) ^

Returns an object of type DBIx::Hash2Table.

See above, in the section called 'Constructor and initialization'.

Method: insert() ^

Returns nothing.

Calling insert() actually executes the SQL insert statement, and recursively writes all hash keys to the table.

FAQ ^

Q: What is the point of this module?

A: To be able to save a hash to permanent storage via a database rather than via a file.

Q: Can your other module DBIx::Table2Hash reconstruct a hash written by this module?

A: No. Sorry. Perhaps one day.

Author ^

DBIx::Hash2Table was written by Ron Savage <ron@savage.net.au> in 2003.

Home page: http://savage.net.au/index.html

Copyright ^

Australian copyright (c) 2003, Ron Savage. All Programs of mine are 'OSI Certified Open Source Software'; you can redistribute them and/or modify them under the terms of The Artistic License, a copy of which is available at: http://www.opensource.org/licenses/index.html

syntax highlighting: