@@ -1,3 +1,5 @@

+0.1637

+  renamed dbi_options to dbi_option. dbi_options is available, but deprecated.

 0.1636

   added tests and cleanup

 0.1635

@@ -18,8 +18,8 @@ use Encode qw/encode_utf8 decode_utf8/;

 __PACKAGE__->attr(

     [qw/data_source dbh password user/],

-    dbi_options => sub { {} },

     cache => 1,

+    dbi_option => sub { {} },

     filter_check  => 1,

     query_builder => sub {DBIx::Custom::QueryBuilder->new},

     result_class  => 'DBIx::Custom::Result',

@@ -165,7 +165,7 @@ sub connect {

       unless $data_source;

     my $user        = $self->user;

     my $password    = $self->password;

-    my $dbi_options = $self->dbi_options || {};

+    my $dbi_option = {%{$self->dbi_options}, %{$self->dbi_option}};

     # Connect

     my $dbh = eval {DBI->connect(

@@ -176,7 +176,7 @@ sub connect {

             RaiseError => 1,

             PrintError => 0,

             AutoCommit => 1,

-            %$dbi_options

+            %$dbi_option

         }

     )};

@@ -731,6 +731,10 @@ sub _croak {

     }

 }

+# DEPRECATED!

+

+__PACKAGE__->attr(dbi_options => sub { {} });

+

 sub default_bind_filter {

     my $self = shift;

@@ -782,67 +786,44 @@ DBIx::Custom - DBI interface, having hash parameter binding and filtering system

 =head1 SYNOPSYS

-Connect to the database.

-    

     use DBIx::Custom;

     my $dbi = DBIx::Custom->connect(data_source => "dbi:mysql:database=dbname",

-                                    user => 'ken', password => '!LFKD%$&');

-

-Insert, update, and delete

+                                    user => 'ken', password => '!LFKD%$&',

+                                    dbi_option => {mysql_enable_utf8 => 1});

     # Insert 

     $dbi->insert(table  => 'book',

                  param  => {title => 'Perl', author => 'Ken'},

-                 filter => {title => 'encode_utf8'});

+                 filter => {title => 'to_something'});

     # Update 

     $dbi->update(table  => 'book', 

                  param  => {title => 'Perl', author => 'Ken'}, 

                  where  => {id => 5},

-                 filter => {title => 'encode_utf8'});

+                 filter => {title => 'to_something'});

     # Update all

     $dbi->update_all(table  => 'book',

                      param  => {title => 'Perl'},

-                     filter => {title => 'encode_utf8'});

+                     filter => {title => 'to_something'});

     # Delete

     $dbi->delete(table  => 'book',

                  where  => {author => 'Ken'},

-                 filter => {title => 'encode_utf8'});

+                 filter => {title => 'to_something'});

     # Delete all

     $dbi->delete_all(table => 'book');

-Select

-

     # Select

-    my $result = $dbi->select(table => 'book');

-    

-    # Select, more complex

     my $result = $dbi->select(

         table  => 'book',

         column => [qw/author title/],

         where  => {author => 'Ken'},

+        relation => {'book.id' => 'rental.book_id'},

         append => 'order by id limit 5',

-        filter => {title => 'encode_utf8'}

-    );

-    

-    # Select, join table

-    my $result = $dbi->select(

-        table    => ['book', 'rental'],

-        column   => ['book.name as book_name']

-        relation => {'book.id' => 'rental.book_id'}

+        filter => {title => 'to_something'}

     );

-    

-    # Select, more flexible where

-    my $result = $dbi->select(

-        table  => 'book',

-        where  => ['{= author} and {like title}', 

-                   {author => 'Ken', title => '%Perl%'}]

-    );

-

-Execute SQL

     # Execute SQL

     $dbi->execute("select title from book");

@@ -850,7 +831,7 @@ Execute SQL

     # Execute SQL with hash binding and filtering

     $dbi->execute("select id from book where {= author} and {like title}",

                   param  => {author => 'ken', title => '%Perl%'},

-                  filter => {title => 'encode_utf8'});

+                  filter => {title => 'to_something'});

     # Create query and execute it

     my $query = $dbi->create_query(

@@ -858,13 +839,9 @@ Execute SQL

     );

     $dbi->execute($query, param => {author => 'Ken', title => '%Perl%'})

-Other features.

-

     # Get DBI object

     my $dbh = $dbi->dbh;

-Fetch row.

-

     # Fetch

     while (my $row = $result->fetch) {

         # ...

@@ -932,10 +909,10 @@ C<connect()> method use this value to connect the database.

 L<DBI> object. You can call all methods of L<DBI>.

-=head2 C<dbi_options>

+=head2 C<dbi_option>

-    my $dbi_options = $dbi->dbi_options;

-    $dbi            = $dbi->dbi_options($dbi_options);

+    my $dbi_option = $dbi->dbi_option;

+    $dbi            = $dbi->dbi_option($dbi_option);

 DBI options.

 C<connect()> method use this value to connect the database.

@@ -947,9 +924,6 @@ Default filter when row is fetched.

     my $filters = $dbi->filters;

     $dbi        = $dbi->filters(\%filters);

-Filter functions.

-"encode_utf8" and "decode_utf8" is registered by default.

-

 =head2 C<filter_check>

     my $filter_check = $dbi->filter_check;

@@ -1068,18 +1042,6 @@ Query is L<DBIx::Custom::Query> object.

 Return value is L<DBIx::Custom::Result> if select statement is executed,

 or the count of affected rows if insert, update, delete statement is executed.

-B<Example:>

-

-    my $result = $dbi->execute(

-        "select * from book where {= author} and {like title}", 

-        param => {author => 'Ken', title => '%Perl%'}

-    );

-    

-    while (my $row = $result->fetch) {

-        my $author = $row->[0];

-        my $title  = $row->[1];

-    }

-

 =head2 C<(experimental) expand>

     my %expand = $dbi->expand($source);

@@ -1114,13 +1076,6 @@ C<query> is if you don't execute sql and get L<DBIx::Custom::Query> object as re

 default to 0. This is experimental.

 Return value of C<delete()> is the count of affected rows.

-B<Example:>

-

-    $dbi->delete(table  => 'book',

-                 where  => {id => 5},

-                 append => 'some statement',

-                 filter => {id => 'encode_utf8'});

-

 =head2 C<delete_all>

     $dbi->delete_all(table => $table);

@@ -1130,10 +1085,6 @@ Arguments is same as C<delete> method,

 except that C<delete_all> don't have C<where> argument.

 Return value of C<delete_all()> is the count of affected rows.

-B<Example:>

-    

-    $dbi->delete_all(table => 'book');

-

 =head2 C<(experimental) helper>

     $dbi->helper(

@@ -1172,13 +1123,6 @@ default to 0. This is experimental.

 This is overwrites C<default_bind_filter>.

 Return value of C<insert()> is the count of affected rows.

-B<Example:>

-

-    $dbi->insert(table  => 'book', 

-                 param  => {title => 'Perl', author => 'Taro'},

-                 append => "some statement",

-                 filter => {title => 'encode_utf8'})

-

 =head2 C<new>

     my $dbi = DBIx::Custom->connect(data_source => "dbi:mysql:database=dbname",

@@ -1235,25 +1179,6 @@ C<default_filter> and C<filter> of C<DBIx::Custom::Result>

 =back

-B<Example:>

-

-    $dbi->register_filter(

-        encode_utf8 => sub {

-            my $value = shift;

-            

-            require Encode;

-            

-            return Encode::encode('UTF-8', $value);

-        },

-        decode_utf8 => sub {

-            my $value = shift;

-            

-            require Encode;

-            

-            return Encode::decode('UTF-8', $value)

-        }

-    );

-

 =head2 C<register_tag_processor>

     $dbi->register_tag_processor(

@@ -1291,30 +1216,6 @@ C<filter> is filters when parameter binding is executed.

 C<query> is if you don't execute sql and get L<DBIx::Custom::Query> object as return value.

 default to 0. This is experimental.

-B<Example:>

-

-    # select * from book;

-    my $result = $dbi->select(table => 'book');

-    

-    # select * from book where title = ?;

-    my $result = $dbi->select(table => 'book', where => {title => 'Perl'});

-    

-    # select title, author from book where id = ? for update;

-    my $result = $dbi->select(

-        table  => 'book',

-        column => ['title', 'author'],

-        where  => {id => 1},

-        appned => 'for update'

-    );

-    

-    # select book.name as book_name from book, rental

-    # where book.id = rental.book_id;

-    my $result = $dbi->select(

-        table    => ['book', 'rental'],

-        column   => ['book.name as book_name']

-        relation => {'book.id' => 'rental.book_id'}

-    );

-

 If you use more complex condition,

 you can specify a array reference to C<where> argument.

@@ -1351,14 +1252,6 @@ default to 0. This is experimental.

 This is overwrites C<default_bind_filter>.

 Return value of C<update()> is the count of affected rows.

-B<Example:>

-

-    $dbi->update(table  => 'book',

-                 param  => {title => 'Perl', author => 'Taro'},

-                 where  => {id => 5},

-                 append => "some statement",

-                 filter => {title => 'encode_utf8'});

-

 =head2 C<(experimental) txn_scope>

     {

@@ -1398,12 +1291,6 @@ Arguments is same as C<update> method,

 except that C<update_all> don't have C<where> argument.

 Return value of C<update_all()> is the count of affected rows.

-B<Example:>

-

-    $dbi->update_all(table  => 'book', 

-                     param  => {author => 'taro'},

-                     filter => {author => 'encode_utf8'});

-

 =head2 C<(experimental) where>

     my $where = $dbi->where;

@@ -1417,23 +1304,6 @@ Create a new L<DBIx::Custom::Where> object.

 Method to set and get caches.

-B<Example:>

-

-    $dbi->cache_method(

-        sub {

-            my $self = shift;

-            

-            $self->{_cached} ||= {};

-            

-            if (@_ > 1) {

-                $self->{_cached}{$_[0]} = $_[1] 

-            }

-            else {

-                return $self->{_cached}{$_[0]}

-            }

-        }

-    );

-

 =head1 STABILITY

 L<DBIx::Custom> is now stable. APIs keep backword compatible in the feature.

@@ -77,7 +77,7 @@ L<DBIx::Custom>を利用するのであればハッシュリファレンスで

 次にテーブルの各列にこのフィルタを適用します。

     $dbi->apply_filter('book',

-        'publish_date' => {out => 'tp_to_date', in => 'date_to_tp'}

+        'issue_date' => {out => 'tp_to_date', in => 'date_to_tp'}

     );

 outはPerlからデータベースに保存する方向、inはデータベースからPerlに取得する方向です。

@@ -482,7 +482,90 @@ C<fetch_hash_first()>を使用します。

 ステートメントハンドルから

 利用できる速度の速いメソッドを利用することができます。

-=head2 4. タグ

+=head2 4. フィルタリング

+

+データベースにデータを登録するときやデータベースからデータを取得する

+ときに自動的に値の変換を行いたい場合が多いと思います。

+たとえば、日付を表現する列の場合は、

+データベースに登録する場合はL<Time::Piece>オブジェクトから

+データベースの日付のフォーマットに、

+データベースからデータを取得するときは、その逆を行えると便利です。

+

+=head3 フィルタの登録

+

+フィルタを登録するにはC<register_filter()>を使用します。

+

+    $dbi->register_filter(

+        # Time::Piece object to DATE format

+        tp_to_date => sub {

+            my $date = shift;

+

+            return '0000-00-00' unless $tp;

+            return $tp->strftime('%Y-%m-%d');

+        },

+        

+        # DATE to Time::Piece object

+        date_to_tp => sub {

+            my $date = shift;

+

+            return if $date eq '0000-00-00';

+            return Time::Piece->strptime($date, '%Y-%m-%d');

+        },

+    );

+

+登録したフィルタはC<apply_filter()>などで利用することができます。

+

+=head3 フィルタの適用

+

+作成したフィルタを適用するには、C<apply_filter()>を使用します。

+

+    $dbi->apply_filter('book',

+        issue_date => {out => 'tp_to_date', in => 'date_to_tp'},

+        first_issue_date => {out => 'tp_to_date', in => 'date_to_tp'}

+    );

+

+第一引数はテーブル名です。第二引数以降は、列名とフィルタルールのペアを記述します。

+フィルタルールのoutには、データベースにデータを送信するときに適用するフィルタを、

+フィルタルールのinには、データベースからデータを取得するときに適用するフィルタを

+記述します。outがデータベースに送信する方向、inがデータベースから取り出す方向です。

+フィルタには、C<register_filter>で登録したフィルタ名の他に、コードリファレンスを

+指定することもできます。

+

+    issue_date => {out => sub { ... }, in => sub { ... }}

+

+適用されたフィルタはC<insert()>、C<update()>、C<update_all()>、C<delete()>、

+C<delete_all()>、C<select()>で有効になります。

+

+    my $tp = Time::Piece->strptime('2010/10/14', '%Y/%m/%d');

+    my $result = $dbi->select(table => 'book', where => {issu_date => $tp});

+

+データベースにデータが送信されるときに、L<Time::Piece>オブジェクトは

+データベースの日付のフォーマット「2010-10-14」に変換されます。

+

+また逆にデータをフェッチするときには、データベースの日付のフォーマットは

+タイムピースオブジェクトに変換されます。

+

+    my $row = $resutl->fetch_hash_first;

+    my $tp = $row->{issue_date};

+

+このような自動的に実行されるフィルタを登録できることがL<DBIx::Custom>の

+特徴のひとつです。

+

+=head3 個別にフィルタを適用する

+

+C<apply_filter()>を使って最初にすべてのテーブルの列について

+フィルタを定義しておくこともできますが、

+さらに個別にフィルタを適用することもできます。

+個別のフィルタはC<apply_filter()>で適用したフィルタを上書きます。

+

+行をフェッチするときに個別にフィルタを適用するには、

+C<DBIx::Custom::Result>クラスのC<filter>メソッドを使用します。

+

+    $result->filter(issue_date => 'date_to_tp', first_issue_date => 'date_to_tp');

+

+これは、C<apply_filter()>のフィルタルールのinで定義されたフィルタを上書きます。

+

+=head2 5. タグ

 L<DBIx::Custom>はハッシュパラメタバインドを提供します。

@@ -547,75 +630,6 @@ C<{>とC<}>は予約語です。これらの文字を使いたい場合は

     'select * from book \\{ something statement \\}'

-=head2 5. フィルタリング

-

-=head3 パラメタバインド時のフィルタリング

-

-データベースに登録するデータをフィルタリングしたい場合

-があります。たとえば、内部文字列で文字列を保持している場合は

-データベースにデータを登録する前に、バイト文字列に変換する

-必要があります。L<DBIx::Custom>のフィルタリングシステムは

-あるデータを他のデータに変換するのを手助けしてくれます。

-

-フィルタリングを利用するにはまず、

-C<register_filter()>メソッドを使用して

-フィルタを登録しておく必要があります。

-

-    $dbi->register_filter(

-        to_upper_case => sub {

-            my $value = shift;

-            return uc $value;

-        }

-    );

-

-デフォルトのフィルタとしてC<encode_utf8>とC<decode_utf8>

-が登録されています。

-

-登録されているフィルタはC<execute()>メソッドのC<filter>オプション

-で指定することができます。

-

-    my $result = $dbi->execute(

-        "select * from book where {= author} and {like title};"

-        param  => {author => 'Ken', title => '%Perl%'},

-        filter => {author => 'to_upper_case, title => 'encode_utf8'}

-    );

-

-この例ではC<author>の値はバインドされるときに大文字に変換され、

-C<title>の値はバイト文字列に変換されます。

-

-C<filter>オプションは

-C<insert()>、C<update()>、 C<update_all()>,

-C<delete()>、C<select()>

-メソッドにおいても使用することができます。

-

-    # insert() with filter option

-    $dbi->insert(table  => 'book',

-                 param  => {title => 'Perl', author => 'Ken'},

-                 filter => {title => 'encode_utf8'});

-    

-    # select() with filter option

-    my $result = $dbi->select(

-        table  => 'book',

-        column => [qw/author title/],

-        where  => {author => 'Ken'},

-        append => 'order by id limit 1',

-        filter => {title => 'encode_utf8'}

-    );

-

-=head3 行のフェッチ時のフィルタリング

-

-行をフェッチするときのフィルタも設定することができます。

-これはL<DBIx::Custom::Result>クラスのC<filter>メソッドを使って

-行います。

-

-    my $result = $dbi->select(table => 'book');

-    $result->filter({title => 'decode_utf8', author => 'to_upper_case'});

-

-フェッチのためのフィルタにおいて、

-たとえ、列名が大文字を含む場合であっても

-列名は小文字であることに注意してください。

-これはデータベースシステムに依存させないための要件です。

-

 =head2 6. パフォーマンスの改善

 =head3 シュガーメソッドを使わない

@@ -664,7 +678,7 @@ C<execute>メソッドの第一引数にクエリオブジェトを渡すこと

 C<begin_work()>、C<commit()>、C<rollback()>

 という三つのメソッドが容易されています。

 これはL<DBI>の同名のメソッドと同じ機能を持ちます。

-

+fc

     $dbi->begin_work;

     eval {

@@ -730,7 +744,7 @@ L<DBIx::Custom>オブジェクトから直接呼び出すことができます

     $dbi->update_or_insert;

     $dbi->find_or_create;

-=head3 ユーティリティメソッド(実験的)

+=head3 ユーティリティメソッド

 C<expand>メソッドを使用すると次のようなハッシュに含まれる

 テーブル名と列名を結合することができます。

@@ -936,9 +936,9 @@ $where = $dbi->where

 eval{$where->to_string};

 like($@, qr/one column/);

-test 'dbi_options default';

+test 'dbi_option default';

 $dbi = DBIx::Custom->new;

-is_deeply($dbi->dbi_options, {});

+is_deeply($dbi->dbi_option, {});

 test 'register_tag_processor';

 $dbi = DBIx::Custom->connect($NEW_ARGS->{0});

@@ -1046,4 +1046,13 @@ is($result->default_filter->(), 1);

 $dbi->table('book');

 eval{$dbi->table('book')->no_exists};

-like($@, qr/locate/);

+like($@, qr/locate/);

+

+test 'dbi_option';

+$dbi = DBIx::Custom->connect(data_source => 'dbi:SQLite:dbname=:memory:',

+                             dbi_option => {PrintError => 1});

+ok($dbi->dbh->{PrintError});

+$dbi = DBIx::Custom->connect(data_source => 'dbi:SQLite:dbname=:memory:',

+                             dbi_options => {PrintError => 1});

+ok($dbi->dbh->{PrintError});

+