=head1 NAME

DBIx::Struct - convenience SQL functions with Class::Struct-like row objects

=head1 SYNOPSIS

    use DBIx::Struct;

    DBIx::Struct::connect($data_source, $username, $auth);

    my $row = one_row("table", $idField);

    print $row->field;

    $row->field('new data');

    $row->update;

    my $rows = all_rows("table", {field => "some data"});

    print $rows->[0]->field;

=head1 DESCRIPTION

Makes SQL queries from Perl data structures. It uses L<SQL::Abstract> 
module to parse "where" and "order by" structures. This module does B<not> 
try to map all possible SQL features to Perl structures but it greatly
simplifies really simple and most often used scenarios. Complex queries
are also possible, but sometimes it'd better to use real SQL.

=head1 USAGE

Suppose you have tables

 session:
   session_key text unique,
   id_client integer references client(id),
   expires timestamp
 
 client
   id serial primary key,
   name text
   
 client_balance
   balance decimal(14,2),
   currency text, 
   id_client integer references client(id),
   unique(currency, id_client)
   
How to access this structure

 # get session object
   my $session = one_row("session", {session => $input->{session}, ip => $input->{ip}});
 # throw exception when there's no session
   NoUser->throw("User is not logged in or does not exist") unless defined $session;
 # get client's row
   my $client = $session->Client;
 # strip microseconds part
   $client->filter_timestamp;
 # throw exception if client is blocked
   BlkUser->throw   if $client->state eq 'blocked';
 # set expire date
   $session->expire(\"now() + interval '2 day'");
 # update session
   $session->update;
 # get usd client's balance from client_balance
   my $usd_balance = $client->refClientBalance(currency => "USD");
 
To use SQL 

 use DBIx::Struct qw(connector);
 # ... 
 my $name;
 connector->run(sub {
   ($name) = $_->selectrow_array('select name from client join '
     . 'session on (id = id_client) where session_key = ?', undef, $input->{session})
   }
 );