package Tao::DBI::db;

use 5.006;
use strict;
use warnings;

require Exporter;

our @ISA = qw(Exporter);
our @EXPORT = qw();

our $VERSION = '0.0008';

use DBI;
use Tao::DBI::st;
use Tao::DBI::st_deep;

# the instance variables:
# DBH
# NAME


# usage:
# $dbh = new Tao::DBI::db($args);
sub new {
  my ($proto, $args) = @_;
  my $class = ref($proto) || $proto;
  my $obj = bless {}, $class;
  $obj->initialize($args);
  return $obj;
}

# usage:
#   $dbh->initialize($args);
# where $args is
# { name => , dsn|url => , user => , password =>, options passed to DBI->connect }
#
#
# protected
sub initialize {
  my ($self, $args) = @_;

  $self->{NAME} = $args->{name};
  $self->{URL} = $args->{dsn} || $args->{url};
  $self->{USER} = $args->{user};
  $self->{PASS} = $args->{password};
  unless (exists $args->{FetchHashKeyName}) {
      $args->{FetchHashKeyName} = 'NAME_lc';
  }
  unless (exists $args->{AutoCommit}) {
      $args->{AutoCommit} = 0;
  }

  my $dbh = DBI->connect($self->{URL},
                         $self->{USER},
                         $self->{PASS},
                         $args); # remaining arguments can be passed to DBI->connect (needs improving!)
  if ($dbh) {
    $self->{DBH} = $dbh;
  } else {
    die "Can't establish connection '$self->{NAME}': $DBI::errstr\n";
  }
}

# $stmt = $dbh->prepare($sql, $args);
# $stmt = $dbh->prepare($args); # $args is hashref
sub prepare {
  my $self = shift;
  my $sql;
  $sql = shift unless ref $_[0]; # first non-ref arg
  my $args = shift || {};
  my $st_type = $args->{type} || 'plain';
  if ($st_type eq 'plain') {
    return new Tao::DBI::st({ 
                 ($sql ? (sql => $sql) : ()), 
                 dbh => $self->{DBH}, %$args });
  } elsif ($st_type eq 'deep') {
    return new Tao::DBI::st_deep({ 
                 ($sql ? (sql => $sql) : ()), 
                 dbh => $self->{DBH}, %$args });  
  } else {
    die "unknown statement type: $st_type\n";
  } 
}

use vars qw ($AUTOLOAD);

# If method wasn't found, delegates to DBH instance variable.
# This way, instances of this class behaves like DBI connections.
#
# this needs improvement: non existent methods will provoke weird
# messages from DBI objects, instead of Tao::DBI::db
sub AUTOLOAD {
  my $self = shift;
  my $meth = $AUTOLOAD;
  $meth =~ s/.*:://;
  return $self->{DBH}->$meth(@_);
}

sub DESTROY {}

1;

# May 29, 2003

__END__

=head1 NAME

Tao::DBI::db - DBI connection with portable support for named placeholders in statements

=head1 SYNOPSIS

  use Tao::DBI qw(dbi_connect dbi_prepare);
  
  $dbh = dbi_connect($args);
  $sql = q{UPDATE T set a = :a, b = :b where k = :k};
  $stmt = $dbh->prepare($sql);
  $rc = $stmt->execute({ k => $k, a => $a, b => $b });
  
  # dbi_prepare() can also be used to create Tao::DBI::st
  $stmt = dbi_prepare($sql, { dbh => $dbh });
  

=head1 DESCRIPTION



=over 4

=item B<new>

  $dbh = DBI::db::new($args)

Note. Unless C<$args> has an explicit pair at key C<"FetchHashKeyName">,
the connection uses C<"FetchHashKeyName" => 'NAME_lc'> which
forces the keys in C<fetchrow_arrayref> to come in lower case.

Note. Unless C<$args> has an explicit pair at key C<"AutoCommit">,
the connection uses C<"AutoCommit" => 0> which
means you have to commit or rollback explicitly.

=item B<execute>

  $sth->execute($hash);
  $sth->execute($param);
  $sth->execute;

Returns 

=back

=head2 EXPORT

Nothing to be exported. Every method is available as a method.

=begin comment

=head1 SEE ALSO

=end comment

=head1 BUGS

Please report bugs via CPAN RT L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Tao-DBI>.

=head1 AUTHOR

Adriano R. Ferreira, E<lt>ferreira@cpan.orgE<gt>

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2005-2007 by Adriano R. Ferreira

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.


=cut